~hc/RK356X_SDK_RELEASE.git

..	..	@@ -3,8 +3,6 @@
3	3	======================
4	4
5	5	:Author: Takashi Iwai <tiwai@suse.de>
6		-:Date: Oct 15, 2007
7		-:Edition: 0.3.7
8	6
9	7	Preface
10	8	=======
..	..	@@ -21,11 +19,6 @@
21	19	low-level driver implementation details. It only describes the standard
22	20	way to write a PCI sound driver on ALSA.
23	21
24		-If you are already familiar with the older ALSA ver.0.5.x API, you can
25		-check the drivers such as ``sound/pci/es1938.c`` or
26		-``sound/pci/maestro3.c`` which have also almost the same code-base in
27		-the ALSA 0.5.x tree, so you can compare the differences.
28		-
29	22	This document is still a draft version. Any feedback and corrections,
30	23	please!!
31	24
..	..	@@ -35,24 +28,7 @@
35	28	General
36	29	-------
37	30
38		-The ALSA drivers are provided in two ways.
39		-
40		-One is the trees provided as a tarball or via cvs from the ALSA's ftp
41		-site, and another is the 2.6 (or later) Linux kernel tree. To
42		-synchronize both, the ALSA driver tree is split into two different
43		-trees: alsa-kernel and alsa-driver. The former contains purely the
44		-source code for the Linux 2.6 (or later) tree. This tree is designed
45		-only for compilation on 2.6 or later environment. The latter,
46		-alsa-driver, contains many subtle files for compiling ALSA drivers
47		-outside of the Linux kernel tree, wrapper functions for older 2.2 and
48		-2.4 kernels, to adapt the latest kernel API, and additional drivers
49		-which are still in development or in tests. The drivers in alsa-driver
50		-tree will be moved to alsa-kernel (and eventually to the 2.6 kernel
51		-tree) when they are finished and confirmed to work fine.
52		-
53		-The file tree structure of ALSA driver is depicted below. Both
54		-alsa-kernel and alsa-driver have almost the same file structure, except
55		-for “core” directory. It's named as “acore” in alsa-driver tree.
	31	+The file tree structure of ALSA driver is depicted below.
56	32
57	33	::
58	34
..	..	@@ -61,14 +37,11 @@
61	37	/oss
62	38	/seq
63	39	/oss
64		- /instr
65		- /ioctl32
66	40	/include
67	41	/drivers
68	42	/mpu401
69	43	/opl3
70	44	/i2c
71		- /l3
72	45	/synth
73	46	/emux
74	47	/pci
..	..	@@ -80,6 +53,7 @@
80	53	/sparc
81	54	/usb
82	55	/pcmcia /(cards)
	56	+ /soc
83	57	/oss
84	58
85	59
..	..	@@ -99,13 +73,6 @@
99	73	code since it's quite small. The sequencer code is stored in
100	74	``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
101	75
102		-core/ioctl32
103		-~~~~~~~~~~~~
104		-
105		-This directory contains the 32bit-ioctl wrappers for 64bit architectures
106		-such like x86-64, ppc64 and sparc64. For 32bit and alpha architectures,
107		-these are not compiled.
108		-
109	76	core/seq
110	77	~~~~~~~~
111	78
..	..	@@ -118,11 +85,6 @@
118	85	~~~~~~~~~~~~
119	86
120	87	This contains the OSS sequencer emulation codes.
121		-
122		-core/seq/instr
123		-~~~~~~~~~~~~~~
124		-
125		-This directory contains the modules for the sequencer instrument layer.
126	88
127	89	include directory
128	90	-----------------
..	..	@@ -160,11 +122,6 @@
160	122	Although there is a standard i2c layer on Linux, ALSA has its own i2c
161	123	code for some cards, because the soundcard needs only a simple operation
162	124	and the standard i2c API is too complicated for such a purpose.
163		-
164		-i2c/l3
165		-~~~~~~
166		-
167		-This is a sub-directory for ARM L3 i2c.
168	125
169	126	synth directory
170	127	---------------
..	..	@@ -209,11 +166,19 @@
209	166	be in the pci directory, because their API is identical to that of
210	167	standard PCI cards.
211	168
	169	+soc directory
	170	+-------------
	171	+
	172	+This directory contains the codes for ASoC (ALSA System on Chip)
	173	+layer including ASoC core, codec and machine drivers.
	174	+
212	175	oss directory
213	176	-------------
214	177
215		-The OSS/Lite source files are stored here in Linux 2.6 (or later) tree.
216		-In the ALSA driver tarball, this directory is empty, of course :)
	178	+Here contains OSS/Lite codes.
	179	+All codes have been deprecated except for dmasound on m68k as of
	180	+writing this.
	181	+
217	182
218	183	Basic Flow for PCI Drivers
219	184	==========================
..	..	@@ -229,7 +194,7 @@
229	194
230	195	- create ``remove`` callback.
231	196
232		-- create a :c:type:`struct pci_driver <pci_driver>` structure
	197	+- create a struct pci_driver structure
233	198	containing the three pointers above.
234	199
235	200	- create an ``init`` function just calling the
..	..	@@ -294,7 +259,7 @@
294	259	{
295	260	struct mychip *chip;
296	261	int err;
297		- static struct snd_device_ops ops = {
	262	+ static const struct snd_device_ops ops = {
298	263	.dev_free = snd_mychip_dev_free,
299	264	};
300	265
..	..	@@ -352,38 +317,37 @@
352	317
353	318	/* (3) */
354	319	err = snd_mychip_create(card, pci, &chip);
355		- if (err < 0) {
356		- snd_card_free(card);
357		- return err;
358		- }
	320	+ if (err < 0)
	321	+ goto error;
359	322
360	323	/* (4) */
361	324	strcpy(card->driver, "My Chip");
362	325	strcpy(card->shortname, "My Own Chip 123");
363	326	sprintf(card->longname, "%s at 0x%lx irq %i",
364		- card->shortname, chip->ioport, chip->irq);
	327	+ card->shortname, chip->port, chip->irq);
365	328
366	329	/* (5) */
367	330	.... /* implemented later */
368	331
369	332	/* (6) */
370	333	err = snd_card_register(card);
371		- if (err < 0) {
372		- snd_card_free(card);
373		- return err;
374		- }
	334	+ if (err < 0)
	335	+ goto error;
375	336
376	337	/* (7) */
377	338	pci_set_drvdata(pci, card);
378	339	dev++;
379	340	return 0;
	341	+
	342	+ error:
	343	+ snd_card_free(card);
	344	+ return err;
380	345	}
381	346
382	347	/* destructor -- see the "Destructor" sub-section */
383	348	static void snd_mychip_remove(struct pci_dev *pci)
384	349	{
385	350	snd_card_free(pci_get_drvdata(pci));
386		- pci_set_drvdata(pci, NULL);
387	351	}
388	352
389	353
..	..	@@ -445,13 +409,25 @@
445	409	struct mychip *chip;
446	410	....
447	411	err = snd_mychip_create(card, pci, &chip);
448		- if (err < 0) {
449		- snd_card_free(card);
450		- return err;
451		- }
	412	+ if (err < 0)
	413	+ goto error;
452	414
453	415	The details will be explained in the section `PCI Resource
454	416	Management`_.
	417	+
	418	+When something goes wrong, the probe function needs to deal with the
	419	+error. In this example, we have a single error handling path placed
	420	+at the end of the function.
	421	+
	422	+::
	423	+
	424	+ error:
	425	+ snd_card_free(card);
	426	+ return err;
	427	+
	428	+Since each component can be properly freed, the single
	429	+:c:func:`snd_card_free()` call should suffice in most cases.
	430	+
455	431
456	432	4) Set the driver ID and name strings.
457	433	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..	..	@@ -461,7 +437,7 @@
461	437	strcpy(card->driver, "My Chip");
462	438	strcpy(card->shortname, "My Own Chip 123");
463	439	sprintf(card->longname, "%s at 0x%lx irq %i",
464		- card->shortname, chip->ioport, chip->irq);
	440	+ card->shortname, chip->port, chip->irq);
465	441
466	442	The driver field holds the minimal ID string of the chip. This is used
467	443	by alsa-lib's configurator, so keep it simple but unique. Even the
..	..	@@ -486,10 +462,8 @@
486	462	::
487	463
488	464	err = snd_card_register(card);
489		- if (err < 0) {
490		- snd_card_free(card);
491		- return err;
492		- }
	465	+ if (err < 0)
	466	+ goto error;
493	467
494	468	Will be explained in the section `Management of Cards and
495	469	Components`_, too.
..	..	@@ -513,14 +487,13 @@
513	487	the ALSA middle layer will release all the attached components
514	488	automatically.
515	489
516		-It would be typically like the following:
	490	+It would be typically just calling :c:func:`snd_card_free()`:
517	491
518	492	::
519	493
520	494	static void snd_mychip_remove(struct pci_dev *pci)
521	495	{
522	496	snd_card_free(pci_get_drvdata(pci));
523		- pci_set_drvdata(pci, NULL);
524	497	}
525	498
526	499
..	..	@@ -546,7 +519,7 @@
546	519	without module options don't need them.
547	520
548	521	In addition to these headers, you'll need ``<linux/interrupt.h>`` for
549		-interrupt handling, and ``<asm/io.h>`` for I/O access. If you use the
	522	+interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
550	523	:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
551	524	to include ``<linux/delay.h>`` too.
552	525
..	..	@@ -587,16 +560,15 @@
587	560	card->private_data for the chip-specific data. Note that these data are
588	561	allocated by :c:func:`snd_card_new()`.
589	562
590		-The first argument, the pointer of struct :c:type:`struct device
591		-<device>`, specifies the parent device. For PCI devices, typically
592		-``&pci->`` is passed there.
	563	+The first argument, the pointer of struct device, specifies the parent
	564	+device. For PCI devices, typically ``&pci->`` is passed there.
593	565
594	566	Components
595	567	----------
596	568
597	569	After the card is created, you can attach the components (devices) to
598	570	the card instance. In an ALSA driver, a component is represented as a
599		-:c:type:`struct snd_device <snd_device>` object. A component
	571	+struct snd_device object. A component
600	572	can be a PCM instance, a control interface, a raw MIDI interface, etc.
601	573	Each such instance has one component entry.
602	574
..	..	@@ -655,7 +627,7 @@
655	627	err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
656	628	sizeof(struct mychip), &card);
657	629
658		-:c:type:`struct mychip <mychip>` is the type of the chip record.
	630	+struct mychip is the type of the chip record.
659	631
660	632	In return, the allocated record can be accessed as
661	633
..	..	@@ -702,7 +674,7 @@
702	674
703	675	::
704	676
705		- static struct snd_device_ops ops = {
	677	+ static const struct snd_device_ops ops = {
706	678	.dev_free = snd_mychip_dev_free,
707	679	};
708	680	....
..	..	@@ -719,6 +691,13 @@
719	691	}
720	692
721	693	where :c:func:`snd_mychip_free()` is the real destructor.
	694	+
	695	+The demerit of this method is the obviously more amount of codes.
	696	+The merit is, however, you can trigger the own callback at registering
	697	+and disconnecting the card via setting in snd_device_ops.
	698	+About the registering and disconnecting the card, see the subsections
	699	+below.
	700	+
722	701
723	702	Registration and Release
724	703	------------------------
..	..	@@ -781,7 +760,7 @@
781	760	{
782	761	struct mychip *chip;
783	762	int err;
784		- static struct snd_device_ops ops = {
	763	+ static const struct snd_device_ops ops = {
785	764	.dev_free = snd_mychip_dev_free,
786	765	};
787	766
..	..	@@ -825,6 +804,7 @@
825	804	return -EBUSY;
826	805	}
827	806	chip->irq = pci->irq;
	807	+ card->sync_irq = chip->irq;
828	808
829	809	/* (2) initialization of the chip hardware */
830	810	.... /* (not implemented in this document) */
..	..	@@ -905,13 +885,11 @@
905	885	-------------------
906	886
907	887	The allocation of I/O ports and irqs is done via standard kernel
908		-functions. Unlike ALSA ver.0.5.x., there are no helpers for that. And
909		-these resources must be released in the destructor function (see below).
910		-Also, on ALSA 0.9.x, you don't need to allocate (pseudo-)DMA for PCI
911		-like in ALSA 0.5.x.
	888	+functions. These resources must be released in the destructor
	889	+function (see below).
912	890
913	891	Now assume that the PCI device has an I/O port with 8 bytes and an
914		-interrupt. Then :c:type:`struct mychip <mychip>` will have the
	892	+interrupt. Then struct mychip will have the
915	893	following fields:
916	894
917	895	::
..	..	@@ -987,6 +965,15 @@
987	965	return IRQ_HANDLED;
988	966	}
989	967
	968	+After requesting the IRQ, you can passed it to ``card->sync_irq``
	969	+field:
	970	+::
	971	+
	972	+ card->irq = chip->irq;
	973	+
	974	+This allows PCM core automatically performing
	975	+:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
	976	+See the later section `sync_stop callback`_ for details.
990	977
991	978	Now let's write the corresponding destructor for the resources above.
992	979	The role of destructor is simple: disable the hardware (if already
..	..	@@ -1064,12 +1051,13 @@
1064	1051
1065	1052	::
1066	1053
1067		- if ((err = pci_request_regions(pci, "My Chip")) < 0) {
	1054	+ err = pci_request_regions(pci, "My Chip");
	1055	+ if (err < 0) {
1068	1056	kfree(chip);
1069	1057	return err;
1070	1058	}
1071	1059	chip->iobase_phys = pci_resource_start(pci, 0);
1072		- chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
	1060	+ chip->iobase_virt = ioremap(chip->iobase_phys,
1073	1061	pci_resource_len(pci, 0));
1074	1062
1075	1063	and the corresponding destructor would be:
..	..	@@ -1086,11 +1074,26 @@
1086	1074	....
1087	1075	}
1088	1076
	1077	+Of course, a modern way with :c:func:`pci_iomap()` will make things a
	1078	+bit easier, too.
	1079	+
	1080	+::
	1081	+
	1082	+ err = pci_request_regions(pci, "My Chip");
	1083	+ if (err < 0) {
	1084	+ kfree(chip);
	1085	+ return err;
	1086	+ }
	1087	+ chip->iobase_virt = pci_iomap(pci, 0, 0);
	1088	+
	1089	+which is paired with :c:func:`pci_iounmap()` at destructor.
	1090	+
	1091	+
1089	1092	PCI Entries
1090	1093	-----------
1091	1094
1092	1095	So far, so good. Let's finish the missing PCI stuff. At first, we need a
1093		-:c:type:`struct pci_device_id <pci_device_id>` table for
	1096	+struct pci_device_id table for
1094	1097	this chipset. It's a table of PCI vendor/device ID number, and some
1095	1098	masks.
1096	1099
..	..	@@ -1106,19 +1109,17 @@
1106	1109	};
1107	1110	MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1108	1111
1109		-The first and second fields of the :c:type:`struct pci_device_id
1110		-<pci_device_id>` structure are the vendor and device IDs. If you
1111		-have no reason to filter the matching devices, you can leave the
1112		-remaining fields as above. The last field of the :c:type:`struct
1113		-pci_device_id <pci_device_id>` struct contains private data
1114		-for this entry. You can specify any value here, for example, to define
1115		-specific operations for supported device IDs. Such an example is found
1116		-in the intel8x0 driver.
	1112	+The first and second fields of the struct pci_device_id are the vendor
	1113	+and device IDs. If you have no reason to filter the matching devices, you can
	1114	+leave the remaining fields as above. The last field of the
	1115	+struct pci_device_id contains private data for this entry. You can specify
	1116	+any value here, for example, to define specific operations for supported
	1117	+device IDs. Such an example is found in the intel8x0 driver.
1117	1118
1118	1119	The last entry of this list is the terminator. You must specify this
1119	1120	all-zero entry.
1120	1121
1121		-Then, prepare the :c:type:`struct pci_driver <pci_driver>`
	1122	+Then, prepare the struct pci_driver
1122	1123	record:
1123	1124
1124	1125	::
..	..	@@ -1153,13 +1154,6 @@
1153	1154
1154	1155	Note that these module entries are tagged with ``__init`` and ``__exit``
1155	1156	prefixes.
1156		-
1157		-Oh, one thing was forgotten. If you have no exported symbols, you need
1158		-to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1159		-
1160		-::
1161		-
1162		- EXPORT_NO_SYMBOLS;
1163	1157
1164	1158	That's all!
1165	1159
..	..	@@ -1283,21 +1277,23 @@
1283	1277	/* the hardware-specific codes will be here */
1284	1278	....
1285	1279	return 0;
1286		-
1287	1280	}
1288	1281
1289	1282	/* hw_params callback */
1290	1283	static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1291	1284	struct snd_pcm_hw_params *hw_params)
1292	1285	{
1293		- return snd_pcm_lib_malloc_pages(substream,
1294		- params_buffer_bytes(hw_params));
	1286	+ /* the hardware-specific codes will be here */
	1287	+ ....
	1288	+ return 0;
1295	1289	}
1296	1290
1297	1291	/* hw_free callback */
1298	1292	static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1299	1293	{
1300		- return snd_pcm_lib_free_pages(substream);
	1294	+ /* the hardware-specific codes will be here */
	1295	+ ....
	1296	+ return 0;
1301	1297	}
1302	1298
1303	1299	/* prepare callback */
..	..	@@ -1352,7 +1348,6 @@
1352	1348	static struct snd_pcm_ops snd_mychip_playback_ops = {
1353	1349	.open = snd_mychip_playback_open,
1354	1350	.close = snd_mychip_playback_close,
1355		- .ioctl = snd_pcm_lib_ioctl,
1356	1351	.hw_params = snd_mychip_pcm_hw_params,
1357	1352	.hw_free = snd_mychip_pcm_hw_free,
1358	1353	.prepare = snd_mychip_pcm_prepare,
..	..	@@ -1364,7 +1359,6 @@
1364	1359	static struct snd_pcm_ops snd_mychip_capture_ops = {
1365	1360	.open = snd_mychip_capture_open,
1366	1361	.close = snd_mychip_capture_close,
1367		- .ioctl = snd_pcm_lib_ioctl,
1368	1362	.hw_params = snd_mychip_pcm_hw_params,
1369	1363	.hw_free = snd_mychip_pcm_hw_free,
1370	1364	.prepare = snd_mychip_pcm_prepare,
..	..	@@ -1395,9 +1389,9 @@
1395	1389	&snd_mychip_capture_ops);
1396	1390	/* pre-allocation of buffers */
1397	1391	/* NOTE: this may fail */
1398		- snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1399		- snd_dma_pci_data(chip->pci),
1400		- 641024, 641024);
	1392	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
	1393	+ &chip->pci->dev,
	1394	+ 641024, 641024);
1401	1395	return 0;
1402	1396	}
1403	1397
..	..	@@ -1442,8 +1436,8 @@
1442	1436	If a chip supports multiple playbacks or captures, you can specify more
1443	1437	numbers, but they must be handled properly in open/close, etc.
1444	1438	callbacks. When you need to know which substream you are referring to,
1445		-then it can be obtained from :c:type:`struct snd_pcm_substream
1446		-<snd_pcm_substream>` data passed to each callback as follows:
	1439	+then it can be obtained from struct snd_pcm_substream data passed to each
	1440	+callback as follows:
1447	1441
1448	1442	::
1449	1443
..	..	@@ -1467,7 +1461,6 @@
1467	1461	static struct snd_pcm_ops snd_mychip_playback_ops = {
1468	1462	.open = snd_mychip_pcm_open,
1469	1463	.close = snd_mychip_pcm_close,
1470		- .ioctl = snd_pcm_lib_ioctl,
1471	1464	.hw_params = snd_mychip_pcm_hw_params,
1472	1465	.hw_free = snd_mychip_pcm_hw_free,
1473	1466	.prepare = snd_mychip_pcm_prepare,
..	..	@@ -1478,13 +1471,14 @@
1478	1471	All the callbacks are described in the Operators_ subsection.
1479	1472
1480	1473	After setting the operators, you probably will want to pre-allocate the
1481		-buffer. For the pre-allocation, simply call the following:
	1474	+buffer and set up the managed allocation mode.
	1475	+For that, simply call the following:
1482	1476
1483	1477	::
1484	1478
1485		- snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1486		- snd_dma_pci_data(chip->pci),
1487		- 641024, 641024);
	1479	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
	1480	+ &chip->pci->dev,
	1481	+ 641024, 641024);
1488	1482
1489	1483	It will allocate a buffer up to 64kB as default. Buffer management
1490	1484	details will be described in the later section `Buffer and Memory
..	..	@@ -1634,8 +1628,7 @@
1634	1628	records are supposed to be read-only. Only the PCM middle-layer changes
1635	1629	/ updates them. The exceptions are the hardware description (hw) DMA
1636	1630	buffer information and the private data. Besides, if you use the
1637		-standard buffer allocation method via
1638		-:c:func:`snd_pcm_lib_malloc_pages()`, you don't need to set the
	1631	+standard managed buffer allocation mode, you don't need to set the
1639	1632	DMA buffer information by yourself.
1640	1633
1641	1634	In the sections below, important records are explained.
..	..	@@ -1643,10 +1636,9 @@
1643	1636	Hardware Description
1644	1637	~~~~~~~~~~~~~~~~~~~~
1645	1638
1646		-The hardware descriptor (:c:type:`struct snd_pcm_hardware
1647		-<snd_pcm_hardware>`) contains the definitions of the fundamental
1648		-hardware configuration. Above all, you'll need to define this in the
1649		-`PCM open callback`_. Note that the runtime instance holds the copy of
	1639	+The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
	1640	+the fundamental hardware configuration. Above all, you'll need to define this
	1641	+in the `PCM open callback`_. Note that the runtime instance holds the copy of
1650	1642	the descriptor, not the pointer to the existing descriptor. That is,
1651	1643	in the open callback, you can modify the copied descriptor
1652	1644	(``runtime->hw``) as you need. For example, if the maximum number of
..	..	@@ -1789,8 +1781,8 @@
1789	1781	the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1790	1782	in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1791	1783
1792		-If you use a standard ALSA function,
1793		-:c:func:`snd_pcm_lib_malloc_pages()`, for allocating the buffer,
	1784	+If you use either the managed buffer allocation mode or the standard
	1785	+API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1794	1786	these fields are set by the ALSA middle layer, and you should not
1795	1787	change them by yourself. You can read them but not write them. On the
1796	1788	other hand, if you want to allocate the buffer by yourself, you'll
..	..	@@ -1804,14 +1796,13 @@
1804	1796	~~~~~~~~~~~~~~
1805	1797
1806	1798	The running status can be referred via ``runtime->status``. This is
1807		-the pointer to the :c:type:`struct snd_pcm_mmap_status
1808		-<snd_pcm_mmap_status>` record. For example, you can get the current
	1799	+the pointer to the struct snd_pcm_mmap_status record.
	1800	+For example, you can get the current
1809	1801	DMA hardware pointer via ``runtime->status->hw_ptr``.
1810	1802
1811	1803	The DMA application pointer can be referred via ``runtime->control``,
1812		-which points to the :c:type:`struct snd_pcm_mmap_control
1813		-<snd_pcm_mmap_control>` record. However, accessing directly to
1814		-this value is not recommended.
	1804	+which points to the struct snd_pcm_mmap_control record.
	1805	+However, accessing directly to this value is not recommended.
1815	1806
1816	1807	Private Data
1817	1808	~~~~~~~~~~~~
..	..	@@ -1847,8 +1838,8 @@
1847	1838	number, it is advised to check what value other parts of the kernel
1848	1839	return when the same kind of request fails.
1849	1840
1850		-The callback function takes at least the argument with :c:type:`struct
1851		-snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
	1841	+The callback function takes at least the argument with
	1842	+struct snd_pcm_substream pointer. To retrieve the chip
1852	1843	record from the given substream instance, you can use the following
1853	1844	macro.
1854	1845
..	..	@@ -1924,7 +1915,10 @@
1924	1915	~~~~~~~~~~~~~~
1925	1916
1926	1917	This is used for any special call to pcm ioctls. But usually you can
1927		-pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`.
	1918	+leave it as NULL, then PCM core calls the generic ioctl callback
	1919	+function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the
	1920	+unique setup of channel info or reset procedure, you can pass your own
	1921	+callback function here.
1928	1922
1929	1923	hw_params callback
1930	1924	~~~~~~~~~~~~~~~~~~~
..	..	@@ -1942,8 +1936,12 @@
1942	1936	allocation of buffers.
1943	1937
1944	1938	Parameters to be initialized are retrieved by
1945		-:c:func:`params_xxx()` macros. To allocate buffer, you can call a
1946		-helper function,
	1939	+:c:func:`params_xxx()` macros.
	1940	+
	1941	+When you set up the managed buffer allocation mode for the substream,
	1942	+a buffer is already allocated before this callback gets
	1943	+called. Alternatively, you can call a helper function below for
	1944	+allocating the buffer, too.
1947	1945
1948	1946	::
1949	1947
..	..	@@ -1977,17 +1975,22 @@
1977	1975	static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1978	1976
1979	1977	This is called to release the resources allocated via
1980		-``hw_params``. For example, releasing the buffer via
1981		-:c:func:`snd_pcm_lib_malloc_pages()` is done by calling the
1982		-following:
1983		-
1984		-::
1985		-
1986		- snd_pcm_lib_free_pages(substream);
	1978	+``hw_params``.
1987	1979
1988	1980	This function is always called before the close callback is called.
1989	1981	Also, the callback may be called multiple times, too. Keep track
1990	1982	whether the resource was already released.
	1983	+
	1984	+When you have set up the managed buffer allocation mode for the PCM
	1985	+substream, the allocated PCM buffer will be automatically released
	1986	+after this callback gets called. Otherwise you'll have to release the
	1987	+buffer manually. Typically, when the buffer was allocated from the
	1988	+pre-allocated pool, you can use the standard API function
	1989	+:c:func:`snd_pcm_lib_malloc_pages()` like:
	1990	+
	1991	+::
	1992	+
	1993	+ snd_pcm_lib_free_pages(substream);
1991	1994
1992	1995	prepare callback
1993	1996	~~~~~~~~~~~~~~~~
..	..	@@ -2061,6 +2064,37 @@
2061	2064	triggering the DMA. The other stuff should be initialized
2062	2065	``hw_params`` and ``prepare`` callbacks properly beforehand.
2063	2066
	2067	+sync_stop callback
	2068	+~~~~~~~~~~~~~~~~~~
	2069	+
	2070	+::
	2071	+
	2072	+ static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
	2073	+
	2074	+This callback is optional, and NULL can be passed. It's called after
	2075	+the PCM core stops the stream and changes the stream state
	2076	+``prepare``, ``hw_params`` or ``hw_free``.
	2077	+Since the IRQ handler might be still pending, we need to wait until
	2078	+the pending task finishes before moving to the next step; otherwise it
	2079	+might lead to a crash due to resource conflicts or access to the freed
	2080	+resources. A typical behavior is to call a synchronization function
	2081	+like :c:func:`synchronize_irq()` here.
	2082	+
	2083	+For majority of drivers that need only a call of
	2084	+:c:func:`synchronize_irq()`, there is a simpler setup, too.
	2085	+While keeping NULL to ``sync_stop`` PCM callback, the driver can set
	2086	+``card->sync_irq`` field to store the valid interrupt number after
	2087	+requesting an IRQ, instead. Then PCM core will look call
	2088	+:c:func:`synchronize_irq()` with the given IRQ appropriately.
	2089	+
	2090	+If the IRQ handler is released at the card destructor, you don't need
	2091	+to clear ``card->sync_irq``, as the card itself is being released.
	2092	+So, usually you'll need to add just a single line for assigning
	2093	+``card->sync_irq`` in the driver code unless the driver re-acquires
	2094	+the IRQ. When the driver frees and re-acquires the IRQ dynamically
	2095	+(e.g. for suspend/resume), it needs to clear and re-set
	2096	+``card->sync_irq`` again appropriately.
	2097	+
2064	2098	pointer callback
2065	2099	~~~~~~~~~~~~~~~~
2066	2100
..	..	@@ -2108,10 +2142,22 @@
2108	2142	page callback
2109	2143	~~~~~~~~~~~~~
2110	2144
2111		-This callback is optional too. This callback is used mainly for
2112		-non-contiguous buffers. The mmap calls this callback to get the page
2113		-address. Some examples will be explained in the later section `Buffer
2114		-and Memory Management`_, too.
	2145	+This callback is optional too. The mmap calls this callback to get the
	2146	+page fault address.
	2147	+
	2148	+Since the recent changes, you need no special callback any longer for
	2149	+the standard SG-buffer or vmalloc-buffer. Hence this callback should
	2150	+be rarely used.
	2151	+
	2152	+mmap calllback
	2153	+~~~~~~~~~~~~~~
	2154	+
	2155	+This is another optional callback for controlling mmap behavior.
	2156	+Once when defined, PCM core calls this callback when a page is
	2157	+memory-mapped instead of dealing via the standard helper.
	2158	+If you need special handling (due to some architecture or
	2159	+device-specific issues), implement everything here as you like.
	2160	+
2115	2161
2116	2162	PCM Interrupt Handler
2117	2163	---------------------
..	..	@@ -2262,10 +2308,10 @@
2262	2308	:c:func:`snd_pcm_period_elapsed()` is called typically from the
2263	2309	interrupt handler. But, if you set up the driver to use a threaded
2264	2310	interrupt handler, this call can be in non-atomic context, too. In such
2265		-a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2266		-<snd_pcm>` object after creating it. When this flag is set, mutex
2267		-and rwsem are used internally in the PCM core instead of spin and
2268		-rwlocks, so that you can call all PCM functions safely in a non-atomic
	2311	+a case, you can set ``nonatomic`` filed of struct snd_pcm object
	2312	+after creating it. When this flag is set, mutex and rwsem are used internally
	2313	+in the PCM core instead of spin and rwlocks, so that you can call all PCM
	2314	+functions safely in a non-atomic
2269	2315	context.
2270	2316
2271	2317	Constraints
..	..	@@ -2306,8 +2352,7 @@
2306	2352	complete list. You can even define your own constraint rules. For
2307	2353	example, let's suppose my_chip can manage a substream of 1 channel if
2308	2354	and only if the format is ``S16_LE``, otherwise it supports any format
2309		-specified in the :c:type:`struct snd_pcm_hardware
2310		-<snd_pcm_hardware>` structure (or in any other
	2355	+specified in struct snd_pcm_hardware> (or in any other
2311	2356	constraint_list). You can build a rule like this:
2312	2357
2313	2358	::
..	..	@@ -2370,6 +2415,27 @@
2370	2415	hw_rule_format_by_channels, NULL,
2371	2416	SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2372	2417
	2418	+One typical usage of the hw constraints is to align the buffer size
	2419	+with the period size. As default, ALSA PCM core doesn't enforce the
	2420	+buffer size to be aligned with the period size. For example, it'd be
	2421	+possible to have a combination like 256 period bytes with 999 buffer
	2422	+bytes.
	2423	+
	2424	+Many device chips, however, require the buffer to be a multiple of
	2425	+periods. In such a case, call
	2426	+:c:func:`snd_pcm_hw_constraint_integer()` for
	2427	+``SNDRV_PCM_HW_PARAM_PERIODS``.
	2428	+
	2429	+::
	2430	+
	2431	+ snd_pcm_hw_constraint_integer(substream->runtime,
	2432	+ SNDRV_PCM_HW_PARAM_PERIODS);
	2433	+
	2434	+This assures that the number of periods is integer, hence the buffer
	2435	+size is aligned with the period size.
	2436	+
	2437	+The hw constraint is a very much powerful mechanism to define the
	2438	+preferred PCM configuration, and there are relevant helpers.
2373	2439	I won't give more details here, rather I would like to say, “Luke, use
2374	2440	the source.”
2375	2441
..	..	@@ -2395,7 +2461,7 @@
2395	2461
2396	2462	To create a new control, you need to define the following three
2397	2463	callbacks: ``info``, ``get`` and ``put``. Then, define a
2398		-:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
	2464	+struct snd_kcontrol_new record, such as:
2399	2465
2400	2466	::
2401	2467
..	..	@@ -2530,8 +2596,8 @@
2530	2596	~~~~~~~~~~~~~
2531	2597
2532	2598	The ``info`` callback is used to get detailed information on this
2533		-control. This must store the values of the given :c:type:`struct
2534		-snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
	2599	+control. This must store the values of the given
	2600	+struct snd_ctl_elem_info object. For example,
2535	2601	for a boolean control with a single element:
2536	2602
2537	2603	::
..	..	@@ -2702,13 +2768,11 @@
2702	2768	if (err < 0)
2703	2769	return err;
2704	2770
2705		-where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2706		-<snd_kcontrol_new>` object defined above, and chip is the object
2707		-pointer to be passed to kcontrol->private_data which can be referred
2708		-to in callbacks.
	2771	+where ``my_control`` is the struct snd_kcontrol_new object defined above,
	2772	+and chip is the object pointer to be passed to kcontrol->private_data which
	2773	+can be referred to in callbacks.
2709	2774
2710		-:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2711		-snd_kcontrol <snd_kcontrol>` instance, and
	2775	+:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
2712	2776	:c:func:`snd_ctl_add()` assigns the given control component to the
2713	2777	card.
2714	2778
..	..	@@ -2725,10 +2789,9 @@
2725	2789	This function takes the card pointer, the event-mask, and the control id
2726	2790	pointer for the notification. The event-mask specifies the types of
2727	2791	notification, for example, in the above example, the change of control
2728		-values is notified. The id pointer is the pointer of :c:type:`struct
2729		-snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2730		-find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2731		-interrupts.
	2792	+values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
	2793	+to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
	2794	+for hardware volume interrupts.
2732	2795
2733	2796	Metadata
2734	2797	--------
..	..	@@ -2843,9 +2906,8 @@
2843	2906
2844	2907	The bus record is shared among all belonging ac97 instances.
2845	2908
2846		-And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2847		-snd_ac97_template <snd_ac97_template>` record together with
2848		-the bus pointer created above.
	2909	+And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
	2910	+record together with the bus pointer created above.
2849	2911
2850	2912	::
2851	2913
..	..	@@ -3046,11 +3108,10 @@
3046	3108
3047	3109	Usually, the port address corresponds to the command port and port + 1
3048	3110	corresponds to the data port. If not, you may change the ``cport``
3049		-field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3050		-However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
	3111	+field of struct snd_mpu401 manually afterward.
	3112	+However, struct snd_mpu401 pointer is
3051	3113	not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3052		-need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3053		-<snd_mpu401>` explicitly,
	3114	+need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
3054	3115
3055	3116	::
3056	3117
..	..	@@ -3254,8 +3315,7 @@
3254	3315	}
3255	3316
3256	3317	If you know beforehand how many bytes you can accept, you can use a
3257		-buffer size greater than one with the
3258		-:c:func:`snd_rawmidi_transmit\*()` functions.
	3318	+buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
3259	3319
3260	3320	The ``trigger`` callback must not sleep. If the hardware FIFO is full
3261	3321	before the substream buffer has been emptied, you have to continue
..	..	@@ -3448,14 +3508,15 @@
3448	3508
3449	3509	“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3450	3510	status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3451		-returns the bitmask for professional mode. They are read-only controls,
3452		-and are defined as MIXER controls (iface =
3453		-``SNDRV_CTL_ELEM_IFACE_MIXER``).
	3511	+returns the bitmask for professional mode. They are read-only controls.
3454	3512
3455	3513	Meanwhile, “IEC958 Playback Default” control is defined for getting and
3456		-setting the current default IEC958 bits. Note that this one is usually
3457		-defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3458		-although in some places it's defined as a MIXER control.
	3514	+setting the current default IEC958 bits.
	3515	+
	3516	+Due to historical reasons, both variants of the Playback Mask and the
	3517	+Playback Default controls can be implemented on either a
	3518	+``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
	3519	+Drivers should expose the mask and default on the same iface though.
3459	3520
3460	3521	In addition, you can define the control switches to enable/disable or to
3461	3522	set the raw bit mode. The implementation will depend on the chip, but
..	..	@@ -3494,7 +3555,7 @@
3494	3555	::
3495	3556
3496	3557	snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3497		- snd_dma_pci_data(pci), size, max);
	3558	+ &pci->dev, size, max);
3498	3559
3499	3560	where ``size`` is the byte size to be pre-allocated and the ``max`` is
3500	3561	the maximum size to be changed via the ``prealloc`` proc file. The
..	..	@@ -3502,15 +3563,17 @@
3502	3563	given size.
3503	3564
3504	3565	The second argument (type) and the third argument (device pointer) are
3505		-dependent on the bus. In the case of the ISA bus, pass
3506		-:c:func:`snd_dma_isa_data()` as the third argument with
	3566	+dependent on the bus. For normal devices, pass the device pointer
	3567	+(typically identical as ``card->dev``) to the third argument with
3507	3568	``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3508		-bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the
3509		-``snd_dma_continuous_data(GFP_KERNEL)`` device pointer, where
3510		-``GFP_KERNEL`` is the kernel allocation flag to use. For the PCI
3511		-scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with
3512		-``snd_dma_pci_data(pci)`` (see the `Non-Contiguous Buffers`_
3513		-section).
	3569	+bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
	3570	+You can pass NULL to the device pointer in that case, which is the
	3571	+default mode implying to allocate with ``GFP_KERNEL`` flag.
	3572	+If you need a different GFP flag, you can pass it by encoding the flag
	3573	+into the device pointer via a special macro
	3574	+:c:func:`snd_dma_continuous_data()`.
	3575	+For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
	3576	+device pointer (see the `Non-Contiguous Buffers`_ section).
3514	3577
3515	3578	Once the buffer is pre-allocated, you can use the allocator in the
3516	3579	``hw_params`` callback:
..	..	@@ -3520,6 +3583,25 @@
3520	3583	snd_pcm_lib_malloc_pages(substream, size);
3521	3584
3522	3585	Note that you have to pre-allocate to use this function.
	3586	+
	3587	+Most of drivers use, though, rather the newly introduced "managed
	3588	+buffer allocation mode" instead of the manual allocation or release.
	3589	+This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
	3590	+instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
	3591	+
	3592	+::
	3593	+
	3594	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
	3595	+ &pci->dev, size, max);
	3596	+
	3597	+where passed arguments are identical in both functions.
	3598	+The difference in the managed mode is that PCM core will call
	3599	+:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
	3600	+the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
	3601	+after the PCM ``hw_free`` callback automatically. So the driver
	3602	+doesn't have to call these functions explicitly in its callback any
	3603	+longer. This made many driver code having NULL ``hw_params`` and
	3604	+``hw_free`` entries.
3523	3605
3524	3606	External Hardware Buffers
3525	3607	-------------------------
..	..	@@ -3675,20 +3757,26 @@
3675	3757	``<sound/pcm.h>``.
3676	3758
3677	3759	For creating the SG-buffer handler, call
3678		-:c:func:`snd_pcm_lib_preallocate_pages()` or
3679		-:c:func:`snd_pcm_lib_preallocate_pages_for_all()` with
	3760	+:c:func:`snd_pcm_set_managed_buffer()` or
	3761	+:c:func:`snd_pcm_set_managed_buffer_all()` with
3680	3762	``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3681		-pre-allocator. You need to pass ``snd_dma_pci_data(pci)``, where pci is
3682		-the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3683		-well. The ``struct snd_sg_buf`` instance is created as
3684		-``substream->dma_private``. You can cast the pointer like:
	3763	+pre-allocator. You need to pass ``&pci->dev``, where pci is
	3764	+the struct pci_dev pointer of the chip as
	3765	+well.
	3766	+
	3767	+::
	3768	+
	3769	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
	3770	+ &pci->dev, size, max);
	3771	+
	3772	+The ``struct snd_sg_buf`` instance is created as
	3773	+``substream->dma_private`` in turn. You can cast the pointer like:
3685	3774
3686	3775	::
3687	3776
3688	3777	struct snd_sg_buf sgbuf = (struct snd_sg_buf )substream->dma_private;
3689	3778
3690		-Then call :c:func:`snd_pcm_lib_malloc_pages()` in the ``hw_params``
3691		-callback as well as in the case of normal PCI buffer. The SG-buffer
	3779	+Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3692	3780	handler will allocate the non-contiguous kernel pages of the given size
3693	3781	and map them onto the virtually contiguous memory. The virtual pointer
3694	3782	is addressed in runtime->dma_area. The physical address
..	..	@@ -3697,34 +3785,40 @@
3697	3785	``sgbuf->table``. You can get the physical address at a certain offset
3698	3786	via :c:func:`snd_pcm_sgbuf_get_addr()`.
3699	3787
3700		-When a SG-handler is used, you need to set
3701		-:c:func:`snd_pcm_sgbuf_ops_page()` as the ``page`` callback. (See
3702		-`page callback`_ section.)
3703		-
3704		-To release the data, call :c:func:`snd_pcm_lib_free_pages()` in
3705		-the ``hw_free`` callback as usual.
	3788	+If you need to release the SG-buffer data explicitly, call the
	3789	+standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3706	3790
3707	3791	Vmalloc'ed Buffers
3708	3792	------------------
3709	3793
3710	3794	It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3711		-example, for an intermediate buffer. Since the allocated pages are not
3712		-contiguous, you need to set the ``page`` callback to obtain the physical
3713		-address at every offset.
3714		-
3715		-The implementation of ``page`` callback would be like this:
	3795	+example, for an intermediate buffer. In the recent version of kernel,
	3796	+you can simply allocate it via standard
	3797	+:c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
	3798	+buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
3716	3799
3717	3800	::
3718	3801
3719		- #include <linux/vmalloc.h>
	3802	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
	3803	+ NULL, 0, 0);
3720	3804
3721		- /* get the physical page pointer on the given offset */
3722		- static struct page mychip_page(struct snd_pcm_substream substream,
3723		- unsigned long offset)
3724		- {
3725		- void *pageptr = substream->runtime->dma_area + offset;
3726		- return vmalloc_to_page(pageptr);
3727		- }
	3805	+The NULL is passed to the device pointer argument, which indicates
	3806	+that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
	3807	+allocated.
	3808	+
	3809	+Also, note that zero is passed to both the size and the max size
	3810	+arguments here. Since each vmalloc call should succeed at any time,
	3811	+we don't need to pre-allocate the buffers like other continuous
	3812	+pages.
	3813	+
	3814	+If you need the 32bit DMA allocation, pass the device pointer encoded
	3815	+by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL\|__GFP_DMA32``
	3816	+argument.
	3817	+
	3818	+::
	3819	+
	3820	+ snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
	3821	+ snd_dma_continuous_data(GFP_KERNEL \| __GFP_DMA32), 0, 0);
3728	3822
3729	3823	Proc Interface
3730	3824	==============
..	..	@@ -3807,7 +3901,7 @@
3807	3901
3808	3902	::
3809	3903
3810		- static struct snd_info_entry_ops my_file_io_ops = {
	3904	+ static const struct snd_info_entry_ops my_file_io_ops = {
3811	3905	.read = my_file_io_read,
3812	3906	};
3813	3907
..	..	@@ -3822,7 +3916,7 @@
3822	3916
3823	3917	The read/write callbacks of raw mode are more direct than the text mode.
3824	3918	You need to use a low-level I/O functions such as
3825		-:c:func:`copy_from/to_user()` to transfer the data.
	3919	+:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
3826	3920
3827	3921	::
3828	3922
..	..	@@ -3848,7 +3942,9 @@
3848	3942
3849	3943	If the chip is supposed to work with suspend/resume functions, you need
3850	3944	to add power-management code to the driver. The additional code for
3851		-power-management should be ifdef-ed with ``CONFIG_PM``.
	3945	+power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
	3946	+with __maybe_unused attribute; otherwise the compiler will complain
	3947	+you.
3852	3948
3853	3949	If the driver fully supports suspend/resume that is, the device can be
3854	3950	properly resumed to its state when suspend was called, you can set the
..	..	@@ -3879,18 +3975,16 @@
3879	3975
3880	3976	::
3881	3977
3882		- #ifdef CONFIG_PM
3883		- static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
	3978	+ static int __maybe_unused snd_my_suspend(struct device *dev)
3884	3979	{
3885	3980	.... /* do things for suspend */
3886	3981	return 0;
3887	3982	}
3888		- static int snd_my_resume(struct pci_dev *pci)
	3983	+ static int __maybe_unused snd_my_resume(struct device *dev)
3889	3984	{
3890	3985	.... /* do things for suspend */
3891	3986	return 0;
3892	3987	}
3893		- #endif
3894	3988
3895	3989	The scheme of the real suspend job is as follows.
3896	3990
..	..	@@ -3899,42 +3993,30 @@
3899	3993	2. Call :c:func:`snd_power_change_state()` with
3900	3994	``SNDRV_CTL_POWER_D3hot`` to change the power status.
3901	3995
3902		-3. Call :c:func:`snd_pcm_suspend_all()` to suspend the running
3903		- PCM streams.
3904		-
3905		-4. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
	3996	+3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3906	3997	each codec.
3907	3998
3908		-5. Save the register values if necessary.
	3999	+4. Save the register values if necessary.
3909	4000
3910		-6. Stop the hardware if necessary.
3911		-
3912		-7. Disable the PCI device by calling
3913		- :c:func:`pci_disable_device()`. Then, call
3914		- :c:func:`pci_save_state()` at last.
	4001	+5. Stop the hardware if necessary.
3915	4002
3916	4003	A typical code would be like:
3917	4004
3918	4005	::
3919	4006
3920		- static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
	4007	+ static int __maybe_unused mychip_suspend(struct device *dev)
3921	4008	{
3922	4009	/* (1) */
3923		- struct snd_card *card = pci_get_drvdata(pci);
	4010	+ struct snd_card *card = dev_get_drvdata(dev);
3924	4011	struct mychip *chip = card->private_data;
3925	4012	/* (2) */
3926	4013	snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3927	4014	/* (3) */
3928		- snd_pcm_suspend_all(chip->pcm);
3929		- /* (4) */
3930	4015	snd_ac97_suspend(chip->ac97);
3931		- /* (5) */
	4016	+ /* (4) */
3932	4017	snd_mychip_save_registers(chip);
3933		- /* (6) */
	4018	+ /* (5) */
3934	4019	snd_mychip_stop_hardware(chip);
3935		- /* (7) */
3936		- pci_disable_device(pci);
3937		- pci_save_state(pci);
3938	4020	return 0;
3939	4021	}
3940	4022
..	..	@@ -3943,55 +4025,42 @@
3943	4025
3944	4026	1. Retrieve the card and the chip data.
3945	4027
3946		-2. Set up PCI. First, call :c:func:`pci_restore_state()`. Then
3947		- enable the pci device again by calling
3948		- :c:func:`pci_enable_device()`. Call
3949		- :c:func:`pci_set_master()` if necessary, too.
	4028	+2. Re-initialize the chip.
3950	4029
3951		-3. Re-initialize the chip.
	4030	+3. Restore the saved registers if necessary.
3952	4031
3953		-4. Restore the saved registers if necessary.
	4032	+4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
3954	4033
3955		-5. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
	4034	+5. Restart the hardware (if any).
3956	4035
3957		-6. Restart the hardware (if any).
3958		-
3959		-7. Call :c:func:`snd_power_change_state()` with
	4036	+6. Call :c:func:`snd_power_change_state()` with
3960	4037	``SNDRV_CTL_POWER_D0`` to notify the processes.
3961	4038
3962	4039	A typical code would be like:
3963	4040
3964	4041	::
3965	4042
3966		- static int mychip_resume(struct pci_dev *pci)
	4043	+ static int __maybe_unused mychip_resume(struct pci_dev *pci)
3967	4044	{
3968	4045	/* (1) */
3969		- struct snd_card *card = pci_get_drvdata(pci);
	4046	+ struct snd_card *card = dev_get_drvdata(dev);
3970	4047	struct mychip *chip = card->private_data;
3971	4048	/* (2) */
3972		- pci_restore_state(pci);
3973		- pci_enable_device(pci);
3974		- pci_set_master(pci);
3975		- /* (3) */
3976	4049	snd_mychip_reinit_chip(chip);
3977		- /* (4) */
	4050	+ /* (3) */
3978	4051	snd_mychip_restore_registers(chip);
3979		- /* (5) */
	4052	+ /* (4) */
3980	4053	snd_ac97_resume(chip->ac97);
3981		- /* (6) */
	4054	+ /* (5) */
3982	4055	snd_mychip_restart_chip(chip);
3983		- /* (7) */
	4056	+ /* (6) */
3984	4057	snd_power_change_state(card, SNDRV_CTL_POWER_D0);
3985	4058	return 0;
3986	4059	}
3987	4060
3988		-As shown in the above, it's better to save registers after suspending
3989		-the PCM operations via :c:func:`snd_pcm_suspend_all()` or
3990		-:c:func:`snd_pcm_suspend()`. It means that the PCM streams are
3991		-already stopped when the register snapshot is taken. But, remember that
3992		-you don't have to restart the PCM stream in the resume callback. It'll
3993		-be restarted via trigger call with ``SNDRV_PCM_TRIGGER_RESUME`` when
3994		-necessary.
	4061	+Note that, at the time this callback gets called, the PCM stream has
	4062	+been already suspended via its own PM ops calling
	4063	+:c:func:`snd_pcm_suspend_all()` internally.
3995	4064
3996	4065	OK, we have all callbacks now. Let's set them up. In the initialization
3997	4066	of the card, make sure that you can get the chip data from the card
..	..	@@ -4046,15 +4115,14 @@
4046	4115
4047	4116	::
4048	4117
	4118	+ static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
	4119	+
4049	4120	static struct pci_driver driver = {
4050	4121	.name = KBUILD_MODNAME,
4051	4122	.id_table = snd_my_ids,
4052	4123	.probe = snd_my_probe,
4053	4124	.remove = snd_my_remove,
4054		- #ifdef CONFIG_PM
4055		- .suspend = snd_my_suspend,
4056		- .resume = snd_my_resume,
4057		- #endif
	4125	+ .driver.pm = &snd_my_pm_ops,
4058	4126	};
4059	4127
4060	4128	Module Parameters
..	..	@@ -4078,7 +4146,7 @@
4078	4146	case, but it would be better to have a dummy option for compatibility.
4079	4147
4080	4148	The module parameters must be declared with the standard
4081		-``module_param()()``, ``module_param_array()()`` and
	4149	+``module_param()``, ``module_param_array()`` and
4082	4150	:c:func:`MODULE_PARM_DESC()` macros.
4083	4151
4084	4152	The typical coding would be like below:
..	..	@@ -4094,15 +4162,14 @@
4094	4162	module_param_array(enable, bool, NULL, 0444);
4095	4163	MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4096	4164
4097		-Also, don't forget to define the module description, classes, license
4098		-and devices. Especially, the recent modprobe requires to define the
	4165	+Also, don't forget to define the module description and the license.
	4166	+Especially, the recent modprobe requires to define the
4099	4167	module license as GPL, etc., otherwise the system is shown as “tainted”.
4100	4168
4101	4169	::
4102	4170
4103		- MODULE_DESCRIPTION("My Chip");
	4171	+ MODULE_DESCRIPTION("Sound driver for My Chip");
4104	4172	MODULE_LICENSE("GPL");
4105		- MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
4106	4173
4107	4174
4108	4175	How To Put Your Driver Into ALSA Tree
..	..	@@ -4117,21 +4184,17 @@
4117	4184
4118	4185	Suppose that you create a new PCI driver for the card “xyz”. The card
4119	4186	module name would be snd-xyz. The new driver is usually put into the
4120		-alsa-driver tree, ``alsa-driver/pci`` directory in the case of PCI
4121		-cards. Then the driver is evaluated, audited and tested by developers
4122		-and users. After a certain time, the driver will go to the alsa-kernel
4123		-tree (to the corresponding directory, such as ``alsa-kernel/pci``) and
4124		-eventually will be integrated into the Linux 2.6 tree (the directory
4125		-would be ``linux/sound/pci``).
	4187	+alsa-driver tree, ``sound/pci`` directory in the case of PCI
	4188	+cards.
4126	4189
4127	4190	In the following sections, the driver code is supposed to be put into
4128		-alsa-driver tree. The two cases are covered: a driver consisting of a
	4191	+Linux kernel tree. The two cases are covered: a driver consisting of a
4129	4192	single source file and one consisting of several source files.
4130	4193
4131	4194	Driver with A Single Source File
4132	4195	--------------------------------
4133	4196
4134		-1. Modify alsa-driver/pci/Makefile
	4197	+1. Modify sound/pci/Makefile
4135	4198
4136	4199	Suppose you have a file xyz.c. Add the following two lines
4137	4200
..	..	@@ -4160,52 +4223,43 @@
4160	4223
4161	4224	For the details of Kconfig script, refer to the kbuild documentation.
4162	4225
4163		-3. Run cvscompile script to re-generate the configure script and build
4164		- the whole stuff again.
4165		-
4166	4226	Drivers with Several Source Files
4167	4227	---------------------------------
4168	4228
4169	4229	Suppose that the driver snd-xyz have several source files. They are
4170		-located in the new subdirectory, pci/xyz.
	4230	+located in the new subdirectory, sound/pci/xyz.
4171	4231
4172		-1. Add a new directory (``xyz``) in ``alsa-driver/pci/Makefile`` as
4173		- below
	4232	+1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
	4233	+ as below
4174	4234
4175	4235	::
4176	4236
4177		- obj-$(CONFIG_SND) += xyz/
	4237	+ obj-$(CONFIG_SND) += sound/pci/xyz/
4178	4238
4179	4239
4180		-2. Under the directory ``xyz``, create a Makefile
	4240	+2. Under the directory ``sound/pci/xyz``, create a Makefile
4181	4241
4182	4242	::
4183		-
4184		- ifndef SND_TOPDIR
4185		- SND_TOPDIR=../..
4186		- endif
4187		-
4188		- include $(SND_TOPDIR)/toplevel.config
4189		- include $(SND_TOPDIR)/Makefile.conf
4190	4243
4191	4244	snd-xyz-objs := xyz.o abc.o def.o
4192		-
4193	4245	obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4194		-
4195		- include $(SND_TOPDIR)/Rules.make
4196	4246
4197	4247	3. Create the Kconfig entry
4198	4248
4199	4249	This procedure is as same as in the last section.
4200	4250
4201		-4. Run cvscompile script to re-generate the configure script and build
4202		- the whole stuff again.
4203	4251
4204	4252	Useful Functions
4205	4253	================
4206	4254
4207	4255	:c:func:`snd_printk()` and friends
4208		----------------------------------------
	4256	+----------------------------------
	4257	+
	4258	+.. note:: This subsection describes a few helper functions for
	4259	+ decorating a bit more on the standard :c:func:`printk()` & co.
	4260	+ However, in general, the use of such helpers is no longer recommended.
	4261	+ If possible, try to stick with the standard functions like
	4262	+ :c:func:`dev_err()` or :c:func:`pr_err()`.
4209	4263
4210	4264	ALSA provides a verbose version of the :c:func:`printk()` function.
4211	4265	If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
..	..	@@ -4221,13 +4275,10 @@
4221	4275	the debugging flag, it's ignored.
4222	4276
4223	4277	:c:func:`snd_printdd()` is compiled in only when
4224		-``CONFIG_SND_DEBUG_VERBOSE`` is set. Please note that
4225		-``CONFIG_SND_DEBUG_VERBOSE`` is not set as default even if you configure
4226		-the alsa-driver with ``--with-debug=full`` option. You need to give
4227		-explicitly ``--with-debug=detect`` option instead.
	4278	+``CONFIG_SND_DEBUG_VERBOSE`` is set.
4228	4279
4229	4280	:c:func:`snd_BUG()`
4230		-------------------------
	4281	+-------------------
4231	4282
4232	4283	It shows the ``BUG?`` message and stack trace as well as
4233	4284	:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
..	..	@@ -4236,7 +4287,7 @@
4236	4287	When no debug flag is set, this macro is ignored.
4237	4288
4238	4289	:c:func:`snd_BUG_ON()`
4239		-----------------------------
	4290	+----------------------
4240	4291
4241	4292	:c:func:`snd_BUG_ON()` macro is similar with
4242	4293	:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or