ALSA: doc: ReSTize compress-offload document

		compress_offload.txt

=========================

		=====================

ALSA Compress-Offload API

=========================

Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>

Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>

Vinod Koul <vinod.koul@linux.intel.com>

Vinod Koul <vinod.koul@linux.intel.com>

Overview

Overview

========

Since its early days, the ALSA API was defined with PCM support or

Since its early days, the ALSA API was defined with PCM support or

constant bitrates payloads such as IEC61937 in mind. Arguments and

constant bitrates payloads such as IEC61937 in mind. Arguments and

returned values in frames are the norm, making it a challenge to

returned values in frames are the norm, making it a challenge to

API in the mainline kernel instead of the staging tree and make it

API in the mainline kernel instead of the staging tree and make it

usable by others.

usable by others.

Requirements

Requirements

============

The main requirements are:

The main requirements are:

- separation between byte counts and time. Compressed formats may have

- separation between byte counts and time. Compressed formats may have

Design

Design

======

The new API shares a number of concepts with the PCM API for flow

The new API shares a number of concepts with the PCM API for flow

control. Start, pause, resume, drain and stop commands have the same

control. Start, pause, resume, drain and stop commands have the same

semantics no matter what the content is.

semantics no matter what the content is.

The main additions are

The main additions are

- get_caps

get_caps

  This routine returns the list of audio formats supported. Querying the

  This routine returns the list of audio formats supported. Querying the

  codecs on a capture stream will return encoders, decoders will be

  codecs on a capture stream will return encoders, decoders will be

  listed for playback streams.

  listed for playback streams.

- get_codec_caps For each codec, this routine returns a list of

get_codec_caps

  For each codec, this routine returns a list of

  capabilities. The intent is to make sure all the capabilities

  capabilities. The intent is to make sure all the capabilities

  correspond to valid settings, and to minimize the risks of

  correspond to valid settings, and to minimize the risks of

  configuration failures. For example, for a complex codec such as AAC,

  configuration failures. For example, for a complex codec such as AAC,

  used by userspace to define how much needs to be written in the ring

  used by userspace to define how much needs to be written in the ring

  buffer before playback can start.

  buffer before playback can start.

- set_params

set_params

  This routine sets the configuration chosen for a specific codec. The

  This routine sets the configuration chosen for a specific codec. The

  most important field in the parameters is the codec type; in most

  most important field in the parameters is the codec type; in most

  cases decoders will ignore other fields, while encoders will strictly

  cases decoders will ignore other fields, while encoders will strictly

  comply to the settings

  comply to the settings

- get_params

get_params

  This routines returns the actual settings used by the DSP. Changes to

  This routines returns the actual settings used by the DSP. Changes to

  the settings should remain the exception.

  the settings should remain the exception.

- get_timestamp

get_timestamp

  The timestamp becomes a multiple field structure. It lists the number

  The timestamp becomes a multiple field structure. It lists the number

  of bytes transferred, the number of samples processed and the number

  of bytes transferred, the number of samples processed and the number

  of samples rendered/grabbed. All these values can be used to determine

  of samples rendered/grabbed. All these values can be used to determine

- Addition of encoding options when required (derived from OpenMAX IL)

- Addition of encoding options when required (derived from OpenMAX IL)

- Addition of rateControlSupported (missing in OpenMAX AL)

- Addition of rateControlSupported (missing in OpenMAX AL)

Gapless Playback

Gapless Playback

================

================

When playing thru an album, the decoders have the ability to skip the encoder

When playing thru an album, the decoders have the ability to skip the encoder

The main additions are:

The main additions are:

- set_metadata

set_metadata

  This routine sets the encoder delay and encoder padding. This can be used by

  This routine sets the encoder delay and encoder padding. This can be used by

  decoder to strip the silence. This needs to be set before the data in the track

  decoder to strip the silence. This needs to be set before the data in the track

  is written.

  is written.

- set_next_track

set_next_track

  This routine tells DSP that metadata and write operation sent after this would

  This routine tells DSP that metadata and write operation sent after this would

  correspond to subsequent track

  correspond to subsequent track

- partial drain

partial drain

  This is called when end of file is reached. The userspace can inform DSP that

  This is called when end of file is reached. The userspace can inform DSP that

  EOF is reached and now DSP can start skipping padding delay. Also next write

  EOF is reached and now DSP can start skipping padding delay. Also next write

  data would belong to next track

  data would belong to next track

- then call partial_drain to flush most of buffer in DSP

- then call partial_drain to flush most of buffer in DSP

- Fill data of the next track

- Fill data of the next track

- DSP switches to second track

- DSP switches to second track

(note: order for partial_drain and write for next track can be reversed as well)

(note: order for partial_drain and write for next track can be reversed as well)

Not supported:

Not supported

=============

- Support for VoIP/circuit-switched calls is not the target of this

- Support for VoIP/circuit-switched calls is not the target of this

  API. Support for dynamic bit-rate changes would require a tight

  API. Support for dynamic bit-rate changes would require a tight

  coupling between the DSP and the host stack, limiting power savings.

  coupling between the DSP and the host stack, limiting power savings.

  rendered output in time, this does not deal with underrun/overrun and

  rendered output in time, this does not deal with underrun/overrun and

  maybe dealt in user-library

  maybe dealt in user-library

Credits:

Credits

=======

- Mark Brown and Liam Girdwood for discussions on the need for this API

- Mark Brown and Liam Girdwood for discussions on the need for this API

- Harsha Priya for her work on intel_sst compressed API

- Harsha Priya for her work on intel_sst compressed API

- Rakesh Ughreja for valuable feedback

- Rakesh Ughreja for valuable feedback

   control-names

   control-names

   channel-mapping-api

   channel-mapping-api

   compress-offload

   procfile

   procfile

   powersave

   powersave

   oss-emulation

   oss-emulation