요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=================
Linux I2C and DMA
=================
Given that I2C is a low-speed bus, over which the majority of messages
transferred are small, it is not considered a prime user of DMA access. At this
time of writing, only 10% of I2C bus master drivers have DMA support
implemented. And the vast majority of transactions are so small that setting up
DMA for it will likely add more overhead than a plain PIO transfer.
Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
It does not seem reasonable to apply additional burdens when the feature is so
rarely used. However, it is recommended to use a DMA-safe buffer if your
message size is likely applicable for DMA. Most drivers have this threshold
around 8 bytes (as of today, this is mostly an educated guess, however). For
any message of 16 byte or larger, it is probably a really good idea. Please
note that other subsystems you use might add requirements. E.g., if your
I2C bus master driver is using USB as a bridge, then you need to have DMA
safe buffers always, because USB requires it.
Clients
-------
For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
flag with it. Then, the I2C core and drivers know they can safely operate DMA
on it. Note that using this flag is optional. I2C host drivers which are not
updated to use this flag will work like before. And like before, they risk
using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
more and more clients and host drivers is the planned way forward. Note also
that setting this flag makes only sense in kernel space. User space data is
copied into kernel space anyhow. The I2C core makes sure the destination
buffers in kernel space are always DMA capable. Also, when the core emulates
SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
know their buffers are DMA safe. Users of i2c_transfer() must set the
I2C_M_DMA_SAFE flag manually.
Masters
-------
Bus master drivers wishing to implement safe DMA can use helper functions from
the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
certain threshold is met::
dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);
If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
bounce buffer. But you don't need to care about that detail, just use the
returned buffer. If NULL is returned, the threshold was not met or a bounce
buffer could not be allocated. Fall back to PIO in that case.
In any case, a buffer obtained from above needs to be released. Another helper
function ensures a potentially used bounce buffer is freed::
i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);
The last argument 'xferred' controls if the buffer is synced back to the
message or not. No syncing is needed in cases setting up DMA had an error and
there was no data transferred.
The bounce buffer handling from the core is generic and simple. It will always
allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
reusing pre-allocated buffers), you are free to implement your own.
Please also check the in-kernel documentation for details. The i2c-sh_mobile
driver can be used as a reference example how to use the above helpers.
Final note: If you plan to use DMA with I2C (or with anything else, actually)
make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
you find various issues which can be complex to debug otherwise.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
I2C에서 DMA가 선택적인 이유
1-20I2C는 저속 버스이고 대부분의 메시지가 작으므로 DMA의 주된 사용처로 보지 않습니다. 문서 작성 당시 I2C 버스 마스터 드라이버 가운데 DMA를 구현한 것은 10%뿐입니다. 대부분의 트랜잭션은 매우 작아서 DMA 준비 비용이 일반 PIO 전송보다 클 가능성이 높습니다.
따라서 I2C 메시지 버퍼가 DMA-safe일 의무는 없습니다. 드물게 쓰는 기능 때문에 모든 사용자에게 부담을 추가하는 것은 합리적이지 않습니다.
그러나 메시지 크기가 DMA 적용 대상일 가능성이 크다면 DMA-safe 버퍼를 권장합니다. 대부분의 드라이버 임계값은 약 8바이트이지만 이는 대체로 경험적 추정입니다. 16바이트 이상 메시지에는 DMA-safe 버퍼를 사용하는 것이 매우 좋습니다.
함께 사용하는 다른 하위 시스템이 추가 요구를 둘 수 있습니다. 예를 들어 I2C 버스 마스터가 USB를 브리지로 사용하면 USB 요구사항 때문에 항상 DMA-safe 버퍼가 필요합니다.
메시지 크기와 하위 시스템에 따른 권장 수준입니다.
메시지 크기와 브리지 요구를 함께 고려합니다.
=================
Linux I2C and DMA
=================
Given that I2C is a low-speed bus, over which the majority of messages
transferred are small, it is not considered a prime user of DMA access. At this
time of writing, only 10% of I2C bus master drivers have DMA support
implemented. And the vast majority of transactions are so small that setting up
DMA for it will likely add more overhead than a plain PIO transfer.
Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
It does not seem reasonable to apply additional burdens when the feature is so
rarely used. However, it is recommended to use a DMA-safe buffer if your
message size is likely applicable for DMA. Most drivers have this threshold
around 8 bytes (as of today, this is mostly an educated guess, however). For
any message of 16 byte or larger, it is probably a really good idea. Please
note that other subsystems you use might add requirements. E.g., if your
I2C bus master driver is using USB as a bridge, then you need to have DMA
safe buffers always, because USB requires it.
I2C 클라이언트의 DMA-safe 표시
21-38클라이언트가 `i2c_msg`에 DMA-safe 버퍼를 사용한다면 `I2C_M_DMA_SAFE` 플래그를 설정하십시오. 그러면 I2C core와 드라이버가 해당 버퍼에 DMA를 안전하게 수행할 수 있음을 압니다.
플래그 사용은 선택 사항입니다. 아직 플래그를 사용하도록 갱신되지 않은 호스트 드라이버도 이전처럼 동작하지만, 이전과 마찬가지로 안전하지 않은 DMA 버퍼를 사용할 위험이 있습니다. 더 많은 클라이언트와 호스트 드라이버가 `I2C_M_DMA_SAFE`를 사용하도록 확대하는 것이 계획입니다.
이 플래그는 커널 공간에서만 의미가 있습니다. 사용자 공간 데이터는 어차피 커널 공간으로 복사되며 I2C core는 목적지 버퍼가 항상 DMA 가능하도록 보장합니다. core가 SMBus 트랜잭션을 I2C로 에뮬레이션할 때도 block transfer 버퍼는 DMA-safe입니다.
버퍼가 DMA-safe임을 아는 `i2c_master_send()`와 `i2c_master_recv()` 사용자는 각각 `i2c_master_send_dmasafe()`와 `i2c_master_recv_dmasafe()`를 사용할 수 있습니다. `i2c_transfer()` 사용자는 `I2C_M_DMA_SAFE`를 직접 설정해야 합니다.
호출 방식별 플래그와 helper 사용법입니다.
버퍼 소유자가 안전성을 표시하고 core가 호스트에 전달합니다.
Clients
-------
For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
flag with it. Then, the I2C core and drivers know they can safely operate DMA
on it. Note that using this flag is optional. I2C host drivers which are not
updated to use this flag will work like before. And like before, they risk
using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
more and more clients and host drivers is the planned way forward. Note also
that setting this flag makes only sense in kernel space. User space data is
copied into kernel space anyhow. The I2C core makes sure the destination
buffers in kernel space are always DMA capable. Also, when the core emulates
SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
know their buffers are DMA safe. Users of i2c_transfer() must set the
I2C_M_DMA_SAFE flag manually.
버스 마스터용 DMA helper
39-71안전한 DMA를 구현하려는 버스 마스터 드라이버는 I2C core helper를 사용할 수 있습니다. `i2c_get_dma_safe_msg_buf(msg, threshold_in_byte)`는 지정한 임계값을 충족하는 `i2c_msg`에 대해 DMA-safe 버퍼를 제공합니다.
버퍼가 반환되면 `I2C_M_DMA_SAFE`인 경우의 `msg->buf`이거나 bounce buffer입니다. 드라이버는 구분할 필요 없이 반환된 버퍼를 사용하면 됩니다. NULL이면 임계값을 충족하지 못했거나 bounce buffer 할당에 실패한 것이므로 PIO로 대체합니다.
얻은 버퍼는 어떤 경우든 해제해야 합니다. `i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred)`는 잠재적으로 사용된 bounce buffer를 해제합니다.
마지막 인자 `xferred`는 버퍼를 메시지로 다시 동기화할지 결정합니다. DMA 설정 중 오류가 나 실제 데이터 전송이 없었다면 동기화할 필요가 없습니다.
core의 bounce buffer 처리는 범용적이고 단순하며 매번 새 bounce buffer를 할당합니다. 미리 할당한 버퍼 재사용 같은 고급 처리가 필요하면 드라이버가 자체 구현할 수 있습니다.
자세한 내용은 커널 내부 문서를 확인하십시오. `i2c-sh_mobile` 드라이버가 이 helper의 참조 예제입니다.
I2C 또는 다른 장치에서 DMA를 사용할 계획이라면 개발 중 `CONFIG_DMA_API_DEBUG`를 반드시 켜십시오. 그렇지 않으면 디버깅하기 복잡한 여러 문제를 찾는 데 도움이 됩니다.
획득·대체·해제와 동기화 규칙입니다.
획득한 버퍼는 성공·실패와 관계없이 helper로 반환합니다.
Masters
-------
Bus master drivers wishing to implement safe DMA can use helper functions from
the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
certain threshold is met::
dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);
If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
bounce buffer. But you don't need to care about that detail, just use the
returned buffer. If NULL is returned, the threshold was not met or a bounce
buffer could not be allocated. Fall back to PIO in that case.
In any case, a buffer obtained from above needs to be released. Another helper
function ensures a potentially used bounce buffer is freed::
i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);
The last argument 'xferred' controls if the buffer is synced back to the
message or not. No syncing is needed in cases setting up DMA had an error and
there was no data transferred.
The bounce buffer handling from the core is generic and simple. It will always
allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
reusing pre-allocated buffers), you are free to implement your own.
Please also check the in-kernel documentation for details. The i2c-sh_mobile
driver can be used as a reference example how to use the above helpers.
Final note: If you plan to use DMA with I2C (or with anything else, actually)
make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
you find various issues which can be complex to debug otherwise.
요약·해설
dma-considerations.rst:1-71작은 I2C 메시지는 PIO가 보통 유리하지만 DMA를 쓸 때는 클라이언트가 안전성을 표시하고 마스터가 core helper로 버퍼를 획득·반환해야 합니다.
원문 분량과 핵심 기능을 요약합니다.
호출 또는 판단의 핵심 순서입니다.