요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
=============================
4
Industrial IIO device buffers
5
=============================
7
1. Overview
8
===========
10
The Industrial I/O core offers a way for continuous data capture based on a
11
trigger source. Multiple data channels can be read at once from
12
``/dev/iio:deviceX`` character device node, thus reducing the CPU load.
14
Devices with buffer support feature an additional sub-directory in the
15
``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where
16
Y defaults to 0, for devices with a single buffer.
18
2. Buffer attributes
19
====================
21
An IIO buffer has an associated attributes directory under
22
``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below.
24
``length``
25
----------
27
Read / Write attribute which states the total number of data samples (capacity)
28
that can be stored by the buffer.
30
``enable``
31
----------
33
Read / Write attribute which starts / stops the buffer capture. This file should
34
be written last, after length and selection of scan elements. Writing a non-zero
35
value may result in an error, such as EINVAL, if, for example, an unsupported
36
combination of channels is given.
38
``watermark``
39
-------------
41
Read / Write positive integer attribute specifying the maximum number of scan
42
elements to wait for.
44
Poll will block until the watermark is reached.
46
Blocking read will wait until the minimum between the requested read amount or
47
the low watermark is available.
49
Non-blocking read will retrieve the available samples from the buffer even if
50
there are less samples than the watermark level. This allows the application to
51
block on poll with a timeout and read the available samples after the timeout
52
expires and thus have a maximum delay guarantee.
54
Data available
55
--------------
57
Read-only attribute indicating the bytes of data available in the buffer. In the
58
case of an output buffer, this indicates the amount of empty space available to
59
write data to. In the case of an input buffer, this indicates the amount of data
60
available for reading.
62
Scan elements
63
-------------
65
The meta information associated with a channel data placed in a buffer is called
66
a scan element. The scan elements attributes are presented below.
68
**_en**
70
Read / Write attribute used for enabling a channel. If and only if its value
71
is non-zero, then a triggered capture will contain data samples for this
72
channel.
74
**_index**
76
Read-only unsigned integer attribute specifying the position of the channel in
77
the buffer. Note these are not dependent on what is enabled and may not be
78
contiguous. Thus for userspace to establish the full layout these must be used
79
in conjunction with all _en attributes to establish which channels are present,
80
and the relevant _type attributes to establish the data storage format.
82
**_type**
84
Read-only attribute containing the description of the scan element data storage
85
within the buffer and hence the form in which it is read from userspace. Format
86
is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where:
88
- **be** or **le** specifies big or little-endian.
89
- **s** or **u** specifies if signed (2's complement) or unsigned.
90
- **bits** is the number of valid data bits.
91
- **storagebits** is the number of bits (after padding) that it occupies in the
92
buffer.
93
- **repeat** specifies the number of bits/storagebits repetitions. When the
94
repeat element is 0 or 1, then the repeat value is omitted.
95
- **shift** if specified, is the shift that needs to be applied prior to
96
masking out unused bits.
98
For example, a driver for a 3-axis accelerometer with 12-bit resolution where
99
data is stored in two 8-bit registers is as follows::
101
7 6 5 4 3 2 1 0
102
+---+---+---+---+---+---+---+---+
103
|D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
104
+---+---+---+---+---+---+---+---+
106
7 6 5 4 3 2 1 0
107
+---+---+---+---+---+---+---+---+
108
|D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
109
+---+---+---+---+---+---+---+---+
111
will have the following scan element type for each axis:
113
.. code-block:: bash
115
$ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
116
le:s12/16>>4
118
A userspace application will interpret data samples read from the buffer as
119
two-byte little-endian signed data, that needs a 4 bits right shift before
120
masking out the 12 valid bits of data.
122
It is also worth mentioning that the data in the buffer will be naturally
123
aligned, so the userspace application has to handle the buffers accordingly.
125
Take for example, a driver with four channels with the following description:
126
- channel0: index: 0, type: be:u16/16>>0
127
- channel1: index: 1, type: be:u32/32>>0
128
- channel2: index: 2, type: be:u32/32>>0
129
- channel3: index: 3, type: be:u64/64>>0
131
If all channels are enabled, the data will be aligned in the buffer as follows::
133
0-1 2 3 4-7 8-11 12 13 14 15 16-23 -> buffer byte number
134
+-----+---+---+-----+-----+---+---+---+---+-----+
135
|CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
136
+-----+---+---+-----+-----+---+---+---+---+-----+
138
If only channel0 and channel3 are enabled, the data will be aligned in the
139
buffer as follows::
141
0-1 2 3 4 5 6 7 8-15 -> buffer byte number
142
+-----+---+---+---+---+---+---+-----+
143
|CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
144
+-----+---+---+---+---+---+---+-----+
146
Typically the buffered data is found in raw format (unscaled with no offset
147
applied), however there are corner cases in which the buffered data may be found
148
in a processed form. Please note that these corner cases are not addressed by
149
this documentation.
151
Please see Documentation/ABI/testing/sysfs-bus-iio for a complete
152
description of the attributes.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Trigger 기반 연속 캡처와 장치 경로
1-17이 문서는 GPL-2.0 라이선스가 적용되는 Industrial IIO 장치 버퍼 설명서입니다.
Industrial I/O core는 trigger source를 기반으로 데이터를 연속 캡처하는 방법을 제공합니다. 여러 데이터 채널을 `/dev/iio:deviceX` 문자 장치 노드에서 한 번에 읽어 CPU 부하를 줄일 수 있습니다.
버퍼를 지원하는 장치에는 `/sys/bus/iio/devices/iio:deviceX/` 계층 아래에 `bufferY`라는 추가 하위 디렉터리가 있습니다. 버퍼가 하나인 장치에서 Y의 기본값은 0입니다.
Trigger source가 캡처 시작→활성 scan element의 채널 값 수집→`bufferY`에 샘플 저장→`/dev/iio:deviceX` 문자 장치로 노출→사용자 공간이 여러 채널을 한 번에 읽음
Trigger 발생에서 사용자 공간 다중 채널 읽기까지의 흐름입니다.
용도경로
Buffer attributes`/sys/bus/iio/devices/iio:deviceX/bufferY/`
기본 단일 buffer`buffer0`
Buffered data`/dev/iio:deviceX`
Sysfs 설정 경로와 문자 장치 데이터 경로를 구분합니다.
.. SPDX-License-Identifier: GPL-2.0
=============================
Industrial IIO device buffers
=============================
1. Overview
===========
The Industrial I/O core offers a way for continuous data capture based on a
trigger source. Multiple data channels can be read at once from
``/dev/iio:deviceX`` character device node, thus reducing the CPU load.
Devices with buffer support feature an additional sub-directory in the
``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where
Y defaults to 0, for devices with a single buffer.
Length·enable·watermark·data available
18-60IIO 버퍼에는 원문이 제시한 `/sys/bus/iio/iio:deviceX/bufferY/` 아래에 연관된 속성 디렉터리가 있습니다.
속성접근설명
`length`Read / Write버퍼가 저장할 수 있는 전체 데이터 샘플 수, 즉 capacity
`enable`Read / Write버퍼 캡처 시작·중지
`watermark`Read / Write positive integer기다릴 scan element의 최대 수
Data availableRead-only입력 데이터 양 또는 출력 버퍼의 빈 공간(byte)
용량·캡처·대기·가용량 속성의 접근 방식과 의미입니다.
`length`는 버퍼에 저장할 수 있는 전체 데이터 샘플 수인 용량을 나타냅니다.
`enable`은 버퍼 캡처를 시작하거나 중지합니다. `length`와 scan element 선택을 끝낸 뒤 마지막에 써야 합니다. 지원하지 않는 채널 조합을 지정한 경우처럼 0이 아닌 값을 쓰면 `EINVAL` 같은 오류가 발생할 수 있습니다.
`watermark`는 기다릴 scan element의 최대 수를 지정하는 양의 정수입니다. `poll`은 watermark에 도달할 때까지 차단됩니다.
Blocking read는 요청한 읽기 양과 low watermark 가운데 더 작은 양이 준비될 때까지 기다립니다.
Non-blocking read는 watermark보다 샘플이 적어도 버퍼에서 사용 가능한 샘플을 가져옵니다. 따라서 응용 프로그램은 timeout을 둔 `poll`에서 대기하고 timeout 뒤 사용 가능한 샘플을 읽어 최대 지연을 보장할 수 있습니다.
Data available은 버퍼에서 사용 가능한 데이터 byte 수를 나타내는 read-only 속성입니다. 출력 버퍼에서는 데이터를 쓸 수 있는 빈 공간의 양을, 입력 버퍼에서는 읽을 수 있는 데이터의 양을 나타냅니다.
사용할 scan elements 선택→`length`로 capacity 설정→`watermark`로 대기 수준 설정→`enable`에 0이 아닌 값 쓰기→`poll` 또는 blocking/non-blocking read 수행
`enable`을 마지막에 써야 하는 설정 순서입니다.
호출동작
`poll`Watermark 도달까지 block
Blocking readmin(requested amount, low watermark) 준비까지 대기
Non-blocking readWatermark 미만이어도 현재 샘플 반환
`poll` + timeoutTimeout 뒤 가용 샘플을 읽어 최대 지연 보장
Poll과 두 read 모드의 대기 조건을 비교합니다.
2. Buffer attributes
====================
An IIO buffer has an associated attributes directory under
``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below.
``length``
----------
Read / Write attribute which states the total number of data samples (capacity)
that can be stored by the buffer.
``enable``
----------
Read / Write attribute which starts / stops the buffer capture. This file should
be written last, after length and selection of scan elements. Writing a non-zero
value may result in an error, such as EINVAL, if, for example, an unsupported
combination of channels is given.
``watermark``
-------------
Read / Write positive integer attribute specifying the maximum number of scan
elements to wait for.
Poll will block until the watermark is reached.
Blocking read will wait until the minimum between the requested read amount or
the low watermark is available.
Non-blocking read will retrieve the available samples from the buffer even if
there are less samples than the watermark level. This allows the application to
block on poll with a timeout and read the available samples after the timeout
expires and thus have a maximum delay guarantee.
Data available
--------------
Read-only attribute indicating the bytes of data available in the buffer. In the
case of an output buffer, this indicates the amount of empty space available to
write data to. In the case of an input buffer, this indicates the amount of data
available for reading.Scan element 선택·순서·저장 형식
61-97버퍼에 놓이는 채널 데이터와 연관된 메타데이터를 scan element라고 합니다.
속성접근의미
`_en`Read / Write0이 아니면 triggered capture에 채널 샘플 포함
`_index`Read-only unsigned integer버퍼 안의 채널 위치
`_type`Read-only버퍼 저장 형식과 사용자 공간 읽기 형식
채널 포함 여부, 위치, 저장 형식을 결정하는 세 속성입니다.
`_en` 값이 0이 아닐 때에만 triggered capture에 해당 채널의 데이터 샘플이 포함됩니다.
`_index`는 활성화 여부와 무관하고 연속적이지 않을 수 있습니다. 사용자 공간이 전체 layout을 정하려면 모든 `_en` 속성으로 존재하는 채널을 판별하고 관련 `_type` 속성으로 저장 형식을 판별하면서 `_index`를 함께 사용해야 합니다.
`_type`의 형식은 `[be|le]:[s|u]bits/storagebits[Xrepeat][>>shift]`입니다.
요소의미
`be` / `le`Big-endian / little-endian
`s` / `u`Signed 2's complement / unsigned
`bits`유효 데이터 bit 수
`storagebits`Padding 뒤 버퍼에서 차지하는 bit 수
`repeat`bits/storagebits 반복 수, 0 또는 1이면 생략
`shift`사용하지 않는 bit를 mask하기 전에 적용할 shift
형식 문자열의 각 구성요소를 원문 정의대로 풀이합니다.
모든 채널의 `_en` 확인→활성 채널의 `_index` 수집→Index 순서로 채널 배치→각 `_type`에서 endian·sign·bits·storagebits 읽기→Shift와 mask를 적용해 유효 값 복원
세 scan 속성을 결합해 버퍼 레코드를 해석합니다.
Scan elements
-------------
The meta information associated with a channel data placed in a buffer is called
a scan element. The scan elements attributes are presented below.
**_en**
Read / Write attribute used for enabling a channel. If and only if its value
is non-zero, then a triggered capture will contain data samples for this
channel.
**_index**
Read-only unsigned integer attribute specifying the position of the channel in
the buffer. Note these are not dependent on what is enabled and may not be
contiguous. Thus for userspace to establish the full layout these must be used
in conjunction with all _en attributes to establish which channels are present,
and the relevant _type attributes to establish the data storage format.
**_type**
Read-only attribute containing the description of the scan element data storage
within the buffer and hence the form in which it is read from userspace. Format
is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where:
- **be** or **le** specifies big or little-endian.
- **s** or **u** specifies if signed (2's complement) or unsigned.
- **bits** is the number of valid data bits.
- **storagebits** is the number of bits (after padding) that it occupies in the
buffer.
- **repeat** specifies the number of bits/storagebits repetitions. When the
repeat element is 0 or 1, then the repeat value is omitted.
- **shift** if specified, is the shift that needs to be applied prior to
masking out unused bits.
12비트 가속도 샘플 저장 예제
98-124예제는 12비트 해상도의 3축 가속도계가 데이터를 두 개의 8비트 레지스터에 저장하는 경우입니다.
레지스터주소bit 7bit 6bit 5bit 4bit 3bit 2bit 1bit 0
LOW byte`0x06`D3D2D1D0XXXX
HIGH byte`0x07`D11D10D9D8D7D6D5D4
원문의 LOW/HIGH byte ASCII 비트 그림을 동일한 bit 위치 표로 재구성했습니다.
각 축의 scan element type은 `le:s12/16>>4`입니다.
$ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
le:s12/16>>4사용자 공간 응용 프로그램은 버퍼에서 읽은 샘플을 2바이트 little-endian signed 데이터로 해석해야 합니다. 사용하지 않는 bit를 mask해 12개의 유효 데이터 bit를 얻기 전에 4비트 right shift를 적용합니다.
2바이트 little-endian 값 읽기→16비트 signed 저장값으로 결합→오른쪽으로 4비트 shift→12개의 유효 bit mask→2's complement 부호 해석
두 레지스터의 raw bytes에서 12비트 signed 값을 복원하는 순서입니다.
버퍼 데이터는 자연 정렬되므로 사용자 공간 응용 프로그램은 그에 맞게 버퍼를 처리해야 합니다.
For example, a driver for a 3-axis accelerometer with 12-bit resolution where
data is stored in two 8-bit registers is as follows::
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)
+---+---+---+---+---+---+---+---+
will have the following scan element type for each axis:
.. code-block:: bash
$ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
le:s12/16>>4
A userspace application will interpret data samples read from the buffer as
two-byte little-endian signed data, that needs a 4 bits right shift before
masking out the 12 valid bits of data.
It is also worth mentioning that the data in the buffer will be naturally
aligned, so the userspace application has to handle the buffers accordingly.
다중 채널 자연 정렬과 raw 데이터
125-152정렬 예제의 네 채널은 channel0 `index: 0, type: be:u16/16>>0`, channel1 `index: 1, type: be:u32/32>>0`, channel2 `index: 2, type: be:u32/32>>0`, channel3 `index: 3, type: be:u64/64>>0`입니다.
채널IndexType크기
channel00`be:u16/16>>0`2 bytes
channel11`be:u32/32>>0`4 bytes
channel22`be:u32/32>>0`4 bytes
channel33`be:u64/64>>0`8 bytes
자연 정렬 예제에 쓰이는 index와 type입니다.
Buffer bytes내용이유
0-1CHN_016-bit channel0
2-3PADChannel1 4-byte alignment
4-7CHN_132-bit channel1
8-11CHN_232-bit channel2
12-15PADChannel3 8-byte alignment
16-23CHN_364-bit channel3
원문의 0..23 byte ASCII 배치를 범위별로 재구성했습니다.
모든 채널을 활성화하면 channel0 뒤와 channel3 앞에 자연 정렬을 위한 padding이 들어가 전체 레코드가 24바이트가 됩니다.
Buffer bytes내용이유
0-1CHN_016-bit channel0
2-7PADChannel3 8-byte alignment
8-15CHN_364-bit channel3
원문의 0..15 byte ASCII 배치를 범위별로 재구성했습니다.
Channel0과 channel3만 활성화하면 2-7번 byte가 padding이 되어 channel3이 8번 byte에서 시작하며 전체 레코드는 16바이트입니다.
활성 `_en` 채널을 index 순으로 정렬→각 채널의 storagebits와 alignment 확인→필요한 PAD bytes 삽입→채널 데이터를 자연 경계에 배치→전체 record stride로 다음 샘플 이동
활성 채널 집합에 따라 padding이 달라지는 과정입니다.
일반적으로 버퍼 데이터는 scale이나 offset을 적용하지 않은 raw 형식입니다. 다만 일부 예외에서는 처리된 형식으로 들어올 수 있으며 이 문서는 그런 예외를 다루지 않습니다.
속성 전체 설명은 `Documentation/ABI/testing/sysfs-bus-iio`를 참고합니다.
Take for example, a driver with four channels with the following description:
- channel0: index: 0, type: be:u16/16>>0
- channel1: index: 1, type: be:u32/32>>0
- channel2: index: 2, type: be:u32/32>>0
- channel3: index: 3, type: be:u64/64>>0
If all channels are enabled, the data will be aligned in the buffer as follows::
0-1 2 3 4-7 8-11 12 13 14 15 16-23 -> buffer byte number
+-----+---+---+-----+-----+---+---+---+---+-----+
|CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
+-----+---+---+-----+-----+---+---+---+---+-----+
If only channel0 and channel3 are enabled, the data will be aligned in the
buffer as follows::
0-1 2 3 4 5 6 7 8-15 -> buffer byte number
+-----+---+---+---+---+---+---+-----+
|CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3| -> buffer content
+-----+---+---+---+---+---+---+-----+
Typically the buffered data is found in raw format (unscaled with no offset
applied), however there are corner cases in which the buffered data may be found
in a processed form. Please note that these corner cases are not addressed by
this documentation.
Please see Documentation/ABI/testing/sysfs-bus-iio for a complete
description of the attributes.
요약·해설
iio_devbuf.rst:1-152IIO device buffer는 trigger 기반 다중 채널 캡처를 문자 장치로 제공합니다. 사용자 공간은 `_en`, `_index`, `_type`을 결합해 record layout을 만들고 endian·sign·shift·mask와 자연 정렬 padding을 반영해 샘플을 해석해야 합니다.
원문 분량과 핵심 인터페이스를 요약합니다.
구성과 데이터 처리 순서를 압축합니다.