[linux-2.6-block.git] / Documentation / sound / alsa / soc / machine.txt

ASoC Machine Driver
===================

The ASoC machine (or board) driver is the code that glues together all the
component drivers (e.g. codecs, platforms and DAIs). It also describes the
relationships between each component which include audio paths, GPIOs,
interrupts, clocking, jacks and voltage regulators.

The machine driver can contain codec and platform specific code. It registers
the audio subsystem with the kernel as a platform device and is represented by
the following struct:-

/* SoC machine */
struct snd_soc_card {
	char *name;

	...

	int (*probe)(struct platform_device *pdev);
	int (*remove)(struct platform_device *pdev);

	/* the pre and post PM functions are used to do any PM work before and
	 * after the codec and DAIs do any PM work. */
	int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
	int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
	int (*resume_pre)(struct platform_device *pdev);
	int (*resume_post)(struct platform_device *pdev);

	...

	/* CPU <--> Codec DAI links  */
	struct snd_soc_dai_link *dai_link;
	int num_links;

	...
};

probe()/remove()
----------------
probe/remove are optional. Do any machine specific probe here.


suspend()/resume()
------------------
The machine driver has pre and post versions of suspend and resume to take care
of any machine audio tasks that have to be done before or after the codec, DAIs
and DMA is suspended and resumed. Optional.


Machine DAI Configuration
-------------------------
The machine DAI configuration glues all the codec and CPU DAIs together. It can
also be used to set up the DAI system clock and for any machine related DAI
initialisation e.g. the machine audio map can be connected to the codec audio
map, unconnected codec pins can be set as such.

struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.

/* corgi digital audio interface glue - connects codec <--> CPU */
static struct snd_soc_dai_link corgi_dai = {
	.name = "WM8731",
	.stream_name = "WM8731",
	.cpu_dai_name = "pxa-is2-dai",
	.codec_dai_name = "wm8731-hifi",
	.platform_name = "pxa-pcm-audio",
	.codec_name = "wm8713-codec.0-001a",
	.init = corgi_wm8731_init,
	.ops = &corgi_ops,
};

struct snd_soc_card then sets up the machine with its DAIs. e.g.

/* corgi audio machine driver */
static struct snd_soc_card snd_soc_corgi = {
	.name = "Corgi",
	.dai_link = &corgi_dai,
	.num_links = 1,
};


Machine Power Map
-----------------

The machine driver can optionally extend the codec power map and to become an
audio power map of the audio subsystem. This allows for automatic power up/down
of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
sockets in the machine init function.


Machine Controls
----------------

Machine specific audio mixer controls can be added in the DAI init function.
Commit	Line	Data
eb1a6af3 LG	1	ASoC Machine Driver
	2	===================
	3
b5c47df9 LG	4	The ASoC machine (or board) driver is the code that glues together all the
b5c47df9 LG	5	component drivers (e.g. codecs, platforms and DAIs). It also describes the
add3873e	6	relationships between each component which include audio paths, GPIOs,
b5c47df9	7	interrupts, clocking, jacks and voltage regulators.
eb1a6af3 LG	8
	9	The machine driver can contain codec and platform specific code. It registers
	10	the audio subsystem with the kernel as a platform device and is represented by
	11	the following struct:-
	12
	13	/* SoC machine */
4f904735	14	struct snd_soc_card {
eb1a6af3 LG	15	char *name;
eb1a6af3 LG	16
379c4bf1 SY	17	...
379c4bf1 SY	18
eb1a6af3 LG	19	int (probe)(struct platform_device pdev);
	20	int (remove)(struct platform_device pdev);
	21
	22	/* the pre and post PM functions are used to do any PM work before and
7c4dbbd8	23	* after the codec and DAIs do any PM work. */
eb1a6af3 LG	24	int (suspend_pre)(struct platform_device pdev, pm_message_t state);
	25	int (suspend_post)(struct platform_device pdev, pm_message_t state);
	26	int (resume_pre)(struct platform_device pdev);
	27	int (resume_post)(struct platform_device pdev);
	28
379c4bf1	29	...
eb1a6af3 LG	30
	31	/* CPU <--> Codec DAI links */
	32	struct snd_soc_dai_link *dai_link;
	33	int num_links;
379c4bf1 SY	34
379c4bf1 SY	35	...
eb1a6af3 LG	36	};
	37
	38	probe()/remove()
	39	----------------
	40	probe/remove are optional. Do any machine specific probe here.
	41
	42
	43	suspend()/resume()
	44	------------------
	45	The machine driver has pre and post versions of suspend and resume to take care
7c4dbbd8	46	of any machine audio tasks that have to be done before or after the codec, DAIs
eb1a6af3 LG	47	and DMA is suspended and resumed. Optional.
	48
	49
eb1a6af3 LG	50	Machine DAI Configuration
eb1a6af3 LG	51	-------------------------
7c4dbbd8	52	The machine DAI configuration glues all the codec and CPU DAIs together. It can
eb1a6af3 LG	53	also be used to set up the DAI system clock and for any machine related DAI
eb1a6af3 LG	54	initialisation e.g. the machine audio map can be connected to the codec audio
145294c3	55	map, unconnected codec pins can be set as such.
eb1a6af3 LG	56
	57	struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
	58
	59	/* corgi digital audio interface glue - connects codec <--> CPU */
	60	static struct snd_soc_dai_link corgi_dai = {
	61	.name = "WM8731",
	62	.stream_name = "WM8731",
379c4bf1 SY	63	.cpu_dai_name = "pxa-is2-dai",
	64	.codec_dai_name = "wm8731-hifi",
	65	.platform_name = "pxa-pcm-audio",
	66	.codec_name = "wm8713-codec.0-001a",
eb1a6af3	67	.init = corgi_wm8731_init,
10b98527	68	.ops = &corgi_ops,
eb1a6af3 LG	69	};
eb1a6af3 LG	70
a33f3224	71	struct snd_soc_card then sets up the machine with its DAIs. e.g.
eb1a6af3 LG	72
eb1a6af3 LG	73	/* corgi audio machine driver */
87506549	74	static struct snd_soc_card snd_soc_corgi = {
eb1a6af3 LG	75	.name = "Corgi",
	76	.dai_link = &corgi_dai,
	77	.num_links = 1,
eb1a6af3 LG	78	};
	79
	80
eb1a6af3 LG	81	Machine Power Map
	82	-----------------
	83
	84	The machine driver can optionally extend the codec power map and to become an
	85	audio power map of the audio subsystem. This allows for automatic power up/down
	86	of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
145294c3	87	sockets in the machine init function.
eb1a6af3 LG	88
	89
	90	Machine Controls
	91	----------------
	92
7c4dbbd8	93	Machine specific audio mixer controls can be added in the DAI init function.