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> 135