compress-accel.rst

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