요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
===================================
High-speed DMABUF interface for IIO
===================================
1. Overview
===========
The Industrial I/O subsystem supports access to buffers through a
file-based interface, with read() and write() access calls through the
IIO device's dev node.
It additionally supports a DMABUF based interface, where the userspace
can attach DMABUF objects (externally created) to an IIO buffer, and
subsequently use them for data transfers.
A userspace application can then use this interface to share DMABUF
objects between several interfaces, allowing it to transfer data in a
zero-copy fashion, for instance between IIO and the USB stack.
The userspace application can also memory-map the DMABUF objects, and
access the sample data directly. The advantage of doing this vs. the
read() interface is that it avoids an extra copy of the data between the
kernel and userspace. This is particularly useful for high-speed devices
which produce several megabytes or even gigabytes of data per second.
It does however increase the userspace-kernelspace synchronization
overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to
be used for data integrity.
2. User API
===========
As part of this interface, three new IOCTLs have been added. These three
IOCTLs have to be performed on the IIO buffer's file descriptor, which
can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.
``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)``
Attach the DMABUF object, identified by its file descriptor, to the
IIO buffer. Returns zero on success, and a negative errno value on
error.
``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)``
Detach the given DMABUF object, identified by its file descriptor,
from the IIO buffer. Returns zero on success, and a negative errno
value on error.
Note that closing the IIO buffer's file descriptor will
automatically detach all previously attached DMABUF objects.
``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``
Enqueue a previously attached DMABUF object to the buffer queue.
Enqueued DMABUFs will be read from (if output buffer) or written to
(if input buffer) as long as the buffer is enabled.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
고속 IIO DMA-BUF 인터페이스
1-30이 문서는 GPL-2.0 라이선스가 적용되는 IIO 고속 DMA-BUF 인터페이스 설명서입니다.
Industrial I/O 하위 시스템은 IIO 장치의 dev node에서 `read()`와 `write()`를 호출하는 파일 기반 인터페이스로 버퍼에 접근할 수 있습니다.
또한 사용자 공간이 외부에서 만든 DMA-BUF 객체를 IIO 버퍼에 연결하고 이후 데이터 전송에 사용하는 DMA-BUF 기반 인터페이스도 지원합니다.
응용 프로그램은 여러 인터페이스 사이에서 DMA-BUF 객체를 공유할 수 있습니다. 예를 들어 IIO와 USB stack 사이에서 데이터를 zero-copy 방식으로 전송할 수 있습니다.
사용자 공간은 DMA-BUF 객체를 memory-map하고 샘플 데이터에 직접 접근할 수도 있습니다. `read()` 인터페이스와 비교하면 kernel과 userspace 사이의 추가 데이터 복사를 피할 수 있다는 장점이 있습니다.
이 방식은 초당 수 megabytes에서 수 gigabytes의 데이터를 만드는 고속 장치에 특히 유용합니다.
반면 데이터 무결성을 위해 `DMA_BUF_SYNC_START`와 `DMA_BUF_SYNC_END` IOCTL을 사용해야 하므로 userspace와 kernelspace 사이의 동기화 overhead가 증가합니다.
파일 기반 read/write와 DMA-BUF 경로의 장단점을 비교합니다.
외부 버퍼 생성부터 여러 하위 시스템의 공유 전송까지의 흐름입니다.
.. SPDX-License-Identifier: GPL-2.0
===================================
High-speed DMABUF interface for IIO
===================================
1. Overview
===========
The Industrial I/O subsystem supports access to buffers through a
file-based interface, with read() and write() access calls through the
IIO device's dev node.
It additionally supports a DMABUF based interface, where the userspace
can attach DMABUF objects (externally created) to an IIO buffer, and
subsequently use them for data transfers.
A userspace application can then use this interface to share DMABUF
objects between several interfaces, allowing it to transfer data in a
zero-copy fashion, for instance between IIO and the USB stack.
The userspace application can also memory-map the DMABUF objects, and
access the sample data directly. The advantage of doing this vs. the
read() interface is that it avoids an extra copy of the data between the
kernel and userspace. This is particularly useful for high-speed devices
which produce several megabytes or even gigabytes of data per second.
It does however increase the userspace-kernelspace synchronization
overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to
be used for data integrity.
DMA-BUF 사용자 API와 세 IOCTL
31-54이 인터페이스에는 세 개의 새 IOCTL이 추가되었습니다. 모두 IIO buffer file descriptor에 대해 실행해야 하며, 이 descriptor는 `IIO_BUFFER_GET_FD_IOCTL()` ioctl로 얻을 수 있습니다.
세 사용자 API의 인자, 동작, 반환 규칙을 정리했습니다.
`IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)`는 file descriptor로 식별한 DMA-BUF 객체를 IIO 버퍼에 연결합니다. 성공하면 0, 오류이면 음수 errno 값을 반환합니다.
`IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)`는 file descriptor로 식별한 DMA-BUF 객체를 IIO 버퍼에서 분리합니다. 성공하면 0, 오류이면 음수 errno 값을 반환합니다.
IIO buffer의 file descriptor를 닫으면 이전에 연결한 모든 DMA-BUF 객체가 자동으로 분리됩니다.
`IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)`는 이전에 연결한 DMA-BUF 객체를 buffer queue에 넣습니다. 버퍼가 활성화되어 있는 동안 output buffer이면 enqueue한 DMA-BUF에서 읽고, input buffer이면 DMA-BUF에 씁니다.
IIO 버퍼 방향에 따른 DMA-BUF 접근을 원문 그대로 구분합니다.
IIO buffer file descriptor를 중심으로 한 API 순서입니다.
2. User API
===========
As part of this interface, three new IOCTLs have been added. These three
IOCTLs have to be performed on the IIO buffer's file descriptor, which
can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.
``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)``
Attach the DMABUF object, identified by its file descriptor, to the
IIO buffer. Returns zero on success, and a negative errno value on
error.
``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)``
Detach the given DMABUF object, identified by its file descriptor,
from the IIO buffer. Returns zero on success, and a negative errno
value on error.
Note that closing the IIO buffer's file descriptor will
automatically detach all previously attached DMABUF objects.
``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``
Enqueue a previously attached DMABUF object to the buffer queue.
Enqueued DMABUFs will be read from (if output buffer) or written to
(if input buffer) as long as the buffer is enabled.
요약·해설
iio_dmabuf_api.rst:1-54IIO DMA-BUF 인터페이스는 외부 버퍼를 IIO에 연결해 여러 하위 시스템과 zero-copy로 공유합니다. 고속 전송에 유리하지만 mmap 접근에서는 동기화 IOCTL이 필요하며, attach·enqueue·detach 순서와 buffer 방향별 데이터 이동을 지켜야 합니다.
원문 분량과 핵심 대상을 요약합니다.
사용 순서를 압축합니다.