1=========================
2ALSA Compress-Offload API
3=========================
4
5Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>
6
7Vinod Koul <vinod.koul@linux.intel.com>
8
9
10Overview
11========
12Since its early days, the ALSA API was defined with PCM support or
13constant bitrates payloads such as IEC61937 in mind. Arguments and
14returned values in frames are the norm, making it a challenge to
15extend the existing API to compressed data streams.
16
17In recent years, audio digital signal processors (DSP) were integrated
18in system-on-chip designs, and DSPs are also integrated in audio
19codecs. Processing compressed data on such DSPs results in a dramatic
20reduction of power consumption compared to host-based
21processing. Support for such hardware has not been very good in Linux,
22mostly because of a lack of a generic API available in the mainline
23kernel.
24
25Rather than requiring a compatibility break with an API change of the
26ALSA PCM interface, a new 'Compressed Data' API is introduced to
27provide a control and data-streaming interface for audio DSPs.
28
29The design of this API was inspired by the 2-year experience with the
30Intel Moorestown SOC, with many corrections required to upstream the
31API in the mainline kernel instead of the staging tree and make it
32usable by others.
33
34
35Requirements
36============
37The main requirements are:
38
39- separation between byte counts and time. Compressed formats may have
40  a header per file, per frame, or no header at all. The payload size
41  may vary from frame-to-frame. As a result, it is not possible to
42  estimate reliably the duration of audio buffers when handling
43  compressed data. Dedicated mechanisms are required to allow for
44  reliable audio-video synchronization, which requires precise
45  reporting of the number of samples rendered at any given time.
46
47- Handling of multiple formats. PCM data only requires a specification
48  of the sampling rate, number of channels and bits per sample. In
49  contrast, compressed data comes in a variety of formats. Audio DSPs
50  may also provide support for a limited number of audio encoders and
51  decoders embedded in firmware, or may support more choices through
52  dynamic download of libraries.
53
54- Focus on main formats. This API provides support for the most
55  popular formats used for audio and video capture and playback. It is
56  likely that as audio compression technology advances, new formats
57  will be added.
58
59- Handling of multiple configurations. Even for a given format like
60  AAC, some implementations may support AAC multichannel but HE-AAC
61  stereo. Likewise WMA10 level M3 may require too much memory and cpu
62  cycles. The new API needs to provide a generic way of listing these
63  formats.
64
65- Rendering/Grabbing only. This API does not provide any means of
66  hardware acceleration, where PCM samples are provided back to
67  user-space for additional processing. This API focuses instead on
68  streaming compressed data to a DSP, with the assumption that the
69  decoded samples are routed to a physical output or logical back-end.
70
71- Complexity hiding. Existing user-space multimedia frameworks all
72  have existing enums/structures for each compressed format. This new
73  API assumes the existence of a platform-specific compatibility layer
74  to expose, translate and make use of the capabilities of the audio
75  DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
76  applications are not supposed to make use of this API.
77
78
79Design
80======
81The new API shares a number of concepts with the PCM API for flow
82control. Start, pause, resume, drain and stop commands have the same
83semantics no matter what the content is.
84
85The concept of memory ring buffer divided in a set of fragments is
86borrowed from the ALSA PCM API. However, only sizes in bytes can be
87specified.
88
89Seeks/trick modes are assumed to be handled by the host.
90
91The notion of rewinds/forwards is not supported. Data committed to the
92ring buffer cannot be invalidated, except when dropping all buffers.
93
94The Compressed Data API does not make any assumptions on how the data
95is transmitted to the audio DSP. DMA transfers from main memory to an
96embedded audio cluster or to a SPI interface for external DSPs are
97possible. As in the ALSA PCM case, a core set of routines is exposed;
98each driver implementer will have to write support for a set of
99mandatory routines and possibly make use of optional ones.
100
101The main additions are
102
103get_caps
104  This routine returns the list of audio formats supported. Querying the
105  codecs on a capture stream will return encoders, decoders will be
106  listed for playback streams.
107
108get_codec_caps
109  For each codec, this routine returns a list of
110  capabilities. The intent is to make sure all the capabilities
111  correspond to valid settings, and to minimize the risks of
112  configuration failures. For example, for a complex codec such as AAC,
113  the number of channels supported may depend on a specific profile. If
114  the capabilities were exposed with a single descriptor, it may happen
115  that a specific combination of profiles/channels/formats may not be
116  supported. Likewise, embedded DSPs have limited memory and cpu cycles,
117  it is likely that some implementations make the list of capabilities
118  dynamic and dependent on existing workloads. In addition to codec
119  settings, this routine returns the minimum buffer size handled by the
120  implementation. This information can be a function of the DMA buffer
121  sizes, the number of bytes required to synchronize, etc, and can be
122  used by userspace to define how much needs to be written in the ring
123  buffer before playback can start.
124
125set_params
126  This routine sets the configuration chosen for a specific codec. The
127  most important field in the parameters is the codec type; in most
128  cases decoders will ignore other fields, while encoders will strictly
129  comply to the settings
130
131get_params
132  This routines returns the actual settings used by the DSP. Changes to
133  the settings should remain the exception.
134
135get_timestamp
136  The timestamp becomes a multiple field structure. It lists the number
137  of bytes transferred, the number of samples processed and the number
138  of samples rendered/grabbed. All these values can be used to determine
139  the average bitrate, figure out if the ring buffer needs to be
140  refilled or the delay due to decoding/encoding/io on the DSP.
141
142Note that the list of codecs/profiles/modes was derived from the
143OpenMAX AL specification instead of reinventing the wheel.
144Modifications include:
145- Addition of FLAC and IEC formats
146- Merge of encoder/decoder capabilities
147- Profiles/modes listed as bitmasks to make descriptors more compact
148- Addition of set_params for decoders (missing in OpenMAX AL)
149- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
150- Addition of format information for WMA
151- Addition of encoding options when required (derived from OpenMAX IL)
152- Addition of rateControlSupported (missing in OpenMAX AL)
153
154State Machine
155=============
156
157The compressed audio stream state machine is described below ::
158
159                                        +----------+
160                                        |          |
161                                        |   OPEN   |
162                                        |          |
163                                        +----------+
164                                             |
165                                             |
166                                             | compr_set_params()
167                                             |
168                                             v
169         compr_free()                  +----------+
170  +------------------------------------|          |
171  |                                    |   SETUP  |
172  |          +-------------------------|          |<-------------------------+
173  |          |       compr_write()     +----------+                          |
174  |          |                              ^                                |
175  |          |                              | compr_drain_notify()           |
176  |          |                              |        or                      |
177  |          |                              |     compr_stop()               |
178  |          |                              |                                |
179  |          |                         +----------+                          |
180  |          |                         |          |                          |
181  |          |                         |   DRAIN  |                          |
182  |          |                         |          |                          |
183  |          |                         +----------+                          |
184  |          |                              ^                                |
185  |          |                              |                                |
186  |          |                              | compr_drain()                  |
187  |          |                              |                                |
188  |          v                              |                                |
189  |    +----------+                    +----------+                          |
190  |    |          |    compr_start()   |          |        compr_stop()      |
191  |    | PREPARE  |------------------->|  RUNNING |--------------------------+
192  |    |          |                    |          |                          |
193  |    +----------+                    +----------+                          |
194  |          |                            |    ^                             |
195  |          |compr_free()                |    |                             |
196  |          |              compr_pause() |    | compr_resume()              |
197  |          |                            |    |                             |
198  |          v                            v    |                             |
199  |    +----------+                   +----------+                           |
200  |    |          |                   |          |         compr_stop()      |
201  +--->|   FREE   |                   |  PAUSE   |---------------------------+
202       |          |                   |          |
203       +----------+                   +----------+
204
205
206Gapless Playback
207================
208When playing thru an album, the decoders have the ability to skip the encoder
209delay and padding and directly move from one track content to another. The end
210user can perceive this as gapless playback as we don't have silence while
211switching from one track to another
212
213Also, there might be low-intensity noises due to encoding. Perfect gapless is
214difficult to reach with all types of compressed data, but works fine with most
215music content. The decoder needs to know the encoder delay and encoder padding.
216So we need to pass this to DSP. This metadata is extracted from ID3/MP4 headers
217and are not present by default in the bitstream, hence the need for a new
218interface to pass this information to the DSP. Also DSP and userspace needs to
219switch from one track to another and start using data for second track.
220
221The main additions are:
222
223set_metadata
224  This routine sets the encoder delay and encoder padding. This can be used by
225  decoder to strip the silence. This needs to be set before the data in the track
226  is written.
227
228set_next_track
229  This routine tells DSP that metadata and write operation sent after this would
230  correspond to subsequent track
231
232partial drain
233  This is called when end of file is reached. The userspace can inform DSP that
234  EOF is reached and now DSP can start skipping padding delay. Also next write
235  data would belong to next track
236
237Sequence flow for gapless would be:
238- Open
239- Get caps / codec caps
240- Set params
241- Set metadata of the first track
242- Fill data of the first track
243- Trigger start
244- User-space finished sending all,
245- Indicate next track data by sending set_next_track
246- Set metadata of the next track
247- then call partial_drain to flush most of buffer in DSP
248- Fill data of the next track
249- DSP switches to second track
250
251(note: order for partial_drain and write for next track can be reversed as well)
252
253Gapless Playback SM
254===================
255
256For Gapless, we move from running state to partial drain and back, along
257with setting of meta_data and signalling for next track ::
258
259
260                                        +----------+
261                compr_drain_notify()    |          |
262              +------------------------>|  RUNNING |
263              |                         |          |
264              |                         +----------+
265              |                              |
266              |                              |
267              |                              | compr_next_track()
268              |                              |
269              |                              V
270              |                         +----------+
271              |                         |          |
272              |                         |NEXT_TRACK|
273              |                         |          |
274              |                         +----------+
275              |                              |
276              |                              |
277              |                              | compr_partial_drain()
278              |                              |
279              |                              V
280              |                         +----------+
281              |                         |          |
282              +------------------------ | PARTIAL_ |
283                                        |  DRAIN   |
284                                        +----------+
285
286Not supported
287=============
288- Support for VoIP/circuit-switched calls is not the target of this
289  API. Support for dynamic bit-rate changes would require a tight
290  coupling between the DSP and the host stack, limiting power savings.
291
292- Packet-loss concealment is not supported. This would require an
293  additional interface to let the decoder synthesize data when frames
294  are lost during transmission. This may be added in the future.
295
296- Volume control/routing is not handled by this API. Devices exposing a
297  compressed data interface will be considered as regular ALSA devices;
298  volume changes and routing information will be provided with regular
299  ALSA kcontrols.
300
301- Embedded audio effects. Such effects should be enabled in the same
302  manner, no matter if the input was PCM or compressed.
303
304- multichannel IEC encoding. Unclear if this is required.
305
306- Encoding/decoding acceleration is not supported as mentioned
307  above. It is possible to route the output of a decoder to a capture
308  stream, or even implement transcoding capabilities. This routing
309  would be enabled with ALSA kcontrols.
310
311- Audio policy/resource management. This API does not provide any
312  hooks to query the utilization of the audio DSP, nor any preemption
313  mechanisms.
314
315- No notion of underrun/overrun. Since the bytes written are compressed
316  in nature and data written/read doesn't translate directly to
317  rendered output in time, this does not deal with underrun/overrun and
318  maybe dealt in user-library
319
320
321Credits
322=======
323- Mark Brown and Liam Girdwood for discussions on the need for this API
324- Harsha Priya for her work on intel_sst compressed API
325- Rakesh Ughreja for valuable feedback
326- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
327  demonstrating and quantifying the benefits of audio offload on a
328  real platform.
329