Documentation/sound/alsa/soc/codec.txt

   1 ASoC Codec Class Driver
   2 =======================
   3
   4 The codec class driver is generic and hardware independent code that configures
   5 the codec, FM, MODEM, BT or external DSP to provide audio capture and playback.
   6 It should contain no code that is specific to the target platform or machine.
   7 All platform and machine specific code should be added to the platform and
   8 machine drivers respectively.
   9
  10 Each codec class driver *must* provide the following features:-
  11
  12  1) Codec DAI and PCM configuration
  13  2) Codec control IO - using RegMap API
  14  3) Mixers and audio controls
  15  4) Codec audio operations
  16  5) DAPM description.
  17  6) DAPM event handler.
  18
  19 Optionally, codec drivers can also provide:-
  20
  21  7) DAC Digital mute control.
  22
  23 Its probably best to use this guide in conjunction with the existing codec
  24 driver code in sound/soc/codecs/
  25
  26 ASoC Codec driver breakdown
  27 ===========================
  28
  29 1 - Codec DAI and PCM configuration
  30 -----------------------------------
  31 Each codec driver must have a struct snd_soc_dai_driver to define its DAI and
  32 PCM capabilities and operations. This struct is exported so that it can be
  33 registered with the core by your machine driver.
  34
  35 e.g.
  36
  37 static struct snd_soc_dai_ops wm8731_dai_ops = {
  38         .prepare        = wm8731_pcm_prepare,
  39         .hw_params      = wm8731_hw_params,
  40         .shutdown       = wm8731_shutdown,
  41         .digital_mute   = wm8731_mute,
  42         .set_sysclk     = wm8731_set_dai_sysclk,
  43         .set_fmt        = wm8731_set_dai_fmt,
  44 };
  45
  46 struct snd_soc_dai_driver wm8731_dai = {
  47         .name = "wm8731-hifi",
  48         .playback = {
  49                 .stream_name = "Playback",
  50                 .channels_min = 1,
  51                 .channels_max = 2,
  52                 .rates = WM8731_RATES,
  53                 .formats = WM8731_FORMATS,},
  54         .capture = {
  55                 .stream_name = "Capture",
  56                 .channels_min = 1,
  57                 .channels_max = 2,
  58                 .rates = WM8731_RATES,
  59                 .formats = WM8731_FORMATS,},
  60         .ops = &wm8731_dai_ops,
  61         .symmetric_rates = 1,
  62 };
  63
  64
  65 2 - Codec control IO
  66 --------------------
  67 The codec can usually be controlled via an I2C or SPI style interface
  68 (AC97 combines control with data in the DAI). The codec driver should use the
  69 Regmap API for all codec IO. Please see include/linux/regmap.h and existing
  70 codec drivers for example regmap usage.
  71
  72
  73 3 - Mixers and audio controls
  74 -----------------------------
  75 All the codec mixers and audio controls can be defined using the convenience
  76 macros defined in soc.h.
  77
  78     #define SOC_SINGLE(xname, reg, shift, mask, invert)
  79
  80 Defines a single control as follows:-
  81
  82   xname = Control name e.g. "Playback Volume"
  83   reg = codec register
  84   shift = control bit(s) offset in register
  85   mask = control bit size(s) e.g. mask of 7 = 3 bits
  86   invert = the control is inverted
  87
  88 Other macros include:-
  89
  90     #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
  91
  92 A stereo control
  93
  94     #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
  95
  96 A stereo control spanning 2 registers
  97
  98     #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
  99
 100 Defines an single enumerated control as follows:-
 101
 102    xreg = register
 103    xshift = control bit(s) offset in register
 104    xmask = control bit(s) size
 105    xtexts = pointer to array of strings that describe each setting
 106
 107    #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
 108
 109 Defines a stereo enumerated control
 110
 111
 112 4 - Codec Audio Operations
 113 --------------------------
 114 The codec driver also supports the following ALSA PCM operations:-
 115
 116 /* SoC audio ops */
 117 struct snd_soc_ops {
 118         int (*startup)(struct snd_pcm_substream *);
 119         void (*shutdown)(struct snd_pcm_substream *);
 120         int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
 121         int (*hw_free)(struct snd_pcm_substream *);
 122         int (*prepare)(struct snd_pcm_substream *);
 123 };
 124
 125 Please refer to the ALSA driver PCM documentation for details.
 126 http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
 127
 128
 129 5 - DAPM description.
 130 ---------------------
 131 The Dynamic Audio Power Management description describes the codec power
 132 components and their relationships and registers to the ASoC core.
 133 Please read dapm.txt for details of building the description.
 134
 135 Please also see the examples in other codec drivers.
 136
 137
 138 6 - DAPM event handler
 139 ----------------------
 140 This function is a callback that handles codec domain PM calls and system
 141 domain PM calls (e.g. suspend and resume). It is used to put the codec
 142 to sleep when not in use.
 143
 144 Power states:-
 145
 146         SNDRV_CTL_POWER_D0: /* full On */
 147         /* vref/mid, clk and osc on, active */
 148
 149         SNDRV_CTL_POWER_D1: /* partial On */
 150         SNDRV_CTL_POWER_D2: /* partial On */
 151
 152         SNDRV_CTL_POWER_D3hot: /* Off, with power */
 153         /* everything off except vref/vmid, inactive */
 154
 155         SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
 156
 157
 158 7 - Codec DAC digital mute control
 159 ----------------------------------
 160 Most codecs have a digital mute before the DACs that can be used to
 161 minimise any system noise.  The mute stops any digital data from
 162 entering the DAC.
 163
 164 A callback can be created that is called by the core for each codec DAI
 165 when the mute is applied or freed.
 166
 167 i.e.
 168
 169 static int wm8974_mute(struct snd_soc_dai *dai, int mute)
 170 {
 171         struct snd_soc_codec *codec = dai->codec;
 172         u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf;
 173
 174         if (mute)
 175                 snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40);
 176         else
 177                 snd_soc_write(codec, WM8974_DAC, mute_reg);
 178         return 0;
 179 }