Dynamic DMA mapping Guide

Dynamic DMA mapping 안내서

Dynamic DMA mapping Guide (동적 DMA mapping 안내서)

저자는 David S. Miller <davem@redhat.com>, Richard Henderson <rth@cygnus.com>, Jakub Jelinek <jakub@redhat.com>입니다.

이 문서는 device driver 작성자가 DMA API를 사용하는 방법을 예제 pseudo-code와 함께 설명합니다. API의 간결한 설명은 `Documentation/core-api/dma-api.rst`를 참고하십시오.

CPU 주소와 DMA 주소

CPU 주소와 DMA 주소

DMA API에는 여러 종류의 주소가 관여하므로 그 차이를 이해하는 것이 중요합니다.

Kernel은 보통 virtual address를 사용합니다. `kmalloc()`, `vmalloc()` 및 비슷한 interface가 반환한 주소는 virtual address이며 `void *`에 저장할 수 있습니다.

Virtual memory system인 TLB와 page table 등은 virtual address를 CPU physical address로 변환합니다. CPU physical address는 `phys_addr_t` 또는 `resource_size_t`에 저장됩니다. Kernel은 register 같은 device resource를 physical address로 관리하고 `/proc/iomem`에 노출합니다. Physical address는 driver가 직접 사용할 수 없으므로 `ioremap()`으로 공간을 mapping해 virtual address를 만들어야 합니다.

I/O device는 세 번째 종류인 bus address를 사용합니다. Device의 register가 MMIO address에 있거나 device가 DMA로 system memory를 읽고 쓸 때 사용하는 주소가 bus address입니다. 일부 시스템에서는 bus address와 CPU physical address가 같지만 일반적으로는 다르며, IOMMU와 host bridge가 둘 사이에 임의의 mapping을 만들 수 있습니다.

Device 관점에서 DMA는 bus address space를 사용하지만 그 일부로 제한될 수 있습니다. 예를 들어 main memory와 PCI BAR가 64-bit address를 지원해도 IOMMU를 사용하면 device는 32-bit DMA address만 다루면 됩니다.

Enumeration 과정에서 kernel은 I/O device, MMIO space, 시스템에 연결하는 host bridge를 파악합니다. PCI device에 BAR가 있으면 kernel은 BAR의 bus address A를 읽어 CPU physical address B로 변환합니다. B는 `struct resource`에 저장되고 보통 `/proc/iomem`에 표시됩니다. Driver가 device를 점유하면 `ioremap()`으로 B를 virtual address C에 mapping하고, 예를 들어 `ioread32(C)`로 bus address A의 register에 접근합니다.

Device가 DMA를 지원하면 driver는 `kmalloc()` 같은 interface로 virtual address X를 반환받아 buffer를 준비합니다. Virtual memory system은 X를 system RAM의 physical address Y로 mapping합니다. Driver는 X로 buffer에 접근하지만 DMA는 CPU virtual memory system을 통과하지 않으므로 device는 X를 사용할 수 없습니다.

단순한 시스템에서는 device가 Y에 직접 DMA할 수 있습니다. 많은 시스템에서는 IOMMU가 DMA address를 physical address로 변환하며, 예를 들어 Z를 Y로 mapping합니다. 이것이 DMA API가 필요한 이유입니다. Driver가 virtual address X를 `dma_map_single()` 같은 interface에 주면 필요한 IOMMU mapping을 만들고 DMA address Z를 반환합니다. Driver는 device에 Z로 DMA하도록 지시하고 IOMMU는 이를 system RAM의 Y buffer로 연결합니다.

Linux의 dynamic DMA mapping을 사용하려면 driver가 DMA address를 실제 사용하는 동안에만 mapping하고 DMA transfer 뒤에는 unmap해야 합니다. 아래 API는 이런 hardware가 없는 platform에서도 동작합니다.

DMA API는 microprocessor architecture와 무관하게 모든 bus에서 동작합니다. Bus 전용 DMA API인 `pci_map_*()` 대신 `dma_map_*()` interface를 사용해야 합니다.

먼저 driver에 다음 header가 포함되어 있는지 확인합니다.

#include <linux/dma-mapping.h>

이 header는 `dma_addr_t`를 정의합니다. 이 type은 platform에서 유효한 모든 DMA address를 담을 수 있으므로 DMA mapping function이 반환한 DMA address를 보관하는 모든 곳에서 사용해야 합니다.

DMA에 사용할 수 있는 메모리

어떤 메모리를 DMA에 사용할 수 있는가?

먼저 DMA mapping 기능에 사용할 수 있는 kernel memory를 알아야 합니다. 과거에는 기록되지 않은 규칙이었으며 이 절에서 이를 명문화합니다.

Page allocator인 `__get_free_page*()` 또는 generic memory allocator인 `kmalloc()`, `kmem_cache_alloc()`으로 얻은 메모리는 해당 routine이 반환한 주소로 DMA 송수신에 사용할 수 있습니다.

`vmalloc()`이 반환한 메모리나 주소는 DMA에 사용할 수 없습니다. `vmalloc()` 영역에 mapping된 실제 하부 메모리에 DMA하는 것은 가능하지만, page table을 순회해 physical address를 얻고 각 page를 `__va()` 같은 방법으로 다시 kernel address로 변환해야 합니다. 원문의 편집 메모리는 Gerd Knorr의 generic code가 통합되면 이 설명을 갱신하라고 적고 있습니다.

Kernel image의 data/text/bss segment 주소, module image 주소, stack 주소 역시 DMA에 사용할 수 없습니다. 이들은 나머지 physical memory와 완전히 다른 곳에 mapping될 수 있습니다. 물리적으로 DMA가 가능하더라도 I/O buffer를 cacheline에 맞춰 정렬해야 합니다. 그렇지 않으면 DMA-incoherent cache를 쓰는 CPU에서 cacheline sharing으로 data corruption이 생길 수 있습니다. CPU와 DMA가 같은 cache line의 서로 다른 word를 쓰면 둘 중 하나가 덮어써질 수 있습니다.

`kmap()` 반환값도 DMA 송수신에 사용할 수 없습니다. 이는 `vmalloc()`과 같은 종류의 제약입니다.

Block I/O와 networking subsystem은 자신들이 제공하는 buffer가 DMA 송수신에 유효하도록 보장합니다.

DMA 주소 지정 능력과 mask 설정

DMA 주소 지정 능력

기본적으로 kernel은 device가 32-bit DMA address를 지정할 수 있다고 가정합니다. 64-bit device는 범위를 늘려야 하고 제약이 있는 device는 줄여야 합니다.

PCI에 관한 특별한 주의 사항으로, PCI-X 명세는 PCI-X device가 모든 transaction에서 64-bit addressing인 DAC를 지원하도록 요구합니다. 적어도 SGI SN2 platform은 I/O bus가 PCI-X mode일 때 올바르게 동작하려면 64-bit coherent allocation이 필요합니다.

올바른 동작을 위해 DMA mask를 설정하여 device의 DMA addressing capability를 kernel에 알려야 합니다. Streaming과 coherent API의 mask를 함께 설정하려면 다음을 호출합니다.

int dma_set_mask_and_coherent(struct device *dev, u64 mask);

특별한 요구가 있으면 두 API를 나누어 설정할 수 있습니다. Streaming mapping에는 다음을 사용합니다.

int dma_set_mask(struct device *dev, u64 mask);

Coherent allocation에는 다음을 사용합니다.

int dma_set_coherent_mask(struct device *dev, u64 mask);

`dev`는 device의 `struct device` pointer이고 `mask`는 device가 지원하는 address bit를 나타내는 bit mask입니다. `struct device`는 보통 bus 전용 device structure 안에 들어 있습니다. 예를 들어 PCI device structure pointer가 `pdev`라면 `&pdev->dev`가 해당 device structure의 pointer입니다.

이 함수들은 주어진 address mask로 해당 시스템에서 DMA를 올바르게 수행할 수 있으면 보통 0을 반환합니다. Mask가 시스템에서 지원하기에 너무 작으면 오류를 반환할 수 있습니다. 0이 아니면 이 platform에서 DMA를 수행할 수 없고 시도 결과는 undefined behavior입니다. `dma_set_mask` 계열이 성공하기 전에는 해당 device에서 DMA를 사용하면 안 됩니다.

실패하면 가능한 선택은 두 가지입니다.

• 가능하다면 data transfer에 DMA가 아닌 mode를 사용합니다.
• 해당 device를 무시하고 초기화하지 않습니다.

DMA mask 설정 실패 시 driver가 kernel `KERN_WARNING` message를 출력하는 것이 좋습니다. 사용자가 성능 저하나 device 미검출을 보고할 때 kernel message를 통해 정확한 원인을 확인할 수 있습니다.

DMA mask 설정 예제와 다기능 device

24-bit addressing device는 다음처럼 설정합니다.

if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(24))) {
        dev_warn(dev, "mydev: No suitable DMA available\n");
        goto ignore_this_device;
}

표준 64-bit addressing device는 다음과 같이 설정합니다.

dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))

`dma_set_mask_and_coherent()`는 `DMA_BIT_MASK(64)`에서 실패를 반환하지 않습니다. 따라서 다음과 같은 fallback code는 잘못되었습니다.

/* Wrong code */
if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)))
        dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))

`dma_set_mask_and_coherent()`는 32-bit보다 큰 mask에서 실패하지 않으므로 device의 capability를 알고 다음과 같이 선택하는 것이 권장됩니다.

/* Recommended code */
if (support_64bit)
        dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64));
else
        dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32));

Device가 coherent allocation의 descriptor에는 32-bit addressing만 지원하지만 streaming mapping에는 전체 64-bit를 지원한다면 streaming mask를 다음처럼 설정합니다.

if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
        dev_warn(dev, "mydev: No suitable DMA available\n");
        goto ignore_this_device;
}

Coherent mask는 항상 streaming mask와 같거나 더 작은 mask로 설정할 수 있습니다. 드물게 coherent allocation만 사용하는 driver라면 `dma_set_coherent_mask()`의 반환값을 검사해야 합니다.

Device가 주소의 낮은 24-bit만 구동한다면 다음처럼 설정합니다.

if (dma_set_mask(dev, DMA_BIT_MASK(24))) {
        dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
        goto ignore_this_device;
}

`dma_set_mask()` 또는 `dma_set_mask_and_coherent()`가 성공해 0을 반환하면 kernel은 제공된 mask를 저장하고 이후 DMA mapping을 만들 때 사용합니다.

Sound card의 playback과 record처럼 여러 기능의 DMA addressing limit가 서로 다르면 각 mask를 probe하고 시스템이 처리할 수 있는 기능만 제공할 수 있습니다. 마지막 `dma_set_mask()` 호출에는 가장 구체적인 mask를 사용해야 합니다.

다음 pseudo-code가 그 방법을 보여 줍니다.

#define PLAYBACK_ADDRESS_BITS        DMA_BIT_MASK(32)
#define RECORD_ADDRESS_BITS        DMA_BIT_MASK(24)

struct my_sound_card *card;
struct device *dev;

...
if (!dma_set_mask(dev, PLAYBACK_ADDRESS_BITS)) {
        card->playback_enabled = 1;
} else {
        card->playback_enabled = 0;
        dev_warn(dev, "%s: Playback disabled due to DMA limitations\n",
               card->name);
}
if (!dma_set_mask(dev, RECORD_ADDRESS_BITS)) {
        card->record_enabled = 1;
} else {
        card->record_enabled = 0;
        dev_warn(dev, "%s: Record disabled due to DMA limitations\n",
               card->name);
}

Sound card를 예로 든 이유는 이런 PCI device에 PCI front end를 붙인 ISA chip이 흔하여 ISA의 16MB DMA addressing limit를 그대로 유지하는 경우가 많기 때문입니다.

Coherent와 streaming DMA mapping

DMA mapping의 종류

DMA mapping은 `Coherent DMA mappings`와 `Streaming DMA mappings` 두 종류입니다.

Coherent DMA mapping은 보통 driver initialization 때 mapping하고 종료 때 unmap합니다. Hardware는 device와 CPU가 data에 병렬로 접근하면서 명시적인 software flush 없이도 서로의 update를 볼 수 있도록 보장해야 합니다. `coherent`를 `synchronous`로 이해하면 됩니다.

현재 기본값은 DMA space의 낮은 32-bit에서 coherent memory를 반환하는 것입니다. Driver가 이 기본값으로 충분하더라도 향후 호환성을 위해 coherent mask를 설정해야 합니다.

Coherent mapping의 좋은 사용 예는 다음과 같습니다.

• Network card DMA ring descriptor
• SCSI adapter mailbox command data structure
• Main memory에서 실행되는 device firmware microcode

이 예들의 공통 불변 조건은 CPU의 memory store가 device에 즉시 보이고 그 반대도 성립해야 한다는 것입니다. Coherent mapping이 이를 보장합니다.

desc->word0 = address;
wmb();
desc->word1 = DESC_VALID;

이렇게 해야 모든 platform에서 올바르게 동작합니다. 일부 platform에서는 PCI bridge의 write buffer를 flush하듯 register를 쓴 뒤 값을 읽는 방식 등으로 CPU write buffer도 flush해야 할 수 있습니다.

Streaming DMA mapping은 보통 한 번의 DMA transfer를 위해 mapping하고 직후 unmap합니다. 아래의 `dma_sync_*`를 쓰는 경우는 예외입니다. Hardware는 sequential access에 맞게 최적화할 수 있습니다. `streaming`을 `asynchronous` 또는 `coherency domain 밖`으로 이해하면 됩니다.

Streaming mapping의 좋은 사용 예는 다음과 같습니다.

• Device가 송수신하는 networking buffer
• SCSI device가 읽고 쓰는 filesystem buffer

Streaming interface는 구현이 hardware가 허용하는 모든 성능 최적화를 할 수 있도록 설계되었습니다. 따라서 사용자는 원하는 동작을 명시해야 합니다.

두 종류 모두 하부 bus에서 비롯된 alignment 제한은 없지만 device 자체의 제한은 있을 수 있습니다. DMA-coherent가 아닌 cache를 쓰는 시스템에서는 buffer가 다른 data와 cache line을 공유하지 않을 때 더 잘 동작합니다.

Coherent DMA mapping 사용법

Coherent DMA mapping 사용

`PAGE_SIZE` 정도의 큰 coherent DMA region을 allocate하고 mapping하려면 다음과 같이 합니다.

dma_addr_t dma_handle;

cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, gfp);

`dev`는 `struct device *`입니다. `GFP_ATOMIC` flag를 사용하면 interrupt context에서 호출할 수 있습니다. `size`는 allocate할 region의 byte 길이입니다.

이 routine은 해당 region의 RAM을 allocate하므로 page order 대신 size를 받는 `__get_free_pages()`와 비슷합니다. 한 page보다 작은 region이 필요하면 아래의 `dma_pool` interface가 더 적합할 수 있습니다.

Coherent DMA mapping interface는 기본적으로 32-bit로 address 가능한 DMA address를 반환합니다. Device가 DMA mask로 상위 32-bit 접근을 표시해도 `dma_set_coherent_mask()`로 coherent DMA mask를 명시적으로 바꾼 경우에만 32-bit보다 큰 DMA address를 반환합니다. `dma_pool`에도 같은 규칙이 적용됩니다.

`dma_alloc_coherent()`는 CPU에서 접근할 virtual address와 card에 전달할 `dma_handle` 두 값을 반환합니다.

CPU virtual address와 DMA address는 모두 요청 size 이상인 가장 작은 `PAGE_SIZE` order에 맞춰 정렬됩니다. 예를 들어 64KB 이하 chunk를 allocate하면 반환된 buffer 범위가 64K boundary를 넘지 않습니다.

이 DMA region을 unmap하고 free하려면 `dma_free_coherent()`를 호출합니다.

dma_free_coherent(dev, size, cpu_addr, dma_handle);

`dev`와 `size`는 allocate 때와 같고 `cpu_addr`와 `dma_handle`은 `dma_alloc_coherent()`의 반환값입니다. 이 함수는 interrupt context에서 호출할 수 없습니다.

작은 memory region이 많이 필요하면 `dma_alloc_coherent()`가 반환한 page를 직접 나누거나 `dma_pool` API를 사용할 수 있습니다. `dma_pool`은 `kmem_cache`와 비슷하지만 `__get_free_pages()` 대신 `dma_alloc_coherent()`를 사용하며, queue head가 N-byte boundary에 정렬되어야 하는 것 같은 hardware alignment constraint도 이해합니다.

다음과 같이 `dma_pool`을 만듭니다.

struct dma_pool *pool;

pool = dma_pool_create(name, dev, size, align, boundary);

`name`은 `kmem_cache` 이름처럼 진단에 쓰입니다. `dev`와 `size`는 위와 같습니다. `align`은 이 data type에 대한 device hardware의 byte 단위 alignment requirement이며 2의 거듭제곱이어야 합니다. Boundary crossing 제한이 없으면 `boundary`에 0을 전달합니다. 4096은 pool allocation이 4KByte boundary를 넘지 못한다는 뜻이며, 이 경우에는 `dma_alloc_coherent()`를 직접 쓰는 편이 나을 수 있습니다.

DMA pool에서 memory를 allocate하려면 다음을 사용합니다.

cpu_addr = dma_pool_alloc(pool, flags, &dma_handle);

Blocking이 허용되면, 즉 interrupt 안이나 SMP lock 보유 중이 아니라면 `flags`는 `GFP_KERNEL`이고 그 밖에는 `GFP_ATOMIC`입니다. `dma_alloc_coherent()`처럼 `cpu_addr`와 `dma_handle`을 반환합니다.

Pool에서 allocate한 memory는 다음과 같이 free합니다.

dma_pool_free(pool, cpu_addr, dma_handle);

`pool`은 `dma_pool_alloc()`에 전달한 값이고 나머지는 그 함수가 반환한 값입니다. 이 함수는 interrupt context에서 호출할 수 있습니다.

DMA pool은 다음과 같이 destroy합니다.

dma_pool_destroy(pool);

Pool을 destroy하기 전에 그 pool에서 allocate한 모든 memory에 `dma_pool_free()`를 호출했는지 확인해야 합니다. `dma_pool_destroy()`는 interrupt context에서 호출할 수 없습니다.

DMA 전송 방향

DMA 방향

이 문서 뒤에서 설명하는 interface는 정수형 DMA direction argument로 다음 값 중 하나를 받습니다.

DMA_BIDIRECTIONAL
DMA_TO_DEVICE
DMA_FROM_DEVICE
DMA_NONE

방향을 안다면 정확히 지정해야 합니다. `DMA_TO_DEVICE`는 main memory에서 device로, `DMA_FROM_DEVICE`는 device에서 main memory로 data가 이동한다는 뜻이며 DMA transfer의 실제 이동 방향을 가리킵니다.

가능한 한 정확한 방향을 지정할 것을 강하게 권장합니다.

DMA transfer 방향을 정말 알 수 없다면 양방향을 뜻하는 `DMA_BIDIRECTIONAL`을 지정합니다. Platform은 이 값이 합법적이며 동작함을 보장하지만 성능 비용이 들 수 있습니다.

`DMA_NONE`은 debugging에 사용합니다. 정확한 방향을 알기 전 data structure에 넣어 두면 direction tracking logic이 올바르게 설정하지 못한 경우를 잡는 데 도움이 됩니다.

정확한 방향은 platform 전용 최적화뿐 아니라 debugging에도 유리합니다. 일부 platform은 user address space의 page protection처럼 DMA mapping에 write permission boolean을 표시할 수 있고, DMA controller가 permission 위반을 감지하면 kernel log에 오류를 보고합니다.

Direction을 지정하는 것은 streaming mapping뿐입니다. Coherent mapping은 암묵적으로 `DMA_BIDIRECTIONAL` direction attribute를 가집니다.

SCSI subsystem은 driver가 처리 중인 SCSI command의 `sc_data_direction` member로 사용할 방향을 알려 줍니다.

Networking driver에서는 transmit packet을 `DMA_TO_DEVICE`로 map/unmap하고 receive packet은 반대로 `DMA_FROM_DEVICE`로 map/unmap합니다.

Streaming single 및 page mapping

Streaming DMA mapping 사용

Streaming DMA mapping routine은 interrupt context에서 호출할 수 있습니다. 각 map/unmap에는 단일 memory region용과 scatterlist용 두 형태가 있습니다.

단일 region은 다음과 같이 mapping합니다.

struct device *dev = &my_dev->dev;
dma_addr_t dma_handle;
void *addr = buffer->ptr;
size_t size = buffer->len;

dma_handle = dma_map_single(dev, addr, size, direction);
if (dma_mapping_error(dev, dma_handle)) {
        /*
         * reduce current DMA mapping usage,
         * delay and try again later or
         * reset driver.
         */
        goto map_error_handling;
}

다음과 같이 unmap합니다.

dma_unmap_single(dev, dma_handle, size, direction);

`dma_map_single()`은 실패해 오류를 반환할 수 있으므로 `dma_mapping_error()`를 호출해야 합니다. 그래야 하부 구현 세부 사항에 의존하지 않고 모든 DMA 구현에서 올바르게 동작합니다. 오류 검사 없이 반환 주소를 사용하면 panic부터 조용한 data corruption까지 발생할 수 있습니다. `dma_map_page()`에도 같은 규칙이 적용됩니다.

DMA activity가 끝나면, 예를 들어 DMA transfer 완료를 알린 interrupt에서 `dma_unmap_single()`을 호출해야 합니다.

CPU pointer를 쓰는 single mapping은 HIGHMEM memory를 참조할 수 없다는 단점이 있습니다. 이를 위해 `dma_{map,unmap}_single()`과 비슷하지만 CPU pointer 대신 page/offset pair를 다루는 interface가 있습니다.

struct device *dev = &my_dev->dev;
dma_addr_t dma_handle;
struct page *page = buffer->page;
unsigned long offset = buffer->offset;
size_t size = buffer->len;

dma_handle = dma_map_page(dev, page, offset, size, direction);
if (dma_mapping_error(dev, dma_handle)) {
        /*
         * reduce current DMA mapping usage,
         * delay and try again later or
         * reset driver.
         */
        goto map_error_handling;
}

...

dma_unmap_page(dev, dma_handle, size, direction);

`offset`은 주어진 page 안의 byte offset입니다. `dma_map_page()`도 실패할 수 있으므로 `dma_mapping_error()`를 호출해야 하며, DMA activity가 끝나면 `dma_unmap_page()`를 호출합니다.

Streaming scatterlist mapping

여러 region에서 모은 영역은 scatterlist로 다음처럼 mapping합니다.

int i, count = dma_map_sg(dev, sglist, nents, direction);
struct scatterlist *sg;

for_each_sg(sglist, sg, count, i) {
        hw_address[i] = sg_dma_address(sg);
        hw_len[i] = sg_dma_len(sg);
}

`nents`는 `sglist` entry 수입니다. 구현은 연속된 여러 entry를 하나로 합칠 수 있습니다. 예를 들어 `PAGE_SIZE` 단위로 mapping할 때 앞 entry가 page boundary에서 끝나고 다음 entry가 그 boundary에서 시작하면 합칠 수 있습니다. Scatter-gather를 지원하지 않거나 entry 수가 매우 제한된 card에 큰 장점입니다. 반환값은 실제 mapping된 sg entry 수이며 실패하면 0입니다.

그 뒤에는 `nents`가 아니라 반환된 `count`만큼 순회하며, 기존의 `sg->address`, `sg->length` 대신 `sg_dma_address()`와 `sg_dma_len()` macro를 사용합니다.

Scatterlist는 다음과 같이 unmap합니다.

dma_unmap_sg(dev, sglist, nents, direction);

이때도 DMA activity가 이미 끝났는지 확인해야 합니다.

DMA address space는 공유 자원이므로 모든 `dma_map_{single,sg}()` 호출에는 대응하는 `dma_unmap_{single,sg}()`가 있어야 합니다. DMA address를 모두 소비하면 시스템을 사용할 수 없게 만들 수 있습니다.

반복 사용하는 streaming buffer 동기화

같은 streaming DMA region을 여러 번 사용하고 transfer 사이에 data를 만진다면 CPU와 device가 최신의 올바른 DMA buffer 사본을 보도록 buffer를 정확히 동기화해야 합니다.

먼저 `dma_map_{single,sg}()`로 mapping하고 각 DMA transfer 뒤 CPU가 접근하기 전에 상황에 맞는 다음 함수 중 하나를 호출합니다.

dma_sync_single_for_cpu(dev, dma_handle, size, direction);

dma_sync_sg_for_cpu(dev, sglist, nents, direction);

Device가 DMA area에 다시 접근하게 하려면 CPU 접근을 마친 뒤 buffer를 hardware에 넘기기 전에 다음 중 맞는 함수를 호출합니다.

dma_sync_single_for_device(dev, dma_handle, size, direction);

dma_sync_sg_for_device(dev, sglist, nents, direction);

마지막 DMA transfer 뒤에는 `dma_unmap_{single,sg}()` 중 하나를 호출합니다. 첫 `dma_map_*()`부터 `dma_unmap_*()`까지 CPU가 data를 건드리지 않는다면 `dma_sync_*()`를 호출할 필요가 없습니다.

다음 pseudo-code는 `dma_sync_*()` interface가 필요한 상황을 보여 줍니다.

my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
{
        dma_addr_t mapping;

        mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE);
        if (dma_mapping_error(cp->dev, mapping)) {
                /*
                 * reduce current DMA mapping usage,
                 * delay and try again later or
                 * reset driver.
                 */
                goto map_error_handling;
        }

        cp->rx_buf = buffer;
        cp->rx_len = len;
        cp->rx_dma = mapping;

        give_rx_buf_to_card(cp);
}

...

my_card_interrupt_handler(int irq, void *devid, struct pt_regs *regs)
{
        struct my_card *cp = devid;

        ...
        if (read_card_status(cp) == RX_BUF_TRANSFERRED) {
                struct my_card_header *hp;

                /* Examine the header to see if we wish
                 * to accept the data.  But synchronize
                 * the DMA transfer with the CPU first
                 * so that we see updated contents.
                 */
                dma_sync_single_for_cpu(&cp->dev, cp->rx_dma,
                                        cp->rx_len,
                                        DMA_FROM_DEVICE);

                /* Now it is safe to examine the buffer. */
                hp = (struct my_card_header *) cp->rx_buf;
                if (header_is_ok(hp)) {
                        dma_unmap_single(&cp->dev, cp->rx_dma, cp->rx_len,
                                         DMA_FROM_DEVICE);
                        pass_to_upper_layers(cp->rx_buf);
                        make_and_setup_new_rx_buf(cp);
                } else {
                        /* CPU should not write to
                         * DMA_FROM_DEVICE-mapped area,
                         * so dma_sync_single_for_device() is
                         * not needed here. It would be required
                         * for DMA_BIDIRECTIONAL mapping if
                         * the memory was modified.
                         */
                        give_rx_buf_to_card(cp);
                }
        }
}

예제는 receive buffer를 `DMA_FROM_DEVICE`로 mapping하고 card에 넘깁니다. Interrupt handler는 header를 검사하기 전에 `dma_sync_single_for_cpu()`로 CPU 관찰 상태를 갱신합니다. Header가 유효하면 unmap하고 상위 layer로 넘깁니다. 유효하지 않으면 buffer를 card에 다시 주며, CPU가 `DMA_FROM_DEVICE` 영역을 쓰지 않았으므로 `dma_sync_single_for_device()`는 필요 없습니다. `DMA_BIDIRECTIONAL` mapping에서 memory를 수정했다면 필요합니다.

DMA mapping 오류 처리

오류 처리

일부 architecture에서는 DMA address space가 제한되어 있습니다. `dma_alloc_coherent()`가 `NULL`을 반환하거나 `dma_map_sg()`가 0을 반환하는지 검사하여 allocation failure를 확인합니다.

`dma_map_single()`과 `dma_map_page()`가 반환한 `dma_addr_t`는 `dma_mapping_error()`로 검사합니다.

dma_addr_t dma_handle;

dma_handle = dma_map_single(dev, addr, size, direction);
if (dma_mapping_error(dev, dma_handle)) {
        /*
         * reduce current DMA mapping usage,
         * delay and try again later or
         * reset driver.
         */
        goto map_error_handling;
}

여러 page를 mapping하는 도중 오류가 나면 이미 mapping한 page를 unmap해야 합니다. 다음 예들은 `dma_map_page()`에도 적용됩니다.

예제 1은 두 번째 mapping 실패 시 첫 번째 mapping을 해제합니다.

dma_addr_t dma_handle1;
dma_addr_t dma_handle2;

dma_handle1 = dma_map_single(dev, addr, size, direction);
if (dma_mapping_error(dev, dma_handle1)) {
        /*
         * reduce current DMA mapping usage,
         * delay and try again later or
         * reset driver.
         */
        goto map_error_handling1;
}
dma_handle2 = dma_map_single(dev, addr, size, direction);
if (dma_mapping_error(dev, dma_handle2)) {
        /*
         * reduce current DMA mapping usage,
         * delay and try again later or
         * reset driver.
         */
        goto map_error_handling2;
}

...

map_error_handling2:
        dma_unmap_single(dma_handle1);
map_error_handling1:

예제 2는 loop 도중 오류가 나면 성공한 index 수를 이용해 앞서 mapping한 모든 buffer를 해제합니다.

/*
 * if buffers are allocated in a loop, unmap all mapped buffers when
 * mapping error is detected in the middle
 */

dma_addr_t dma_addr;
dma_addr_t array[DMA_BUFFERS];
int save_index = 0;

for (i = 0; i < DMA_BUFFERS; i++) {

        ...

        dma_addr = dma_map_single(dev, addr, size, direction);
        if (dma_mapping_error(dev, dma_addr)) {
                /*
                 * reduce current DMA mapping usage,
                 * delay and try again later or
                 * reset driver.
                 */
                goto map_error_handling;
        }
        array[i].dma_addr = dma_addr;
        save_index++;
}

...

map_error_handling:

for (i = 0; i < save_index; i++) {

        ...

        dma_unmap_single(array[i].dma_addr);
}

Networking driver는 transmit hook인 `ndo_start_xmit`에서 DMA mapping이 실패하면 `dev_kfree_skb()`로 socket buffer를 free하고 `NETDEV_TX_OK`를 반환해야 합니다. 실패한 socket buffer는 drop됩니다.

SCSI driver는 `queuecommand` hook에서 DMA mapping이 실패하면 `SCSI_MLQUEUE_HOST_BUSY`를 반환해야 합니다. 그러면 SCSI subsystem이 나중에 command를 다시 driver에 전달합니다.

Unmap 상태 공간 사용량 최적화

Unmap 상태 공간 사용량 최적화

많은 platform에서 `dma_unmap_{single,page}()`는 단순한 nop입니다. 이 경우 mapping address와 length를 계속 저장하는 것은 공간 낭비입니다. Portable API의 목적을 해치는 `#ifdef` 우회 대신 다음 기능을 사용합니다.

Macro를 하나씩 설명하는 대신 예제 code를 변환해 보겠습니다. 첫째, state 저장 structure에서 `DEFINE_DMA_UNMAP_{ADDR,LEN}`을 사용합니다. 변경 전:

struct ring_state {
        struct sk_buff *skb;
        dma_addr_t mapping;
        __u32 len;
};

변경 후:

struct ring_state {
        struct sk_buff *skb;
        DEFINE_DMA_UNMAP_ADDR(mapping);
        DEFINE_DMA_UNMAP_LEN(len);
};

둘째, 값을 설정할 때 `dma_unmap_{addr,len}_set()`을 사용합니다. 변경 전:

ringp->mapping = FOO;
ringp->len = BAR;

변경 후:

dma_unmap_addr_set(ringp, mapping, FOO);
dma_unmap_len_set(ringp, len, BAR);

셋째, 값에 접근할 때 `dma_unmap_{addr,len}()`을 사용합니다. 변경 전:

dma_unmap_single(dev, ringp->mapping, ringp->len,
                 DMA_FROM_DEVICE);

변경 후:

dma_unmap_single(dev,
                 dma_unmap_addr(ringp, mapping),
                 dma_unmap_len(ringp, len),
                 DMA_FROM_DEVICE);

동작은 이름 그대로입니다. 구현에 따라 unmap operation에 address만 필요할 수 있으므로 `ADDR`과 `LEN`은 별도로 취급합니다.

Architecture port의 platform 고려 사항

Platform 문제

Linux driver만 작성하고 kernel architecture port를 유지하지 않는다면 이 절을 건너뛰고 `Closing`으로 가도 됩니다.

1) `struct scatterlist` 요구 사항: Architecture가 software IOMMU를 포함한 IOMMU를 지원한다면 `CONFIG_NEED_SG_DMA_LENGTH`를 활성화해야 합니다.

2) `ARCH_DMA_MINALIGN`: Architecture는 `kmalloc()` buffer가 DMA-safe하도록 보장해야 하며 driver와 subsystem은 이를 전제로 합니다. Hardware가 CPU cache의 data와 main memory의 data가 같음을 보장하지 않는 등 완전히 DMA-coherent하지 않다면 memory allocator가 `kmalloc()` buffer를 다른 data와 같은 cache line에 두지 않도록 `ARCH_DMA_MINALIGN`을 설정해야 합니다. 예제는 `arch/arm/include/asm/cache.h`를 참고하십시오.

`ARCH_DMA_MINALIGN`은 DMA memory alignment constraint를 위한 것입니다. 64-bit object 정렬 같은 architecture data alignment constraint는 여기서 고려할 필요가 없습니다.

맺음말과 기여자

맺음말

수많은 사람의 feedback과 제안이 없었다면 이 문서와 API는 현재 형태가 되지 못했을 것입니다. 특별히 다음 기여자들을 순서 없이 언급합니다.

Russell King <rmk@arm.linux.org.uk>
Leo Dagum <dagum@barrel.engr.sgi.com>
Ralf Baechle <ralf@oss.sgi.com>
Grant Grundler <grundler@cup.hp.com>
Jay Estabrook <Jay.Estabrook@compaq.com>
Thomas Sailer <sailer@ife.ee.ethz.ch>
Andrea Arcangeli <andrea@suse.de>
Jens Axboe <jens.axboe@oracle.com>
David Mosberger-Tang <davidm@hpl.hp.com>