From 8e5336a14476e7350b0cf78a99541de6ed51655c Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 10 Nov 2016 22:11:21 +0100 Subject: ASoC: doc: ReSTize overview.txt A simple conversion from a plain text file. Created a new subdirectory, Documentation/sound/soc, for this and other ASoC documents. Since the index page contains the TOC, so "Documentation" section got removed from overview. Acked-by: Mark Brown Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/soc/overview.txt | 95 ------------------------------- Documentation/sound/index.rst | 1 + Documentation/sound/soc/index.rst | 10 ++++ Documentation/sound/soc/overview.rst | 69 ++++++++++++++++++++++ 4 files changed, 80 insertions(+), 95 deletions(-) delete mode 100644 Documentation/sound/alsa/soc/overview.txt create mode 100644 Documentation/sound/soc/index.rst create mode 100644 Documentation/sound/soc/overview.rst diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt deleted file mode 100644 index f3f28b7ae242..000000000000 --- a/Documentation/sound/alsa/soc/overview.txt +++ /dev/null @@ -1,95 +0,0 @@ -ALSA SoC Layer -============== - -The overall project goal of the ALSA System on Chip (ASoC) layer is to -provide better ALSA support for embedded system-on-chip processors (e.g. -pxa2xx, au1x00, iMX, etc) and portable audio codecs. Prior to the ASoC -subsystem there was some support in the kernel for SoC audio, however it -had some limitations:- - - * Codec drivers were often tightly coupled to the underlying SoC - CPU. This is not ideal and leads to code duplication - for example, - Linux had different wm8731 drivers for 4 different SoC platforms. - - * There was no standard method to signal user initiated audio events (e.g. - Headphone/Mic insertion, Headphone/Mic detection after an insertion - event). These are quite common events on portable devices and often require - machine specific code to re-route audio, enable amps, etc., after such an - event. - - * Drivers tended to power up the entire codec when playing (or - recording) audio. This is fine for a PC, but tends to waste a lot of - power on portable devices. There was also no support for saving - power via changing codec oversampling rates, bias currents, etc. - - -ASoC Design -=========== - -The ASoC layer is designed to address these issues and provide the following -features :- - - * Codec independence. Allows reuse of codec drivers on other platforms - and machines. - - * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC - interface and codec registers its audio interface capabilities with the - core and are subsequently matched and configured when the application - hardware parameters are known. - - * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to - its minimum power state at all times. This includes powering up/down - internal power blocks depending on the internal codec audio routing and any - active streams. - - * Pop and click reduction. Pops and clicks can be reduced by powering the - codec up/down in the correct sequence (including using digital mute). ASoC - signals the codec when to change power states. - - * Machine specific controls: Allow machines to add controls to the sound card - (e.g. volume control for speaker amplifier). - -To achieve all this, ASoC basically splits an embedded audio system into -multiple re-usable component drivers :- - - * Codec class drivers: The codec class driver is platform independent and - contains audio controls, audio interface capabilities, codec DAPM - definition and codec IO functions. This class extends to BT, FM and MODEM - ICs if required. Codec class drivers should be generic code that can run - on any architecture and machine. - - * Platform class drivers: The platform class driver includes the audio DMA - engine driver, digital audio interface (DAI) drivers (e.g. I2S, AC97, PCM) - and any audio DSP drivers for that platform. - - * Machine class driver: The machine driver class acts as the glue that - describes and binds the other component drivers together to form an ALSA - "sound card device". It handles any machine specific controls and - machine level audio events (e.g. turning on an amp at start of playback). - - -Documentation -============= - -The documentation is spilt into the following sections:- - -overview.txt: This file. - -codec.txt: Codec driver internals. - -DAI.txt: Description of Digital Audio Interface standards and how to configure -a DAI within your codec and CPU DAI drivers. - -dapm.txt: Dynamic Audio Power Management - -platform.txt: Platform audio DMA and DAI. - -machine.txt: Machine driver internals. - -pop_clicks.txt: How to minimise audio artifacts. - -clocking.txt: ASoC clocking for best power performance. - -jack.txt: ASoC jack detection. - -DPCM.txt: Dynamic PCM - Describes DPCM with DSP examples. diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 1f5d166f81c4..47b89f014e69 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -7,6 +7,7 @@ Linux Sound Subsystem Documentation kernel-api/index designs/index + soc/index alsa-configuration hd-audio/index cards/index diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst new file mode 100644 index 000000000000..e974fd9f38a3 --- /dev/null +++ b/Documentation/sound/soc/index.rst @@ -0,0 +1,10 @@ +============== +ALSA SoC Layer +============== + +The documentation is spilt into the following sections:- + +.. toctree:: + :maxdepth: 2 + + overview diff --git a/Documentation/sound/soc/overview.rst b/Documentation/sound/soc/overview.rst new file mode 100644 index 000000000000..dc8370bbfff6 --- /dev/null +++ b/Documentation/sound/soc/overview.rst @@ -0,0 +1,69 @@ +======================= +ALSA SoC Layer Overview +======================= + +The overall project goal of the ALSA System on Chip (ASoC) layer is to +provide better ALSA support for embedded system-on-chip processors (e.g. +pxa2xx, au1x00, iMX, etc) and portable audio codecs. Prior to the ASoC +subsystem there was some support in the kernel for SoC audio, however it +had some limitations:- + + * Codec drivers were often tightly coupled to the underlying SoC + CPU. This is not ideal and leads to code duplication - for example, + Linux had different wm8731 drivers for 4 different SoC platforms. + + * There was no standard method to signal user initiated audio events (e.g. + Headphone/Mic insertion, Headphone/Mic detection after an insertion + event). These are quite common events on portable devices and often require + machine specific code to re-route audio, enable amps, etc., after such an + event. + + * Drivers tended to power up the entire codec when playing (or + recording) audio. This is fine for a PC, but tends to waste a lot of + power on portable devices. There was also no support for saving + power via changing codec oversampling rates, bias currents, etc. + + +ASoC Design +=========== + +The ASoC layer is designed to address these issues and provide the following +features :- + + * Codec independence. Allows reuse of codec drivers on other platforms + and machines. + + * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC + interface and codec registers its audio interface capabilities with the + core and are subsequently matched and configured when the application + hardware parameters are known. + + * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to + its minimum power state at all times. This includes powering up/down + internal power blocks depending on the internal codec audio routing and any + active streams. + + * Pop and click reduction. Pops and clicks can be reduced by powering the + codec up/down in the correct sequence (including using digital mute). ASoC + signals the codec when to change power states. + + * Machine specific controls: Allow machines to add controls to the sound card + (e.g. volume control for speaker amplifier). + +To achieve all this, ASoC basically splits an embedded audio system into +multiple re-usable component drivers :- + + * Codec class drivers: The codec class driver is platform independent and + contains audio controls, audio interface capabilities, codec DAPM + definition and codec IO functions. This class extends to BT, FM and MODEM + ICs if required. Codec class drivers should be generic code that can run + on any architecture and machine. + + * Platform class drivers: The platform class driver includes the audio DMA + engine driver, digital audio interface (DAI) drivers (e.g. I2S, AC97, PCM) + and any audio DSP drivers for that platform. + + * Machine class driver: The machine driver class acts as the glue that + describes and binds the other component drivers together to form an ALSA + "sound card device". It handles any machine specific controls and + machine level audio events (e.g. turning on an amp at start of playback). -- cgit v1.2.3