Core elements

Industrial I/O core

문서 제목은 `Core elements`입니다. Industrial I/O core는 여러 종류의 embedded sensor driver를 작성하는 unified framework와 sensor를 조작하는 userspace application용 standard interface를 함께 제공합니다. 구현은 `drivers/iio/industrialio-*` 아래에 있습니다.

IIO device lifecycle

`struct iio_dev`는 industrial I/O device입니다. Driver는 `iio_device_alloc()`으로 할당하고 `iio_device_free()`로 해제하며, `iio_device_register()`로 IIO subsystem에 등록하고 `iio_device_unregister()`로 등록을 해제합니다.

IIO device는 보통 hardware sensor 하나에 대응하며 device를 다루는 driver에 필요한 모든 정보를 제공합니다.

Userspace application이 IIO driver와 상호작용하는 방법은 두 가지입니다. `/sys/bus/iio/devices/iio:device{X}/`는 hardware sensor를 나타내고 같은 chip의 data channel을 묶습니다. `/dev/iio:device{X}` character device node는 buffered data transfer와 event information retrieval에 사용합니다.

일반적인 IIO driver는 I2C 또는 SPI driver로 등록하고 `probe`와 `remove` routine을 만듭니다. Probe에서는 `iio_device_alloc()`으로 memory를 할당하고 device name·channel 같은 driver-specific field를 초기화한 뒤 `iio_device_register()`를 호출합니다. 이 호출 뒤 device가 userspace request를 받을 수 있습니다.

Remove에서는 probe의 역순으로 resource를 해제합니다. 먼저 `iio_device_unregister()`로 IIO core 등록을 해제하고 `iio_device_free()`로 device memory를 해제합니다.

IIO device sysfs interface

Sysfs attribute는 chip information을 노출하고 application이 configuration parameter를 설정하게 하는 file입니다. Index X인 device의 attribute는 `/sys/bus/iio/devices/iio:deviceX/` 아래에 있습니다.

일반 attribute에는 physical chip 설명인 `name`, `/dev/iio:deviceX` node의 `major:minor` pair를 보여 주는 `dev`, device가 지원하는 discrete sampling frequency 집합인 `sampling_frequency_available`이 있습니다. IIO standard attribute 전체는 kernel source의 `Documentation/ABI/testing/sysfs-bus-iio`에 설명됩니다.

IIO channel과 iio_chan_spec

`struct iio_chan_spec`은 single channel specification입니다. IIO device channel은 data channel 하나를 표현하며 device에는 channel이 하나 또는 여러 개 있을 수 있습니다.

Thermometer는 temperature measurement channel 하나, light sensor는 visible·infrared spectrum channel 두 개, accelerometer는 X·Y·Z acceleration channel을 최대 세 개 가질 수 있습니다.

IIO channel은 `struct iio_chan_spec`으로 설명합니다. 예제 thermometer는 `IIO_TEMP` type이고 `IIO_CHAN_INFO_PROCESSED`를 channel-specific processed attribute로 노출합니다.

static const struct iio_chan_spec temp_channel[] = {
     {
         .type = IIO_TEMP,
         .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
     },
};

Channel attribute mask와 식별

Userspace에 노출하는 channel sysfs attribute는 bitmask로 지정합니다. Shared 범위에 따라 `info_mask_separate`는 특정 channel만, `info_mask_shared_by_type`은 같은 type의 모든 channel, `info_mask_shared_by_dir`은 같은 direction의 모든 channel, `info_mask_shared_by_all`은 모든 channel이 공유합니다.

한 channel type에 data channel이 여러 개면 두 방식으로 구분합니다. 첫째, `iio_chan_spec.modified = 1`로 두고 같은 structure의 `.channel2`에 modifier를 지정합니다. Modifier는 direction이나 spectral response처럼 물리적으로 unique한 특성을 나타냅니다. 예를 들어 light sensor는 infrared channel과 infrared+visible channel을 둘 수 있습니다.

둘째, `iio_chan_spec.indexed = 1`로 두고 `.channel` field에 index를 지정합니다. 이 경우 channel은 단순히 index가 다른 instance입니다.

Channel modifier와 생성 attribute

예제 light sensor는 `IIO_INTENSITY` channel 두 개에 `IIO_MOD_LIGHT_IR`와 `IIO_MOD_LIGHT_BOTH` modifier를 적용하고 raw data를 channel별로, sampling frequency를 공유 attribute로 노출합니다. 별도의 `IIO_LIGHT` channel은 processed illuminance 값을 노출합니다.

static const struct iio_chan_spec light_channels[] = {
        {
                .type = IIO_INTENSITY,
                .modified = 1,
                .channel2 = IIO_MOD_LIGHT_IR,
                .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
                .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
        },
        {
                .type = IIO_INTENSITY,
                .modified = 1,
                .channel2 = IIO_MOD_LIGHT_BOTH,
                .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
                .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
        },
        {
                .type = IIO_LIGHT,
                .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
                .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
        },
   }

이 정의는 raw data용 `/sys/bus/iio/devices/iio:device{X}/in_intensity_ir_raw`와 `in_intensity_both_raw`, processed data용 `in_illuminance_input`, 공유 sampling frequency용 `sampling_frequency` file을 생성합니다.

Indexed channel과 생성 attribute

Channel indexing 예제는 `IIO_VOLTAGE` type 두 channel에 `.indexed = 1`을 설정하고 `.channel`을 0과 1로 지정합니다.

static const struct iio_chan_spec light_channels[] = {
        {
                .type = IIO_VOLTAGE,
                .indexed = 1,
                .channel = 0,
                .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
        },
        {
                .type = IIO_VOLTAGE,
                .indexed = 1,
                .channel = 1,
                .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
        },
}

그 결과 `/sys/bus/iio/devices/iio:device{X}/in_voltage0_raw`는 channel 0 voltage measurement를, `in_voltage1_raw`는 channel 1 measurement를 나타냅니다.

IIO core kernel API source

IIO public core declaration은 `include/linux/iio/iio.h`, exported core implementation은 `drivers/iio/industrialio-core.c`의 kernel-doc에서 가져옵니다.

.. kernel-doc:: include/linux/iio/iio.h
.. kernel-doc:: drivers/iio/industrialio-core.c
   :export: