Documentation/driver-api/iio/buffers.rst GitHub 원문 ↗

Linux 6.18.37 · Driver API

Buffers

IIO continuous capture, buffer·scan_elements sysfs, scan type encoding과 driver channel setup을 설명합니다.

Source pathDocumentation/driver-api/iio/buffers.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

buffers.rst:1-126

IIO buffer는 trigger event마다 여러 channel sample을 정해진 scan_index 순서와 scan_type storage 형식으로 쌓아 character device에서 효율적으로 읽게 합니다. Driver와 userspace는 endian, signedness, valid bits, padding과 shift를 같은 방식으로 해석해야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 =======
2 Buffers
3 =======
4
5 * struct iio_buffer — general buffer structure
6 * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
7 is selected
8 * :c:func:`iio_buffer_get` — Grab a reference to the buffer
9 * :c:func:`iio_buffer_put` — Release the reference to the buffer
10
11 The Industrial I/O core offers a way for continuous data capture based on a
12 trigger source. Multiple data channels can be read at once from
13 :file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
14
15 IIO buffer sysfs interface
16 ==========================
17 An IIO buffer has an associated attributes directory under
18 :file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the
19 existing attributes:
20
21 * :file:`length`, the total number of data samples (capacity) that can be
22 stored by the buffer.
23 * :file:`enable`, activate buffer capture.
24
25 IIO buffer setup
26 ================
27
28 The meta information associated with a channel reading placed in a buffer is
29 called a scan element. The important bits configuring scan elements are
30 exposed to userspace applications via the
31 :file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This
32 directory contains attributes of the following form:
33
34 * :file:`enable`, used for enabling a channel. If and only if its attribute
35 is non *zero*, then a triggered capture will contain data samples for this
36 channel.
37 * :file:`index`, the scan_index of the channel.
38 * :file:`type`, description of the scan element data storage within the buffer
39 and hence the form in which it is read from user space.
40 Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] .
41
42 * *be* or *le*, specifies big or little endian.
43 * *s* or *u*, specifies if signed (2's complement) or unsigned.
44 * *bits*, is the number of valid data bits.
45 * *storagebits*, is the number of bits (after padding) that it occupies in the
46 buffer.
47 * *repeat*, specifies the number of bits/storagebits repetitions. When the
48 repeat element is 0 or 1, then the repeat value is omitted.
49 * *shift*, if specified, is the shift that needs to be applied prior to
50 masking out unused bits.
51
52 For example, a driver for a 3-axis accelerometer with 12 bit resolution where
53 data is stored in two 8-bits registers as follows::
54
55 7 6 5 4 3 2 1 0
56 +---+---+---+---+---+---+---+---+
57 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
58 +---+---+---+---+---+---+---+---+
59
60 7 6 5 4 3 2 1 0
61 +---+---+---+---+---+---+---+---+
62 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
63 +---+---+---+---+---+---+---+---+
64
65 will have the following scan element type for each axis::
66
67 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
68 le:s12/16>>4
69
70 A user space application will interpret data samples read from the buffer as
71 two byte little endian signed data, that needs a 4 bits right shift before
72 masking out the 12 valid bits of data.
73
74 For implementing buffer support a driver should initialize the following
75 fields in iio_chan_spec definition::
76
77 struct iio_chan_spec {
78 /* other members */
79 int scan_index
80 struct {
81 char sign;
82 u8 realbits;
83 u8 storagebits;
84 u8 shift;
85 u8 repeat;
86 enum iio_endian endianness;
87 } scan_type;
88 };
89
90 The driver implementing the accelerometer described above will have the
91 following channel definition::
92
93 struct iio_chan_spec accel_channels[] = {
94 {
95 .type = IIO_ACCEL,
96 .modified = 1,
97 .channel2 = IIO_MOD_X,
98 /* other stuff here */
99 .scan_index = 0,
100 .scan_type = {
101 .sign = 's',
102 .realbits = 12,
103 .storagebits = 16,
104 .shift = 4,
105 .endianness = IIO_LE,
106 },
107 }
108 /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
109 * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
110 */
111 }
112
113 Here **scan_index** defines the order in which the enabled channels are placed
114 inside the buffer. Channels with a lower **scan_index** will be placed before
115 channels with a higher index. Each channel needs to have a unique
116 **scan_index**.
117
118 Setting **scan_index** to -1 can be used to indicate that the specific channel
119 does not support buffered capture. In this case no entries will be created for
120 the channel in the scan_elements directory.
121
122 More details
123 ============
124 .. kernel-doc:: include/linux/iio/buffer.h
125 .. kernel-doc:: drivers/iio/industrialio-buffer.c
126 :export:
127

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

IIO buffer 개요

1-14

문서 제목은 `Buffers`입니다. `struct iio_buffer`는 일반 buffer 구조이고, `iio_validate_scan_mask_onehot`은 channel이 정확히 하나 선택됐는지 검증합니다. `iio_buffer_get`은 buffer reference를 얻고 `iio_buffer_put`은 그 reference를 해제합니다.

Industrial I/O core는 trigger source를 기반으로 continuous data capture를 제공합니다. `/dev/iio:device{X}` character device node에서 여러 data channel을 한꺼번에 읽을 수 있어 CPU load를 줄입니다.

IIO continuous capture
Trigger source eventIIO core가 capture 시작여러 channel sample을 buffer에 배치/dev/iio:device{X}에서 묶음 readPer-sample polling 감소CPU load 절감

Trigger에서 multi-channel userspace read까지의 경로입니다.

IIO buffer sysfs interface

15-24

IIO buffer의 attribute directory는 `/sys/bus/iio/devices/iio:device{X}/buffer/*` 아래에 있습니다. `length`는 buffer가 저장할 수 있는 data sample 총수, 즉 capacity이고 `enable`은 buffer capture를 활성화합니다.

Buffer sysfs attribute
Attribute의미
length저장 가능한 data sample 총수(capacity)
enableBuffer capture 활성화

Capacity와 capture 활성화를 제어합니다.

Scan element 설정

25-51

Buffer에 놓이는 channel reading의 meta information을 scan element라고 합니다. Scan element를 구성하는 핵심 bit는 userspace에 `/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory로 노출됩니다.

`enable` 값이 0이 아닐 때에만 triggered capture에 해당 channel sample이 포함됩니다. `index`는 channel의 `scan_index`이고, `type`은 buffer 내부 storage와 userspace에서 읽는 data 형식을 설명합니다.

`type` 형식은 `[be|le]:[s|u]bits/storagebits[Xrepeat][>>shift]`입니다. `be`·`le`은 big endian·little endian, `s`·`u`는 signed 2's complement·unsigned, `bits`는 유효 data bit 수, `storagebits`는 padding 뒤 buffer에서 차지하는 bit 수입니다.

`repeat`는 bits/storagebits 반복 횟수이며 값이 0 또는 1이면 생략합니다. `shift`가 있으면 쓰지 않는 bit를 masking하기 전에 적용할 shift입니다.

Scan element type 형식
Token의미
be | leBig endian | little endian
s | uSigned 2's complement | unsigned
bits유효 data bit 수
storagebitsPadding 포함 buffer 점유 bit 수
Xrepeat반복 횟수, 0·1이면 생략
>>shiftMask 전에 적용할 right shift

각 token이 buffer sample 해석에 주는 의미입니다.

12-bit accelerometer 예제

52-72

예제는 resolution 12-bit인 3-axis accelerometer가 data를 두 8-bit register에 저장하는 경우입니다. 원문의 register ASCII diagram은 아래에 그대로 보존하고 같은 내용을 bit-field 표로 다시 구성했습니다.

  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
+---+---+---+---+---+---+---+---+

  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
+---+---+---+---+---+---+---+---+
Accelerometer register bit 배치
RegisterAddressbit 7..4bit 3..0
LOW byte0x06D3 D2 D1 D0X X X X
HIGH byte0x07D11 D10 D9 D8D7 D6 D5 D4

LOW·HIGH byte의 address와 유효 bit를 구조화했습니다.

각 axis의 scan element type은 다음과 같습니다.

$ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
le:s12/16>>4

Userspace application은 buffer sample을 two-byte little-endian signed data로 해석하고, 유효한 12 data bit를 masking하기 전에 4-bit right shift해야 합니다.

le:s12/16>>4 해석
2-byte little endian readSigned 16-bit storage로 결합4-bit right shift하위 12 valid bits mask12-bit 2's-complement 값 해석

Raw 16-bit storage에서 signed 12-bit 값을 얻는 순서입니다.

Driver buffer channel 정의

73-120

Buffer support를 구현하려면 driver가 `iio_chan_spec` 정의의 `scan_index`와 `scan_type` field를 초기화해야 합니다. `scan_type`에는 `sign`, `realbits`, `storagebits`, `shift`, `repeat`, `endianness`가 있습니다.

struct iio_chan_spec {
/* other members */
        int scan_index
        struct {
                char sign;
                u8 realbits;
                u8 storagebits;
                u8 shift;
                u8 repeat;
                enum iio_endian endianness;
               } scan_type;
       };

앞의 accelerometer를 구현하는 channel definition은 각 axis를 signed 12-bit data, 16-bit storage, shift 4, little endian으로 선언합니다.

struct iio_chan_spec accel_channels[] = {
        {
                .type = IIO_ACCEL,
                .modified = 1,
                .channel2 = IIO_MOD_X,
                /* other stuff here */
                .scan_index = 0,
                .scan_type = {
                        .sign = 's',
                        .realbits = 12,
                        .storagebits = 16,
                        .shift = 4,
                        .endianness = IIO_LE,
                },
        }
        /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
         * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
         */
 }

`scan_index`는 enable된 channel이 buffer 안에 놓이는 순서를 정의합니다. 값이 낮은 channel이 높은 channel보다 먼저 놓이며 각 channel의 `scan_index`는 unique해야 합니다.

`scan_index = -1`은 해당 channel이 buffered capture를 지원하지 않음을 나타냅니다. 이 경우 그 channel의 entry는 `scan_elements` directory에 생성되지 않습니다.

scan_type field
Field예제 값역할
signsSigned data
realbits12유효 data bit
storagebits16Buffer 점유 bit
shift4Mask 전 shift
repeat생략Element 반복
endiannessIIO_LELittle endian

Channel storage 형식을 만드는 driver field입니다.

scan_index 규칙
값·관계동작
낮은 indexBuffer에서 먼저 배치
높은 index낮은 index 뒤에 배치
동일 index허용되지 않음, channel마다 unique
-1Buffered capture 미지원, scan_elements entry 없음

Buffer 배치 순서와 비지원 channel 표시입니다.

Buffer kernel API source

121-126

Buffer structure와 core API의 kernel-doc source는 `include/linux/iio/buffer.h`와 `drivers/iio/industrialio-buffer.c`입니다. 두 번째 source는 exported symbol을 문서화합니다.

.. kernel-doc:: include/linux/iio/buffer.h
.. kernel-doc:: drivers/iio/industrialio-buffer.c
   :export:
IIO buffer kernel-doc source
범위Source path
Buffer declarationinclude/linux/iio/buffer.h
Exported buffer coredrivers/iio/industrialio-buffer.c

Declaration과 exported implementation을 구분합니다.