Industrial I/O (IIO)

IIO(Industrial I/O) 서브시스템을 센서, ADC/DAC, IMU, DAQ 데이터 경로의 표준화 계층으로 정리합니다. iio_dev, iio_chan_spec, iio_info, trigger, buffer, 이벤트, scan layout, /dev/iio:deviceX 문자 디바이스, in-kernel consumer API, Device Tree의 io-channels, DMA/DMABUF 기반 고속 수집, 그리고 hwmon·input·power_supply와의 역할 경계를 실무 관점에서 최대한 자세히 설명합니다.

IIO가 필요한 이유와 다른 서브시스템과의 경계

IIO는 "센서 값을 커널에 넣는다"는 느슨한 목표가 아니라, 측정 채널의 의미와 샘플 시점을 함께 표준화하려는 서브시스템입니다. ADC, DAC, IMU, 가속도계, 자이로, 자기장 센서, 압력 센서, 조도 센서, 근접 센서, 정밀 계측용 컨버터, 다채널 DAQ처럼 채널 수가 많고 샘플 레이아웃이 중요하며 연속 캡처가 필요한 장치가 주 대상입니다.

실무에서 가장 흔한 오해는 "센서면 전부 IIO" 또는 "숫자를 읽기만 하면 hwmon과 비슷하다"는 생각입니다. 실제로는 하드웨어가 제공하는 데이터의 성격과 사용자 공간이 원하는 소비 방식에 따라 서브시스템 경계가 분명합니다.

IIO를 읽는 기본 관점: 속성 평면, 데이터 평면, 이벤트 평면

IIO는 하나의 인터페이스가 아니라 세 개의 평면이 겹쳐진 구조로 보는 것이 가장 이해하기 쉽습니다.

이 세 평면을 분리해 보면 IIO의 설계 원칙이 보입니다.

• 원시값은 물리량이 아니다 — raw는 대개 ADC 코드나 센서 레지스터 값이며, 실제 물리량은 (raw + offset) x scale 또는 processed로 해석합니다.
• 버퍼 해석은 메타데이터가 먼저다 — 같은 16바이트 샘플이라도 채널 순서, 엔디언, 부호, 패딩(Padding), 타임스탬프가 달라지면 전혀 다른 의미가 됩니다.
• 샘플링 주파수와 도착 주파수는 항상 같지 않다 — 하드웨어 FIFO, DMA burst, runtime PM, trigger 지터 때문에 사용자 공간이 받는 간격이 설정값과 다를 수 있습니다. 이것은 해석이며, 실제 장치와 trigger 구성에 따라 달라집니다.
• 직접 읽기와 버퍼 모드는 경합(Contention)할 수 있습니다 — 버퍼가 켜진 상태에서 원샷 direct read를 허용하면 하드웨어 상태가 꼬일 수 있으므로, 커널은 direct/buffer mode를 구분해 다룹니다.
• 이벤트는 데이터의 일부가 아니다 — 이벤트는 "언제 특정 조건이 성립했는가"를 알리는 별도 경로입니다. 연속 샘플을 재구성할 수 있는 것은 아닙니다.

핵심 객체 모델: iio_dev, 채널, trigger, buffer, consumer

IIO 드라이버를 읽을 때는 자료구조의 역할을 먼저 고정해 두는 것이 좋습니다. 커널 헤더 기준으로 IIO는 장치 전체를 나타내는 struct iio_dev, 채널 정의를 담는 struct iio_chan_spec, 콜백(Callback) 집합인 struct iio_info, 샘플 시점을 규정하는 struct iio_trigger, 그리고 연속 샘플 경로를 나타내는 buffer 계층이 맞물려 동작합니다.

장치 등록의 기본 흐름은 대개 비슷합니다. devm_iio_device_alloc()으로 iio_dev를 할당하고, iio_priv()로 private state를 붙인 다음, 채널 배열과 iio_info를 연결하고, 적절한 버퍼/트리거 helper를 붙인 뒤 devm_iio_device_register()로 마무리합니다.

#include <linux/iio/iio.h>
#include <linux/iio/triggered_buffer.h>

struct acme_state {
    struct regmap *regmap;
    int odr_hz;
};

static int acme_probe(struct spi_device *spi)
{
    struct iio_dev *indio_dev;
    struct acme_state *st;
    int ret;

    indio_dev = devm_iio_device_alloc(&spi->dev, sizeof(*st));
    if (!indio_dev)
        return -ENOMEM;

    st = iio_priv(indio_dev);
    st->odr_hz = 200;

    indio_dev->name = "acme-imu";
    indio_dev->info = &acme_info;
    indio_dev->modes = INDIO_DIRECT_MODE | INDIO_BUFFER_TRIGGERED;
    indio_dev->channels = acme_channels;
    indio_dev->num_channels = ARRAY_SIZE(acme_channels);

    ret = devm_iio_triggered_buffer_setup(&spi->dev, indio_dev,
                                            iio_pollfunc_store_time,
                                            acme_trigger_handler, NULL);
    if (ret)
        return ret;

    return devm_iio_device_register(&spi->dev, indio_dev);
}

indio_dev->modes는 장치가 어떤 사용 모델을 지원하는지를 표현합니다. 최신 커널 헤더에는 INDIO_DIRECT_MODE, INDIO_BUFFER_TRIGGERED, INDIO_BUFFER_SOFTWARE, INDIO_BUFFER_HARDWARE, INDIO_EVENT_TRIGGERED, INDIO_HARDWARE_TRIGGERED가 정의되어 있으며, 이 조합을 보면 드라이버가 원샷 읽기, kfifo 기반 triggered buffer, 순수 하드웨어 버퍼, 이벤트 중심 장치 중 어느 축에 가까운지 짐작할 수 있습니다.

채널 모델과 값 해석 규칙

IIO의 진짜 중심은 struct iio_chan_spec입니다. 이 구조체(Struct)가 단순히 "채널이 하나 있다"를 넘어서, 이 채널이 무엇을 측정하고 어떤 형식으로 버퍼에 실리며 어떤 속성과 이벤트를 제공하는지를 모두 설명합니다.

#include <linux/iio/iio.h>

static const struct iio_chan_spec acme_channels[] = {
    {
        .type = IIO_ACCEL,
        .modified = 1,
        .channel2 = IIO_MOD_X,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
        .info_mask_shared_by_type =
            BIT(IIO_CHAN_INFO_SCALE) |
            BIT(IIO_CHAN_INFO_SAMP_FREQ),
        .info_mask_shared_by_type_available =
            BIT(IIO_CHAN_INFO_SAMP_FREQ),
        .scan_index = 0,
        .scan_type = {
            .sign = 's',
            .realbits = 16,
            .storagebits = 16,
            .shift = 0,
            .repeat = 1,
            .endianness = IIO_LE,
        },
        .event_spec = acme_accel_events,
        .num_event_specs = ARRAY_SIZE(acme_accel_events),
    },
    IIO_CHAN_SOFT_TIMESTAMP(3),
};

채널 이름은 대개 다음 요소의 조합으로 읽습니다.

헤더를 보면 iio_chan_spec는 단일 숫자 이상을 담고 있습니다.

• type — 전압, 전류, 가속도, 각속도, 조도 등 측정 종류
• channel / channel2 — 채널 번호 또는 modifier
• modified — X/Y/Z축, I/Q, red/green/blue 같은 수정자 사용 여부
• indexed — 파일명에 숫자 인덱스를 넣을지 여부
• output — 입력이 아니라 출력 채널임을 표현
• differential — 차동 채널 여부
• scan_index — 버퍼 안에서의 순서
• scan_type — 부호, 유효 비트, 저장 비트, 반복 수, 엔디언
• info_mask_* — 어떤 속성을 어떤 공유 범위로 노출할지 결정
• event_spec — threshold, rate-of-change 같은 이벤트 지원
• ext_info — mount matrix, enum, 벤더 확장 속성(Extended Attribute)

info_mask_separate, info_mask_shared_by_type, info_mask_shared_by_dir, info_mask_shared_by_all는 sysfs 파일이 채널별인지, 동일 타입 전체 공유인지, 방향 공유인지, 장치 전체 공유인지 결정합니다. 사용자 공간 입장에서는 파일 개수 차이로 보이지만, 드라이버 입장에서는 ABI 안정성과 구현 단순성에 큰 영향을 줍니다.

값 해석 규칙도 채널 모델의 일부입니다. 커널의 in-kernel consumer 헤더는 raw 값을 표준 단위로 쓰려면 대개 (raw + offset) x scale을 적용해야 한다고 설명합니다. 반대로 processed 속성이나 iio_read_channel_processed()를 지원하는 경우, 드라이버 또는 IIO 코어가 이미 단위 변환을 끝낸 값을 돌려줄 수 있습니다.

값 반환 형식도 중요합니다. read_raw()는 단순히 정수를 채우는 것이 아니라, IIO_VAL_INT, IIO_VAL_INT_PLUS_MICRO, IIO_VAL_FRACTIONAL, IIO_VAL_FRACTIONAL_LOG2 같은 형식 코드를 통해 val, val2를 어떻게 해석할지 함께 알려줍니다.

static int acme_read_raw(struct iio_dev *indio_dev,
                         const struct iio_chan_spec *chan,
                         int *val, int *val2, long mask)
{
    struct acme_state *st = iio_priv(indio_dev);
    unsigned int raw;
    int ret;

    switch (mask) {
    case IIO_CHAN_INFO_RAW:
        ret = iio_device_claim_direct_mode(indio_dev);
        if (ret)
            return ret;

        ret = regmap_read(st->regmap, chan->address, &raw);
        iio_device_release_direct_mode(indio_dev);
        if (ret)
            return ret;

        *val = sign_extend32(raw, chan->scan_type.realbits - 1);
        return IIO_VAL_INT;

    case IIO_CHAN_INFO_SCALE:
        *val = 0;
        *val2 = 598;
        return IIO_VAL_INT_PLUS_MICRO;

    case IIO_CHAN_INFO_SAMP_FREQ:
        *val = st->odr_hz;
        return IIO_VAL_INT;
    }

    return -EINVAL;
}

sysfs ABI: 채널 설명과 제어 평면

IIO 코어 문서는 사용자 공간이 장치와 상호작용하는 방법을 크게 두 가지로 설명합니다. 하나는 sysfs 속성 파일을 통한 제어 및 원샷 읽기이고, 다른 하나는 문자 디바이스를 통한 버퍼/이벤트 소비입니다. sysfs는 "설명과 제어", 문자 디바이스는 "연속 데이터"라고 기억하면 대부분 맞습니다.

장치 루트에는 보통 다음 종류의 정보가 있습니다.

• 장치 정체성 — name, dev
• 채널 값 — *_raw, *_input, *_scale, *_offset
• 구성 가능 항목 — *_sampling_frequency, *_oversampling_ratio, *_calibbias, *_calibscale
• 허용값 조회 — *_available
• 레이블/방향 정보 — label, mount_matrix
• 버퍼/이벤트/트리거 하위 디렉터리 — buffer 또는 buffer0, events, trigger

실전에서는 먼저 장치 이름과 채널 속성 목록을 확인한 뒤, available 파일을 읽어 어떤 값이 합법적인지 파악하는 습관이 중요합니다. 샘플링 주기, full-scale range, oversampling ratio를 드라이버마다 임의로 추측하면 ABI 위반과 같은 효과를 냅니다.

# IIO 장치 나열
ls /sys/bus/iio/devices/

# 장치 정체성 확인
cat /sys/bus/iio/devices/iio:device0/name

# 채널 값과 메타데이터 확인
cat /sys/bus/iio/devices/iio:device0/in_accel_x_raw
cat /sys/bus/iio/devices/iio:device0/in_accel_scale
cat /sys/bus/iio/devices/iio:device0/in_accel_sampling_frequency
cat /sys/bus/iio/devices/iio:device0/in_accel_sampling_frequency_available

# 사람이 읽기 쉬운 채널 이름과 장착 방향
cat /sys/bus/iio/devices/iio:device0/in_accel_x_label
cat /sys/bus/iio/devices/iio:device0/in_accel_mount_matrix

속성 파일의 단위는 채널마다 다를 수 있습니다. 예를 들어 sampling_frequency는 보통 Hz 계열이지만, scale는 센서 종류에 따라 m/s², degree/s, lux, volt 등 의미가 달라집니다. IIO는 hwmon처럼 모든 속성을 극도로 제한된 단위 집합으로 통일하는 구조가 아니므로, 채널 타입과 드라이버 문맥을 함께 읽어야 합니다.

또한 read_avail()가 구현된 장치는 목록형 또는 범위형 *_available 파일을 제공합니다. 커널 헤더 문서에 따르면 범위형은 min step max의 세 값을, 목록형은 가능한 값을 나열합니다. 사용자 공간 도구는 이를 이용해 유효하지 않은 설정 쓰기를 피할 수 있습니다.

버퍼와 scan layout: IIO에서 가장 중요한 ABI

IIO를 깊게 다룰수록 핵심은 sysfs의 단일 속성이 아니라 buffer ABI라는 점이 분명해집니다. 공식 버퍼 문서는 버퍼 인스턴스 아래에 length, enable, watermark, bytes_per_datum, data_available 같은 속성이 있음을 설명합니다. 여기서 length는 버퍼 깊이, watermark는 사용자 공간을 깨우는 기준, bytes_per_datum은 한 scan의 총 바이트 수, data_available는 현재 읽을 수 있는 양을 나타냅니다.

scan layout은 각 채널별 _index, _type, _en 파일로 설명됩니다. 중요한 점은 예전 문서와 최신 ABI가 경로 표기에서 다를 수 있다는 점입니다.

_type 파일은 버퍼 바이트열을 어떻게 해석해야 하는지 알려주는 핵심 메타데이터입니다. 예를 들어 le:s16/16>>0는 리틀엔디언, 부호 있는 16비트, 저장 16비트, 오른쪽 시프트 0을 의미합니다. 여기에 repeat가 붙으면 같은 형식이 여러 번 반복되는 채널입니다.

버퍼 활성화 순서도 중요합니다. 공식 ABI 문서는 enable을 마지막에 쓰라고 설명합니다. 즉, 채널 선택, trigger 선택, length/watermark 설정, 필요한 경우 sampling_frequency 조정이 끝난 뒤에 enable을 켜는 것이 안전합니다.

# 최신 다중 버퍼 ABI 예시
cat /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_x_index
cat /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_x_type
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_x_en
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_y_en
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_z_en
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_timestamp_en
echo 64 > /sys/bus/iio/devices/iio:device0/buffer0/length
echo 16 > /sys/bus/iio/devices/iio:device0/buffer0/watermark
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/enable

# 레거시 문서에서 자주 보이는 표기
echo 1 > /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_x_en
echo 64 > /sys/bus/iio/devices/iio:device0/buffer/length
echo 1 > /sys/bus/iio/devices/iio:device0/buffer/enable

드라이버 입장에서는 update_scan_mode()가 이 순간의 중심 함수입니다. 어떤 채널이 켜졌는지, scan mask가 어떤지에 따라 하드웨어 레지스터를 다시 프로그래밍해야 하기 때문입니다. 특정 ADC처럼 한 번에 하나의 채널만 선택 가능한 장치라면 iio_validate_scan_mask_onehot() 같은 helper로 제약을 모델링하는 것이 일반적입니다.

Trigger 모델과 triggered buffer 흐름

IIO trigger는 단순 IRQ 번호가 아니라, "샘플 캡처 시점을 표현하는 커널 객체"입니다. 하드웨어 data-ready IRQ, hrtimer 기반 소프트웨어 trigger, 외부 동기 신호, 다른 장치가 제공하는 공용 trigger가 모두 IIO trigger로 모델링될 수 있습니다.

공식 트리거 문서는 trigger 자체가 /sys/bus/iio/devices/triggerY/에 노출되고, 장치는 보통 자신의 trigger/current_trigger를 통해 어떤 trigger를 사용할지 선택한다고 설명합니다. 장치 쪽 validate_trigger()와 trigger 쪽 validate_device()가 맞물려 호환되지 않는 조합을 막습니다.

#include <linux/iio/triggered_buffer.h>
#include <linux/iio/trigger_consumer.h>

static irqreturn_t acme_trigger_handler(int irq, void *p)
{
    struct iio_poll_func *pf = p;
    struct iio_dev *indio_dev = pf->indio_dev;
    struct acme_state *st = iio_priv(indio_dev);
    __le16 frame[4];
    int ret;

    ret = acme_read_xyz_locked(st, frame);
    if (!ret)
        iio_push_to_buffers_with_timestamp(indio_dev, frame, pf->timestamp);

    iio_trigger_notify_done(indio_dev->trig);
    return IRQ_HANDLED;
}

iio_pollfunc_store_time()는 timestamp를 가능한 이른 시점에 잡아 thread handler로 넘기는 helper입니다. scan frame이 자연 정렬을 따르지 않는 packed 형식이라면 iio_push_to_buffers_with_ts_unaligned() 같은 helper가 필요할 수 있습니다.

장치가 외부 trigger를 허용하지 않고 자기 own trigger만 써야 하는 경우, trigger 헤더가 제공하는 iio_trigger_set_immutable()나 iio_validate_own_trigger() 계열 helper를 활용하면 정책을 분명하게 만들 수 있습니다.

이벤트 ABI: threshold, hysteresis, 상태 변화 알림

IIO 이벤트는 "샘플을 모두 읽어서 조건을 후처리"하는 경로가 아닙니다. 하드웨어나 드라이버가 이미 감지한 의미 있는 상태 변화를 별도로 올려주는 통로입니다. 예를 들면 threshold 상승/하강, rate-of-change, FIFO 상태, gesture, 데이터 준비 완료와 같은 신호가 여기에 들어갑니다.

커널 헤더의 struct iio_event_spec는 이벤트 타입, 방향, 그리고 이벤트 속성의 공유 범위를 정의합니다. 실제 활성화와 값 읽기/쓰기는 read_event_config(), write_event_config(), read_event_value(), write_event_value() 같은 iio_info 콜백으로 이어집니다.

공식 ABI 설명에서 특히 중요한 점은 hysteresis의 적용 방식입니다. 상승 이벤트라면 일반적으로 값이 threshold를 넘을 때 활성화되고, 다시 threshold - hysteresis 아래로 내려가야 해제됩니다. 하강 이벤트는 반대로 threshold + hysteresis 위로 올라가야 해제됩니다. 이 규칙을 이해하지 못하면 "이벤트가 한 번 울린 뒤 왜 바로 다시 안 울리나?" 같은 혼란이 생깁니다.

static const struct iio_event_spec acme_accel_events[] = {
    {
        .type = IIO_EV_TYPE_THRESH,
        .dir = IIO_EV_DIR_RISING,
        .mask_separate =
            BIT(IIO_EV_INFO_VALUE) |
            BIT(IIO_EV_INFO_HYSTERESIS),
    },
    {
        .type = IIO_EV_TYPE_THRESH,
        .dir = IIO_EV_DIR_FALLING,
        .mask_separate =
            BIT(IIO_EV_INFO_VALUE) |
            BIT(IIO_EV_INFO_HYSTERESIS),
    },
};

이벤트가 실제 발생하면 드라이버는 보통 iio_push_event()로 코드와 timestamp를 올립니다. 사용자 공간은 iio_event_monitor 같은 도구나 자체 이벤트 소비 코드로 이를 관찰합니다. 이벤트는 상태 변화 알림이지, 전체 신호를 재구성할 수 있는 샘플 스트림이 아니라는 점을 계속 유지해야 합니다.

사용자 공간 인터페이스: sysfs, 문자 디바이스, libiio, configfs

IIO 코어 문서가 강조하듯 사용자 공간에는 두 가지 기본 상호작용 방식이 있습니다.

1. sysfs 속성 — 원샷 읽기, 설정 쓰기, scan layout과 이벤트/trigger 정보 확인
2. 문자 디바이스 — 버퍼 기반 샘플 스트림과 이벤트 소비

실전 도구 생태계에서는 libiio와 함께 iio_info, iio_attr, iio_generic_buffer, iio_event_monitor, lsiio 같은 도구가 자주 쓰입니다. 커널 문서의 IIO tools 페이지(Page)도 이러한 유틸리티 집합을 소개합니다.

# 장치와 채널 메타데이터 확인
iio_info -n local

# 특정 속성 조회
iio_attr -q -c local acme-imu in_accel_scale

# 버퍼 스트림 읽기
iio_generic_buffer -n local -c acme-imu -s 128

# 이벤트 관찰
iio_event_monitor -n local acme-imu

/dev/iio:deviceX는 단순 파일처럼 보이지만, 읽기 전에 scan layout과 버퍼 상태를 정확히 구성하지 않으면 얻는 바이트열은 쓸모가 없습니다. 특히 버퍼 크기와 watermark를 적절히 맞추지 않으면 시스템 호출(System Call) 오버헤드(Overhead)가 커지거나 지연(Latency)이 늘어납니다.

IIO configfs 지원도 알아둘 만합니다. 커널 문서는 CONFIG_IIO_CONFIGFS를 활성화하면 configfs 아래 /config/iio에 IIO 객체가 생기며, 소프트웨어 trigger를 /config/iio/triggers 아래에서 생성할 수 있다고 설명합니다. hrtimer trigger를 이용하면 하드웨어 DRDY가 없는 환경에서도 실험용 트리거를 만들 수 있습니다.

# configfs mount
mkdir -p /config
mount -t configfs none /config

# IIO 소프트웨어 trigger 확인
ls /config/iio/triggers/

고속 장치에서는 read/write 기반 버퍼 인터페이스 외에 DMABUF 기반 인터페이스도 중요합니다. 공식 DMABUF 문서는 IIO 버퍼에 외부에서 생성한 DMABUF 객체를 붙여 zero-copy에 가까운 전송을 구성할 수 있다고 설명합니다. 이는 IIO와 USB 스택 같은 다른 인터페이스 사이에서 대용량 데이터를 복사 없이 넘기고 싶을 때 특히 유용합니다. 대신 DMA_BUF_SYNC_START, DMA_BUF_SYNC_END와 같은 동기화 비용이 생기므로, "무조건 빠르다"가 아니라 대역폭과 동기화 오버헤드를 저울질해야 하는 기법입니다.

in-kernel consumer API와 io-channels

IIO는 사용자 공간용 프레임워크일 뿐 아니라, 다른 커널 드라이버가 채널을 소비하도록 연결하는 계층이기도 합니다. 예를 들어 배터리 측정용 ADC 채널을 전원 드라이버가 읽거나, 보드 센서의 아날로그 입력을 LED 드라이버나 thermal 보조 드라이버가 읽을 수 있습니다.

커널 헤더 include/linux/iio/consumer.h에는 다음 API들이 정의되어 있습니다.

Device Tree에서는 보통 provider가 #io-channel-cells를 선언하고, consumer가 io-channels와 io-channel-names로 연결합니다. 이후 consumer 드라이버는 이름 기반으로 채널을 요청합니다.

/* provider */
adc@4000 {
    compatible = "vendor,sigma-delta-adc";
    reg = <0x4000 0x100>;
    #io-channel-cells = <1>;
    vref-supply = <&vref_1v8>;
};

/* consumer */
battery-monitor {
    compatible = "vendor,battery-monitor";
    io-channels = <&adc 3>, <&adc 4>;
    io-channel-names = "battery_voltage", "ntc_temp";
};

#include <linux/iio/consumer.h>

static int battery_mon_probe(struct platform_device *pdev)
{
    struct iio_channel *vbat;
    int uv;
    int ret;

    vbat = devm_iio_channel_get(&pdev->dev, "battery_voltage");
    if (IS_ERR(vbat))
        return PTR_ERR(vbat);

    ret = iio_read_channel_processed(vbat, &uv);
    if (ret)
        return ret;

    /* uv는 이미 처리된 단위 값일 수 있다. 단위는 provider 문서와 채널 타입을 함께 확인한다. */
    return 0;
}

펌웨어 셀 해석이 단순 채널 번호가 아니라 더 복잡한 경우, 코어 문서에 나온 fwnode_xlate 콜백을 통해 provider가 자신만의 specifier 해석 규칙을 제공할 수 있습니다. 따라서 #io-channel-cells는 단순 숫자 하나일 수도 있지만, 더 많은 셀을 요구하는 ABI로 확장될 수도 있습니다.

드라이버 구현 패턴과 좋은 설계 습관

IIO 드라이버는 센서 레지스터를 읽는 코드만으로 끝나지 않습니다. 좋은 드라이버는 채널 ABI, 트리거 제약, 버퍼 모드, 이벤트, 전원 관리(Power Management), 디버깅(Debugging) 경로를 함께 설계합니다.

1. 장치 등록을 먼저 단순화합니다
   devm_iio_device_alloc()와 devm_iio_device_register()를 기본으로 하고, iio_priv()에 state를 보관합니다.
2. 채널 ABI를 먼저 고정합니다
   채널 번호와 파일 이름이 바뀌면 사용자 공간, DT consumer, 테스트 스크립트가 모두 깨질 수 있으므로 초기 설계가 중요합니다.
3. read_avail()를 적극적으로 구현합니다
   지원 ODR, oversampling ratio, full-scale range를 *_available로 노출하면 userspace와 테스트 도구가 안정됩니다.
4. read_label()을 우선합니다
   헤더가 말하듯 extend_name은 sysfs 파일 이름에 영향을 주는 오래된 방식이고, 사람이 읽는 라벨은 read_label()이 더 적절합니다.
5. update_scan_mode()를 대충 넘기지 않는다
   활성 채널 조합에 따라 레지스터 맵, burst length, FIFO 패킹이 달라지는 장치는 이 함수가 핵심입니다.
6. direct/buffer 경합을 의식한다
   원샷 읽기 경로는 iio_device_claim_direct_mode()를 검토하고, buffer enabled 상태에서 허용되지 않는 작업을 분리합니다.
7. 디버그용 register access를 준비한다
   debugfs_reg_access()를 구현하면 bring-up 단계에서 레지스터 확인이 쉬워집니다.

static const struct iio_info acme_info = {
    .read_raw = acme_read_raw,
    .read_avail = acme_read_avail,
    .write_raw = acme_write_raw,
    .read_label = acme_read_label,
    .read_event_config = acme_read_event_config,
    .write_event_config = acme_write_event_config,
    .read_event_value = acme_read_event_value,
    .write_event_value = acme_write_event_value,
    .validate_trigger = iio_validate_own_trigger,
    .update_scan_mode = acme_update_scan_mode,
    .debugfs_reg_access = acme_debugfs_reg_access,
};

write_raw_get_fmt()도 잊기 쉬운 포인트입니다. 쓰기 정밀도를 명확히 정의하지 않으면 사용자 공간은 기본적으로 IIO_VAL_INT_PLUS_MICRO 형식을 기대하게 됩니다. 정밀한 스케일 설정이나 캘리브레이션 값을 쓰는 장치에서는 이 차이가 중요한 ABI 차이로 이어집니다.

고속 수집: kfifo, hardware buffer, DMA engine, DMABUF

IIO는 느린 센서 몇 개만 다루는 프레임워크가 아닙니다. 수십 kSPS부터 수 MSPS 이상까지 올라가는 ADC나 SDR 계열 장치에서는 버퍼 구현 방식이 성능의 핵심이 됩니다.

코어 문서에는 hwfifo_set_watermark, hwfifo_flush_to_buffer 같은 포인터도 정의되어 있습니다. 이는 장치 내부 FIFO가 별도로 있고, 그 안의 샘플을 IIO 버퍼로 옮겨 담아야 하는 드라이버에서 매우 중요합니다. 즉, "하드웨어 FIFO"와 "IIO 버퍼"는 같은 개념이 아닐 수 있습니다.

DMABUF를 쓰더라도 언제나 최선은 아닙니다. 작은 샘플을 간헐적으로 읽는 센서라면 단순 read() 기반 버퍼가 더 낫고, 수 MB/s 이상 고속 장치에서만 DMABUF의 복사 절감 이점이 체감되는 경우가 많습니다.

Device Tree와 펌웨어 연결: provider, consumer, 보드 정보

IIO 장치의 DT 바인딩은 버스(Bus) 주소만 넣는 수준을 넘습니다. 센서는 공급 전원, 인터럽트(Interrupt), 참조 전압, mount matrix, 채널 번호 ABI, 외부 clock, reset, trigger 연결까지 보드 의존 정보를 많이 가집니다.

센서 provider 노드의 대표적인 요소는 다음과 같습니다.

• 버스 식별 — reg, compatible
• IRQ/DRDY — interrupts, interrupt-parent
• 전원 — vdd-supply, vddio-supply, vref-supply
• 보드 장착 방향 — mount-matrix
• consumer 연결 ABI — #io-channel-cells

imu@68 {
    compatible = "vendor,my-imu";
    reg = <0x68>;
    interrupt-parent = <&gpio1>;
    interrupts = <12 1>;
    vdd-supply = <&vdd_3v3>;
    vddio-supply = <&vdd_1v8>;
    mount-matrix = "1", "0", "0",
                   "0", "1", "0",
                   "0", "0", "1";
};

mount-matrix는 특히 IMU 계열에서 중요합니다. 센서 칩의 물리적인 장착 방향이 보드 기준 좌표와 다르면, raw X/Y/Z를 그대로 쓰는 상위 소프트웨어는 전부 틀린 데이터를 보게 됩니다. IIO 헤더는 IIO_MOUNT_MATRIX() helper와 iio_read_mount_matrix()를 제공하여 이 정보를 채널 ext_info로 노출할 수 있게 합니다.

consumer와 연결할 때는 provider가 어떤 채널 번호를 어떤 의미로 해석하는지 문서화해야 합니다. 숫자 하나 바꾸는 것이 사소해 보이지만, io-channels = <&adc 3>를 쓰는 모든 consumer에게는 ABI 변경입니다.

디버깅 절차: 값이 틀린가, 타이밍이 틀린가, ABI 해석이 틀린가

IIO 문제를 디버깅할 때는 "값이 이상하다"를 세 종류로 분해해야 합니다.

1. 원시값 자체가 틀리다
   레지스터 읽기, 전원, 레퍼런스 전압, range 설정, sign extension이 문제일 가능성이 큽니다.
2. 값 해석이 틀리다
   scale, offset, label, mount_matrix, _type 해석이 문제일 수 있습니다.
3. 타이밍이 틀리다
   trigger 선택, watermark, FIFO flush, DMA burst, runtime PM 재개 지연이 문제일 수 있습니다.

# 1. 장치 존재와 이름 확인
for d in /sys/bus/iio/devices/iio:device*; do
    echo "== $d =="
    cat "$d/name"
done

# 2. 핵심 채널 메타데이터 점검
cat /sys/bus/iio/devices/iio:device0/in_accel_x_raw
cat /sys/bus/iio/devices/iio:device0/in_accel_scale
cat /sys/bus/iio/devices/iio:device0/in_accel_sampling_frequency
cat /sys/bus/iio/devices/iio:device0/in_accel_sampling_frequency_available

# 3. 버퍼/scan layout 점검
cat /sys/bus/iio/devices/iio:device0/buffer0/bytes_per_datum
cat /sys/bus/iio/devices/iio:device0/buffer0/data_available
cat /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_accel_x_type

# 4. trigger 연결 점검
cat /sys/bus/iio/devices/iio:device0/trigger/current_trigger
ls /sys/bus/iio/devices/trigger*

드라이버가 debugfs_reg_access()를 구현했다면 debugfs 아래에 장치별 direct register access 경로가 나타날 수 있습니다. 다만 debugfs는 안정 ABI가 아니므로, 이는 생산 환경용 인터페이스가 아니라 bring-up과 개발용 관찰점으로 보는 것이 맞습니다.

흔한 실패 패턴과 원인

끝까지 따라가는 상태 전이 예제

SPI IMU가 accel X/Y/Z와 timestamp를 triggered buffer로 제공하는 전형적인 예를 따라가 보겠습니다.

1. probe
   드라이버는 iio_dev를 할당하고 채널 배열, iio_info, triggered buffer helper를 등록합니다.
2. 사용자 공간 구성
   sampling_frequency를 설정하고, X/Y/Z와 timestamp scan element를 enable하고, current_trigger를 DRDY trigger로 선택합니다.
3. buffer enable
   update_scan_mode()가 호출되어 하드웨어 burst 형식과 FIFO 패킹을 재설정합니다.
4. DRDY 발생
   top half가 timestamp를 저장하고, threaded handler가 실제 샘플 frame을 읽어 버퍼에 push합니다.
5. userspace read
   사용자 공간은 /dev/iio:deviceX에서 scan 단위로 읽고, _type와 _index로 복원합니다.
6. threshold event 병행
   같은 장치가 threshold 이벤트도 켜 둔 경우, 별도 이벤트 큐로 임계값 crossing을 보고할 수 있습니다.

이 흐름을 머리에 넣고 나면 IIO 디버깅도 단순해집니다. 문제가 probe인지, scan 구성인지, trigger인지, frame 조립인지, 사용자 공간 해석인지 단계별로 잘라서 볼 수 있기 때문입니다.

iio_info 콜백 구조

struct iio_info는 IIO 디바이스의 sysfs 읽기/쓰기 동작을 정의하는 핵심 콜백 테이블입니다. 드라이버 작성 시 반드시 구현해야 합니다:

/* include/linux/iio/iio.h */
struct iio_info {
    /* 채널 값 읽기: sysfs에서 in_voltage0_raw 읽을 때 호출 */
    int (*read_raw)(struct iio_dev *indio_dev,
                    struct iio_chan_spec const *chan,
                    int *val, int *val2, long mask);

    /* 채널 값 쓰기: sysfs에서 out_voltage0_raw 쓸 때 호출 */
    int (*write_raw)(struct iio_dev *indio_dev,
                     struct iio_chan_spec const *chan,
                     int val, int val2, long mask);

    /* 사용 가능한 값 목록 제공: _available sysfs 파일 */
    int (*read_avail)(struct iio_dev *indio_dev,
                      struct iio_chan_spec const *chan,
                      const int **vals, int *type,
                      int *length, long mask);
};

/* mask 값에 따른 동작 분기 */
switch (mask) {
case IIO_CHAN_INFO_RAW:       /* ADC 원시 값 (예: 0~4095) */
    *val = read_adc_register(chan->channel);
    return IIO_VAL_INT;
case IIO_CHAN_INFO_SCALE:     /* 스케일: 실제값 = raw × scale */
    *val = 0;
    *val2 = 805664;           /* 3.3V / 4096 = 0.000805664V */
    return IIO_VAL_INT_PLUS_NANO;
case IIO_CHAN_INFO_SAMP_FREQ: /* 샘플링 주파수 (Hz) */
    *val = 100;
    return IIO_VAL_INT;
}

DMA와 IIO 통합

고속 샘플 수집(>100kSPS)에서는 CPU 인터럽트 기반 전송이 병목(Bottleneck)이 됩니다. DMAEngine consumer API를 사용하면 ADC 하드웨어 FIFO에서 직접 메모리로 데이터를 전송하여 CPU 부하를 최소화할 수 있습니다:

/* IIO DMA buffer 설정 예제 (drivers/iio/buffer/industrialio-buffer-dmaengine.c) */

/* probe()에서 DMA 채널 요청 */
struct dma_chan *chan = dma_request_chan(dev, "rx");

/* IIO DMA buffer 등록 */
ret = devm_iio_dmaengine_buffer_setup(dev, indio_dev, "rx");

/* Device Tree 바인딩:
 * adc@48000000 {
 *     compatible = "ti,adc108s102";
 *     dmas = <&edma 0 24>;       // DMA 채널 지정
 *     dma-names = "rx";
 *     #io-channel-cells = <1>;
 * };
 */

/* DMA buffer vs kfifo buffer 비교:
 * kfifo:   CPU가 IRQ마다 데이터 복사 → 저속(~10kSPS)에 적합
 * DMA:     하드웨어가 직접 메모리에 기록 → 고속(>100kSPS)에 필수
 * DMABUF:  유저 공간과 zero-copy 공유 (커널 6.4+)
 */

커널 소스 분석: iio_device_register() 호출 체인

devm_iio_device_register()는 대부분의 IIO 드라이버가 probe 마지막에 호출하는 함수입니다. 이 함수는 내부적으로 iio_device_register()를 호출하고, 여기서 sysfs 속성 등록, 버퍼 마스크 할당, 문자 디바이스(Character Device) 등록이 순차적으로 이루어집니다. 커널 소스(drivers/iio/industrialio-core.c)를 따라가면 다음과 같은 체인이 보입니다.

/* drivers/iio/industrialio-core.c — 등록 호출 체인 (간략화) */

int __iio_device_register(struct iio_dev *indio_dev, struct module *this_mod)
{
    struct iio_dev_opaque *iio_dev_opaque = to_iio_dev_opaque(indio_dev);
    int ret;

    /* 1단계: sysfs 속성 그룹 등록 — 채널별 파일 생성 */
    ret = iio_device_register_sysfs(indio_dev);
    if (ret)
        return ret;

    /* 2단계: 버퍼 sysfs + scan mask 할당 */
    ret = iio_buffer_alloc_sysfs_and_mask(indio_dev);
    if (ret)
        goto error_unreg_sysfs;

    /* 3단계: cdev + device 등록 → /dev/iio:deviceX 생성 */
    ret = cdev_device_add(&iio_dev_opaque->chrdev, &indio_dev->dev);
    if (ret)
        goto error_free_sysfs;

    return 0;

error_free_sysfs:
    iio_buffer_free_sysfs_and_mask(indio_dev);
error_unreg_sysfs:
    iio_device_unregister_sysfs(indio_dev);
    return ret;
}

커널 소스 분석: struct iio_dev 필드별 해설

struct iio_dev는 IIO 서브시스템에서 하나의 물리 장치를 표현하는 최상위 구조체입니다. 커널 헤더(include/linux/iio/iio.h)에서 드라이버가 직접 접근하는 필드와, iio_dev_opaque에 숨겨진 내부 필드가 분리되어 있습니다.

/* include/linux/iio/iio.h — struct iio_dev 주요 필드 (간략화) */
struct iio_dev {
    int                          modes;          /* INDIO_DIRECT_MODE | INDIO_BUFFER_TRIGGERED 등 */
    int                          currentmode;    /* 현재 활성 모드 (코어가 관리) */
    struct device                dev;            /* 내장 device — sysfs, devres 연결 */

    struct iio_buffer            *buffer;        /* 주 버퍼 (레거시 호환) */
    int                          scan_bytes;     /* 활성 채널 기준 한 scan의 바이트 수 */

    const struct iio_chan_spec   *channels;      /* 채널 정의 배열 포인터 */
    int                          num_channels;   /* 채널 배열 크기 */

    const struct iio_info        *info;          /* 콜백 테이블 (read_raw 등) */
    const unsigned long          *available_scan_masks; /* HW가 지원하는 채널 조합 */
    unsigned                     masklength;     /* scan mask 비트 길이 */

    struct iio_trigger           *trig;          /* 현재 연결된 trigger */
    const char                   *name;          /* 장치 이름 (sysfs name 파일) */
    const char                   *label;         /* 보드별 라벨 (DT label 프로퍼티) */

    void                         *priv;          /* iio_priv()로 접근하는 드라이버 state */
    const struct iio_mount_matrix *(*read_mount_matrix)(...);
};

커널 소스 분석: struct iio_chan_spec 필드별 해설

struct iio_chan_spec는 IIO 채널 하나의 메타데이터 전체를 담는 구조체입니다. 드라이버는 보통 정적 배열로 이것을 정의하며, IIO 코어는 이 정보를 바탕으로 sysfs 파일명, scan layout, 이벤트 인터페이스를 자동 생성합니다.

/* include/linux/iio/iio.h — struct iio_chan_spec 주요 필드 (간략화) */
struct iio_chan_spec {
    enum iio_chan_type  type;       /* IIO_VOLTAGE, IIO_ACCEL, IIO_TEMP 등 */
    int                channel;    /* 채널 번호 (indexed=1일 때 사용) */
    int                channel2;   /* modifier: IIO_MOD_X, IIO_MOD_Y 또는 차동 pair */
    unsigned long      address;    /* 드라이버 전용: 레지스터 주소 등 */

    int                scan_index; /* 버퍼 내 순서 (-1이면 버퍼 불가) */
    struct {
        char           sign;       /* 's' 부호 있음, 'u' 부호 없음 */
        u8             realbits;   /* 유효 데이터 비트 수 */
        u8             storagebits;/* 저장 공간 비트 수 (8의 배수) */
        u8             shift;      /* storagebits 내 오른쪽 shift 양 */
        u8             repeat;     /* 반복 횟수 (oversampled 등) */
        enum iio_endian endianness; /* IIO_LE / IIO_BE / IIO_CPU */
    }                  scan_type;

    long  info_mask_separate;          /* 채널별 고유 속성 (BIT(IIO_CHAN_INFO_RAW) 등) */
    long  info_mask_shared_by_type;    /* 같은 타입 채널이 공유하는 속성 */
    long  info_mask_shared_by_dir;     /* 같은 방향 채널이 공유하는 속성 */
    long  info_mask_shared_by_all;     /* 전체 장치가 공유하는 속성 */

    const struct iio_event_spec *event_spec;
    unsigned int                  num_event_specs;

    unsigned  modified:1;   /* channel2를 modifier로 사용 */
    unsigned  indexed:1;    /* 파일명에 채널 번호 포함 */
    unsigned  output:1;     /* 출력 채널 (DAC 등) */
    unsigned  differential:1;/* 차동 채널 */
};

커널 소스 분석: struct iio_info 주요 콜백

struct iio_info는 IIO 코어가 sysfs 읽기/쓰기, 이벤트 설정, 트리거 검증, 디버그 접근 시 호출하는 콜백 함수 포인터 테이블입니다. 드라이버는 이 구조체를 정적 상수로 정의하고 indio_dev->info에 연결합니다.

/* include/linux/iio/iio.h — struct iio_info 주요 콜백 (간략화) */
struct iio_info {
    /* ── 채널 값 읽기/쓰기 ── */
    int (*read_raw)(struct iio_dev *indio_dev,
                    struct iio_chan_spec const *chan,
                    int *val, int *val2, long mask);

    int (*write_raw)(struct iio_dev *indio_dev,
                     struct iio_chan_spec const *chan,
                     int val, int val2, long mask);

    int (*read_avail)(struct iio_dev *indio_dev,
                      struct iio_chan_spec const *chan,
                      const int **vals, int *type,
                      int *length, long mask);

    int (*write_raw_get_fmt)(struct iio_dev *indio_dev,
                            struct iio_chan_spec const *chan,
                            long mask);

    /* ── 이벤트 ── */
    int (*read_event_config)(struct iio_dev *indio_dev,
                            const struct iio_chan_spec *chan,
                            enum iio_event_type type,
                            enum iio_event_direction dir);

    int (*write_event_config)(struct iio_dev *indio_dev,
                             const struct iio_chan_spec *chan,
                             enum iio_event_type type,
                             enum iio_event_direction dir,
                             int state);

    int (*read_event_value)(struct iio_dev *indio_dev,
                           const struct iio_chan_spec *chan,
                           enum iio_event_type type,
                           enum iio_event_direction dir,
                           enum iio_event_info info,
                           int *val, int *val2);

    int (*write_event_value)(struct iio_dev *indio_dev,
                            const struct iio_chan_spec *chan,
                            enum iio_event_type type,
                            enum iio_event_direction dir,
                            enum iio_event_info info,
                            int val, int val2);

    /* ── 트리거/스캔/디버그 ── */
    int (*validate_trigger)(struct iio_dev *indio_dev,
                           struct iio_trigger *trig);

    int (*update_scan_mode)(struct iio_dev *indio_dev,
                           const unsigned long *scan_mask);

    int (*debugfs_reg_access)(struct iio_dev *indio_dev,
                             unsigned reg, unsigned writeval,
                             unsigned *readval);

    int (*read_label)(struct iio_dev *indio_dev,
                     struct iio_chan_spec const *chan,
                     char *label);
};

커널 소스 분석: iio_read_channel_raw() 데이터 경로

사용자 공간이 sysfs에서 in_voltage0_raw를 읽거나, 커널 내 다른 드라이버가 iio_read_channel_raw()를 호출할 때, 데이터는 하드웨어에서 최종 소비자까지 다음 경로를 따라 흐릅니다.

/* 경로 1: 사용자 공간 sysfs 읽기 (industrialio-core.c 간략화) */

/* cat /sys/bus/iio/.../in_voltage0_raw 시 호출되는 show 함수 */
static ssize_t iio_read_channel_info(struct device *dev, ...)
{
    struct iio_dev *indio_dev = dev_to_iio_dev(dev);
    struct iio_chan_spec *chan = ...;
    int val, val2;

    /* 드라이버의 read_raw() 콜백 호출 */
    ret = indio_dev->info->read_raw(indio_dev, chan, &val, &val2, mask);

    /* 반환 형식에 따라 문자열 변환 */
    return iio_format_value(buf, ret, 2, vals);
}

/* 경로 2: in-kernel consumer (industrialio-core.c 간략화) */
int iio_read_channel_raw(struct iio_channel *chan, int *val)
{
    struct iio_dev *indio_dev = chan->indio_dev;
    int val2;

    /* 동일한 read_raw() 콜백을 IIO_CHAN_INFO_RAW로 호출 */
    ret = indio_dev->info->read_raw(indio_dev, chan->channel,
                                     val, &val2, IIO_CHAN_INFO_RAW);
    return ret;
}

/* iio_read_channel_processed()는 추가로 scale/offset 변환을 적용 */
int iio_read_channel_processed(struct iio_channel *chan, int *val)
{
    /* 먼저 read_raw(PROCESSED)를 시도 */
    /* 실패하면 read_raw(RAW) + scale 변환을 코어가 수행 */
    ret = iio_channel_read(chan, val, NULL, IIO_CHAN_INFO_PROCESSED);
    if (ret == -EINVAL) {
        ret = iio_channel_read(chan, val, NULL, IIO_CHAN_INFO_RAW);
        if (!ret)
            ret = iio_convert_raw_to_processed(chan, *val, val, 1);
    }
    return ret;
}

커널 소스 분석: iio_triggered_buffer_setup() 내부

devm_iio_triggered_buffer_setup()은 IIO 드라이버에서 가장 많이 쓰이는 helper 중 하나입니다. 이 한 줄의 호출이 내부적으로 kfifo 버퍼 할당, pollfunc 등록, trigger consumer 연결을 모두 처리합니다. 커널 소스(drivers/iio/buffer/industrialio-triggered-buffer.c)를 따라가면 다음 단계로 분해됩니다.

/* drivers/iio/buffer/industrialio-triggered-buffer.c (간략화) */

int iio_triggered_buffer_setup_ext(struct iio_dev *indio_dev,
    irqreturn_t (*h)(int, void *),      /* top half: 보통 iio_pollfunc_store_time */
    irqreturn_t (*thread)(int, void *), /* bottom half: 드라이버 handler */
    enum iio_buffer_direction direction,
    const struct iio_buffer_setup_ops *setup_ops,
    const struct iio_dev_attr *ext_info)
{
    struct iio_buffer *buffer;

    /* 1단계: kfifo 기반 소프트웨어 버퍼 할당 */
    buffer = iio_kfifo_allocate();
    if (!buffer)
        return -ENOMEM;

    /* 2단계: pollfunc 할당 — top half + threaded handler 쌍 */
    indio_dev->pollfunc = iio_alloc_pollfunc(h, thread,
                                              IRQF_ONESHOT,
                                              indio_dev, "%s_consumer%d",
                                              ...);
    if (!indio_dev->pollfunc)
        goto error_kfifo_free;

    /* 3단계: setup_ops 연결 (preenable, postenable, predisable 등) */
    buffer->setup_ops = setup_ops;
    buffer->direction = direction;

    /* 4단계: 버퍼를 iio_dev에 연결 */
    ret = iio_device_attach_buffer(indio_dev, buffer);
    if (ret)
        goto error_pollfunc_free;

    return 0;

error_pollfunc_free:
    iio_dealloc_pollfunc(indio_dev->pollfunc);
error_kfifo_free:
    iio_kfifo_free(buffer);
    return ret;
}

커널 소스 분석: trigger handler 해부

triggered buffer의 threaded handler는 IIO 드라이버에서 실제 데이터가 하드웨어에서 버퍼로 전달되는 핵심 지점입니다. 실전 드라이버의 전형적인 패턴을 분석합니다.

/* 실전 패턴: 3축 가속도계 + 타임스탬프 trigger handler */

struct acme_state {
    struct regmap *regmap;
    /* 자연 정렬 보장을 위한 버퍼: s16[3] + padding + s64 timestamp */
    struct {
        __le16 channels[3];  /* accel X, Y, Z — 각 16비트 */
        s64 timestamp;        /* 8바이트 정렬 필요 */
    } __aligned(8) scan;       /* 컴파일러가 자연 정렬 보장 */
};

static irqreturn_t acme_trigger_handler(int irq, void *p)
{
    struct iio_poll_func *pf = p;
    struct iio_dev *indio_dev = pf->indio_dev;
    struct acme_state *st = iio_priv(indio_dev);
    int ret;

    /* 1. 활성 채널 데이터를 burst 읽기 */
    ret = regmap_bulk_read(st->regmap, ACME_REG_ACCEL_X_L,
                           st->scan.channels,
                           sizeof(st->scan.channels));
    if (ret)
        goto done;

    /* 2. 타임스탬프와 함께 kfifo에 push */
    iio_push_to_buffers_with_timestamp(indio_dev,
                                        &st->scan,
                                        pf->timestamp);

done:
    /* 3. trigger use-count 감소 → 다음 trigger 재활성화 */
    iio_trigger_notify_done(indio_dev->trig);
    return IRQ_HANDLED;
}

채널 타입 레퍼런스: IIO가 지원하는 모든 측정 종류

IIO 코어는 수십 가지 채널 타입을 정의하며, 각 타입은 sysfs 파일명의 접두사와 표준 단위를 결정합니다. 실무에서 자주 만나는 타입을 분류별로 정리합니다.

완전한 ADC 드라이버 예제

SPI 기반 12비트 ADC를 IIO 드라이버로 구현하는 완전한 예제입니다. 4채널 single-ended 입력, triggered buffer, sysfs 원샷 읽기를 모두 지원합니다.

#include <linux/spi/spi.h>
#include <linux/module.h>
#include <linux/iio/iio.h>
#include <linux/iio/sysfs.h>
#include <linux/iio/trigger_consumer.h>
#include <linux/iio/triggered_buffer.h>
#include <linux/regulator/consumer.h>

#define EXAMPLE_ADC_CHANNELS  4
#define EXAMPLE_ADC_BITS      12

struct example_adc {
    struct spi_device *spi;
    struct regulator *vref;
    struct mutex lock;
    /* 자연 정렬 scan 버퍼: u16[4] + s64 timestamp */
    struct {
        __be16 channels[EXAMPLE_ADC_CHANNELS];
        s64 timestamp;
    } __aligned(8) scan;
};

/* SPI를 통해 특정 채널의 ADC 값을 읽는 함수 */
static int example_adc_read_channel(
    struct example_adc *adc, int ch, int *val)
{
    u8 tx[3] = { 0x06 | (ch >> 2), (ch & 3) << 6, 0 };
    u8 rx[3] = {};
    struct spi_transfer xfer = {
        .tx_buf = tx, .rx_buf = rx, .len = 3,
    };
    int ret;

    ret = spi_sync_transfer(adc->spi, &xfer, 1);
    if (ret)
        return ret;

    *val = ((rx[1] & 0x0f) << 8) | rx[2];
    return 0;
}

static int example_adc_read_raw(
    struct iio_dev *indio_dev,
    const struct iio_chan_spec *chan,
    int *val, int *val2, long mask)
{
    struct example_adc *adc = iio_priv(indio_dev);
    int ret, uv;

    switch (mask) {
    case IIO_CHAN_INFO_RAW:
        ret = iio_device_claim_direct_mode(indio_dev);
        if (ret)
            return ret;

        mutex_lock(&adc->lock);
        ret = example_adc_read_channel(adc,
                                        chan->channel, val);
        mutex_unlock(&adc->lock);
        iio_device_release_direct_mode(indio_dev);

        return ret ? ret : IIO_VAL_INT;

    case IIO_CHAN_INFO_SCALE:
        /* scale = Vref / 2^12 (마이크로볼트 단위) */
        uv = regulator_get_voltage(adc->vref);
        if (uv < 0)
            return uv;
        *val = uv / 1000;
        *val2 = EXAMPLE_ADC_BITS;
        return IIO_VAL_FRACTIONAL_LOG2;
    }

    return -EINVAL;
}

static const struct iio_info example_adc_info = {
    .read_raw = example_adc_read_raw,
};

#define EXAMPLE_ADC_CHANNEL(idx)                    \
{                                                   \
    .type = IIO_VOLTAGE,                           \
    .indexed = 1,                                  \
    .channel = (idx),                               \
    .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),  \
    .info_mask_shared_by_type =                     \
        BIT(IIO_CHAN_INFO_SCALE),                   \
    .scan_index = (idx),                            \
    .scan_type = {                                  \
        .sign = 'u',                              \
        .realbits = 12,                             \
        .storagebits = 16,                          \
        .endianness = IIO_BE,                      \
    },                                              \
}

static const struct iio_chan_spec example_adc_channels[] = {
    EXAMPLE_ADC_CHANNEL(0),
    EXAMPLE_ADC_CHANNEL(1),
    EXAMPLE_ADC_CHANNEL(2),
    EXAMPLE_ADC_CHANNEL(3),
    IIO_CHAN_SOFT_TIMESTAMP(EXAMPLE_ADC_CHANNELS),
};

static irqreturn_t example_adc_trigger_handler(
    int irq, void *p)
{
    struct iio_poll_func *pf = p;
    struct iio_dev *indio_dev = pf->indio_dev;
    struct example_adc *adc = iio_priv(indio_dev);
    int val, bit, j = 0;

    mutex_lock(&adc->lock);

    /* 활성 채널만 읽어서 scan 버퍼에 채움 */
    iio_for_each_active_channel(indio_dev, bit) {
        if (example_adc_read_channel(adc, bit, &val))
            goto done;
        adc->scan.channels[j++] = cpu_to_be16(val);
    }

    iio_push_to_buffers_with_timestamp(indio_dev,
                                        &adc->scan,
                                        pf->timestamp);
done:
    mutex_unlock(&adc->lock);
    iio_trigger_notify_done(indio_dev->trig);
    return IRQ_HANDLED;
}

static int example_adc_probe(struct spi_device *spi)
{
    struct iio_dev *indio_dev;
    struct example_adc *adc;
    int ret;

    indio_dev = devm_iio_device_alloc(&spi->dev,
                                       sizeof(*adc));
    if (!indio_dev)
        return -ENOMEM;

    adc = iio_priv(indio_dev);
    adc->spi = spi;
    mutex_init(&adc->lock);

    adc->vref = devm_regulator_get(&spi->dev, "vref");
    if (IS_ERR(adc->vref))
        return PTR_ERR(adc->vref);

    ret = regulator_enable(adc->vref);
    if (ret)
        return ret;

    indio_dev->name = "example-adc";
    indio_dev->info = &example_adc_info;
    indio_dev->modes = INDIO_DIRECT_MODE;
    indio_dev->channels = example_adc_channels;
    indio_dev->num_channels =
        ARRAY_SIZE(example_adc_channels);

    ret = devm_iio_triggered_buffer_setup(&spi->dev,
        indio_dev, iio_pollfunc_store_time,
        example_adc_trigger_handler, NULL);
    if (ret)
        return ret;

    return devm_iio_device_register(&spi->dev, indio_dev);
}

static const struct of_device_id example_adc_of_match[] = {
    { .compatible = "example,adc12" },
    { },
};
MODULE_DEVICE_TABLE(of, example_adc_of_match);

static struct spi_driver example_adc_driver = {
    .driver = {
        .name = "example-adc",
        .of_match_table = example_adc_of_match,
    },
    .probe = example_adc_probe,
};
module_spi_driver(example_adc_driver);

MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("Example 12-bit SPI ADC IIO Driver");

가속도계/자이로 드라이버 패턴: 6축 IMU

6축 IMU(관성 측정 장치, Inertial Measurement Unit)는 가속도 3축과 각속도 3축을 동시에 제공하는 장치로, IIO 드라이버에서 가장 복잡한 패턴 중 하나입니다. 채널 modifier, 공유 속성, triggered buffer, 이벤트를 모두 활용합니다.

IMU 채널 정의 패턴

/* 6축 IMU 채널 정의: accel X/Y/Z + gyro X/Y/Z + timestamp */

#define IMU_ACCEL_CHAN(axis, idx)                     \
{                                                       \
    .type = IIO_ACCEL,                                \
    .modified = 1,                                    \
    .channel2 = IIO_MOD_##axis,                       \
    .info_mask_separate = BIT(IIO_CHAN_INFO_RAW) |    \
                          BIT(IIO_CHAN_INFO_CALIBBIAS),\
    .info_mask_shared_by_type =                         \
        BIT(IIO_CHAN_INFO_SCALE) |                      \
        BIT(IIO_CHAN_INFO_SAMP_FREQ),                  \
    .info_mask_shared_by_type_available =               \
        BIT(IIO_CHAN_INFO_SCALE) |                      \
        BIT(IIO_CHAN_INFO_SAMP_FREQ),                  \
    .scan_index = (idx),                                \
    .scan_type = {                                      \
        .sign = 's',                                  \
        .realbits = 16,                                 \
        .storagebits = 16,                              \
        .endianness = IIO_LE,                          \
    },                                                  \
    .event_spec = imu_accel_events,                     \
    .num_event_specs = ARRAY_SIZE(imu_accel_events),    \
}

#define IMU_GYRO_CHAN(axis, idx)                      \
{                                                       \
    .type = IIO_ANGL_VEL,                             \
    .modified = 1,                                    \
    .channel2 = IIO_MOD_##axis,                       \
    .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),     \
    .info_mask_shared_by_type =                         \
        BIT(IIO_CHAN_INFO_SCALE) |                      \
        BIT(IIO_CHAN_INFO_SAMP_FREQ),                  \
    .info_mask_shared_by_type_available =               \
        BIT(IIO_CHAN_INFO_SCALE) |                      \
        BIT(IIO_CHAN_INFO_SAMP_FREQ),                  \
    .scan_index = (idx),                                \
    .scan_type = {                                      \
        .sign = 's',                                  \
        .realbits = 16,                                 \
        .storagebits = 16,                              \
        .endianness = IIO_LE,                          \
    },                                                  \
}

static const struct iio_chan_spec imu_channels[] = {
    IMU_ACCEL_CHAN(X, 0),
    IMU_ACCEL_CHAN(Y, 1),
    IMU_ACCEL_CHAN(Z, 2),
    IMU_GYRO_CHAN(X, 3),
    IMU_GYRO_CHAN(Y, 4),
    IMU_GYRO_CHAN(Z, 5),
    IIO_CHAN_SOFT_TIMESTAMP(6),
};

read_avail() 구현: 허용 값 노출

/* ODR과 full-scale range의 허용 값 목록 */

static const int imu_accel_scale_avail[] = {
    0, 598,     /* +-2g: 0.000598 m/s^2 per LSB */
    0, 1196,    /* +-4g */
    0, 2392,    /* +-8g */
    0, 4785,    /* +-16g */
};

static const int imu_odr_avail[] = {
    12, 26, 52, 104, 208, 416, 833,
};

static int imu_read_avail(struct iio_dev *indio_dev,
    const struct iio_chan_spec *chan,
    const int **vals, int *type,
    int *length, long mask)
{
    switch (mask) {
    case IIO_CHAN_INFO_SCALE:
        if (chan->type == IIO_ACCEL) {
            *vals = imu_accel_scale_avail;
            *type = IIO_VAL_INT_PLUS_MICRO;
            *length = ARRAY_SIZE(imu_accel_scale_avail);
            return IIO_AVAIL_LIST;
        }
        break;

    case IIO_CHAN_INFO_SAMP_FREQ:
        *vals = imu_odr_avail;
        *type = IIO_VAL_INT;
        *length = ARRAY_SIZE(imu_odr_avail);
        return IIO_AVAIL_LIST;
    }

    return -EINVAL;
}

mount_matrix: 보드 장착 방향 보정

/* DT에서 mount-matrix를 읽어 ext_info로 노출 */

static const struct iio_mount_matrix *
imu_get_mount_matrix(const struct iio_dev *indio_dev,
                     const struct iio_chan_spec *chan)
{
    struct imu_state *st = iio_priv(indio_dev);
    return &st->orientation;
}

static const struct iio_chan_spec_ext_info imu_ext_info[] = {
    IIO_MOUNT_MATRIX(IIO_SHARED_BY_DIR, imu_get_mount_matrix),
    { },
};

/* probe에서 DT mount-matrix 파싱 */
iio_read_mount_matrix(&spi->dev, &st->orientation);

/* 사용자 공간에서 확인:
 * cat /sys/bus/iio/devices/iio:device0/in_accel_mount_matrix
 * 1, 0, 0; 0, 1, 0; 0, 0, 1
 */

IIO 소비자: 다른 서브시스템과의 연동

IIO의 in-kernel consumer API는 다양한 서브시스템에서 활용됩니다. 대표적인 연동 패턴을 정리합니다.

주요 소비자 패턴

power_supply 연동 예제

#include <linux/iio/consumer.h>
#include <linux/power_supply.h>

struct battery_gauge {
    struct iio_channel *voltage_chan;
    struct iio_channel *current_chan;
    struct iio_channel *temp_chan;
    struct power_supply *psy;
};

static int battery_get_voltage(struct battery_gauge *bg,
                               int *uv)
{
    int ret;

    /* IIO ADC에서 배터리 전압 읽기 (마이크로볼트) */
    ret = iio_read_channel_processed(bg->voltage_chan, uv);
    if (ret)
        return ret;

    /* voltage divider 보정 (1:2 분압) */
    *uv *= 2;

    return 0;
}

static int battery_get_temp(struct battery_gauge *bg,
                             int *temp)
{
    int raw, ret;

    /* NTC 서미스터 ADC 값 읽기 */
    ret = iio_read_channel_raw(bg->temp_chan, &raw);
    if (ret)
        return ret;

    /* ADC 코드를 온도로 변환 (보드별 NTC 특성 테이블) */
    *temp = ntc_adc_to_temp(raw);

    return 0;
}

static int battery_gauge_probe(struct platform_device *pdev)
{
    struct battery_gauge *bg;

    bg = devm_kzalloc(&pdev->dev, sizeof(*bg), GFP_KERNEL);
    if (!bg)
        return -ENOMEM;

    /* DT io-channel-names로 채널 획득 */
    bg->voltage_chan = devm_iio_channel_get(&pdev->dev,
                                            "battery_voltage");
    if (IS_ERR(bg->voltage_chan))
        return PTR_ERR(bg->voltage_chan);

    bg->temp_chan = devm_iio_channel_get(&pdev->dev,
                                         "battery_temp");
    if (IS_ERR(bg->temp_chan))
        return PTR_ERR(bg->temp_chan);

    /* power_supply 등록 ... */
    return 0;
}

/* Device Tree에서의 IIO consumer 연결 */
adc@48000000 {
    compatible = "ti,am3359-adc";
    #io-channel-cells = <1>;
};

battery-gauge {
    compatible = "vendor,battery-gauge";
    io-channels = <&adc 5>, <&adc 6>;
    io-channel-names = "battery_voltage", "battery_temp";
};

트리거 종류별 상세: hrtimer, sysfs, interrupt, data-ready

IIO trigger는 "샘플 캡처 시점을 결정하는 커널 객체"입니다. 실무에서 자주 쓰이는 trigger 종류를 비교합니다.

hrtimer 트리거 생성 (configfs)

# hrtimer trigger 생성
mkdir /config/iio/triggers/hrtimer/my_trigger

# trigger가 등록되었는지 확인
ls /sys/bus/iio/devices/trigger*
cat /sys/bus/iio/devices/trigger0/name

# 장치에 trigger 연결
echo "my_trigger" > /sys/bus/iio/devices/iio:device0/trigger/current_trigger

# sampling frequency 설정 (trigger가 아닌 장치 속성)
echo 100 > /sys/bus/iio/devices/trigger0/sampling_frequency

# 채널 활성화 + 버퍼 시작
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/scan_elements/in_voltage0_en
echo 64 > /sys/bus/iio/devices/iio:device0/buffer0/length
echo 1 > /sys/bus/iio/devices/iio:device0/buffer0/enable

자체 trigger 드라이버 등록

/* 장치가 자체 DRDY IRQ를 trigger로 등록하는 패턴 */

static int sensor_setup_trigger(struct iio_dev *indio_dev)
{
    struct sensor_state *st = iio_priv(indio_dev);
    struct iio_trigger *trig;
    int ret;

    trig = devm_iio_trigger_alloc(&st->spi->dev,
                                   "%s-drdy%d",
                                   indio_dev->name,
                                   iio_device_id(indio_dev));
    if (!trig)
        return -ENOMEM;

    /* DRDY IRQ를 trigger에 연결 */
    ret = devm_request_irq(&st->spi->dev,
                           st->irq,
                           iio_trigger_generic_data_rdy_poll,
                           IRQF_ONESHOT,
                           "sensor-drdy",
                           trig);
    if (ret)
        return ret;

    ret = devm_iio_trigger_register(&st->spi->dev, trig);
    if (ret)
        return ret;

    /* 자체 trigger만 허용하도록 설정 */
    iio_trigger_set_immutable(indio_dev, trig);
    indio_dev->trig = iio_trigger_get(trig);

    return 0;
}

이벤트 모니터링 실전: threshold 설정부터 userspace 수신까지

IIO 이벤트의 전체 흐름을 끝에서 끝까지 따라가 봅니다.

이벤트 흐름 전체

/* 드라이버: 이벤트 콜백 구현 */

static int sensor_write_event_config(
    struct iio_dev *indio_dev,
    const struct iio_chan_spec *chan,
    enum iio_event_type type,
    enum iio_event_direction dir,
    int state)
{
    struct sensor_state *st = iio_priv(indio_dev);
    u8 reg_val;

    /* 하드웨어 인터럽트 마스크 설정/해제 */
    regmap_read(st->regmap, SENSOR_INT_MASK, &reg_val);

    if (state)
        reg_val |= BIT(chan->scan_index);
    else
        reg_val &= ~BIT(chan->scan_index);

    return regmap_write(st->regmap, SENSOR_INT_MASK, reg_val);
}

static int sensor_write_event_value(
    struct iio_dev *indio_dev,
    const struct iio_chan_spec *chan,
    enum iio_event_type type,
    enum iio_event_direction dir,
    enum iio_event_info info,
    int val, int val2)
{
    struct sensor_state *st = iio_priv(indio_dev);

    switch (info) {
    case IIO_EV_INFO_VALUE:
        /* threshold 값을 하드웨어 레지스터에 쓰기 */
        return regmap_write(st->regmap,
                            dir == IIO_EV_DIR_RISING ?
                            SENSOR_THRESH_HIGH : SENSOR_THRESH_LOW,
                            val);
    case IIO_EV_INFO_HYSTERESIS:
        return regmap_write(st->regmap,
                            SENSOR_HYST, val);
    }
    return -EINVAL;
}

/* 이벤트 발생 시 IRQ handler에서 push */
static irqreturn_t sensor_event_handler(int irq, void *p)
{
    struct iio_dev *indio_dev = p;
    struct sensor_state *st = iio_priv(indio_dev);
    u8 status;

    regmap_read(st->regmap, SENSOR_INT_STATUS, &status);

    if (status & SENSOR_THRESH_HIGH_BIT)
        iio_push_event(indio_dev,
            IIO_UNMOD_EVENT_CODE(IIO_VOLTAGE, 0,
                                IIO_EV_TYPE_THRESH,
                                IIO_EV_DIR_RISING),
            iio_get_time_ns(indio_dev));

    /* status 클리어 */
    regmap_write(st->regmap, SENSOR_INT_STATUS, status);

    return IRQ_HANDLED;
}

사용자 공간에서 이벤트 수신

# 1. threshold 설정
echo 3000 > /sys/bus/iio/devices/iio:device0/events/in_voltage0_thresh_rising_value
echo 100 > /sys/bus/iio/devices/iio:device0/events/in_voltage0_thresh_rising_hysteresis

# 2. 이벤트 활성화
echo 1 > /sys/bus/iio/devices/iio:device0/events/in_voltage0_thresh_rising_en

# 3. 이벤트 모니터링
iio_event_monitor /dev/iio:device0

# 출력 예시:
# Event: time: 1234567890, type: voltage, channel: 0,
#        evtype: thresh, direction: rising

IIO API 레퍼런스 요약

Core API

Trigger API

Consumer API

관련 문서와 참고 자료

• hwmon — 느린 상태 관측과 IIO의 경계
• Device Tree — io-channels, 공급 전원, 인터럽트, mount matrix 바인딩
• I2C / SPI / GPIO — 센서가 붙는 물리 버스와 IRQ/DRDY 배선
• DMA Engine — 고속 샘플 수집의 DMA 경로
• Power Supply — IIO ADC 값을 상위 상태 모델에서 소비하는 대표 예
• Thermal Management — IIO 온도 센서와 thermal zone 연동
• NVMEM 프레임워크 — 센서 캘리브레이션(Calibration) 데이터 저장과 NVMEM 연동
• Linux Kernel IIO Core Documentation — IIO 서브시스템 핵심 API와 아키텍처를 설명합니다
• IIO Triggers Documentation — IIO 트리거 모델과 등록 API를 다룹니다
• IIO Triggered Buffers Documentation — triggered buffer 설정과 데이터 수집 흐름입니다
• IIO Buffer and scan_elements ABI — 버퍼 및 scan_elements sysfs 인터페이스 규격입니다
• Industrial IIO configfs support — configfs를 통한 소프트웨어 트리거 생성 방법입니다
• High-speed DMABUF interface for IIO — zero-copy 고속 데이터 수집을 위한 DMABUF API입니다
• IIO Interfacing Tools — iio_generic_buffer 등 사용자 공간 도구를 설명합니다
• drivers/iio/ (Bootlin Elixir) — IIO 드라이버 소스 코드를 온라인에서 탐색할 수 있습니다
• include/linux/iio/iio.h (Bootlin Elixir) — iio_dev, iio_chan_spec 구조체 정의를 확인할 수 있습니다
• LWN: The Industrial I/O subsystem — IIO 서브시스템의 설계 철학과 초기 아키텍처를 다룹니다
• LWN: High-speed IIO data acquisition — 고속 데이터 수집과 DMA 통합 전략을 설명합니다
• libiio (Analog Devices) — IIO 디바이스 접근을 위한 사용자 공간 라이브러리입니다