DMAengine controller documentation

Hardware 기본 원리

이 DMAengine controller documentation은 provider driver 구현을 설명합니다. 대부분의 Slave DMA controller는 같은 일반 동작 원리를 따릅니다.

controller에는 DMA transfer에 사용할 일정 수의 channel과 request line이 있습니다. request와 channel은 거의 서로 독립적입니다. channel 하나가 여러 request를 처리할 수 있습니다. 단순화하면 channel은 copy를 수행하는 entity이고 request는 어떤 endpoint가 관여하는지를 나타냅니다.

request line은 DMA를 사용할 수 있는 device에서 controller로 이어지는 물리적 line입니다. device가 transfer를 시작하려면 해당 request line을 assert해 DMA request, 즉 DRQ를 발생시킵니다.

아주 단순한 DMA controller는 transfer size 하나만 고려하며, 매 clock cycle마다 한 buffer에서 다른 buffer로 byte 하나를 옮겨 목표 크기에 도달할 때까지 반복합니다.

실제 slave device는 한 cycle에 특정 bit 수를 전송해야 할 수 있습니다. 단순 memory copy에서는 physical bus가 허용하는 만큼 옮겨 성능을 높이고 싶지만, audio device의 좁은 FIFO는 정확히 16bit 또는 24bit씩 기록해야 할 수 있습니다. 그래서 거의 모든 DMA controller는 transfer width parameter를 조절할 수 있습니다.

RAM이 source나 destination이면 일부 controller는 memory read/write를 buffer에 묶어 작은 access를 많이 수행하는 대신 큰 transfer 여러 개로 처리합니다. burst size는 controller가 더 작은 sub-transfer로 나누기 전에 연속해서 수행할 수 있는 단일 read/write 수를 정의합니다.

Scatter-gather와 hardware descriptor collection

이론적인 단순 controller는 contiguous data block 하나만 전송할 수 있지만 실제 workload에는 non-contiguous buffer에서 contiguous buffer로 복사하는 scatter-gather가 필요합니다.

DMAEngine은 적어도 mem2dev transfer에 scatter-gather 지원을 요구합니다. controller가 직접 지원하지 않으면 driver가 software로 구현해야 하고, 고급 controller라면 hardware scatter-gather를 사용합니다.

hardware scatter-gather controller는 전송할 chunk collection으로 program합니다. transfer를 시작하면 controller가 collection을 순회해 지정된 동작을 수행합니다. collection은 보통 table 또는 linked list이며, channel에 table address와 element 수 또는 list의 첫 item을 전달합니다. DRQ가 assert되면 collection을 따라가며 data source를 찾습니다.

collection format은 hardware마다 다릅니다. 각 chunk에는 최소한 source/destination address, 각 address의 increment 여부, burst size, transfer width, transfer size가 필요합니다.

slave device는 보통 기본 상태에서 DRQ를 발생시키지 않으므로 DMA를 사용하기 전에 slave device driver에서 이를 enable해야 합니다.

지금까지는 memory-to-memory(mem2mem)와 memory-to-device(mem2dev)의 일반 원리입니다. 많은 device가 다른 transfer 또는 memory operation도 지원하며 뒤에서 설명합니다.

Linux의 DMA 지원 계층

역사적으로 DMA controller driver는 async TX API를 사용해 memory copy, XOR, cryptography 등 memory-to-memory operation을 offload했습니다.

memory-to-device transfer 수요가 생기면서 dmaengine이 확장됐습니다. 현재 async TX API는 dmaengine 위의 client layer로 구현됩니다. dmaengine은 일부 경우 이 API를 수용하며 호환성을 유지하기 위한 design choice도 포함합니다.

Async TX API의 자세한 내용은 `Documentation/crypto/async-tx-api.rst`를 참조합니다.

struct dma_device 초기화

다른 kernel framework와 마찬가지로 DMAEngine 등록은 driver가 구조체를 채워 framework에 등록하는 방식이며 여기서는 `dma_device`를 사용합니다. 일반 allocator로 구조체를 할당한 뒤 다음 field를 초기화합니다.

• `channels`: `INIT_LIST_HEAD` 같은 macro로 list를 초기화합니다.
• `src_addr_widths`: 지원하는 source transfer width bitmask입니다.
• `dst_addr_widths`: 지원하는 destination transfer width bitmask입니다.
• `directions`: mem2mem을 제외한 지원 slave direction bitmask입니다.
• `residue_granularity`: `dma_set_residue`에 보고하는 transfer residue의 granularity입니다.
• `dev`: 현재 driver instance와 연결된 `struct device` pointer입니다.

지원 transaction type: memory operation

다음으로 device와 driver가 지원하는 transaction type을 설정합니다. `dma_device`의 `cap_mask`를 `dma_cap_set()`으로 수정하며, capability는 `include/linux/dmaengine.h`의 `dma_transaction_type` enum에 정의되어 있습니다.

• `DMA_MEMCPY`: memory-to-memory copy를 수행합니다. source와 destination scatter-gather list의 chunk 수와 크기가 달라도 두 list의 전체 크기 중 작은 값만큼만 전송합니다. 이는 `count`가 두 list buffer의 작은 전체 크기인 `strncpy`와 기능적으로 같습니다. modern PCI graphics card에서 host memory와 memory-mapped GPU memory 사이 pixel data를 복사하는 데 흔히 쓰이며, 큰 framebuffer를 host memory로 그대로 복사할 수 있는 OpenGL `glReadPixels()`가 대표 예입니다.
• `DMA_XOR`: memory area에 XOR operation을 수행해 RAID5 같은 XOR 집약 작업을 가속합니다.
• `DMA_XOR_VAL`: memory buffer에 XOR algorithm으로 parity check를 수행합니다.
• `DMA_PQ`: RAID6 P+Q 계산을 수행합니다. P는 단순 XOR이고 Q는 Reed-Solomon algorithm입니다.
• `DMA_PQ_VAL`: memory buffer에 RAID6 P+Q algorithm으로 parity check를 수행합니다.
• `DMA_MEMSET`: 제공된 pattern으로 memory를 채웁니다. pattern은 single-byte signed value로 취급합니다.
• `DMA_INTERRUPT`: periodic interrupt를 생성하는 dummy transfer를 trigger합니다. client driver는 정기적으로 DMA controller interrupt를 통해 호출될 callback을 등록할 때 사용합니다.
• `DMA_PRIVATE`: device가 slave transfer만 지원하므로 async transfer에는 사용할 수 없습니다.
• `DMA_ASYNC_TX`: memcpy, memset, xor, pq, xor_val, pq_val을 포함한 asynchronous memory-to-memory operation을 지원합니다. DMA engine framework가 자동으로 설정하므로 device driver가 수동으로 구성하면 안 됩니다.

지원 transaction type: slave, cyclic, interleaved와 반복

• `DMA_SLAVE`: scatter-gather를 포함한 device-to-memory transfer를 처리합니다. mem2mem처럼 single chunk와 collection을 나누지 않고 transaction type 하나가 둘 다 처리합니다. contiguous buffer 하나는 item 하나짜리 scatterlist로 표현합니다.
• `DMA_CYCLIC`: 마지막 item이 첫 item을 가리켜 chunk collection이 반복되는 cyclic transfer를 처리합니다. audio data를 채우는 ring buffer에 흔히 사용합니다.
• `DMA_INTERLEAVE`: non-contiguous source에서 non-contiguous destination으로 전송합니다. non-contiguous data set에서 continuous destination으로 옮기는 `DMA_SLAVE`와 다릅니다. 보통 uncompressed 2D content 일부를 display로 직접 전송할 때 사용합니다.
• `DMA_COMPLETION_NO_ORDER`: in-order completion을 지원하지 않습니다. operation이 out of order로 끝나면 `device_tx_status`가 `DMA_OUT_OF_ORDER`를 반환해야 합니다. 모든 cookie tracking/checking API는 무효로 취급하고 현재 dmatest polling과 호환되지 않습니다. descriptor마다 unique identifier를 제공해 completion을 추적하는 것을 권장합니다.
• `DMA_REPEAT`: `DMA_PREP_REPEAT` flag로 끝날 때 자동 반복되며 client가 교체할 수도 있습니다. 현재 interleaved transfer에만 한정되므로 `DMA_INTERLEAVE` 없이 설정하면 안 됩니다. 다른 type 지원은 client 수요가 생길 때 추가할 수 있습니다.
• `DMA_LOAD_EOT`: `DMA_PREP_LOAD_EOT`를 설정한 새 transfer를 queue해 end of transfer(EOT)에서 반복 transfer를 교체할 수 있습니다. end of burst 같은 다른 교체 지점은 향후 client 수요에 따라 추가할 수 있습니다.

transaction type에 따라 source/destination address 변화도 달라집니다. RAM address는 transfer마다 보통 증가하거나 감소하고 ring buffer에서는 `DMA_CYCLIC`으로 순환할 수 있습니다. FIFO 같은 device register address는 대개 고정됩니다.

Descriptor별 metadata 지원

일부 data movement architecture는 transaction과 연결된 metadata를 사용합니다. DMA controller는 payload와 metadata를 함께 전송합니다. metadata 자체는 DMA engine이 쓰지 않으며 peripheral에 전달하거나 peripheral에서 받은 parameter, key, vector 등을 담습니다.

DMAengine framework는 descriptor metadata를 위한 generic mechanism을 제공합니다. architecture에 따라 DMA driver가 한 mode 또는 둘 다 구현하고 client driver가 사용할 mode를 선택합니다.

• `DESC_METADATA_CLIENT`: client driver가 buffer를 할당·제공하고 `dmaengine_desc_attach_metadata()`로 descriptor에 연결합니다. `DMA_MEM_TO_DEV`와 `DEV_MEM_TO_MEM`에서는 payload와 함께 보낼 metadata를 hardware descriptor나 tightly coupled packet으로 준비합니다. `DMA_DEV_TO_MEM`에서는 completion을 알리기 전에 metadata를 client buffer로 복사하고, 완료 뒤에는 provider가 buffer를 건드리면 안 됩니다.
• `DESC_METADATA_ENGINE`: DMA driver가 buffer를 할당·관리합니다. client는 `dmaengine_desc_get_metadata_ptr()`로 pointer, 최대 크기, 현재 유효 크기를 얻어 직접 읽거나 쓰고 `dmaengine_desc_set_metadata_len()`으로 유효 byte 수를 알립니다. provider의 `get_metadata_ptr()`는 세 값을 반환해야 하고 `set_metadata_len()`은 client가 기록한 길이를 받습니다. `DMA_DEV_TO_MEM` client가 completion callback에서 pointer를 요청하므로 callback 전에는 descriptor를 해제하면 안 됩니다.

Device operation: resource와 descriptor 준비

`dma_device`에는 실제 logic을 구현하는 function pointer도 필요하며 어떤 function을 채울지는 보고한 transaction type에 따라 달라집니다.

• `device_alloc_chan_resources` / `device_free_chan_resources`: driver가 연결된 channel에 처음 `dma_request_channel()`을 호출하거나 마지막 `dma_release_channel()`을 호출할 때 실행됩니다. channel 사용에 필요한 resource를 할당·해제하며 sleep할 수 있습니다.
• `device_prep_dma_*`: 등록한 capability에 대응합니다. transfer buffer나 scatterlist를 받아 hardware descriptor 또는 descriptor list를 생성합니다. interrupt context에서 호출될 수 있으므로 allocation은 sleep과 emergency pool 고갈을 피하도록 `GFP_NOWAIT`를 써야 합니다. nowait allocator 부담을 줄이기 위해 probe 때 필요한 memory를 미리 할당하는 것이 좋습니다.
• prepare function은 transfer를 나타내는 unique `dma_async_tx_descriptor` instance를 반환해야 하며 `dma_async_tx_descriptor_init()`로 초기화할 수 있습니다.
• descriptor의 `flags`에는 원문에 driver가 수정할 수 있는지 argument flag를 그대로 써야 하는지에 대한 TODO가 남아 있습니다. `tx_submit`은 descriptor를 pending queue에 넣어 `issue_pending` 호출을 기다리는 provider function pointer입니다.
• submitter completion 통지는 `callback_result`로 초기화할 수 있습니다. 과거의 `callback`은 transaction status를 제공하지 않아 deprecated될 예정입니다. 전달되는 `dmaengine_result`의 `result`는 `dmaengine_tx_result`로 success 또는 error condition을 나타내고 `residue`는 지원되는 transfer의 남은 byte 수를 제공합니다.

Device operation: vector, issue와 status

• `device_prep_peripheral_dma_vec`: `device_prep_slave_sg`와 비슷하지만 장기적으로 scatterlist를 대체할 `dma_vec` 구조체 배열 pointer를 받습니다.
• `device_issue_pending`: pending queue의 첫 descriptor를 가져와 transfer를 시작하고 완료될 때마다 다음 transaction으로 이동합니다. interrupt context에서 호출될 수 있습니다.
• `device_tx_status`: 전달받은 transaction descriptor의 channel 잔여 byte를 보고해야 하며 channel의 현재 active descriptor를 기준으로 삼으면 안 됩니다. `tx_state`는 NULL일 수 있고 `dma_set_residue()`로 residue를 기록합니다. cyclic transfer에서는 cyclic buffer 전체 크기만 고려합니다. in-order completion을 지원하지 않고 out of order로 끝났다면 `DMA_OUT_OF_ORDER`를 반환합니다. interrupt context에서 호출될 수 있습니다.

Device operation: configuration과 channel control

• `device_config`: argument로 받은 `dma_slave_config`에 따라 channel을 재구성합니다. 현재 queue에 있거나 실행 중인 transfer에 동기적으로 적용하지 않고 이후 transfer에만 적용해야 합니다. 구조체의 `direction` field는 prepare function의 direction argument와 중복되어 deprecated되었습니다. slave operation에만 필수이며 memcpy에는 설정하거나 기대하면 안 됩니다. 둘 다 지원하는 driver도 slave에만 사용합니다.
• `device_pause`: channel transfer를 즉시 pause하는 synchronous operation입니다.
• `device_resume`: channel transfer를 즉시 resume하는 synchronous operation입니다.
• `device_terminate_all`: channel의 pending 및 ongoing transfer를 모두 abort하며 abort된 transfer의 completion callback은 호출하지 않습니다. atomic context나 descriptor completion callback 안에서 호출될 수 있으므로 sleep하면 안 됩니다. termination은 asynchronous일 수 있어 active transfer가 완전히 멈출 때까지 기다릴 의무는 없으며 `device_synchronize`와 함께 사용합니다.
• `device_synchronize`: channel termination을 current context와 synchronize합니다. 이전 descriptor memory에 controller가 더 이상 접근하지 않고, 이전 descriptor의 모든 completion callback이 끝났으며 새 callback이 schedule되지 않음을 보장해야 합니다. sleep할 수 있습니다.

기타 note: dependency, cookie와 dma_vec

다음 내용은 별도 위치가 정해지지 않은 추가 contract입니다.

• `dma_run_dependencies()`: async TX transfer 끝에 호출해 완료로 표시하기 전에 dependent operation이 실행되도록 합니다. slave transfer에서는 무시할 수 있습니다.
• `dma_cookie_t`: 시간이 지날수록 증가하는 DMA transaction ID입니다. 이를 추상화하는 `virt-dma`가 도입된 뒤에는 중요성이 줄었습니다.
• `dma_vec`: DMA address와 length를 담는 작은 구조체입니다.

DMA_CTRL_ACK와 descriptor 재사용

• `DMA_CTRL_ACK`가 clear이면 client가 receipt를 acknowledge해 dependency chain을 설정할 기회를 얻기 전까지 provider가 descriptor를 재사용할 수 없습니다. `async_tx_ack()`로 acknowledge할 수 있습니다. flag가 set이라고 해서 descriptor를 곧바로 재사용할 수 있다는 뜻은 아닙니다.
• `DMA_CTRL_REUSE`가 set이면 완료 뒤 descriptor를 재사용할 수 있고 provider는 이를 free하면 안 됩니다. `dmaengine_desc_set_reuse()`로 재사용을 준비하며 channel capability가 reusable descriptor를 지원할 때만 성공합니다.
• 따라서 DMA data가 사용되지 않아 두 transfer 사이 `dma_map_sg()`와 `dma_unmap_sg()`를 생략하려는 driver는 completion 직후 transfer를 resubmit할 수 있습니다.
• descriptor를 free하는 방법은 `dmaengine_desc_clear_reuse()`로 `DMA_CTRL_REUSE`를 clear한 뒤 마지막 transaction으로 submit하는 것, 이미 reuse flag가 set된 상태에서만 성공하는 `dmaengine_desc_free()`를 명시적으로 호출하는 것, channel을 terminate하는 것입니다.

DMA_PREP command, repeat와 load-at-EOT flag

• `DMA_PREP_CMD`: client가 DMA API로 전달한 data가 command data임을 controller에 알립니다. 해석은 controller별로 다르며 peripheral command, register read/write처럼 일반 data descriptor와 다른 format이 필요한 작업에 쓸 수 있습니다.
• `DMA_PREP_REPEAT`: transfer가 끝날 때 자동 반복합니다. 같은 channel에 `DMA_PREP_LOAD_EOT`를 설정한 새 transfer가 queue되면 교체됩니다. 다음 transfer에 LOAD_EOT가 없으면 client가 모든 transfer를 terminate할 때까지 현재 transfer를 반복합니다. channel이 `DMA_REPEAT` capability를 보고할 때만 지원됩니다.
• `DMA_PREP_LOAD_EOT`: 현재 실행 중인 transfer를 end of transfer에서 교체합니다. non-repeated transfer의 기본 behavior이므로 그런 transfer에 설정해도 차이가 없습니다. repeated transfer에서는 보통 모든 새 transfer에 설정해야 하며, 빠뜨리면 channel이 마지막 반복 transfer를 계속 실행하고 새 queue를 무시해 이전 transfer에 고정된 것처럼 보입니다. channel이 `DMA_LOAD_EOT` capability를 보고할 때만 지원됩니다.

General design note: transfer 사이 latency

많은 DMAEngine driver는 end-of-transfer interrupt를 handler에서 처리하지만, 이전 transfer가 끝난 뒤 새 transfer를 시작하는 일을 포함한 대부분의 처리를 tasklet로 미룹니다.

이 design은 transfer 사이 latency에 interrupt latency뿐 아니라 tasklet scheduling latency까지 더해 channel이 그동안 idle 상태가 되고 전체 transfer rate가 낮아집니다.

따라서 새 transfer를 tasklet에서 선택하지 말고 interrupt handler로 옮겨 피할 수 없는 idle window를 최대한 줄여야 합니다.

Glossary

• Burst: memory로 flush하기 전에 buffer에 queue할 수 있는 연속 read 또는 write operation 수입니다.
• Chunk: contiguous burst collection입니다.
• Transfer: contiguous 여부와 관계없이 chunk collection입니다.