Documentation/sound/alsa/soc/codec.txt

   1 ASoC Codec Driver
   2 =================
   3
   4 The codec driver is generic and hardware independent code that configures the
   5 codec to provide audio capture and playback. It should contain no code that is
   6 specific to the target platform or machine. All platform and machine specific
   7 code should be added to the platform and machine drivers respectively.
   8
   9 Each codec driver must provide the following features:-
  10
  11  1) Digital audio interface (DAI) description
  12  2) Digital audio interface configuration
  13  3) PCM's description
  14  4) Codec control IO - using I2C, 3 Wire(SPI) or both API's
  15  5) Mixers and audio controls
  16  6) Sysclk configuration
  17  7) Codec audio operations
  18
  19 Optionally, codec drivers can also provide:-
  20
  21  8) DAPM description.
  22  9) DAPM event handler.
  23 10) DAC Digital mute control.
  24
  25 It's probably best to use this guide in conjuction with the existing codec
  26 driver code in sound/soc/codecs/
  27
  28 ASoC Codec driver breakdown
  29 ===========================
  30
  31 1 - Digital Audio Interface (DAI) description
  32 ---------------------------------------------
  33 The DAI is a digital audio data transfer link between the codec and host SoC
  34 CPU. It typically has data transfer capabilities in both directions
  35 (playback and capture) and can run at a variety of different speeds.
  36 Supported interfaces currently include AC97, I2S and generic PCM style links.
  37 Please read DAI.txt for implementation information.
  38
  39
  40 2 - Digital Audio Interface (DAI) configuration
  41 -----------------------------------------------
  42 DAI configuration is handled by the codec_pcm_prepare function and is
  43 responsible for configuring and starting the DAI on the codec. This can be
  44 called multiple times and is atomic. It can access the runtime parameters.
  45
  46 This usually consists of a large function with numerous switch statements to
  47 set up each configuration option. These options are set by the core at runtime.
  48
  49
  50 3 - Codec PCM's
  51 ---------------
  52 Each codec must have it's PCM's defined. This defines the number of channels,
  53 stream names, callbacks and codec name. It is also used to register the DAI
  54 with the ASoC core. The PCM structure also associates the DAI capabilities with
  55 the ALSA PCM.
  56
  57 e.g.
  58
  59 static struct snd_soc_pcm_codec wm8731_pcm_client = {
  60         .name = "WM8731",
  61         .playback = {
  62                 .stream_name = "Playback",
  63                 .channels_min = 1,
  64                 .channels_max = 2,
  65         },
  66         .capture = {
  67                 .stream_name = "Capture",
  68                 .channels_min = 1,
  69                 .channels_max = 2,
  70         },
  71         .config_sysclk = wm8731_config_sysclk,
  72         .ops = {
  73                 .prepare = wm8731_pcm_prepare,
  74         },
  75         .caps = {
  76                 .num_modes = ARRAY_SIZE(wm8731_hwfmt),
  77                 .modes = &wm8731_hwfmt[0],
  78         },
  79 };
  80
  81
  82 4 - Codec control IO
  83 --------------------
  84 The codec can ususally be controlled via an I2C or SPI style interface (AC97
  85 combines control with data in the DAI). The codec drivers will have to provide
  86 functions to read and write the codec registers along with supplying a register
  87 cache:-
  88
  89         /* IO control data and register cache */
  90     void *control_data; /* codec control (i2c/3wire) data */
  91     void *reg_cache;
  92
  93 Codec read/write should do any data formatting and call the hardware read write
  94 below to perform the IO. These functions are called by the core and alsa when
  95 performing DAPM or changing the mixer:-
  96
  97     unsigned int (*read)(struct snd_soc_codec *, unsigned int);
  98     int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
  99
 100 Codec hardware IO functions - usually points to either the I2C, SPI or AC97
 101 read/write:-
 102
 103         hw_write_t hw_write;
 104         hw_read_t hw_read;
 105
 106
 107 5 - Mixers and audio controls
 108 -----------------------------
 109 All the codec mixers and audio controls can be defined using the convenience
 110 macros defined in soc.h.
 111
 112     #define SOC_SINGLE(xname, reg, shift, mask, invert)
 113
 114 Defines a single control as follows:-
 115
 116   xname = Control name e.g. "Playback Volume"
 117   reg = codec register
 118   shift = control bit(s) offset in register
 119   mask = control bit size(s) e.g. mask of 7 = 3 bits
 120   invert = the control is inverted
 121
 122 Other macros include:-
 123
 124     #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
 125
 126 A stereo control
 127
 128     #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
 129
 130 A stereo control spanning 2 registers
 131
 132     #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
 133
 134 Defines an single enumerated control as follows:-
 135
 136    xreg = register
 137    xshift = control bit(s) offset in register
 138    xmask = control bit(s) size
 139    xtexts = pointer to array of strings that describe each setting
 140
 141    #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
 142
 143 Defines a stereo enumerated control
 144
 145
 146 6 - System clock configuration.
 147 -------------------------------
 148 The system clock that drives the audio subsystem can change depending on sample
 149 rate and the system power state. i.e.
 150
 151 o Higher sample rates sometimes need a higher system clock.
 152 o Low system power states can sometimes limit the available clocks.
 153
 154 This function is a callback that the machine driver can call to set and
 155 determine if the clock and sample rate combination is supported by the codec at
 156 the present time (and system state).
 157
 158 NOTE: If the codec has a PLL then it has a lot more flexability wrt clock and
 159 sample rate combinations.
 160
 161 Your config_sysclock function should return the MCLK if it's a valid
 162 combination for your codec else 0;
 163
 164 Please read clocking.txt now.
 165
 166
 167 7 - Codec Audio Operations
 168 --------------------------
 169 The codec driver also supports the following alsa operations:-
 170
 171 /* SoC audio ops */
 172 struct snd_soc_ops {
 173         int (*startup)(struct snd_pcm_substream *);
 174         void (*shutdown)(struct snd_pcm_substream *);
 175         int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
 176         int (*hw_free)(struct snd_pcm_substream *);
 177         int (*prepare)(struct snd_pcm_substream *);
 178 };
 179
 180 Please refer to the alsa driver PCM documentation for details.
 181 http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
 182
 183
 184 8 - DAPM description.
 185 ---------------------
 186 The Dynamic Audio Power Management description describes the codec's power
 187 components, their relationships and registers to the ASoC core. Please read
 188 dapm.txt for details of building the description.
 189
 190 Please also see the examples in other codec drivers.
 191
 192
 193 9 - DAPM event handler
 194 ----------------------
 195 This function is a callback that handles codec domain PM calls and system
 196 domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
 197 when not in use.
 198
 199 Power states:-
 200
 201         SNDRV_CTL_POWER_D0: /* full On */
 202         /* vref/mid, clk and osc on, active */
 203
 204         SNDRV_CTL_POWER_D1: /* partial On */
 205         SNDRV_CTL_POWER_D2: /* partial On */
 206
 207         SNDRV_CTL_POWER_D3hot: /* Off, with power */
 208         /* everything off except vref/vmid, inactive */
 209
 210         SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
 211
 212
 213 10 - Codec DAC digital mute control.
 214 ------------------------------------
 215 Most codecs have a digital mute before the DAC's that can be used to minimise
 216 any system noise.  The mute stops any digital data from entering the DAC.
 217
 218 A callback can be created that is called by the core for each codec DAI when the
 219 mute is applied or freed.
 220
 221 i.e.
 222
 223 static int wm8974_mute(struct snd_soc_codec *codec,
 224         struct snd_soc_codec_dai *dai, int mute)
 225 {
 226         u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
 227         if(mute)
 228                 wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
 229         else
 230                 wm8974_write(codec, WM8974_DAC, mute_reg);
 231         return 0;
 232 }