From: Liam Girdwood Subject: [PATCH] ASoC documentation updates Date: Thu, 08 Feb 2007 15:57:01 +0000 Message-ID: <1170950221.4476.217.camel@localhost.localdomain> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-EigEHW2QP1mmWSecNKnS" Return-path: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: alsa-devel-bounces@lists.sourceforge.net Errors-To: alsa-devel-bounces@lists.sourceforge.net To: alsa-devel@lists.sourceforge.net List-Id: alsa-devel@alsa-project.org --=-EigEHW2QP1mmWSecNKnS Content-Type: text/plain Content-Transfer-Encoding: 7bit This patch updates the documentation for ASoC to reflect the recent changes in API between 0.12.x and 0.13.x Changes:- o Removed all reference to old API's. o Removed references and examples of automatic DAI config and matching. o Fixed 80 char line length on some files. Signed-off-by: Liam Girdwood --=-EigEHW2QP1mmWSecNKnS Content-Disposition: attachment; filename=asoc-docs.patch Content-Type: text/x-patch; name=asoc-docs.patch; charset=UTF-8 Content-Transfer-Encoding: 7bit diff -r 693e2a521575 Documentation/soc/DAI.txt --- a/Documentation/soc/DAI.txt Thu Feb 08 14:50:31 2007 +0100 +++ b/Documentation/soc/DAI.txt Thu Feb 08 15:39:07 2007 +0000 @@ -54,493 +54,3 @@ Common PCM operating modes:- o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC. o Mode B - MSB is transmitted on rising edge of FRAME/SYNC. - - -ASoC DAI Configuration -====================== - -Every CODEC DAI and SoC DAI must have their capabilities defined in order to -be configured together at runtime when the audio and clocking parameters are -known. This is achieved by creating an array of struct snd_soc_hw_mode in the -the CODEC and SoC interface drivers. Each element in the array describes a DAI -mode and each mode is usually based upon the DAI system clock to sample rate -ratio (FS). - -i.e. 48k sample rate @ 256 FS = sytem clock of 12.288 MHz - 48000 * 256 = 12288000 - -The CPU and Codec DAI modes are then ANDed together at runtime to determine the -rutime DAI configuration for both the Codec and CPU. - -When creating a new codec or SoC DAI it's probably best to start of with a few -sample rates first and then test your interface. - -struct snd_soc_dai_mode is defined (in soc.h) as:- - -/* SoC DAI mode */ -struct snd_soc_dai_mode { - u16 fmt; /* SND_SOC_DAIFMT_* */ - u16 tdm; /* SND_SOC_HWTDM_* */ - u64 pcmfmt; /* SNDRV_PCM_FMTBIT_* */ - u16 pcmrate; /* SND_SOC_HWRATE_* */ - u16 pcmdir:2; /* SND_SOC_HWDIR_* */ - u16 flags:8; /* hw flags */ - u16 fs; /* mclk to rate divider */ - u64 bfs; /* mclk to bclk dividers */ - unsigned long priv; /* private mode data */ -}; - -fmt: ----- -This field defines the DAI mode hardware format (e.g. I2S settings) and -supports the following settings:- - - 1) hardware DAI formats - -#define SND_SOC_DAIFMT_I2S (1 << 0) /* I2S mode */ -#define SND_SOC_DAIFMT_RIGHT_J (1 << 1) /* Right justified mode */ -#define SND_SOC_DAIFMT_LEFT_J (1 << 2) /* Left Justified mode */ -#define SND_SOC_DAIFMT_DSP_A (1 << 3) /* L data msb after FRM */ -#define SND_SOC_DAIFMT_DSP_B (1 << 4) /* L data msb during FRM */ -#define SND_SOC_DAIFMT_AC97 (1 << 5) /* AC97 */ - - 2) hw DAI signal inversions - -#define SND_SOC_DAIFMT_NB_NF (1 << 8) /* normal bit clock + frame */ -#define SND_SOC_DAIFMT_NB_IF (1 << 9) /* normal bclk + inv frm */ -#define SND_SOC_DAIFMT_IB_NF (1 << 10) /* invert bclk + nor frm */ -#define SND_SOC_DAIFMT_IB_IF (1 << 11) /* invert bclk + frm */ - - 3) hw clock masters - This is wrt the codec, the inverse is true for the interface - i.e. if the codec is clk and frm master then the interface is - clk and frame slave. - -#define SND_SOC_DAIFMT_CBM_CFM (1 << 12) /* codec clk & frm master */ -#define SND_SOC_DAIFMT_CBS_CFM (1 << 13) /* codec clk slave & frm master */ -#define SND_SOC_DAIFMT_CBM_CFS (1 << 14) /* codec clk master & frame slave */ -#define SND_SOC_DAIFMT_CBS_CFS (1 << 15) /* codec clk & frm slave */ - -At least one option from each section must be selected. Multiple selections are -also supported e.g. - - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_RIGHT_J | \ - SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_NB_IF | SND_SOC_DAIFMT_IB_NF | \ - SND_SOC_DAIFMT_IB_IF - - -tdm: ------- -This field defines the Time Division Multiplexing left and right word -positions for the DAI mode if applicable. Set to SND_SOC_DAITDM_LRDW(0,0) for -no TDM. - - -pcmfmt: ---------- -The hardware PCM format. This describes the PCM formats supported by the DAI -mode e.g. - - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \ - SNDRV_PCM_FORMAT_S24_3LE - -pcmrate: ----------- -The PCM sample rates supported by the DAI mode. e.g. - - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \ - SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \ - SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000 - - -pcmdir: ---------- -The stream directions supported by this mode. e.g. playback and capture - - -flags: --------- -The DAI hardware flags supported by the mode. - -/* use bfs mclk divider mode (BCLK = MCLK / x) */ -#define SND_SOC_DAI_BFS_DIV 0x1 -/* use bfs rate mulitplier (BCLK = RATE * x)*/ -#define SND_SOC_DAI_BFS_RATE 0x2 -/* use bfs rcw multiplier (BCLK = RATE * CHN * WORD SIZE) */ -#define SND_SOC_DAI_BFS_RCW 0x4 -/* capture and playback can use different clocks */ -#define SND_SOC_DAI_ASYNC 0x8 - -NOTE: Bitclock division and mulitiplication modes can be safely matched by the -core logic. - - -fs: ------ -The FS supported by this DAI mode FS is the ratio between the system clock and -the sample rate. See above - -bfs: ------- -BFS is the ratio of BCLK to MCLK or the ratio of BCLK to sample rate (this -depends on the codec or CPU DAI). - -The BFS supported by the DAI mode. This can either be the ratio between the -bitclock (BCLK) and the sample rate OR the ratio between the system clock and -the sample rate. Depends on the flags above. - -priv: ------ -private codec mode data. - - - -Examples -======== - -Note that Codec DAI and CPU DAI examples are interchangeable in these examples -as long as the bus master is reversed. i.e. - - SND_SOC_DAIFMT_CBM_CFM would become SND_SOC_DAIFMT_CBS_CFS - and vice versa. - -This applies to all SND_SOC_DAIFMT_CB*_CF*. - -Example 1 ---------- - -Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a -BCLK of either MCLK/2 or MCLK/4. - - /* codec master */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(2) | SND_SOC_FSBD(4), - } - - -Example 2 ---------- -Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a -BCLK of either Rate * 32 or Rate * 64. - - /* codec master */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = 256, - .bfs = 32, - }, - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = 256, - .bfs = 64, - }, - - -Example 3 ---------- -Codec that runs at 8k & 48k @ 256FS in master mode, can generate a BCLK that -is a multiple of Rate * channels * word size. (RCW) i.e. - - BCLK = 8000 * 2 * 16 (8k, stereo, 16bit) - = 256kHz - -This codecs supports a RCW multiple of 1,2 - - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RCW, - .fs = 256, - .bfs = SND_SOC_FSBW(1) | SND_SOC_FSBW(2), - } - - -Example 4 ---------- -Codec that only runs at 8k & 48k @ 256FS in master mode, can generate a -BCLK of either Rate * 32 or Rate * 64. Codec can also run in slave mode as long -as BCLK is rate * 32 or rate * 64. - - /* codec master */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = 256, - .bfs = 32, - }, - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = 256, - .bfs = 64, - }, - - /* codec slave */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmdir = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = SND_SOC_FS_ALL, - .bfs = 32, - }, - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmdir = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_RATE, - .fs = SND_SOC_FS_ALL, - .bfs = 64, - }, - - -Example 5 ---------- -Codec that only runs at 8k, 16k, 32k, 48k, 96k @ 128FS, 192FS & 256FS in master -mode and can generate a BCLK of MCLK / (1,2,4,8,16). Codec can also run in slave -mode as and does not care about FS or BCLK (as long as there is enough bandwidth). - - #define CODEC_FSB \ - (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \ - SND_SOC_FSBD(8) | SND_SOC_FSBD(16)) - - #define CODEC_RATES \ - (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_16000 | SNDRV_PCM_RATE_32000 |\ - SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_96000) - - /* codec master @ 128, 192 & 256 FS */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = CODEC_RATES, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 128, - .bfs = CODEC_FSB, - }, - - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = CODEC_RATES, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 192, - .bfs = CODEC_FSB - }, - - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = CODEC_RATES, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = CODEC_FSB, - }, - - /* codec slave */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = CODEC_RATES, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .fs = SND_SOC_FS_ALL, - .bfs = SND_SOC_FSB_ALL, - }, - - -Example 6 ---------- -Codec that only runs at 8k, 44.1k, 48k @ different FS in master mode (for use -with a fixed MCLK) and can generate a BCLK of MCLK / (1,2,4,8,16). -Codec can also run in slave mode as and does not care about FS or BCLK (as long -as there is enough bandwidth). Codec can support 16, 24 and 32 bit PCM sample -sizes. - - #define CODEC_FSB \ - (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \ - SND_SOC_FSBD(8) | SND_SOC_FSBD(16)) - - #define CODEC_PCM_FORMATS \ - (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \ - SNDRV_PCM_FORMAT_S24_3LE | SNDRV_PCM_FORMAT_S24_LE | SNDRV_PCM_FORMAT_S32_LE) - - /* codec master */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 1536, - .bfs = CODEC_FSB, - }, - - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_44100, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 272, - .bfs = CODEC_FSB, - }, - - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_48000, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = CODEC_FSB, - }, - - /* codec slave */ - { - .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FORMAT_S16_LE, - .pcmrate = CODEC_RATES, - .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, - .fs = SND_SOC_FS_ALL, - .bfs = SND_SOC_FSB_ALL, - }, - - -Example 7 ---------- -AC97 Codec that does not support VRA (i.e only runs at 48k). - - #define AC97_DIR \ - (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE) - - #define AC97_PCM_FORMATS \ - (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S18_3LE | \ - SNDRV_PCM_FORMAT_S20_3LE) - - /* AC97 with no VRA */ - { - .pcmfmt = AC97_PCM_FORMATS, - .pcmrate = SNDRV_PCM_RATE_48000, - } - - -Example 8 ---------- - -CPU DAI that supports 8k - 48k @ 256FS and BCLK = MCLK / 4 in master mode. -Slave mode (CPU DAI is FRAME master) supports 8k - 96k at any FS as long as -BCLK = 64 * rate. (Intel XScale I2S controller). - - #define PXA_I2S_DAIFMT \ - (SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_NB_NF) - - #define PXA_I2S_DIR \ - (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE) - - #define PXA_I2S_RATES \ - (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \ - SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \ - SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000) - - /* priv is divider */ - static struct snd_soc_dai_mode pxa2xx_i2s_modes[] = { - /* pxa2xx I2S frame and clock master modes */ - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_8000, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0x48, - }, - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_11025, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0x34, - }, - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_16000, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0x24, - }, - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_22050, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0x1a, - }, - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_44100, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0xd, - }, - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = SNDRV_PCM_RATE_48000, - .pcmdir = PXA_I2S_DIR, - .flags = SND_SOC_DAI_BFS_DIV, - .fs = 256, - .bfs = SND_SOC_FSBD(4), - .priv = 0xc, - }, - - /* pxa2xx I2S frame master and clock slave mode */ - { - .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBM_CFS, - .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE, - .pcmrate = PXA_I2S_RATES, - .pcmdir = PXA_I2S_DIR, - .fs = SND_SOC_FS_ALL, - .flags = SND_SOC_DAI_BFS_RATE, - .bfs = 64, - .priv = 0x48, - }, -}; diff -r 693e2a521575 Documentation/soc/clocking.txt --- a/Documentation/soc/clocking.txt Thu Feb 08 14:50:31 2007 +0100 +++ b/Documentation/soc/clocking.txt Thu Feb 08 14:21:48 2007 +0000 @@ -40,275 +40,12 @@ BCLK = LRC * x BCLK = LRC * Channels * Word Size -This relationship depends on the codec or SoC CPU in particular. ASoC can quite -easily match BCLK generated by division (SND_SOC_DAI_BFS_DIV) with BCLK by -multiplication (SND_SOC_DAI_BFS_RATE) or BCLK generated by -Rate * Channels * Word size (RCW or SND_SOC_DAI_BFS_RCW). +This relationship depends on the codec or SoC CPU in particular. In general +it's best to configure BCLK to the lowest possible speed (depending on your +rate, number of channels and wordsize) to save on power. +It's also desireable to use the codec (if possible) to drive (or master) the +audio clocks as it's usually gives more accurate sample rates than the CPU. -ASoC Clocking -------------- -The ASoC core determines the clocking for each particular configuration at -runtime. This is to allow for dynamic audio clocking wereby the audio clock is -variable and depends on the system state or device usage scenario. i.e. a voice -call requires slower clocks (and hence less power) than MP3 playback. -ASoC will call the config_sysclock() function for the target machine during the -audio parameters configuration. The function is responsible for then clocking -the machine audio subsytem and returning the audio clock speed to the core. -This function should also call the codec and cpu DAI clock_config() functions -to configure their respective internal clocking if required. - - -ASoC Clocking Control Flow --------------------------- - -The ASoC core will call the machine drivers config_sysclock() when most of the -DAI capabilities are known. The machine driver is then responsible for calling -the codec and/or CPU DAI drivers with the selected capabilities and the current -MCLK. Note that the machine driver is also resonsible for setting the MCLK (and -enabling it). - - (1) Match Codec and CPU DAI capabilities. At this point we have - matched the majority of the DAI fields and now need to make sure this - mode is currently clockable. - - (2) machine->config_sysclk() is now called with the matched DAI FS, sample - rate and BCLK master. This function then gets/sets the current audio - clock (depening on usage) and calls the codec and CPUI DAI drivers with - the FS, rate, BCLK master and MCLK. - - (3) Codec/CPU DAI config_sysclock(). This function checks that the FS, rate, - BCLK master and MCLK are acceptable for the codec or CPU DAI. It also - sets the DAI internal state to work with said clocks. - -The config_sysclk() functions for CPU, codec and machine should return the MCLK -on success and 0 on failure. - - -Examples (b = BCLK, l = LRC) -============================ - -Example 1 ---------- - -Simple codec that only runs at 48k @ 256FS in master mode. - -CPU only runs as slave DAI, however it generates a variable MCLK. - - -------- --------- - | | <----mclk--- | | - | Codec |b -----------> | CPU | - | |l -----------> | | - | | | | - -------- --------- - -The codec driver has the following config_sysclock() - - static unsigned int config_sysclk(struct snd_soc_codec_dai *dai, - struct snd_soc_clock_info *info, unsigned int clk) - { - /* make sure clock is 256 * rate */ - if(info->rate << 8 == clk) { - dai->mclk = clk; - return clk; - } - - return 0; - } - -The CPU I2S DAI driver has the following config_sysclk() - - static unsigned int config_sysclk(struct snd_soc_codec_dai *dai, - struct snd_soc_clock_info *info, unsigned int clk) - { - /* can we support this clk */ - if(set_audio_clk(clk) < 0) - return -EINVAL; - - dai->mclk = clk; - return dai->clk; - } - -The machine driver config_sysclk() in this example is as follows:- - - unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd, - struct snd_soc_clock_info *info) - { - int clk = info->rate * info->fs; - - /* check that CPU can deliver clock */ - if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0) - return -EINVAL; - - /* can codec work with this clock */ - return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk); - } - - -Example 2 ---------- - -Codec that can master at 8k and 48k at various FS (and hence supports a fixed -set of input MCLK's) and can also be slave at various FS . - -The CPU can master at 8k and 48k @256 FS and can be slave at any FS. - -MCLK is a 12.288MHz crystal on this machine. - - -------- --------- - | | <---xtal---> | | - | Codec |b <----------> | CPU | - | |l <----------> | | - | | | | - -------- --------- - - -The codec driver has the following config_sysclock() - - /* supported input clocks */ - const static int hifi_clks[] = {11289600, 12000000, 12288000, - 16934400, 18432000}; - - static unsigned int config_hsysclk(struct snd_soc_codec_dai *dai, - struct snd_soc_clock_info *info, unsigned int clk) - { - int i; - - /* is clk supported */ - for(i = 0; i < ARRAY_SIZE(hifi_clks); i++) { - if(clk == hifi_clks[i]) { - dai->mclk = clk; - return clk; - } - } - - /* this clk is not supported */ - return 0; - } - -The CPU I2S DAI driver has the following config_sysclk() - - static unsigned int config_sysclk(struct snd_soc_codec_dai *dai, - struct snd_soc_clock_info *info, unsigned int clk) - { - /* are we master or slave */ - if (info->bclk_master & - (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) { - - /* we can only master @ 256FS */ - if(info->rate << 8 == clk) { - dai->mclk = clk; - return dai->mclk; - } - } else { - /* slave we can run at any FS */ - dai->mclk = clk; - return dai->mclk; - } - - /* not supported */ - return dai->clk; - } - -The machine driver config_sysclk() in this example is as follows:- - - unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd, - struct snd_soc_clock_info *info) - { - int clk = 12288000; /* 12.288MHz */ - - /* who's driving the link */ - if (info->bclk_master & - (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) { - /* codec master */ - - /* check that CPU can work with clock */ - if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0) - return -EINVAL; - - /* can codec work with this clock */ - return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk); - } else { - /* cpu master */ - - /* check that codec can work with clock */ - if(rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk) < 0) - return -EINVAL; - - /* can CPU work with this clock */ - return rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk); - } - } - - - -Example 3 ---------- - -Codec that masters at 8k ... 48k @256 FS. Codec can also be slave and -doesn't care about FS. The codec has an internal PLL and dividers to generate -the necessary internal clocks (for 256FS). - -CPU can only be slave and doesn't care about FS. - -MCLK is a non controllable 13MHz clock from the CPU. - - - -------- --------- - | | <----mclk--- | | - | Codec |b <----------> | CPU | - | |l <----------> | | - | | | | - -------- --------- - -The codec driver has the following config_sysclock() - - /* valid PCM clock dividers * 2 */ - static int pcm_divs[] = {2, 6, 11, 4, 8, 12, 16}; - - static unsigned int config_vsysclk(struct snd_soc_codec_dai *dai, - struct snd_soc_clock_info *info, unsigned int clk) - { - int i, j, best_clk = info->fs * info->rate; - - /* can we run at this clk without the PLL ? */ - for (i = 0; i < ARRAY_SIZE(pcm_divs); i++) { - if ((best_clk >> 1) * pcm_divs[i] == clk) { - dai->pll_in = 0; - dai->clk_div = pcm_divs[i]; - dai->mclk = best_clk; - return dai->mclk; - } - } - - /* now check for PLL support */ - for (i = 0; i < ARRAY_SIZE(pll_div); i++) { - if (pll_div[i].pll_in == clk) { - for (j = 0; j < ARRAY_SIZE(pcm_divs); j++) { - if (pll_div[i].pll_out == pcm_divs[j] * (best_clk >> 1)) { - dai->pll_in = clk; - dai->pll_out = pll_div[i].pll_out; - dai->clk_div = pcm_divs[j]; - dai->mclk = best_clk; - return dai->mclk; - } - } - } - } - - /* this clk is not supported */ - return 0; - } - - -The CPU I2S DAI driver has the does not need a config_sysclk() as it can slave -at any FS. - - unsigned int config_sysclk(struct snd_soc_pcm_runtime *rtd, - struct snd_soc_clock_info *info) - { - /* codec has pll that generates mclk from 13MHz xtal */ - return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, 13000000); - } diff -r 693e2a521575 Documentation/soc/codec.txt --- a/Documentation/soc/codec.txt Thu Feb 08 14:50:31 2007 +0100 +++ b/Documentation/soc/codec.txt Thu Feb 08 14:21:48 2007 +0000 @@ -6,21 +6,18 @@ specific to the target platform or machi specific to the target platform or machine. All platform and machine specific code should be added to the platform and machine drivers respectively. -Each codec driver must provide the following features:- +Each codec driver *must* provide the following features:- - 1) Digital audio interface (DAI) description - 2) Digital audio interface configuration - 3) PCM's description - 4) Codec control IO - using I2C, 3 Wire(SPI) or both API's - 5) Mixers and audio controls - 6) Sysclk configuration - 7) Codec audio operations + 1) Codec DAI and PCM configuration + 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's + 3) Mixers and audio controls + 4) Codec audio operations Optionally, codec drivers can also provide:- - 8) DAPM description. - 9) DAPM event handler. -10) DAC Digital mute control. + 5) DAPM description. + 6) DAPM event handler. + 7) DAC Digital mute control. It's probably best to use this guide in conjuction with the existing codec driver code in sound/soc/codecs/ @@ -28,58 +25,47 @@ ASoC Codec driver breakdown ASoC Codec driver breakdown =========================== -1 - Digital Audio Interface (DAI) description ---------------------------------------------- -The DAI is a digital audio data transfer link between the codec and host SoC -CPU. It typically has data transfer capabilities in both directions -(playback and capture) and can run at a variety of different speeds. -Supported interfaces currently include AC97, I2S and generic PCM style links. -Please read DAI.txt for implementation information. - - -2 - Digital Audio Interface (DAI) configuration ------------------------------------------------ -DAI configuration is handled by the codec_pcm_prepare function and is -responsible for configuring and starting the DAI on the codec. This can be -called multiple times and is atomic. It can access the runtime parameters. - -This usually consists of a large function with numerous switch statements to -set up each configuration option. These options are set by the core at runtime. - - -3 - Codec PCM's ---------------- -Each codec must have it's PCM's defined. This defines the number of channels, -stream names, callbacks and codec name. It is also used to register the DAI -with the ASoC core. The PCM structure also associates the DAI capabilities with -the ALSA PCM. +1 - Codec DAI and PCM configuration +----------------------------------- +Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and +PCM's capablities and operations. This struct is exported so that it can be +registered with the core by your machine driver. e.g. -static struct snd_soc_pcm_codec wm8731_pcm_client = { +struct snd_soc_codec_dai wm8731_dai = { .name = "WM8731", + /* playback capabilities */ .playback = { .stream_name = "Playback", .channels_min = 1, .channels_max = 2, - }, + .rates = WM8731_RATES, + .formats = WM8731_FORMATS,}, + /* capture capabilities */ .capture = { .stream_name = "Capture", .channels_min = 1, .channels_max = 2, - }, - .config_sysclk = wm8731_config_sysclk, + .rates = WM8731_RATES, + .formats = WM8731_FORMATS,}, + /* pcm operations - see section 4 below */ .ops = { .prepare = wm8731_pcm_prepare, + .hw_params = wm8731_hw_params, + .shutdown = wm8731_shutdown, }, - .caps = { - .num_modes = ARRAY_SIZE(wm8731_hwfmt), - .modes = &wm8731_hwfmt[0], - }, + /* DAI operations - see DAI.txt */ + .dai_ops = { + .digital_mute = wm8731_mute, + .set_sysclk = wm8731_set_dai_sysclk, + .set_fmt = wm8731_set_dai_fmt, + } }; +EXPORT_SYMBOL_GPL(wm8731_dai); -4 - Codec control IO +2 - Codec control IO -------------------- The codec can ususally be controlled via an I2C or SPI style interface (AC97 combines control with data in the DAI). The codec drivers will have to provide @@ -104,7 +90,7 @@ read/write:- hw_read_t hw_read; -5 - Mixers and audio controls +3 - Mixers and audio controls ----------------------------- All the codec mixers and audio controls can be defined using the convenience macros defined in soc.h. @@ -143,28 +129,7 @@ Defines a stereo enumerated control Defines a stereo enumerated control -6 - System clock configuration. -------------------------------- -The system clock that drives the audio subsystem can change depending on sample -rate and the system power state. i.e. - -o Higher sample rates sometimes need a higher system clock. -o Low system power states can sometimes limit the available clocks. - -This function is a callback that the machine driver can call to set and -determine if the clock and sample rate combination is supported by the codec at -the present time (and system state). - -NOTE: If the codec has a PLL then it has a lot more flexability wrt clock and -sample rate combinations. - -Your config_sysclock function should return the MCLK if it's a valid -combination for your codec else 0; - -Please read clocking.txt now. - - -7 - Codec Audio Operations +4 - Codec Audio Operations -------------------------- The codec driver also supports the following alsa operations:- @@ -181,7 +146,7 @@ http://www.alsa-project.org/~iwai/writin http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm -8 - DAPM description. +5 - DAPM description. --------------------- The Dynamic Audio Power Management description describes the codec's power components, their relationships and registers to the ASoC core. Please read @@ -190,7 +155,7 @@ Please also see the examples in other co Please also see the examples in other codec drivers. -9 - DAPM event handler +6 - DAPM event handler ---------------------- This function is a callback that handles codec domain PM calls and system domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep @@ -210,7 +175,7 @@ Power states:- SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ -10 - Codec DAC digital mute control. +7 - Codec DAC digital mute control. ------------------------------------ Most codecs have a digital mute before the DAC's that can be used to minimise any system noise. The mute stops any digital data from entering the DAC. diff -r 693e2a521575 Documentation/soc/machine.txt --- a/Documentation/soc/machine.txt Thu Feb 08 14:50:31 2007 +0100 +++ b/Documentation/soc/machine.txt Thu Feb 08 14:21:48 2007 +0000 @@ -64,7 +64,7 @@ static struct snd_soc_dai_link corgi_dai .cpu_dai = &pxa_i2s_dai, .codec_dai = &wm8731_dai, .init = corgi_wm8731_init, - .config_sysclk = corgi_config_sysclk, + .ops = &corgi_ops, }; struct snd_soc_machine then sets up the machine with it's DAI's. e.g. @@ -74,7 +74,6 @@ static struct snd_soc_machine snd_soc_ma .name = "Corgi", .dai_link = &corgi_dai, .num_links = 1, - .ops = &corgi_ops, }; diff -r 693e2a521575 Documentation/soc/pops_clicks.txt --- a/Documentation/soc/pops_clicks.txt Thu Feb 08 14:50:31 2007 +0100 +++ b/Documentation/soc/pops_clicks.txt Thu Feb 08 14:21:48 2007 +0000 @@ -2,14 +2,14 @@ Audio Pops and Clicks ===================== Pops and clicks are unwanted audio artifacts caused by the powering up and down -of components within the audio subsystem. This is noticable on PC's when an audio -module is either loaded or unloaded (at module load time the sound card is +of components within the audio subsystem. This is noticable on PC's when an +audio module is either loaded or unloaded (at module load time the sound card is powered up and causes a popping noise on the speakers). -Pops and clicks can be more frequent on portable systems with DAPM. This is because -the components within the subsystem are being dynamically powered depending on -the audio usage and this can subsequently cause a small pop or click every time a -component power state is changed. +Pops and clicks can be more frequent on portable systems with DAPM. This is +because the components within the subsystem are being dynamically powered +depending on the audio usage and this can subsequently cause a small pop or +click every time a component power state is changed. Minimising Playback Pops and Clicks --=-EigEHW2QP1mmWSecNKnS Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier. Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 --=-EigEHW2QP1mmWSecNKnS Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Alsa-devel mailing list Alsa-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/alsa-devel --=-EigEHW2QP1mmWSecNKnS--