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 #ifdef CONFIG_SND_HDA_POWER_SAVE
  53         void (*pm_notify)(struct hda_codec *codec);
  54 #endif
  55 };
  56
  57 The command callback is called when the codec module needs to send a
  58 VERB to the controller.  It's always a single command.
  59 The get_response callback is called when the codec requires the answer
  60 for the last command.  These two callbacks are mandatory and have to
  61 be given.
  62 The third, private_free callback, is optional.  It's called in the
  63 destructor to release any necessary data in the lowlevel driver.
  64
  65 The pm_notify callback is available only with
  66 CONFIG_SND_HDA_POWER_SAVE kconfig.  It's called when the codec needs
  67 to power up or may power down.  The controller should check the all
  68 belonging codecs on the bus whether they are actually powered off
  69 (check codec->power_on), and optionally the driver may power down the
  70 contoller side, too.
  71
  72 The bus instance is created via snd_hda_bus_new().  You need to pass
  73 the card instance, the template, and the pointer to store the
  74 resultant bus instance.
  75
  76 int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
  77                     struct hda_bus **busp);
  78
  79 It returns zero if successful.  A negative return value means any
  80 error during creation.
  81
  82
  83 Creation of Codec Instance
  84 ==========================
  85
  86 Each codec chip on the board is then created on the BUS instance.
  87 To create a codec instance, call snd_hda_codec_new().
  88
  89 int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
  90                       struct hda_codec **codecp);
  91
  92 The first argument is the BUS instance, the second argument is the
  93 address of the codec, and the last one is the pointer to store the
  94 resultant codec instance (can be NULL if not needed).
  95
  96 The codec is stored in a linked list of bus instance.  You can follow
  97 the codec list like:
  98
  99         struct hda_codec *codec;
 100         list_for_each_entry(codec, &bus->codec_list, list) {
 101                 ...
 102         }
 103
 104 The codec isn't initialized at this stage properly.  The
 105 initialization sequence is called when the controls are built later.
 106
 107
 108 Codec Access
 109 ============
 110
 111 To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
 112 snd_hda_param_read() is for reading parameters.
 113 For writing a sequence of verbs, use snd_hda_sequence_write().
 114
 115 There are variants of cached read/write, snd_hda_codec_write_cache(),
 116 snd_hda_sequence_write_cache().  These are used for recording the
 117 register states for the power-mangement resume.  When no PM is needed,
 118 these are equivalent with non-cached version.
 119
 120 To retrieve the number of sub nodes connected to the given node, use
 121 snd_hda_get_sub_nodes().  The connection list can be obtained via
 122 snd_hda_get_connections() call.
 123
 124 When an unsolicited event happens, pass the event via
 125 snd_hda_queue_unsol_event() so that the codec routines will process it
 126 later.
 127
 128
 129 (Mixer) Controls
 130 ================
 131
 132 To create mixer controls of all codecs, call
 133 snd_hda_build_controls().  It then builds the mixers and does
 134 initialization stuff on each codec.
 135
 136
 137 PCM Stuff
 138 =========
 139
 140 snd_hda_build_pcms() gives the necessary information to create PCM
 141 streams.  When it's called, each codec belonging to the bus stores
 142 codec->num_pcms and codec->pcm_info fields.  The num_pcms indicates
 143 the number of elements in pcm_info array.  The card driver is supposed
 144 to traverse the codec linked list, read the pcm information in
 145 pcm_info array, and build pcm instances according to them.
 146
 147 The pcm_info array contains the following record:
 148
 149 /* PCM information for each substream */
 150 struct hda_pcm_stream {
 151         unsigned int substreams;        /* number of substreams, 0 = not exist */
 152         unsigned int channels_min;      /* min. number of channels */
 153         unsigned int channels_max;      /* max. number of channels */
 154         hda_nid_t nid;  /* default NID to query rates/formats/bps, or set up */
 155         u32 rates;      /* supported rates */
 156         u64 formats;    /* supported formats (SNDRV_PCM_FMTBIT_) */
 157         unsigned int maxbps;    /* supported max. bit per sample */
 158         struct hda_pcm_ops ops;
 159 };
 160
 161 /* for PCM creation */
 162 struct hda_pcm {
 163         char *name;
 164         struct hda_pcm_stream stream[2];
 165 };
 166
 167 The name can be passed to snd_pcm_new().  The stream field contains
 168 the information  for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
 169 capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions.  The card driver
 170 should pass substreams to snd_pcm_new() for the number of substreams
 171 to create.
 172
 173 The channels_min, channels_max, rates and formats should be copied to
 174 runtime->hw record.  They and maxbps fields are used also to compute
 175 the format value for the HDA codec and controller.  Call
 176 snd_hda_calc_stream_format() to get the format value.
 177
 178 The ops field contains the following callback functions:
 179
 180 struct hda_pcm_ops {
 181         int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
 182                     struct snd_pcm_substream *substream);
 183         int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
 184                      struct snd_pcm_substream *substream);
 185         int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
 186                        unsigned int stream_tag, unsigned int format,
 187                        struct snd_pcm_substream *substream);
 188         int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
 189                        struct snd_pcm_substream *substream);
 190 };
 191
 192 All are non-NULL, so you can call them safely without NULL check.
 193
 194 The open callback should be called in PCM open after runtime->hw is
 195 set up.  It may override some setting and constraints additionally.
 196 Similarly, the close callback should be called in the PCM close.
 197
 198 The prepare callback should be called in PCM prepare.  This will set
 199 up the codec chip properly for the operation.  The cleanup should be
 200 called in hw_free to clean up the configuration.
 201
 202 The caller should check the return value, at least for open and
 203 prepare callbacks.  When a negative value is returned, some error
 204 occurred.
 205
 206
 207 Proc Files
 208 ==========
 209
 210 Each codec dumps the widget node information in
 211 /proc/asound/card*/codec#* file.  This information would be really
 212 helpful for debugging.  Please provide its contents together with the
 213 bug report.
 214
 215
 216 Power Management
 217 ================
 218
 219 It's simple:
 220 Call snd_hda_suspend() in the PM suspend callback.
 221 Call snd_hda_resume() in the PM resume callback.
 222
 223
 224 Codec Preset (Patch)
 225 ====================
 226
 227 To set up and handle the codec functionality fully, each codec may
 228 have a codec preset (patch).  It's defined in struct hda_codec_preset:
 229
 230         struct hda_codec_preset {
 231                 unsigned int id;
 232                 unsigned int mask;
 233                 unsigned int subs;
 234                 unsigned int subs_mask;
 235                 unsigned int rev;
 236                 const char *name;
 237                 int (*patch)(struct hda_codec *codec);
 238         };
 239
 240 When the codec id and codec subsystem id match with the given id and
 241 subs fields bitwise (with bitmask mask and subs_mask), the callback
 242 patch is called.  The patch callback should initialize the codec and
 243 set the codec->patch_ops field.  This is defined as below:
 244
 245         struct hda_codec_ops {
 246                 int (*build_controls)(struct hda_codec *codec);
 247                 int (*build_pcms)(struct hda_codec *codec);
 248                 int (*init)(struct hda_codec *codec);
 249                 void (*free)(struct hda_codec *codec);
 250                 void (*unsol_event)(struct hda_codec *codec, unsigned int res);
 251         #ifdef CONFIG_PM
 252                 int (*suspend)(struct hda_codec *codec, pm_message_t state);
 253                 int (*resume)(struct hda_codec *codec);
 254         #endif
 255         #ifdef CONFIG_SND_HDA_POWER_SAVE
 256                 int (*check_power_status)(struct hda_codec *codec,
 257                                           hda_nid_t nid);
 258         #endif
 259         };
 260
 261 The build_controls callback is called from snd_hda_build_controls().
 262 Similarly, the build_pcms callback is called from
 263 snd_hda_build_pcms().  The init callback is called after
 264 build_controls to initialize the hardware.
 265 The free callback is called as a destructor.
 266
 267 The unsol_event callback is called when an unsolicited event is
 268 received.
 269
 270 The suspend and resume callbacks are for power management.
 271 They can be NULL if no special sequence is required.  When the resume
 272 callback is NULL, the driver calls the init callback and resumes the
 273 registers from the cache.  If other handling is needed, you'd need to
 274 write your own resume callback.  There, the amp values can be resumed
 275 via
 276         void snd_hda_codec_resume_amp(struct hda_codec *codec);
 277 and the other codec registers via
 278         void snd_hda_codec_resume_cache(struct hda_codec *codec);
 279
 280 The check_power_status callback is called when the amp value of the
 281 given widget NID is changed.  The codec code can turn on/off the power
 282 appropriately from this information.
 283
 284 Each entry can be NULL if not necessary to be called.
 285
 286
 287 Generic Parser
 288 ==============
 289
 290 When the device doesn't match with any given presets, the widgets are
 291 parsed via th generic parser (hda_generic.c).  Its support is
 292 limited: no multi-channel support, for example.
 293
 294
 295 Digital I/O
 296 ===========
 297
 298 Call snd_hda_create_spdif_out_ctls() from the patch to create controls
 299 related with SPDIF out.
 300
 301
 302 Helper Functions
 303 ================
 304
 305 snd_hda_get_codec_name() stores the codec name on the given string.
 306
 307 snd_hda_check_board_config() can be used to obtain the configuration
 308 information matching with the device.  Define the model string table
 309 and the table with struct snd_pci_quirk entries (zero-terminated),
 310 and pass it to the function.  The function checks the modelname given
 311 as a module parameter, and PCI subsystem IDs.  If the matching entry
 312 is found, it returns the config field value.
 313
 314 snd_hda_add_new_ctls() can be used to create and add control entries.
 315 Pass the zero-terminated array of struct snd_kcontrol_new
 316
 317 Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
 318 used for the entry of struct snd_kcontrol_new.
 319
 320 The input MUX helper callbacks for such a control are provided, too:
 321 snd_hda_input_mux_info() and snd_hda_input_mux_put().  See
 322 patch_realtek.c for example.