Dynamic DMA mapping using the generic device

Generic device를 사용하는 dynamic DMA mapping

Dynamic DMA mapping using the generic device (generic device를 사용하는 동적 DMA mapping)

저자는 James E.J. Bottomley <James.Bottomley@HansenPartnership.com>입니다.

이 문서는 DMA API를 설명합니다. 더 쉬운 소개와 실제 예제는 `Documentation/core-api/dma-api-howto.rst`를 참고하십시오.

API는 두 부분으로 나뉩니다. Part I은 기본 API를, Part II는 non-coherent memory machine 지원 확장을 설명합니다. Driver가 보통 legacy platform인 non-coherent platform을 반드시 지원해야 한다는 확신이 없다면 Part I의 API만 사용해야 합니다.

Part I 기본 DMA API

Part I - DMA API

DMA API를 사용하려면 `#include <linux/dma-mapping.h>`가 필요합니다. 이 header는 `dma_addr_t`와 아래 interface를 제공합니다.

`dma_addr_t`는 platform에서 유효한 모든 DMA address를 담을 수 있고 DMA source 또는 target으로 device에 전달할 수 있습니다. CPU physical address space와 DMA address space 사이에 변환이 있을 수 있으므로 CPU가 `dma_addr_t`를 직접 참조할 수는 없습니다.

Part Ia 큰 DMA-coherent buffer

Part Ia - 큰 DMA-coherent buffer 사용

void *
dma_alloc_coherent(struct device *dev, size_t size,
                   dma_addr_t *dma_handle, gfp_t flag)

Coherent memory는 device나 processor 어느 쪽이 write해도 caching effect를 걱정하지 않고 상대가 즉시 읽을 수 있는 memory입니다. 다만 device에 읽으라고 알리기 전에 processor write buffer를 flush해야 할 수 있습니다.

`dma_alloc_coherent()`는 `size` byte의 coherent memory region을 allocate합니다. 성공하면 processor virtual address space의 pointer를, 실패하면 `NULL`을 반환합니다. 또한 bus와 같은 폭의 unsigned integer로 cast하여 device에 region의 DMA address base로 줄 수 있는 `dma_handle`을 반환합니다.

`flag` parameter로 allocation의 `GFP_` flag를 지정합니다. 의미는 `kmalloc()`을 참고하십시오. 구현은 `GFP_DMA`처럼 반환 memory 위치에 영향을 주는 flag를 무시할 수 있습니다.

void
dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
                  dma_addr_t dma_handle)

이 함수는 앞서 allocate한 coherent memory region을 free합니다. `dev`, `size`, `dma_handle`은 `dma_alloc_coherent()`에 전달한 값과 같아야 하며 `cpu_addr`는 그 함수가 반환한 virtual address여야 합니다.

Allocation 함수와 달리 `dma_free_coherent()`는 IRQ가 활성화된 상태에서만 호출할 수 있습니다.

Part Ib 작은 DMA-coherent buffer

Part Ib - 작은 DMA-coherent buffer 사용

이 DMA API 부분을 사용하려면 `#include <linux/dmapool.h>`가 필요합니다.

많은 driver는 DMA descriptor나 I/O buffer용 작은 DMA-coherent memory region을 많이 필요로 합니다. `dma_alloc_coherent()`로 page 이상 단위로 allocate하는 대신 DMA pool을 사용할 수 있습니다. DMA pool은 `struct kmem_cache`와 비슷하지만 `__get_free_pages()`가 아니라 DMA-coherent allocator를 사용하고, queue head의 N-byte boundary 정렬 같은 hardware alignment constraint를 이해합니다.

공개 API의 kernel-doc은 `mm/dmapool.c`의 exported symbol과 `include/linux/dmapool.h`에서 가져옵니다.

Part Ic DMA 주소 지정 한계

Part Ic - DMA addressing limitation

DMA mask는 device가 address할 수 있는 영역의 bit mask입니다. Memory region의 DMA address와 mask를 bitwise AND했을 때 address의 bit가 하나도 지워지지 않으면 device가 그 region에 DMA할 수 있습니다.

아래의 DMA mask 설정 함수는 요청한 mask를 device와 함께 사용할 수 없거나 device가 DMA를 수행할 수 없으면 실패할 수 있습니다.

int
dma_set_mask_and_coherent(struct device *dev, u64 mask)

`dma_set_mask_and_coherent()`는 streaming과 coherent DMA mask를 모두 갱신하며 성공하면 0, 실패하면 음수 error를 반환합니다.

int
dma_set_mask(struct device *dev, u64 mask)

`dma_set_mask()`는 streaming DMA mask만 갱신하며 성공하면 0, 실패하면 음수 error를 반환합니다.

int
dma_set_coherent_mask(struct device *dev, u64 mask)

`dma_set_coherent_mask()`는 coherent DMA mask만 갱신하며 성공하면 0, 실패하면 음수 error를 반환합니다.

u64
dma_get_required_mask(struct device *dev)

`dma_get_required_mask()`는 platform이 효율적으로 동작하는 데 필요한 mask를 반환합니다. 보통 전체 memory를 덮는 최소 mask이며, variable descriptor size를 지원하는 driver는 이를 보고 더 작은 descriptor를 선택할 수 있습니다. 이 조회는 현재 mask를 바꾸지 않으므로 활용하려면 반환값으로 `dma_set_mask()`를 호출해야 합니다.

size_t
dma_max_mapping_size(struct device *dev);

`dma_max_mapping_size()`는 device에서 가능한 mapping의 최대 size를 반환합니다. `dma_map_single()`, `dma_map_page()` 같은 mapping 함수의 size parameter가 이 값을 넘으면 안 됩니다.

size_t
dma_opt_mapping_size(struct device *dev);

`dma_opt_mapping_size()`는 최적 mapping의 최대 size를 반환합니다. 일부 상황에서 큰 buffer mapping은 훨씬 오래 걸리며, 짧게 유지되는 고속 streaming mapping에서는 준비 시간이 전체 request lifetime의 상당 부분일 수 있습니다. 큰 request를 나누어도 성능 손해가 크지 않다면 전체 DMA streaming mapping 길이를 반환값 이하로 제한하는 것이 좋습니다.

bool
dma_need_sync(struct device *dev, dma_addr_t dma_addr);

`dma_need_sync()`는 memory ownership 전환에 `dma_sync_single_for_{device,cpu}` 호출이 필요하면 `%true`, 생략할 수 있으면 `%false`를 반환합니다.

unsigned long
dma_get_merge_boundary(struct device *dev);

`dma_get_merge_boundary()`는 DMA merge boundary를 반환합니다. Device가 DMA address segment를 전혀 merge할 수 없으면 0을 반환합니다.

Part Id streaming single mapping과 방향

Part Id - Streaming DMA mapping

Streaming DMA는 기존 buffer를 DMA transfer용으로 mapping하고 끝나면 unmap합니다. Map 함수는 성공이 보장되지 않으므로 반환값을 검사해야 합니다.

dma_addr_t
dma_map_single(struct device *dev, void *cpu_addr, size_t size,
               enum dma_data_direction direction)

`dma_map_single()`은 processor virtual memory 일부를 device가 접근할 수 있도록 mapping하고 그 memory의 DMA address를 반환합니다.

DMA API의 direction은 강한 type의 enumerator입니다.

`DMA_TO_DEVICE` synchronization은 software가 memory region을 마지막으로 수정한 뒤 device에 넘기기 전에 수행합니다. 그 뒤 해당 memory는 device 관점에서 read-only로 취급해야 하며 device가 쓸 수 있다면 `DMA_BIDIRECTIONAL`을 사용해야 합니다.

`DMA_FROM_DEVICE` synchronization은 driver가 device가 바꿨을 수 있는 data에 접근하기 전에 수행합니다. 이 memory는 driver 관점에서 read-only로 취급해야 하며 driver가 써야 한다면 `DMA_BIDIRECTIONAL`을 사용합니다.

`DMA_BIDIRECTIONAL`은 memory를 device에 넘기기 전에 driver가 수정했는지, device도 수정할지 모두 확실하지 않은 경우입니다. 따라서 device에 넘기기 전 processor의 변경을 flush하기 위해 한 번, device 사용 뒤 접근하기 전 device가 바꾼 data로 processor cache line을 갱신하기 위해 한 번, 항상 두 번 sync해야 합니다.

Streaming unmap, page, resource와 오류 API

void
dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
                 enum dma_data_direction direction)

`dma_unmap_single()`은 앞서 mapping한 region을 unmap합니다. 모든 parameter는 `dma_map_single()`에 전달하고 반환받은 값과 동일해야 합니다.

dma_addr_t
dma_map_page(struct device *dev, struct page *page,
             unsigned long offset, size_t size,
             enum dma_data_direction direction)

void
dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
               enum dma_data_direction direction)

`dma_map_page()`와 `dma_unmap_page()`는 page를 mapping하고 unmap하는 API입니다. 다른 mapping API의 모든 note와 warning이 적용됩니다. `offset`과 `size`로 partial page mapping을 할 수 있지만 cache width를 정확히 아는 경우가 아니라면 사용하지 않는 것이 좋습니다.

dma_addr_t
dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size,
                 enum dma_data_direction dir, unsigned long attrs)

void
dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size,
                   enum dma_data_direction dir, unsigned long attrs)

`dma_map_resource()`와 `dma_unmap_resource()`는 MMIO resource를 mapping하고 unmap합니다. 다른 mapping API의 note와 warning이 모두 적용되며 device MMIO resource에만 사용해야 하고 RAM mapping은 허용되지 않습니다.

int
dma_mapping_error(struct device *dev, dma_addr_t dma_addr)

`dma_map_single()`, `dma_map_page()`, `dma_map_resource()`는 mapping 생성에 실패할 수 있습니다. Driver는 반환된 DMA address를 `dma_mapping_error()`로 검사합니다. 0이 아닌 반환값은 mapping 실패를 뜻하므로 현재 DMA mapping 사용량을 줄이거나 지연 후 재시도하는 등 적절히 처리해야 합니다.

Streaming scatter/gather mapping

int
dma_map_sg(struct device *dev, struct scatterlist *sg,
           int nents, enum dma_data_direction direction)

`dma_map_sg()`는 scatter/gather list를 DMA용으로 mapping하고 DMA address segment 수를 반환합니다. 연속된 sglist entry를 IOMMU로 merge하거나 인접 segment가 우연히 물리적으로 연속이면 반환값이 입력 `nents`보다 작을 수 있습니다.

한 번 mapping한 `sg`는 다시 mapping할 수 없습니다. Mapping 과정은 `sg` 안의 정보를 파괴할 수 있습니다.

`dma_map_sg()`도 실패할 수 있으며 0을 반환합니다. Driver는 반드시 처리해야 합니다. Block driver라면 아무것도 하지 않아 filesystem을 손상시키는 것보다 request를 abort하거나 심지어 oops하는 편이 낫습니다.

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를 하나로 merge할 수 있고 반환값은 실제 mapping된 sg entry 수이며 실패 시 0입니다. 반환된 `count`만큼 순회하면서 기존 `sg->address`, `sg->length` 대신 `sg_dma_address()`와 `sg_dma_len()`을 사용합니다.

void
dma_unmap_sg(struct device *dev, struct scatterlist *sg,
             int nents, enum dma_data_direction direction)

`dma_unmap_sg()`는 앞서 mapping한 scatter/gather list를 unmap하며 parameter는 mapping API에 전달한 것과 같아야 합니다. 특히 `nents`는 반환된 DMA address entry 수가 아니라 입력으로 전달한 수여야 합니다.

Streaming mapping 동기화

void
dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle,
                        size_t size,
                        enum dma_data_direction direction)

void
dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle,
                           size_t size,
                           enum dma_data_direction direction)

void
dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,
                    int nents,
                    enum dma_data_direction direction)

void
dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg,
                       int nents,
                       enum dma_data_direction direction)

이 함수들은 single contiguous 또는 scatter/gather mapping을 CPU와 device에 맞게 synchronize합니다. `sync_sg` API의 모든 parameter는 sg mapping API에 전달한 것과 같아야 합니다. `sync_single` API는 single mapping 때와 다른 `dma_handle`과 `size`로 partial sync를 수행할 수 있습니다.

• Device가 DMA로 쓴 값을 읽기 전에는 DMA_FROM_DEVICE direction을 사용합니다.
• DMA로 device에 보낼 값을 쓴 뒤에는 DMA_TO_DEVICE direction을 사용합니다.
• Memory가 DMA_BIDIRECTIONAL이면 device에 넘기기 전과 돌려받은 뒤 모두 수행합니다.

관련 규칙은 `dma_map_single()` 설명도 참고하십시오.

DMA attribute가 있는 mapping

dma_addr_t
dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
                     enum dma_data_direction dir,
                     unsigned long attrs)

void
dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
                       size_t size, enum dma_data_direction dir,
                       unsigned long attrs)

int
dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
                 int nents, enum dma_data_direction dir,
                 unsigned long attrs)

void
dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
                   int nents, enum dma_data_direction dir,
                   unsigned long attrs)

위 네 함수는 `_attrs` suffix가 없는 대응 함수와 같지만 optional `dma_attrs`를 추가로 전달합니다.

DMA attribute 해석은 architecture마다 다르며 각 attribute는 `Documentation/core-api/dma-attributes.rst`에 문서화해야 합니다.

`dma_attrs`가 0이면 각 함수의 의미는 `_attrs` 없는 대응 함수와 같습니다. 따라서 일반적으로 `dma_map_single_attrs()`가 `dma_map_single()`을 대체할 수 있습니다.

`*_attrs` 함수로 memory를 DMA mapping할 때 `DMA_ATTR_FOO` attribute를 전달하는 예는 다음과 같습니다.

#include <linux/dma-mapping.h>
/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
* documented in Documentation/core-api/dma-attributes.rst */
...

        unsigned long attr;
        attr |= DMA_ATTR_FOO;
        ....
        n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, attr);
        ....

`DMA_ATTR_FOO`를 고려하는 architecture는 mapping 및 unmapping 구현에서 attribute 존재를 다음처럼 검사합니다.

void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
                             size_t size, enum dma_data_direction dir,
                             unsigned long attrs)
{
        ....
        if (attrs & DMA_ATTR_FOO)
                /* twizzle the frobnozzle */
        ....
}

Part Ie IOVA 기반 DMA mapping

Part Ie - IOVA-based DMA mapping

이 API는 IOMMU 사용 시 매우 효율적인 mapping을 제공합니다. 추가 code가 필요한 optional path이며 DMA mapping 성능이나 DMA address 저장 공간이 중요한 driver에만 권장합니다. 앞 절의 모든 고려 사항이 그대로 적용됩니다.

bool dma_iova_try_alloc(struct device *dev, struct dma_iova_state *state,
            phys_addr_t phys, size_t size);

`dma_iova_try_alloc()`은 mapping operation을 위한 IOVA space allocation을 시도합니다. `false`면 해당 device에 이 API를 사용할 수 없으므로 일반 streaming DMA mapping API를 사용합니다. `struct dma_iova_state`는 driver가 allocate하고 unmap 때까지 유지해야 합니다.

static inline bool dma_use_iova(struct dma_iova_state *state)

`dma_use_iova()`는 `dma_iova_try_alloc()` 호출 뒤 IOVA 기반 API가 사용 중인지 driver가 확인합니다. Unmap path에서 유용합니다.

int dma_iova_link(struct device *dev, struct dma_iova_state *state,
            phys_addr_t phys, size_t offset, size_t size,
            enum dma_data_direction dir, unsigned long attrs);

`dma_iova_link()`는 앞서 allocate한 IOVA에 range를 연결합니다. 한 state에 대한 첫 호출을 제외한 모든 range 시작점은 `dma_get_merge_boundary()`가 반환한 DMA merge boundary에 맞춰야 하며 마지막을 제외한 모든 range size도 같은 boundary에 맞춰야 합니다.

int dma_iova_sync(struct device *dev, struct dma_iova_state *state,
            size_t offset, size_t size);

`dma_iova_sync()`는 하나 이상의 `dma_iova_link()` 호출로 mapping한 IOVA range의 IOMMU page table을 synchronize하기 위해 호출해야 합니다.

One-shot mapping driver는 다음 함수로 모든 range를 unmap하고 IOVA를 free할 수 있습니다.

void dma_iova_destroy(struct device *dev, struct dma_iova_state *state,
             size_t mapped_len, enum dma_data_direction dir,
             unsigned long attrs);

또는 개별 region을 mapping/unmapping하여 IOVA space를 동적으로 관리할 수 있습니다. 앞서 mapping한 range는 다음으로 unmap합니다.

void dma_iova_unlink(struct device *dev, struct dma_iova_state *state,
            size_t offset, size_t size, enum dma_data_direction dir,
            unsigned long attrs);

IOVA space는 다음으로 free합니다.

void dma_iova_free(struct device *dev, struct dma_iova_state *state);

`dma_iova_free()` 호출 전에 모든 region을 `dma_iova_unlink()`로 unmap해야 합니다.

Part II non-coherent page allocation

Part II - Non-coherent DMA allocation

이 API는 주어진 device가 DMA address로 접근할 수 있음을 보장하는 page를 allocate하지만 kernel과 device 사이의 memory ownership을 명시적으로 관리해야 합니다. Processor와 I/O device 사이의 cache line coherency를 이해하지 못한다면 이 API 부분을 사용하면 안 됩니다.

struct page *
dma_alloc_pages(struct device *dev, size_t size, dma_addr_t *dma_handle,
                enum dma_data_direction dir, gfp_t gfp)

`dma_alloc_pages()`는 `size` byte의 non-coherent memory region을 allocate합니다. 성공하면 region의 첫 `struct page` pointer를, 실패하면 `NULL`을 반환합니다. 결과 page는 일반 `struct page` 용도에 사용할 수 있습니다. 함께 반환하는 `dma_handle`은 bus 폭의 unsigned integer로 cast하여 device에 region의 DMA address base로 전달할 수 있습니다.

`dir`은 device가 data를 읽거나 쓰는 방향이며 자세한 내용은 `dma_map_single()`을 참고합니다. `gfp`는 `kmalloc()`과 같은 `GFP_` flag를 지정하지만 `GFP_DMA`, `GFP_HIGHMEM`처럼 memory zone을 고르는 flag는 거부합니다.

Memory를 device에 넘기기 전에 `dma_sync_single_for_device()`를, device가 쓴 memory를 읽기 전에 `dma_sync_single_for_cpu()`를 호출해야 합니다. 재사용하는 streaming DMA mapping과 같은 규칙입니다.

void
dma_free_pages(struct device *dev, size_t size, struct page *page,
                dma_addr_t dma_handle, enum dma_data_direction dir)

`dma_free_pages()`는 `dma_alloc_pages()`가 allocate한 memory를 free합니다. `dev`, `size`, `dma_handle`, `dir`은 allocation 때와 같아야 하고 `page`는 반환받은 pointer여야 합니다.

int
dma_mmap_pages(struct device *dev, struct vm_area_struct *vma,
               size_t size, struct page *page)

`dma_mmap_pages()`는 `dma_alloc_pages()` allocation을 user address space에 mapping합니다. `dev`, `size`, `page`는 allocation 때 사용하거나 반환받은 값과 같아야 합니다.

void *
dma_alloc_noncoherent(struct device *dev, size_t size,
                dma_addr_t *dma_handle, enum dma_data_direction dir,
                gfp_t gfp)

`dma_alloc_noncoherent()`는 `dma_alloc_pages()`의 편의 wrapper로, page structure 대신 allocate한 memory의 kernel virtual address를 반환합니다.

void
dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
                dma_addr_t dma_handle, enum dma_data_direction dir)

`dma_free_noncoherent()`는 앞 함수로 allocate한 memory를 free합니다. 모든 parameter는 allocation 때 전달하거나 반환받은 값과 같아야 합니다.

Non-contiguous allocation과 cache alignment

struct sg_table *
dma_alloc_noncontiguous(struct device *dev, size_t size,
                        enum dma_data_direction dir, gfp_t gfp,
                        unsigned long attrs);

`dma_alloc_noncontiguous()`는 `size` byte의 non-coherent하고 물리적으로 연속되지 않을 수 있는 memory를 allocate합니다. 성공하면 allocate 및 DMA mapping된 memory를 설명하는 `struct sg_table` pointer를, 실패하면 `NULL`을 반환합니다.

반환 `sg_table`은 `sgt->nents` 기준으로 DMA mapped segment가 정확히 하나임을 보장하지만 CPU 쪽 segment는 `sgt->orig_nents`가 나타내듯 여러 개일 수 있습니다. `dir`과 `gfp` 규칙은 위와 같고 `attrs`는 0 또는 `DMA_ATTR_ALLOC_SINGLE_PAGES`여야 합니다.

Device에 넘기기 전에 `dma_sync_sgtable_for_device()`를, device가 쓴 memory를 읽기 전에 `dma_sync_sgtable_for_cpu()`를 호출합니다.

void
dma_free_noncontiguous(struct device *dev, size_t size,
                       struct sg_table *sgt,
                       enum dma_data_direction dir)

`dma_free_noncontiguous()`는 앞 함수가 allocate한 memory를 free합니다. `dev`, `size`, `dir`은 같아야 하고 `sgt`는 반환받은 pointer여야 합니다.

void *
dma_vmap_noncontiguous(struct device *dev, size_t size,
        struct sg_table *sgt)

`dma_vmap_noncontiguous()`는 non-contiguous allocation에 대한 contiguous kernel mapping을 반환합니다. Mapping 뒤에는 `flush_kernel_vmap_range()`와 `invalidate_kernel_vmap_range()`를 사용해 kernel mapping, device, user space mapping 사이의 coherency를 관리해야 합니다.

void
dma_vunmap_noncontiguous(struct device *dev, void *vaddr)

`dma_vunmap_noncontiguous()`는 위 함수가 반환한 kernel mapping을 unmap합니다. `dev`는 allocation 때와 같고 `vaddr`는 반환받은 pointer여야 합니다.

int
dma_mmap_noncontiguous(struct device *dev, struct vm_area_struct *vma,
                       size_t size, struct sg_table *sgt)

`dma_mmap_noncontiguous()`는 non-contiguous allocation을 user address space에 mapping하며 `dev`, `size`, `sgt`는 allocation과 일치해야 합니다.

int
dma_get_cache_alignment(void)

`dma_get_cache_alignment()`는 processor cache alignment를 반환합니다. Memory mapping이나 partial flush에서 지켜야 할 절대 최소 alignment이자 width입니다.

Part III DMA API 사용 오류 디버깅

Part III - Driver의 DMA API 사용 디버깅

DMA API에는 같은 size와 대응 함수로 DMA address를 해제해야 하는 등의 제약이 있습니다. Hardware IOMMU가 보편화되면서 driver가 이를 지키는 일이 더 중요해졌고, 최악에는 filesystem 파괴까지 포함한 data corruption이 생길 수 있습니다.

DMA API 사용 bug를 찾기 위한 검사 code를 kernel에 compile할 수 있습니다. Architecture가 지원하면 kernel configuration에서 `Enable debugging of DMA API usage`를 선택합니다. 성능 영향이 있으므로 production kernel에서는 활성화하지 마십시오.

이 kernel은 어느 device에 어떤 DMA memory가 allocate되었는지 bookkeeping하고 오류를 발견하면 상세 warning을 kernel log에 출력합니다. 예시는 다음과 같습니다.

WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
        check_unmap+0x203/0x490()
Hardware name:
forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
        function [device address=0x00000000640444be] [size=66 bytes] [mapped as
single] [unmapped as page]
Modules linked in: nfsd exportfs bridge stp llc r8169
Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
Call Trace:
<IRQ>  [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
[<ffffffff80647b70>] _spin_unlock+0x10/0x30
[<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
[<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
[<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
[<ffffffff80252f96>] queue_work+0x56/0x60
[<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
[<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
[<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
[<ffffffff80235177>] find_busiest_group+0x207/0x8a0
[<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
[<ffffffff803c7ea3>] check_unmap+0x203/0x490
[<ffffffff803c8259>] debug_dma_unmap_phys+0x49/0x50
[<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
[<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
[<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
[<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
[<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
[<ffffffff8020c093>] ret_from_intr+0x0/0xa
<EOI> <4>---[ end trace f6435a98e2a38c0e ]---

Driver developer는 warning을 발생시킨 DMA API 호출의 stack trace와 함께 driver와 device를 찾을 수 있습니다.

기본적으로 첫 오류만 warning message를 만들고 나머지는 조용히 count합니다. Kernel log flooding을 막기 위한 제한이며 driver debugging 중에는 아래 debugfs interface로 해제할 수 있습니다.

DMA API debugfs interface와 boot parameter

DMA API debugging code의 debugfs directory는 `dma-api/`이며 다음 file을 제공합니다.

Code를 kernel에 compile하면 기본 활성화됩니다. Bookkeeping 없이 부팅하려면 `dma_debug=off` boot parameter를 사용합니다. Runtime에는 다시 활성화할 수 없으므로 reboot해야 합니다.

특정 device driver의 debug message만 보려면 `dma_debug_driver=<drivername>` parameter를 사용합니다. Boot 때 driver filter를 활성화하며 이후 debugfs에서 끄거나 바꿀 수 있습니다.

Runtime에 code가 스스로 비활성화되었다면 보통 `dma_debug_entries`가 바닥나 추가 allocate에 실패한 경우입니다. Boot 때 65536개를 preallocate하며 부족하면 `dma_debug_entries=<your_desired_number>`로 기본값을 덮어씁니다. Entry는 batch로 allocate하므로 실제 preallocation 수가 요청보다 클 수 있습니다. 동적 allocation 누계가 최초 preallocation만큼 늘 때마다 kernel log에 알리며, 더 큰 사전 할당이 필요하거나 계속 반복된다면 driver가 mapping을 leak할 수 있음을 뜻합니다.

Mapping 오류 검사 누락 탐지

void
debug_dma_mapping_error(struct device *dev, dma_addr_t dma_addr);

`debug_dma_mapping_error()`는 `dma_map_single()`과 `dma_map_page()` 반환 주소의 DMA mapping error 검사를 빠뜨린 driver를 디버깅합니다. `debug_dma_map_phys()`가 설정한 flag를 지워 driver가 `dma_mapping_error()`를 호출했음을 표시합니다. Unmap 때 `debug_dma_unmap()`이 flag를 검사하고 그대로 남아 있으면 unmap까지 이어진 call trace를 포함한 warning을 출력합니다. DMA mapping error check debugging을 활성화하도록 `dma_mapping_error()` routine에서 호출할 수 있습니다.

함수와 구조체

함수와 구조체

공개 함수와 structure의 kernel-doc은 `include/linux/scatterlist.h`와 `lib/scatterlist.c`에서 가져옵니다.