Documentation/sound/alsa/hda_codec.txt

   1 Notes on Universal Interface for Intel High Definition Audio Codec
   2 ------------------------------------------------------------------
   3
   4 Takashi Iwai <tiwai@suse.de>
   5
   6
   7 [Still a draft version]
   8
   9
  10 General
  11 =======
  12
  13 The snd-hda-codec module supports the generic access function for the
  14 High Definition (HD) audio codecs.  It's designed to be independent
  15 from the controller code like ac97 codec module.  The real accessors
  16 from/to the controller must be implemented in the lowlevel driver.
  17
  18 The structure of this module is similar with ac97_codec module.
  19 Each codec chip belongs to a bus class which communicates with the
  20 controller.
  21
  22
  23 Initialization of Bus Instance
  24 ==============================
  25
  26 The card driver has to create struct hda_bus at first.  The template
  27 struct should be filled and passed to the constructor:
  28
  29 struct hda_bus_template {
  30         void *private_data;
  31         struct pci_dev *pci;
  32         const char *modelname;
  33         struct hda_bus_ops ops;
  34 };
  35
  36 The card driver can set and use the private_data field to retrieve its
  37 own data in callback functions.  The pci field is used when the patch
  38 needs to check the PCI subsystem IDs, so on.  For non-PCI system, it
  39 doesn't have to be set, of course.
  40 The modelname field specifies the board's specific configuration.  The
  41 string is passed to the codec parser, and it depends on the parser how
  42 the string is used.
  43 These fields, private_data, pci and modelname are all optional.
  44
  45 The ops field contains the callback functions as the following:
  46
  47 struct hda_bus_ops {
  48         int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct,
  49                        unsigned int verb, unsigned int parm);
  50         unsigned int (*get_response)(struct hda_codec *codec);
  51         void (*private_free)(struct hda_bus *);
  52 };
  53
  54 The command callback is called when the codec module needs to send a
  55 VERB to the controller.  It's always a single command.
  56 The get_response callback is called when the codec requires the answer
  57 for the last command.  These two callbacks are mandatory and have to
  58 be given.
  59 The last, private_free callback, is optional.  It's called in the
  60 destructor to release any necessary data in the lowlevel driver.
  61
  62 The bus instance is created via snd_hda_bus_new().  You need to pass
  63 the card instance, the template, and the pointer to store the
  64 resultant bus instance.
  65
  66 int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
  67                     struct hda_bus **busp);
  68
  69 It returns zero if successful.  A negative return value means any
  70 error during creation.
  71
  72
  73 Creation of Codec Instance
  74 ==========================
  75
  76 Each codec chip on the board is then created on the BUS instance.
  77 To create a codec instance, call snd_hda_codec_new().
  78
  79 int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
  80                       struct hda_codec **codecp);
  81
  82 The first argument is the BUS instance, the second argument is the
  83 address of the codec, and the last one is the pointer to store the
  84 resultant codec instance (can be NULL if not needed).
  85
  86 The codec is stored in a linked list of bus instance.  You can follow
  87 the codec list like:
  88
  89         struct list_head *p;
  90         struct hda_codec *codec;
  91         list_for_each(p, &bus->codec_list) {
  92                 codec = list_entry(p, struct hda_codec, list);
  93                 ...
  94         }
  95
  96 The codec isn't initialized at this stage properly.  The
  97 initialization sequence is called when the controls are built later.
  98
  99
 100 Codec Access
 101 ============
 102
 103 To access codec, use snd_codec_read() and snd_codec_write().
 104 snd_hda_param_read() is for reading parameters.
 105 For writing a sequence of verbs, use snd_hda_sequence_write().
 106
 107 To retrieve the number of sub nodes connected to the given node, use
 108 snd_hda_get_sub_nodes().  The connection list can be obtained via
 109 snd_hda_get_connections() call.
 110
 111 When an unsolicited event happens, pass the event via
 112 snd_hda_queue_unsol_event() so that the codec routines will process it
 113 later.
 114
 115
 116 (Mixer) Controls
 117 ================
 118
 119 To create mixer controls of all codecs, call
 120 snd_hda_build_controls().  It then builds the mixers and does
 121 initialization stuff on each codec.
 122
 123
 124 PCM Stuff
 125 =========
 126
 127 snd_hda_build_pcms() gives the necessary information to create PCM
 128 streams.  When it's called, each codec belonging to the bus stores
 129 codec->num_pcms and codec->pcm_info fields.  The num_pcms indicates
 130 the number of elements in pcm_info array.  The card driver is supposed
 131 to traverse the codec linked list, read the pcm information in
 132 pcm_info array, and build pcm instances according to them.
 133
 134 The pcm_info array contains the following record:
 135
 136 /* PCM information for each substream */
 137 struct hda_pcm_stream {
 138         unsigned int substreams;        /* number of substreams, 0 = not exist */
 139         unsigned int channels_min;      /* min. number of channels */
 140         unsigned int channels_max;      /* max. number of channels */
 141         hda_nid_t nid;  /* default NID to query rates/formats/bps, or set up */
 142         u32 rates;      /* supported rates */
 143         u64 formats;    /* supported formats (SNDRV_PCM_FMTBIT_) */
 144         unsigned int maxbps;    /* supported max. bit per sample */
 145         struct hda_pcm_ops ops;
 146 };
 147
 148 /* for PCM creation */
 149 struct hda_pcm {
 150         char *name;
 151         struct hda_pcm_stream stream[2];
 152 };
 153
 154 The name can be passed to snd_pcm_new().  The stream field contains
 155 the information  for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
 156 capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions.  The card driver
 157 should pass substreams to snd_pcm_new() for the number of substreams
 158 to create.
 159
 160 The channels_min, channels_max, rates and formats should be copied to
 161 runtime->hw record.  They and maxbps fields are used also to compute
 162 the format value for the HDA codec and controller.  Call
 163 snd_hda_calc_stream_format() to get the format value.
 164
 165 The ops field contains the following callback functions:
 166
 167 struct hda_pcm_ops {
 168         int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
 169                     struct snd_pcm_substream *substream);
 170         int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
 171                      struct snd_pcm_substream *substream);
 172         int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
 173                        unsigned int stream_tag, unsigned int format,
 174                        struct snd_pcm_substream *substream);
 175         int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
 176                        struct snd_pcm_substream *substream);
 177 };
 178
 179 All are non-NULL, so you can call them safely without NULL check.
 180
 181 The open callback should be called in PCM open after runtime->hw is
 182 set up.  It may override some setting and constraints additionally.
 183 Similarly, the close callback should be called in the PCM close.
 184
 185 The prepare callback should be called in PCM prepare.  This will set
 186 up the codec chip properly for the operation.  The cleanup should be
 187 called in hw_free to clean up the configuration.
 188
 189 The caller should check the return value, at least for open and
 190 prepare callbacks.  When a negative value is returned, some error
 191 occurred.
 192
 193
 194 Proc Files
 195 ==========
 196
 197 Each codec dumps the widget node information in
 198 /proc/asound/card*/codec#* file.  This information would be really
 199 helpful for debugging.  Please provide its contents together with the
 200 bug report.
 201
 202
 203 Power Management
 204 ================
 205
 206 It's simple:
 207 Call snd_hda_suspend() in the PM suspend callback.
 208 Call snd_hda_resume() in the PM resume callback.
 209
 210
 211 Codec Preset (Patch)
 212 ====================
 213
 214 To set up and handle the codec functionality fully, each codec may
 215 have a codec preset (patch).  It's defined in struct hda_codec_preset:
 216
 217         struct hda_codec_preset {
 218                 unsigned int id;
 219                 unsigned int mask;
 220                 unsigned int subs;
 221                 unsigned int subs_mask;
 222                 unsigned int rev;
 223                 const char *name;
 224                 int (*patch)(struct hda_codec *codec);
 225         };
 226
 227 When the codec id and codec subsystem id match with the given id and
 228 subs fields bitwise (with bitmask mask and subs_mask), the callback
 229 patch is called.  The patch callback should initialize the codec and
 230 set the codec->patch_ops field.  This is defined as below:
 231
 232         struct hda_codec_ops {
 233                 int (*build_controls)(struct hda_codec *codec);
 234                 int (*build_pcms)(struct hda_codec *codec);
 235                 int (*init)(struct hda_codec *codec);
 236                 void (*free)(struct hda_codec *codec);
 237                 void (*unsol_event)(struct hda_codec *codec, unsigned int res);
 238         #ifdef CONFIG_PM
 239                 int (*suspend)(struct hda_codec *codec, pm_message_t state);
 240                 int (*resume)(struct hda_codec *codec);
 241         #endif
 242         };
 243
 244 The build_controls callback is called from snd_hda_build_controls().
 245 Similarly, the build_pcms callback is called from
 246 snd_hda_build_pcms().  The init callback is called after
 247 build_controls to initialize the hardware.
 248 The free callback is called as a destructor.
 249
 250 The unsol_event callback is called when an unsolicited event is
 251 received.
 252
 253 The suspend and resume callbacks are for power management.
 254
 255 Each entry can be NULL if not necessary to be called.
 256
 257
 258 Generic Parser
 259 ==============
 260
 261 When the device doesn't match with any given presets, the widgets are
 262 parsed via th generic parser (hda_generic.c).  Its support is
 263 limited: no multi-channel support, for example.
 264
 265
 266 Digital I/O
 267 ===========
 268
 269 Call snd_hda_create_spdif_out_ctls() from the patch to create controls
 270 related with SPDIF out.  In the patch resume callback, call
 271 snd_hda_resume_spdif().
 272
 273
 274 Helper Functions
 275 ================
 276
 277 snd_hda_get_codec_name() stores the codec name on the given string.
 278
 279 snd_hda_check_board_config() can be used to obtain the configuration
 280 information matching with the device.  Define the table with struct
 281 hda_board_config entries (zero-terminated), and pass it to the
 282 function.  The function checks the modelname given as a module
 283 parameter, and PCI subsystem IDs.  If the matching entry is found, it
 284 returns the config field value.
 285
 286 snd_hda_add_new_ctls() can be used to create and add control entries.
 287 Pass the zero-terminated array of struct snd_kcontrol_new.  The same array
 288 can be passed to snd_hda_resume_ctls() for resume.
 289 Note that this will call control->put callback of these entries.  So,
 290 put callback should check codec->in_resume and force to restore the
 291 given value if it's non-zero even if the value is identical with the
 292 cached value.
 293
 294 Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
 295 used for the entry of struct snd_kcontrol_new.
 296
 297 The input MUX helper callbacks for such a control are provided, too:
 298 snd_hda_input_mux_info() and snd_hda_input_mux_put().  See
 299 patch_realtek.c for example.