DMA Engine API Guide

DMA Engine Slave-DMA API 안내

이 문서는 Vinod Koul이 작성한 DMA Engine API 안내서입니다.

`async_tx`에서 DMA Engine을 사용하는 방법은 `Documentation/crypto/async-tx-api.rst`를 참조합니다.

아래 내용은 device driver 작성자가 DMA Engine의 Slave-DMA API를 사용하는 방법을 설명하며, slave DMA 용도에만 적용됩니다.

Slave DMA 사용 절차

slave DMA 사용은 다음 단계로 구성됩니다.

• DMA slave channel을 할당합니다.
• slave와 controller별 parameter를 설정합니다.
• transaction descriptor를 얻습니다.
• transaction을 submit합니다.
• pending request를 issue하고 callback notification을 기다립니다.

각 동작의 세부 내용은 다음과 같습니다.

1. DMA slave channel 할당

slave DMA 문맥에서 channel 할당은 조금 다릅니다. client driver는 보통 특정 DMA controller의 channel이 필요하고, 경우에 따라서는 특정 channel 자체가 필요합니다. channel 요청에는 `dma_request_chan()` API를 사용합니다.

Interface:

.. code-block:: c

   struct dma_chan *dma_request_chan(struct device *dev, const char *name);

이 함수는 `dev` device와 연결된 이름 `name`의 DMA channel을 찾아 반환합니다. 연결 관계는 DT, ACPI 또는 board file 기반 `dma_slave_map` matching table로 정의됩니다.

이 interface로 할당한 channel은 `dma_release_channel()`을 호출할 때까지 호출자가 독점합니다.

2. Slave와 controller parameter 설정

다음 단계에서는 항상 DMA driver에 구체적인 정보를 전달합니다. slave DMA가 사용할 수 있는 대부분의 generic 정보는 `struct dma_slave_config`에 들어 있습니다. client는 이 구조체로 peripheral의 DMA direction, DMA address, bus width, DMA burst length 등을 지정할 수 있습니다.

DMA controller에 추가 parameter가 필요하다면 controller별 구조체 안에 `struct dma_slave_config`를 포함하는 방식을 권장합니다. 그러면 필요할 때 client가 더 많은 parameter를 전달할 수 있습니다.

Interface:

.. code-block:: c

   int dmaengine_slave_config(struct dma_chan *chan,
                     struct dma_slave_config *config)

각 member의 자세한 설명은 `dmaengine.h`의 `dma_slave_config` 구조체 정의를 참조합니다. `direction` member는 prepare 호출에 이미 전달되는 direction과 중복되므로 향후 제거될 예정입니다.

3. Transaction descriptor 준비

slave 용도로 DMA-engine이 지원하는 slave transfer mode는 다음과 같습니다.

• `slave_sg`: scatter-gather buffer 목록을 peripheral에서 또는 peripheral로 DMA합니다.
• `peripheral_dma_vec`: scatter-gather buffer 배열을 peripheral에서 또는 peripheral로 DMA합니다. `slave_sg`와 비슷하지만 scatterlist 대신 `dma_vec` 구조체 배열을 사용합니다.
• `dma_cyclic`: 명시적으로 중지할 때까지 peripheral에서 또는 peripheral로 cyclic DMA operation을 수행합니다.
• `interleaved_dma`: Slave client와 M2M client가 함께 사용하는 mode입니다. slave에서는 device FIFO address를 driver가 이미 알고 있을 수 있습니다. `dma_interleaved_template` member에 적절한 값을 넣어 여러 operation을 표현합니다. channel이 지원한다면 `DMA_PREP_REPEAT` transfer flag를 설정해 cyclic interleaved DMA transfer도 수행할 수 있습니다.

이 transfer API가 NULL이 아닌 값을 반환하면 해당 transaction의 descriptor를 뜻합니다.

Interface:

.. code-block:: c

   struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
              struct dma_chan *chan, struct scatterlist *sgl,
              unsigned int sg_len, enum dma_data_direction direction,
              unsigned long flags);

   struct dma_async_tx_descriptor *dmaengine_prep_peripheral_dma_vec(
              struct dma_chan *chan, const struct dma_vec *vecs,
              size_t nents, enum dma_data_direction direction,
              unsigned long flags);

   struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
              struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
              size_t period_len, enum dma_data_direction direction);

   struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
              struct dma_chan *chan, struct dma_interleaved_template *xt,
              unsigned long flags);

peripheral driver는 `dmaengine_prep_slave_sg()`를 호출하기 전에 DMA operation용 scatterlist를 mapping해야 하며, DMA operation이 완료될 때까지 mapping을 유지해야 합니다. scatterlist는 DMA struct device를 사용해 mapping해야 합니다. 나중에 mapping을 synchronize해야 한다면 `dma_sync_*_for_*()`도 같은 DMA struct device로 호출해야 합니다. 일반적인 설정은 다음과 같습니다.

.. code-block:: c

   struct device *dma_dev = dmaengine_get_dma_device(chan);

   nr_sg = dma_map_sg(dma_dev, sgl, sg_len);
      if (nr_sg == 0)
              /* error */

      desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags);

descriptor를 얻은 뒤 callback 정보를 추가하고 descriptor를 submit해야 합니다. 일부 DMA engine driver는 prepare 성공부터 submit 사이에 spinlock을 유지할 수 있으므로 두 operation을 가깝게 연속해서 수행하는 것이 중요합니다.

`async_tx` API에서는 completion callback이 새 operation을 submit할 수 없다고 규정하지만 slave/cyclic DMA에는 이 제한이 적용되지 않습니다.

• slave DMA에서는 callback이 호출되기 전까지 다음 transaction을 submit할 수 없는 경우가 있으므로 callback에서 새 transaction을 prepare하고 submit할 수 있습니다.
• cyclic DMA callback에서는 `dmaengine_terminate_async()`로 DMA를 종료할 수 있습니다.
• callback이 다시 DMA API를 호출해 deadlock을 만들 수 있으므로 DMA engine driver는 callback을 부르기 전에 모든 lock을 해제해야 합니다.
• callback은 항상 DMA engine의 tasklet에서 실행되며 interrupt context에서는 절대 실행되지 않습니다.

선택 사항: descriptor별 metadata

DMAengine은 metadata를 두 방식으로 지원합니다.

`DESC_METADATA_CLIENT`에서는 client driver가 metadata buffer를 할당하거나 제공하고 descriptor에 연결합니다.

.. code-block:: c

   int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc,
                                 void *data, size_t len);

`DESC_METADATA_ENGINE`에서는 DMA driver가 metadata buffer를 할당하고 관리합니다. client driver는 metadata pointer, 최대 크기, 현재 사용 크기를 요청하고 해당 영역을 직접 갱신하거나 읽을 수 있습니다.

DMA driver가 metadata memory area를 관리하므로 client는 해당 descriptor의 transfer completion callback이 실행된 뒤에는 영역에 접근하거나 pointer를 얻어서는 안 됩니다. completion callback이 정의되지 않았다면 `issue_pending` 뒤에 metadata에 접근하면 안 됩니다. 즉 transfer 완료 뒤 metadata를 되읽으려면 client가 반드시 completion callback을 사용해야 합니다.

.. code-block:: c

   void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc,
              size_t *payload_len, size_t *max_len);

   int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc,
              size_t payload_len);

Client drivers can query if a given mode is supported with:

.. code-block:: c

   bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan,
              enum dma_desc_metadata_mode mode);

client driver는 `dmaengine_is_metadata_mode_supported()`로 mode 지원 여부를 조회할 수 있습니다.

사용하는 mode에 따라 client driver가 따라야 할 흐름이 다릅니다.

• `DESC_METADATA_CLIENT`, `DMA_MEM_TO_DEV` / `DEV_MEM_TO_MEM`: descriptor를 prepare하고 client buffer에 metadata를 만든 다음 `dmaengine_desc_attach_metadata()`로 buffer를 연결하고 transfer를 submit합니다.
• `DESC_METADATA_CLIENT`, `DMA_DEV_TO_MEM`: descriptor를 prepare하고 buffer를 연결한 뒤 submit합니다. transfer가 완료되면 연결한 buffer에서 metadata를 사용할 수 있습니다.
• `DESC_METADATA_ENGINE`, `DMA_MEM_TO_DEV` / `DEV_MEM_TO_MEM`: descriptor를 prepare하고 `dmaengine_desc_get_metadata_ptr()`로 engine metadata area pointer를 얻어 내용을 갱신합니다. `dmaengine_desc_set_metadata_len()`으로 client가 넣은 양을 알린 뒤 transfer를 submit합니다.
• `DESC_METADATA_ENGINE`, `DMA_DEV_TO_MEM`: descriptor를 prepare하고 submit합니다. transfer completion 시 `dmaengine_desc_get_metadata_ptr()`로 engine metadata area pointer를 얻어 metadata를 읽습니다.

`DESC_METADATA_ENGINE` mode에서 descriptor metadata area는 transfer 완료 뒤 더 이상 유효하지 않습니다. completion callback을 사용했다면 callback이 반환할 때까지만 유효합니다.

한 descriptor에서 `DESC_METADATA_CLIENT`와 `DESC_METADATA_ENGINE`을 섞어 사용할 수 없습니다. client driver는 descriptor마다 둘 중 하나의 mode만 사용해야 합니다.

4. Transaction submit

descriptor를 prepare하고 callback 정보를 추가했으면 DMA engine driver의 pending queue에 넣어야 합니다.

Interface:

.. code-block:: c

   dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)

반환되는 `dma_cookie_t` cookie는 이 문서에서 다루지 않는 다른 DMA engine 호출로 DMA engine activity의 진행 상태를 확인할 때 사용할 수 있습니다.

`dmaengine_submit()`은 DMA operation을 시작하지 않고 pending queue에 추가하기만 합니다. 시작은 5단계의 `dma_async_issue_pending`을 참조합니다.

`dmaengine_submit()` 호출 뒤 submit한 `struct dma_async_tx_descriptor`는 DMA engine 소유가 됩니다. 따라서 client는 해당 descriptor pointer를 무효한 것으로 간주해야 합니다.

5. Pending request 실행과 callback 대기

pending queue의 transaction은 issue_pending API를 호출해 활성화합니다. channel이 idle이면 queue의 첫 transaction이 시작되고 이후 transaction은 대기열에 남습니다.

각 DMA operation이 완료되면 queue의 다음 operation이 시작되고 tasklet이 trigger됩니다. completion callback을 설정했다면 tasklet이 client driver의 callback routine을 호출해 완료를 알립니다.

Interface:

.. code-block:: c

   void dma_async_issue_pending(struct dma_chan *chan);

추가 API 1. Terminate

Terminate interface는 다음과 같습니다.

.. code-block:: c

   int dmaengine_terminate_sync(struct dma_chan *chan)
   int dmaengine_terminate_async(struct dma_chan *chan)
   int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */

이 API는 DMA channel의 모든 activity를 중지하며, 아직 완전히 전송되지 않은 DMA FIFO data를 버릴 수 있습니다. 완료되지 않은 transfer의 callback은 호출되지 않습니다.

이 기능에는 두 variant가 있습니다.

• `dmaengine_terminate_async()`는 DMA가 완전히 멈추거나 실행 중인 completion callback이 끝날 때까지 기다리지 않을 수 있습니다. 대신 atomic context 또는 completion callback 안에서 호출할 수 있습니다. DMA transfer가 접근한 memory나 completion callback이 접근한 resource를 해제하기 전에 반드시 `dmaengine_synchronize()`를 호출해야 합니다.
• `dmaengine_terminate_sync()`는 transfer와 실행 중인 completion callback이 끝날 때까지 기다린 뒤 반환합니다. atomic context나 completion callback 안에서는 호출하면 안 됩니다.
• `dmaengine_terminate_all()`은 deprecated되었으므로 새 code에서 사용하면 안 됩니다.

추가 API 2-3. Pause와 resume

Pause interface:

.. code-block:: c

   int dmaengine_pause(struct dma_chan *chan)

`dmaengine_pause()`는 data 손실 없이 DMA channel activity를 일시 중지합니다.

Resume interface:

.. code-block:: c

    int dmaengine_resume(struct dma_chan *chan)

`dmaengine_resume()`은 이전에 일시 중지한 DMA channel을 재개합니다. 현재 pause 상태가 아닌 channel을 resume하는 것은 잘못된 사용입니다.

추가 API 4. Transaction 완료 확인

Interface:

.. code-block:: c

   enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
             dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used)

`dma_async_is_tx_complete()`는 channel 상태를 확인하는 데 사용할 수 있습니다. 더 자세한 설명은 `include/linux/dmaengine.h` 문서를 참조합니다.

이 API를 `dma_async_is_complete()` 및 `dmaengine_submit()`이 반환한 cookie와 함께 사용하면 특정 DMA transaction의 완료 여부를 확인할 수 있습니다.

모든 DMA engine driver가 실행 중인 DMA channel에 대해 신뢰할 수 있는 정보를 반환하는 것은 아닙니다. 이 API를 쓰기 전에 DMA engine 사용자가 channel을 pause하거나 `dmaengine_terminate_all()`로 중지하는 것을 권장합니다.

추가 API 5. Termination synchronize

Interface:

.. code-block:: c

   void dmaengine_synchronize(struct dma_chan *chan)

`dmaengine_synchronize()`는 DMA channel termination을 현재 context와 synchronize합니다.

`dmaengine_terminate_async()` 뒤에 이 함수를 사용해야 합니다. 함수는 transfer와 실행 중인 completion callback이 끝날 때까지 기다린 뒤 반환합니다.

`dmaengine_terminate_async()`로 DMA channel을 중지했다면 이전에 submit한 descriptor가 접근한 memory 또는 이전 completion callback이 접근한 resource를 안전하게 해제하기 전에 이 함수를 반드시 호출해야 합니다.

`dmaengine_terminate_async()`와 이 함수 사이에 `dma_async_issue_pending()`을 호출하면 동작은 정의되지 않습니다.