src/vlib/dma/dma.rst

   1 .. _dma_plugin:
   2
   3 .. toctree::
   4
   5 DMA plugin
   6 ==========
   7
   8 Overview
   9 --------
  10 This plugin utilize platform DMA accelerators like CBDMA/DSA for streaming
  11 data movement. Modern DMA accelerators has high memory bandwidth and benefit
  12 cross-numa traffic. Accelerator like DSA has the capability to do IO page
  13 fault recovery, it will save IOMMU setup for the memory which not pinned.
  14
  15 Terminology & Usage
  16 -------------------
  17
  18 A ``backend`` is the abstract of resource which inherited from DMA device,
  19 it support necessary operations for DMA offloading like configuration, DMA
  20 request and result query.
  21
  22 A ``config`` is the abstract of application DMA capability. Application can
  23 request a config instance through DMA node. DMA node will check the
  24 requirements of application and bind suitable backend with it.
  25
  26 Enable DSA work queue:
  27 ----------------------
  28
  29 .. code-block:: console
  30   # configure 1 groups, each with one engine
  31   accel-config config-engine dsa0/engine0.0 --group-id=0
  32
  33   # configure 1 queues, putting each in a different group, so each
  34   # is backed by a single engine
  35   accel-config config-wq dsa0/wq0.0 --group-id=0 --type=user  \
  36     --priority=10 --max-batch-size=1024 --mode=dedicated -b 1 -a 0 --name=vpp1
  37
  38 DMA transfer:
  39 -------------
  40
  41 In this sample, application will request DMA capability which can hold
  42 a batch contained maximum 256 transfers and each transfer hold maximum 4K bytes
  43 from DMA node. If config_index value is not negative, mean resource has
  44 been allocated and DMA engine is ready for serve.
  45
  46 .. code-block:: console
  47   void dma_completion_cb (vlib_main_t *vm, vlib_dma_batch_t *b);
  48
  49   vlib_dma_config_args_t args;
  50   args->max_transfers = 256;
  51   args->max_transfer_size = 4096;
  52   args->cpu_fallback = 1;
  53   args->barrier_before_last = 1;
  54   args->cb = dma_completion_cb;
  55   u32 config_index = vlib_dma_config (vm, &args);
  56   if (config_index < 0)
  57     return;
  58
  59   u8 *dst[n_transfers];
  60   u8 *src[n_transfers];
  61   u32 i = 0, size = 4096;
  62
  63   vlib_dma_batch_t *b;
  64   b = vlib_dma_batch_new (vm, config_index);
  65   while (wrk_t->config_index >= 0 && n_transfers) {
  66     vlib_dma_batch_add (vm, b, dst[i], src[i], size);
  67     n_transfers --;
  68     i ++;
  69   }
  70   vlib_dma_batch_submit (vm, config_index);