Documentation/sound/designs/compress-accel.rst

   1 ==================================
   2 ALSA Co-processor Acceleration API
   3 ==================================
   4
   5 Jaroslav Kysela <perex@perex.cz>
   6
   7
   8 Overview
   9 ========
  10
  11 There is a requirement to expose the audio hardware that accelerates various
  12 tasks for user space such as sample rate converters, compressed
  13 stream decoders, etc.
  14
  15 This is description for the API extension for the compress ALSA API which
  16 is able to handle "tasks" that are not bound to real-time operations
  17 and allows for the serialization of operations.
  18
  19 Requirements
  20 ============
  21
  22 The main requirements are:
  23
  24 - serialization of multiple tasks for user space to allow multiple
  25   operations without user space intervention
  26
  27 - separate buffers (input + output) for each operation
  28
  29 - expose buffers using mmap to user space
  30
  31 - signal user space when the task is finished (standard poll mechanism)
  32
  33 Design
  34 ======
  35
  36 A new direction SND_COMPRESS_ACCEL is introduced to identify
  37 the passthrough API.
  38
  39 The API extension shares device enumeration and parameters handling from
  40 the main compressed API. All other realtime streaming ioctls are deactivated
  41 and a new set of task related ioctls are introduced. The standard
  42 read/write/mmap I/O operations are not supported in the passthrough device.
  43
  44 Device ("stream") state handling is reduced to OPEN/SETUP. All other
  45 states are not available for the passthrough mode.
  46
  47 Data I/O mechanism is using standard dma-buf interface with all advantages
  48 like mmap, standard I/O, buffer sharing etc. One buffer is used for the
  49 input data and second (separate) buffer is used for the output data. Each task
  50 have separate I/O buffers.
  51
  52 For the buffering parameters, the fragments means a limit of allocated tasks
  53 for given device. The fragment_size limits the input buffer size for the given
  54 device. The output buffer size is determined by the driver (may be different
  55 from the input buffer size).
  56
  57 State Machine
  58 =============
  59
  60 The passthrough audio stream state machine is described below::
  61
  62                                        +----------+
  63                                        |          |
  64                                        |   OPEN   |
  65                                        |          |
  66                                        +----------+
  67                                              |
  68                                              |
  69                                              | compr_set_params()
  70                                              |
  71                                              v
  72          all passthrough task ops      +----------+
  73   +------------------------------------|          |
  74   |                                    |   SETUP  |
  75   |                                    |
  76   |                                    +----------+
  77   |                                          |
  78   +------------------------------------------+
  79
  80
  81 Passthrough operations (ioctls)
  82 ===============================
  83
  84 All operations are protected using stream->device->lock (mutex).
  85
  86 CREATE
  87 ------
  88 Creates a set of input/output buffers. The input buffer size is
  89 fragment_size. Allocates unique seqno.
  90
  91 The hardware drivers allocate internal 'struct dma_buf' for both input and
  92 output buffers (using 'dma_buf_export()' function). The anonymous
  93 file descriptors for those buffers are passed to user space.
  94
  95 FREE
  96 ----
  97 Free a set of input/output buffers. If a task is active, the stop
  98 operation is executed before. If seqno is zero, operation is executed for all
  99 tasks.
 100
 101 START
 102 -----
 103 Starts (queues) a task. There are two cases of the task start - right after
 104 the task is created. In this case, origin_seqno must be zero.
 105 The second case is for reusing of already finished task. The origin_seqno
 106 must identify the task to be reused. In both cases, a new seqno value
 107 is allocated and returned to user space.
 108
 109 The prerequisite is that application filled input dma buffer with
 110 new source data and set input_size to pass the real data size to the driver.
 111
 112 The order of data processing is preserved (first started job must be
 113 finished at first).
 114
 115 If the multiple tasks require a state handling (e.g. resampling operation),
 116 the user space may set SND_COMPRESS_TFLG_NEW_STREAM flag to mark the
 117 start of the new stream data. It is useful to keep the allocated buffers
 118 for the new operation rather using open/close mechanism.
 119
 120 STOP
 121 ----
 122 Stop (dequeues) a task. If seqno is zero, operation is executed for all
 123 tasks.
 124
 125 STATUS
 126 ------
 127 Obtain the task status (active, finished). Also, the driver will set
 128 the real output data size (valid area in the output buffer).
 129
 130 Credits
 131 =======
 132 - Shengjiu Wang <shengjiu.wang@gmail.com>
 133 - Takashi Iwai <tiwai@suse.de>
 134 - Vinod Koul <vkoul@kernel.org>