Documentation/sound/soc/codec.rst

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