Notes on Universal Interface for Intel High Definition Audio Codec
------------------------------------------------------------------

Takashi Iwai <tiwai@suse.de>


General
=======

The snd-hda-codec module supports the generic access function for the
High Definition (HD) audio codecs.  It's designed to be independent
from the controller code like ac97 codec module.  The real accessor
from/to the controller must be implemented in the lowlevel driver.

The structure of this module is similar with ac97_codec module.
Each codec chip belongs to a bus class which communicates with the
controller.


Initialization of Bus Instance
==============================

The card driver has to create struct hda_bus at first.  The template
struct should be filled and passed to the constructor:

struct hda_bus_template {
	void *private_data;
	struct pci_dev *pci;
	const char *modelname;
	struct hda_bus_ops ops;
};

The card driver can set and use the private_data field to retrieve its
own data in callback functions.  The pci field is used when the patch
needs to check the PCI subsystem IDs, so on.  For non-PCI system, it
doesn't have to be set, of course.
The modelname field specifies the board's specific configuration.  The
string is passed to the codec parser, and it depends on the parser how
the string is used.
These fields, private_data, pci and modelname are all optional.

The ops field contains the callback functions as the following:

struct hda_bus_ops {
	int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct,
		       unsigned int verb, unsigned int parm);
	unsigned int (*get_response)(struct hda_codec *codec);
	void (*private_free)(struct hda_bus *);
};

The command callback is called when the codec module needs to send a
VERB to the controller.  It's always a single command.
The get_response callback is called when the codec requires the answer
for the last command.  These two callbacks are mandatory and have to
be given.
The last, private_free callback, is optional.  It's called in the
destructor to release any necessary data in the lowlevel driver.

The bus instance is created via snd_hda_bus_new().  You need to pass
the card instance, the template, and the pointer to store the
resultant bus instance.

int snd_hda_bus_new(snd_card_t *card, const struct hda_bus_template *temp,
		    struct hda_bus **busp);

It returns zero if successful.  A negative return value means any
error during creation.


Creation of Codec Instance
==========================

Each codec chip on the board is then created on the BUS instance.
To create a codec instance, call snd_hda_codec_new().

int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
		      struct hda_codec **codecp);

The first argument is the BUS instance, the second argument is the
address of the codec, and the last one is the pointer to store the
resultant codec instance (can be NULL if not needed).

The codec is stored in a linked list of bus instance.  You can follow
the codec list like:

	struct list_head *p;
	struct hda_codec *codec;
	list_for_each(p, &bus->codec_list) {
		codec = list_entry(p, struct hda_codec, list);
		...
	}

The codec isn't initialized at this stage properly.  The
initialization sequnce is called when the controls are built later.


(Mixer) Controls
================

To create mixer controls of all codecs, call
snd_hda_build_controls().  It then builds the mixers and does
initialization stuff on each codec.


PCM Stuff
=========

snd_hda_build_pcms() gives the necessary information to create PCM
streams.  When it's called, each codec belonging to the bus stores 
codec->num_pcms and codec->pcm_info fields.  The num_pcms indicates
the number of elements in pcm_info array.  The card driver is supposed
to traverse the codec linked list, read the pcm information in
pcm_info array, and build pcm instances according to them. 

The pcm_info array contains the following record:

/* PCM information for each substream */
struct hda_pcm_stream {
	unsigned int substreams;	/* number of substreams, 0 = not exist */
	unsigned int channels_min;	/* min. number of channels */
	unsigned int channels_max;	/* max. number of channels */
	hda_nid_t nid;	/* default NID to query rates/formats/bps, or set up */
	u32 rates;	/* supported rates */
	u64 formats;	/* supported formats (SNDRV_PCM_FMTBIT_) */
	unsigned int maxbps;	/* supported max. bit per sample */
	struct hda_pcm_ops ops;
};

/* for PCM creation */
struct hda_pcm {
	char *name;
	struct hda_pcm_stream stream[2];
};

The name can be passed to snd_pcm_new().  The stream field contains
the information  for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions.  The card driver
should pass substreams to snd_pcm_new() for the number of substreams
to create.

The channels_min, channels_max, rates and formats should be copied to
runtime->hw record.  They and maxbps fields are used also to compute
the format value for the HDA codec and controller.  Call
snd_hda_calc_stream_format() to get the format value.

The ops field contains the following callback functions:

struct hda_pcm_ops {
	int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
		    snd_pcm_substream_t *substream);
	int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
		     snd_pcm_substream_t *substream);
	int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
		       unsigned int stream_tag, unsigned int format,
		       snd_pcm_substream_t *substream);
	int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
		       snd_pcm_substream_t *substream);
};

All are non-NULL, so you can call them safely without NULL check.

The open callback should be called in PCM open after runtime->hw is
set up.  It may override some setting and constraints additionally.
Similarly, the close callback should be called in the PCM close.

The prepare callback should be called in PCM prepare.  This will set
up the codec chip properly for the operation.  The cleanup should be
called in hw_free to clean up the configuration.

The caller should check the return value, at least for open and
prepare callbacks.  When a negative value is returned, some error
occured.


Proc Files
==========

Each codec dumps the widget node information in
/proc/asound/card*/codec#* file.  This information would be really
helpful for debugging.  Please provide its contents together with the
bug report.


Power Management
================

It's simple:
Call snd_hda_suspend() in the PM suspend callback.
Call snd_hda_resume() in the PM resume callback.


Codec Preset (Patch)
====================

(TODO)


Generic Parser
==============

(TODO)


Digital I/O
===========

(TODO)


Helper Functions
================

(TODO)


Any Others?
===========

(TODO)

