aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sound
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sound')
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt34
-rw-r--r--Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl100
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl6210
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt3
4 files changed, 12 insertions, 6335 deletions
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
index 012afd7afb13..ab163b701f9d 100644
--- a/Documentation/sound/alsa/ALSA-Configuration.txt
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
@@ -346,6 +346,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
346 sbirq - IRQ # for CMI8330 chip (SB16) 346 sbirq - IRQ # for CMI8330 chip (SB16)
347 sbdma8 - 8bit DMA # for CMI8330 chip (SB16) 347 sbdma8 - 8bit DMA # for CMI8330 chip (SB16)
348 sbdma16 - 16bit DMA # for CMI8330 chip (SB16) 348 sbdma16 - 16bit DMA # for CMI8330 chip (SB16)
349 fmport - (optional) OPL3 I/O port
350 mpuport - (optional) MPU401 I/O port
351 mpuirq - (optional) MPU401 irq #
349 352
350 This module supports multiple cards and autoprobe. 353 This module supports multiple cards and autoprobe.
351 354
@@ -388,34 +391,11 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
388 391
389 The power-management is supported. 392 The power-management is supported.
390 393
391 Module snd-cs4232
392 -----------------
393
394 Module for sound cards based on CS4232/CS4232A ISA chips.
395
396 isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
397
398 with isapnp=0, the following options are available:
399
400 port - port # for CS4232 chip (PnP setup - 0x534)
401 cport - control port # for CS4232 chip (PnP setup - 0x120,0x210,0xf00)
402 mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable
403 fm_port - FM port # for CS4232 chip (PnP setup - 0x388), -1 = disable
404 irq - IRQ # for CS4232 chip (5,7,9,11,12,15)
405 mpu_irq - IRQ # for MPU-401 UART (9,11,12,15)
406 dma1 - first DMA # for CS4232 chip (0,1,3)
407 dma2 - second DMA # for Yamaha CS4232 chip (0,1,3), -1 = disable
408
409 This module supports multiple cards. This module does not support autoprobe
410 (if ISA PnP is not used) thus main port must be specified!!! Other ports are
411 optional.
412
413 The power-management is supported.
414
415 Module snd-cs4236 394 Module snd-cs4236
416 ----------------- 395 -----------------
417 396
418 Module for sound cards based on CS4235/CS4236/CS4236B/CS4237B/ 397 Module for sound cards based on CS4232/CS4232A,
398 CS4235/CS4236/CS4236B/CS4237B/
419 CS4238B/CS4239 ISA chips. 399 CS4238B/CS4239 ISA chips.
420 400
421 isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) 401 isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
@@ -437,6 +417,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
437 417
438 The power-management is supported. 418 The power-management is supported.
439 419
420 This module is aliased as snd-cs4232 since it provides the old
421 snd-cs4232 functionality, too.
422
440 Module snd-cs4281 423 Module snd-cs4281
441 ----------------- 424 -----------------
442 425
@@ -606,6 +589,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
606 Module for ESS AudioDrive ES-1688 and ES-688 sound cards. 589 Module for ESS AudioDrive ES-1688 and ES-688 sound cards.
607 590
608 port - port # for ES-1688 chip (0x220,0x240,0x260) 591 port - port # for ES-1688 chip (0x220,0x240,0x260)
592 fm_port - port # for OPL3 (option; share the same port as default)
609 mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) 593 mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default)
610 irq - IRQ # for ES-1688 chip (5,7,9,10) 594 irq - IRQ # for ES-1688 chip (5,7,9,10)
611 mpu_irq - IRQ # for MPU-401 port (5,7,9,10) 595 mpu_irq - IRQ # for MPU-401 port (5,7,9,10)
diff --git a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
deleted file mode 100644
index 9d644f7e241e..000000000000
--- a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
+++ /dev/null
@@ -1,100 +0,0 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2
3<book>
4<?dbhtml filename="index.html">
5
6<!-- ****************************************************** -->
7<!-- Header -->
8<!-- ****************************************************** -->
9 <bookinfo>
10 <title>The ALSA Driver API</title>
11
12 <legalnotice>
13 <para>
14 This document is free; you can redistribute it and/or modify it
15 under the terms of the GNU General Public License as published by
16 the Free Software Foundation; either version 2 of the License, or
17 (at your option) any later version.
18 </para>
19
20 <para>
21 This document is distributed in the hope that it will be useful,
22 but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
23 implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
24 PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
25 for more details.
26 </para>
27
28 <para>
29 You should have received a copy of the GNU General Public
30 License along with this program; if not, write to the Free
31 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
32 MA 02111-1307 USA
33 </para>
34 </legalnotice>
35
36 </bookinfo>
37
38 <chapter><title>Management of Cards and Devices</title>
39 <sect1><title>Card Management</title>
40!Esound/core/init.c
41 </sect1>
42 <sect1><title>Device Components</title>
43!Esound/core/device.c
44 </sect1>
45 <sect1><title>Module requests and Device File Entries</title>
46!Esound/core/sound.c
47 </sect1>
48 <sect1><title>Memory Management Helpers</title>
49!Esound/core/memory.c
50!Esound/core/memalloc.c
51 </sect1>
52 </chapter>
53 <chapter><title>PCM API</title>
54 <sect1><title>PCM Core</title>
55!Esound/core/pcm.c
56!Esound/core/pcm_lib.c
57!Esound/core/pcm_native.c
58 </sect1>
59 <sect1><title>PCM Format Helpers</title>
60!Esound/core/pcm_misc.c
61 </sect1>
62 <sect1><title>PCM Memory Management</title>
63!Esound/core/pcm_memory.c
64 </sect1>
65 </chapter>
66 <chapter><title>Control/Mixer API</title>
67 <sect1><title>General Control Interface</title>
68!Esound/core/control.c
69 </sect1>
70 <sect1><title>AC97 Codec API</title>
71!Esound/pci/ac97/ac97_codec.c
72!Esound/pci/ac97/ac97_pcm.c
73 </sect1>
74 </chapter>
75 <chapter><title>MIDI API</title>
76 <sect1><title>Raw MIDI API</title>
77!Esound/core/rawmidi.c
78 </sect1>
79 <sect1><title>MPU401-UART API</title>
80!Esound/drivers/mpu401/mpu401_uart.c
81 </sect1>
82 </chapter>
83 <chapter><title>Proc Info API</title>
84 <sect1><title>Proc Info Interface</title>
85!Esound/core/info.c
86 </sect1>
87 </chapter>
88 <chapter><title>Miscellaneous Functions</title>
89 <sect1><title>Hardware-Dependent Devices API</title>
90!Esound/core/hwdep.c
91 </sect1>
92 <sect1><title>ISA DMA Helpers</title>
93!Esound/core/isadma.c
94 </sect1>
95 <sect1><title>Other Helper Macros</title>
96!Iinclude/sound/core.h
97 </sect1>
98 </chapter>
99
100</book>
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
deleted file mode 100644
index 87a7c07ab658..000000000000
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ /dev/null
@@ -1,6210 +0,0 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2
3<book>
4<?dbhtml filename="index.html">
5
6<!-- ****************************************************** -->
7<!-- Header -->
8<!-- ****************************************************** -->
9 <bookinfo>
10 <title>Writing an ALSA Driver</title>
11 <author>
12 <firstname>Takashi</firstname>
13 <surname>Iwai</surname>
14 <affiliation>
15 <address>
16 <email>tiwai@suse.de</email>
17 </address>
18 </affiliation>
19 </author>
20
21 <date>Oct 15, 2007</date>
22 <edition>0.3.7</edition>
23
24 <abstract>
25 <para>
26 This document describes how to write an ALSA (Advanced Linux
27 Sound Architecture) driver.
28 </para>
29 </abstract>
30
31 <legalnotice>
32 <para>
33 Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email>
34 </para>
35
36 <para>
37 This document is free; you can redistribute it and/or modify it
38 under the terms of the GNU General Public License as published by
39 the Free Software Foundation; either version 2 of the License, or
40 (at your option) any later version.
41 </para>
42
43 <para>
44 This document is distributed in the hope that it will be useful,
45 but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
46 implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
47 PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
48 for more details.
49 </para>
50
51 <para>
52 You should have received a copy of the GNU General Public
53 License along with this program; if not, write to the Free
54 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
55 MA 02111-1307 USA
56 </para>
57 </legalnotice>
58
59 </bookinfo>
60
61<!-- ****************************************************** -->
62<!-- Preface -->
63<!-- ****************************************************** -->
64 <preface id="preface">
65 <title>Preface</title>
66 <para>
67 This document describes how to write an
68 <ulink url="http://www.alsa-project.org/"><citetitle>
69 ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
70 driver. The document focuses mainly on PCI soundcards.
71 In the case of other device types, the API might
72 be different, too. However, at least the ALSA kernel API is
73 consistent, and therefore it would be still a bit help for
74 writing them.
75 </para>
76
77 <para>
78 This document targets people who already have enough
79 C language skills and have basic linux kernel programming
80 knowledge. This document doesn't explain the general
81 topic of linux kernel coding and doesn't cover low-level
82 driver implementation details. It only describes
83 the standard way to write a PCI sound driver on ALSA.
84 </para>
85
86 <para>
87 If you are already familiar with the older ALSA ver.0.5.x API, you
88 can check the drivers such as <filename>sound/pci/es1938.c</filename> or
89 <filename>sound/pci/maestro3.c</filename> which have also almost the same
90 code-base in the ALSA 0.5.x tree, so you can compare the differences.
91 </para>
92
93 <para>
94 This document is still a draft version. Any feedback and
95 corrections, please!!
96 </para>
97 </preface>
98
99
100<!-- ****************************************************** -->
101<!-- File Tree Structure -->
102<!-- ****************************************************** -->
103 <chapter id="file-tree">
104 <title>File Tree Structure</title>
105
106 <section id="file-tree-general">
107 <title>General</title>
108 <para>
109 The ALSA drivers are provided in two ways.
110 </para>
111
112 <para>
113 One is the trees provided as a tarball or via cvs from the
114 ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
115 tree. To synchronize both, the ALSA driver tree is split into
116 two different trees: alsa-kernel and alsa-driver. The former
117 contains purely the source code for the Linux 2.6 (or later)
118 tree. This tree is designed only for compilation on 2.6 or
119 later environment. The latter, alsa-driver, contains many subtle
120 files for compiling ALSA drivers outside of the Linux kernel tree,
121 wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
122 and additional drivers which are still in development or in
123 tests. The drivers in alsa-driver tree will be moved to
124 alsa-kernel (and eventually to the 2.6 kernel tree) when they are
125 finished and confirmed to work fine.
126 </para>
127
128 <para>
129 The file tree structure of ALSA driver is depicted below. Both
130 alsa-kernel and alsa-driver have almost the same file
131 structure, except for <quote>core</quote> directory. It's
132 named as <quote>acore</quote> in alsa-driver tree.
133
134 <example>
135 <title>ALSA File Tree Structure</title>
136 <literallayout>
137 sound
138 /core
139 /oss
140 /seq
141 /oss
142 /instr
143 /ioctl32
144 /include
145 /drivers
146 /mpu401
147 /opl3
148 /i2c
149 /l3
150 /synth
151 /emux
152 /pci
153 /(cards)
154 /isa
155 /(cards)
156 /arm
157 /ppc
158 /sparc
159 /usb
160 /pcmcia /(cards)
161 /oss
162 </literallayout>
163 </example>
164 </para>
165 </section>
166
167 <section id="file-tree-core-directory">
168 <title>core directory</title>
169 <para>
170 This directory contains the middle layer which is the heart
171 of ALSA drivers. In this directory, the native ALSA modules are
172 stored. The sub-directories contain different modules and are
173 dependent upon the kernel config.
174 </para>
175
176 <section id="file-tree-core-directory-oss">
177 <title>core/oss</title>
178
179 <para>
180 The codes for PCM and mixer OSS emulation modules are stored
181 in this directory. The rawmidi OSS emulation is included in
182 the ALSA rawmidi code since it's quite small. The sequencer
183 code is stored in <filename>core/seq/oss</filename> directory (see
184 <link linkend="file-tree-core-directory-seq-oss"><citetitle>
185 below</citetitle></link>).
186 </para>
187 </section>
188
189 <section id="file-tree-core-directory-ioctl32">
190 <title>core/ioctl32</title>
191
192 <para>
193 This directory contains the 32bit-ioctl wrappers for 64bit
194 architectures such like x86-64, ppc64 and sparc64. For 32bit
195 and alpha architectures, these are not compiled.
196 </para>
197 </section>
198
199 <section id="file-tree-core-directory-seq">
200 <title>core/seq</title>
201 <para>
202 This directory and its sub-directories are for the ALSA
203 sequencer. This directory contains the sequencer core and
204 primary sequencer modules such like snd-seq-midi,
205 snd-seq-virmidi, etc. They are compiled only when
206 <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
207 config.
208 </para>
209 </section>
210
211 <section id="file-tree-core-directory-seq-oss">
212 <title>core/seq/oss</title>
213 <para>
214 This contains the OSS sequencer emulation codes.
215 </para>
216 </section>
217
218 <section id="file-tree-core-directory-deq-instr">
219 <title>core/seq/instr</title>
220 <para>
221 This directory contains the modules for the sequencer
222 instrument layer.
223 </para>
224 </section>
225 </section>
226
227 <section id="file-tree-include-directory">
228 <title>include directory</title>
229 <para>
230 This is the place for the public header files of ALSA drivers,
231 which are to be exported to user-space, or included by
232 several files at different directories. Basically, the private
233 header files should not be placed in this directory, but you may
234 still find files there, due to historical reasons :)
235 </para>
236 </section>
237
238 <section id="file-tree-drivers-directory">
239 <title>drivers directory</title>
240 <para>
241 This directory contains code shared among different drivers
242 on different architectures. They are hence supposed not to be
243 architecture-specific.
244 For example, the dummy pcm driver and the serial MIDI
245 driver are found in this directory. In the sub-directories,
246 there is code for components which are independent from
247 bus and cpu architectures.
248 </para>
249
250 <section id="file-tree-drivers-directory-mpu401">
251 <title>drivers/mpu401</title>
252 <para>
253 The MPU401 and MPU401-UART modules are stored here.
254 </para>
255 </section>
256
257 <section id="file-tree-drivers-directory-opl3">
258 <title>drivers/opl3 and opl4</title>
259 <para>
260 The OPL3 and OPL4 FM-synth stuff is found here.
261 </para>
262 </section>
263 </section>
264
265 <section id="file-tree-i2c-directory">
266 <title>i2c directory</title>
267 <para>
268 This contains the ALSA i2c components.
269 </para>
270
271 <para>
272 Although there is a standard i2c layer on Linux, ALSA has its
273 own i2c code for some cards, because the soundcard needs only a
274 simple operation and the standard i2c API is too complicated for
275 such a purpose.
276 </para>
277
278 <section id="file-tree-i2c-directory-l3">
279 <title>i2c/l3</title>
280 <para>
281 This is a sub-directory for ARM L3 i2c.
282 </para>
283 </section>
284 </section>
285
286 <section id="file-tree-synth-directory">
287 <title>synth directory</title>
288 <para>
289 This contains the synth middle-level modules.
290 </para>
291
292 <para>
293 So far, there is only Emu8000/Emu10k1 synth driver under
294 the <filename>synth/emux</filename> sub-directory.
295 </para>
296 </section>
297
298 <section id="file-tree-pci-directory">
299 <title>pci directory</title>
300 <para>
301 This directory and its sub-directories hold the top-level card modules
302 for PCI soundcards and the code specific to the PCI BUS.
303 </para>
304
305 <para>
306 The drivers compiled from a single file are stored directly
307 in the pci directory, while the drivers with several source files are
308 stored on their own sub-directory (e.g. emu10k1, ice1712).
309 </para>
310 </section>
311
312 <section id="file-tree-isa-directory">
313 <title>isa directory</title>
314 <para>
315 This directory and its sub-directories hold the top-level card modules
316 for ISA soundcards.
317 </para>
318 </section>
319
320 <section id="file-tree-arm-ppc-sparc-directories">
321 <title>arm, ppc, and sparc directories</title>
322 <para>
323 They are used for top-level card modules which are
324 specific to one of these architectures.
325 </para>
326 </section>
327
328 <section id="file-tree-usb-directory">
329 <title>usb directory</title>
330 <para>
331 This directory contains the USB-audio driver. In the latest version, the
332 USB MIDI driver is integrated in the usb-audio driver.
333 </para>
334 </section>
335
336 <section id="file-tree-pcmcia-directory">
337 <title>pcmcia directory</title>
338 <para>
339 The PCMCIA, especially PCCard drivers will go here. CardBus
340 drivers will be in the pci directory, because their API is identical
341 to that of standard PCI cards.
342 </para>
343 </section>
344
345 <section id="file-tree-oss-directory">
346 <title>oss directory</title>
347 <para>
348 The OSS/Lite source files are stored here in Linux 2.6 (or
349 later) tree. In the ALSA driver tarball, this directory is empty,
350 of course :)
351 </para>
352 </section>
353 </chapter>
354
355
356<!-- ****************************************************** -->
357<!-- Basic Flow for PCI Drivers -->
358<!-- ****************************************************** -->
359 <chapter id="basic-flow">
360 <title>Basic Flow for PCI Drivers</title>
361
362 <section id="basic-flow-outline">
363 <title>Outline</title>
364 <para>
365 The minimum flow for PCI soundcards is as follows:
366
367 <itemizedlist>
368 <listitem><para>define the PCI ID table (see the section
369 <link linkend="pci-resource-entries"><citetitle>PCI Entries
370 </citetitle></link>).</para></listitem>
371 <listitem><para>create <function>probe()</function> callback.</para></listitem>
372 <listitem><para>create <function>remove()</function> callback.</para></listitem>
373 <listitem><para>create a <structname>pci_driver</structname> structure
374 containing the three pointers above.</para></listitem>
375 <listitem><para>create an <function>init()</function> function just calling
376 the <function>pci_register_driver()</function> to register the pci_driver table
377 defined above.</para></listitem>
378 <listitem><para>create an <function>exit()</function> function to call
379 the <function>pci_unregister_driver()</function> function.</para></listitem>
380 </itemizedlist>
381 </para>
382 </section>
383
384 <section id="basic-flow-example">
385 <title>Full Code Example</title>
386 <para>
387 The code example is shown below. Some parts are kept
388 unimplemented at this moment but will be filled in the
389 next sections. The numbers in the comment lines of the
390 <function>snd_mychip_probe()</function> function
391 refer to details explained in the following section.
392
393 <example>
394 <title>Basic Flow for PCI Drivers - Example</title>
395 <programlisting>
396<![CDATA[
397 #include <linux/init.h>
398 #include <linux/pci.h>
399 #include <linux/slab.h>
400 #include <sound/core.h>
401 #include <sound/initval.h>
402
403 /* module parameters (see "Module Parameters") */
404 /* SNDRV_CARDS: maximum number of cards supported by this module */
405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
407 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
408
409 /* definition of the chip-specific record */
410 struct mychip {
411 struct snd_card *card;
412 /* the rest of the implementation will be in section
413 * "PCI Resource Management"
414 */
415 };
416
417 /* chip-specific destructor
418 * (see "PCI Resource Management")
419 */
420 static int snd_mychip_free(struct mychip *chip)
421 {
422 .... /* will be implemented later... */
423 }
424
425 /* component-destructor
426 * (see "Management of Cards and Components")
427 */
428 static int snd_mychip_dev_free(struct snd_device *device)
429 {
430 return snd_mychip_free(device->device_data);
431 }
432
433 /* chip-specific constructor
434 * (see "Management of Cards and Components")
435 */
436 static int __devinit snd_mychip_create(struct snd_card *card,
437 struct pci_dev *pci,
438 struct mychip **rchip)
439 {
440 struct mychip *chip;
441 int err;
442 static struct snd_device_ops ops = {
443 .dev_free = snd_mychip_dev_free,
444 };
445
446 *rchip = NULL;
447
448 /* check PCI availability here
449 * (see "PCI Resource Management")
450 */
451 ....
452
453 /* allocate a chip-specific data with zero filled */
454 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
455 if (chip == NULL)
456 return -ENOMEM;
457
458 chip->card = card;
459
460 /* rest of initialization here; will be implemented
461 * later, see "PCI Resource Management"
462 */
463 ....
464
465 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
466 if (err < 0) {
467 snd_mychip_free(chip);
468 return err;
469 }
470
471 snd_card_set_dev(card, &pci->dev);
472
473 *rchip = chip;
474 return 0;
475 }
476
477 /* constructor -- see "Constructor" sub-section */
478 static int __devinit snd_mychip_probe(struct pci_dev *pci,
479 const struct pci_device_id *pci_id)
480 {
481 static int dev;
482 struct snd_card *card;
483 struct mychip *chip;
484 int err;
485
486 /* (1) */
487 if (dev >= SNDRV_CARDS)
488 return -ENODEV;
489 if (!enable[dev]) {
490 dev++;
491 return -ENOENT;
492 }
493
494 /* (2) */
495 card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0);
496 if (card == NULL)
497 return -ENOMEM;
498
499 /* (3) */
500 err = snd_mychip_create(card, pci, &chip);
501 if (err < 0) {
502 snd_card_free(card);
503 return err;
504 }
505
506 /* (4) */
507 strcpy(card->driver, "My Chip");
508 strcpy(card->shortname, "My Own Chip 123");
509 sprintf(card->longname, "%s at 0x%lx irq %i",
510 card->shortname, chip->ioport, chip->irq);
511
512 /* (5) */
513 .... /* implemented later */
514
515 /* (6) */
516 err = snd_card_register(card);
517 if (err < 0) {
518 snd_card_free(card);
519 return err;
520 }
521
522 /* (7) */
523 pci_set_drvdata(pci, card);
524 dev++;
525 return 0;
526 }
527
528 /* destructor -- see the "Destructor" sub-section */
529 static void __devexit snd_mychip_remove(struct pci_dev *pci)
530 {
531 snd_card_free(pci_get_drvdata(pci));
532 pci_set_drvdata(pci, NULL);
533 }
534]]>
535 </programlisting>
536 </example>
537 </para>
538 </section>
539
540 <section id="basic-flow-constructor">
541 <title>Constructor</title>
542 <para>
543 The real constructor of PCI drivers is the <function>probe</function> callback.
544 The <function>probe</function> callback and other component-constructors which are called
545 from the <function>probe</function> callback should be defined with
546 the <parameter>__devinit</parameter> prefix. You
547 cannot use the <parameter>__init</parameter> prefix for them,
548 because any PCI device could be a hotplug device.
549 </para>
550
551 <para>
552 In the <function>probe</function> callback, the following scheme is often used.
553 </para>
554
555 <section id="basic-flow-constructor-device-index">
556 <title>1) Check and increment the device index.</title>
557 <para>
558 <informalexample>
559 <programlisting>
560<![CDATA[
561 static int dev;
562 ....
563 if (dev >= SNDRV_CARDS)
564 return -ENODEV;
565 if (!enable[dev]) {
566 dev++;
567 return -ENOENT;
568 }
569]]>
570 </programlisting>
571 </informalexample>
572
573 where enable[dev] is the module option.
574 </para>
575
576 <para>
577 Each time the <function>probe</function> callback is called, check the
578 availability of the device. If not available, simply increment
579 the device index and returns. dev will be incremented also
580 later (<link
581 linkend="basic-flow-constructor-set-pci"><citetitle>step
582 7</citetitle></link>).
583 </para>
584 </section>
585
586 <section id="basic-flow-constructor-create-card">
587 <title>2) Create a card instance</title>
588 <para>
589 <informalexample>
590 <programlisting>
591<![CDATA[
592 struct snd_card *card;
593 ....
594 card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0);
595]]>
596 </programlisting>
597 </informalexample>
598 </para>
599
600 <para>
601 The details will be explained in the section
602 <link linkend="card-management-card-instance"><citetitle>
603 Management of Cards and Components</citetitle></link>.
604 </para>
605 </section>
606
607 <section id="basic-flow-constructor-create-main">
608 <title>3) Create a main component</title>
609 <para>
610 In this part, the PCI resources are allocated.
611
612 <informalexample>
613 <programlisting>
614<![CDATA[
615 struct mychip *chip;
616 ....
617 err = snd_mychip_create(card, pci, &chip);
618 if (err < 0) {
619 snd_card_free(card);
620 return err;
621 }
622]]>
623 </programlisting>
624 </informalexample>
625
626 The details will be explained in the section <link
627 linkend="pci-resource"><citetitle>PCI Resource
628 Management</citetitle></link>.
629 </para>
630 </section>
631
632 <section id="basic-flow-constructor-main-component">
633 <title>4) Set the driver ID and name strings.</title>
634 <para>
635 <informalexample>
636 <programlisting>
637<![CDATA[
638 strcpy(card->driver, "My Chip");
639 strcpy(card->shortname, "My Own Chip 123");
640 sprintf(card->longname, "%s at 0x%lx irq %i",
641 card->shortname, chip->ioport, chip->irq);
642]]>
643 </programlisting>
644 </informalexample>
645
646 The driver field holds the minimal ID string of the
647 chip. This is used by alsa-lib's configurator, so keep it
648 simple but unique.
649 Even the same driver can have different driver IDs to
650 distinguish the functionality of each chip type.
651 </para>
652
653 <para>
654 The shortname field is a string shown as more verbose
655 name. The longname field contains the information
656 shown in <filename>/proc/asound/cards</filename>.
657 </para>
658 </section>
659
660 <section id="basic-flow-constructor-create-other">
661 <title>5) Create other components, such as mixer, MIDI, etc.</title>
662 <para>
663 Here you define the basic components such as
664 <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
665 mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
666 MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
667 and other interfaces.
668 Also, if you want a <link linkend="proc-interface"><citetitle>proc
669 file</citetitle></link>, define it here, too.
670 </para>
671 </section>
672
673 <section id="basic-flow-constructor-register-card">
674 <title>6) Register the card instance.</title>
675 <para>
676 <informalexample>
677 <programlisting>
678<![CDATA[
679 err = snd_card_register(card);
680 if (err < 0) {
681 snd_card_free(card);
682 return err;
683 }
684]]>
685 </programlisting>
686 </informalexample>
687 </para>
688
689 <para>
690 Will be explained in the section <link
691 linkend="card-management-registration"><citetitle>Management
692 of Cards and Components</citetitle></link>, too.
693 </para>
694 </section>
695
696 <section id="basic-flow-constructor-set-pci">
697 <title>7) Set the PCI driver data and return zero.</title>
698 <para>
699 <informalexample>
700 <programlisting>
701<![CDATA[
702 pci_set_drvdata(pci, card);
703 dev++;
704 return 0;
705]]>
706 </programlisting>
707 </informalexample>
708
709 In the above, the card record is stored. This pointer is
710 used in the remove callback and power-management
711 callbacks, too.
712 </para>
713 </section>
714 </section>
715
716 <section id="basic-flow-destructor">
717 <title>Destructor</title>
718 <para>
719 The destructor, remove callback, simply releases the card
720 instance. Then the ALSA middle layer will release all the
721 attached components automatically.
722 </para>
723
724 <para>
725 It would be typically like the following:
726
727 <informalexample>
728 <programlisting>
729<![CDATA[
730 static void __devexit snd_mychip_remove(struct pci_dev *pci)
731 {
732 snd_card_free(pci_get_drvdata(pci));
733 pci_set_drvdata(pci, NULL);
734 }
735]]>
736 </programlisting>
737 </informalexample>
738
739 The above code assumes that the card pointer is set to the PCI
740 driver data.
741 </para>
742 </section>
743
744 <section id="basic-flow-header-files">
745 <title>Header Files</title>
746 <para>
747 For the above example, at least the following include files
748 are necessary.
749
750 <informalexample>
751 <programlisting>
752<![CDATA[
753 #include <linux/init.h>
754 #include <linux/pci.h>
755 #include <linux/slab.h>
756 #include <sound/core.h>
757 #include <sound/initval.h>
758]]>
759 </programlisting>
760 </informalexample>
761
762 where the last one is necessary only when module options are
763 defined in the source file. If the code is split into several
764 files, the files without module options don't need them.
765 </para>
766
767 <para>
768 In addition to these headers, you'll need
769 <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
770 handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
771 access. If you use the <function>mdelay()</function> or
772 <function>udelay()</function> functions, you'll need to include
773 <filename>&lt;linux/delay.h&gt;</filename> too.
774 </para>
775
776 <para>
777 The ALSA interfaces like the PCM and control APIs are defined in other
778 <filename>&lt;sound/xxx.h&gt;</filename> header files.
779 They have to be included after
780 <filename>&lt;sound/core.h&gt;</filename>.
781 </para>
782
783 </section>
784 </chapter>
785
786
787<!-- ****************************************************** -->
788<!-- Management of Cards and Components -->
789<!-- ****************************************************** -->
790 <chapter id="card-management">
791 <title>Management of Cards and Components</title>
792
793 <section id="card-management-card-instance">
794 <title>Card Instance</title>
795 <para>
796 For each soundcard, a <quote>card</quote> record must be allocated.
797 </para>
798
799 <para>
800 A card record is the headquarters of the soundcard. It manages
801 the whole list of devices (components) on the soundcard, such as
802 PCM, mixers, MIDI, synthesizer, and so on. Also, the card
803 record holds the ID and the name strings of the card, manages
804 the root of proc files, and controls the power-management states
805 and hotplug disconnections. The component list on the card
806 record is used to manage the correct release of resources at
807 destruction.
808 </para>
809
810 <para>
811 As mentioned above, to create a card instance, call
812 <function>snd_card_new()</function>.
813
814 <informalexample>
815 <programlisting>
816<![CDATA[
817 struct snd_card *card;
818 card = snd_card_new(index, id, module, extra_size);
819]]>
820 </programlisting>
821 </informalexample>
822 </para>
823
824 <para>
825 The function takes four arguments, the card-index number, the
826 id string, the module pointer (usually
827 <constant>THIS_MODULE</constant>),
828 and the size of extra-data space. The last argument is used to
829 allocate card-&gt;private_data for the
830 chip-specific data. Note that these data
831 are allocated by <function>snd_card_new()</function>.
832 </para>
833 </section>
834
835 <section id="card-management-component">
836 <title>Components</title>
837 <para>
838 After the card is created, you can attach the components
839 (devices) to the card instance. In an ALSA driver, a component is
840 represented as a struct <structname>snd_device</structname> object.
841 A component can be a PCM instance, a control interface, a raw
842 MIDI interface, etc. Each such instance has one component
843 entry.
844 </para>
845
846 <para>
847 A component can be created via
848 <function>snd_device_new()</function> function.
849
850 <informalexample>
851 <programlisting>
852<![CDATA[
853 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
854]]>
855 </programlisting>
856 </informalexample>
857 </para>
858
859 <para>
860 This takes the card pointer, the device-level
861 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
862 callback pointers (<parameter>&amp;ops</parameter>). The
863 device-level defines the type of components and the order of
864 registration and de-registration. For most components, the
865 device-level is already defined. For a user-defined component,
866 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
867 </para>
868
869 <para>
870 This function itself doesn't allocate the data space. The data
871 must be allocated manually beforehand, and its pointer is passed
872 as the argument. This pointer is used as the
873 (<parameter>chip</parameter> identifier in the above example)
874 for the instance.
875 </para>
876
877 <para>
878 Each pre-defined ALSA component such as ac97 and pcm calls
879 <function>snd_device_new()</function> inside its
880 constructor. The destructor for each component is defined in the
881 callback pointers. Hence, you don't need to take care of
882 calling a destructor for such a component.
883 </para>
884
885 <para>
886 If you wish to create your own component, you need to
887 set the destructor function to the dev_free callback in
888 the <parameter>ops</parameter>, so that it can be released
889 automatically via <function>snd_card_free()</function>.
890 The next example will show an implementation of chip-specific
891 data.
892 </para>
893 </section>
894
895 <section id="card-management-chip-specific">
896 <title>Chip-Specific Data</title>
897 <para>
898 Chip-specific information, e.g. the I/O port address, its
899 resource pointer, or the irq number, is stored in the
900 chip-specific record.
901
902 <informalexample>
903 <programlisting>
904<![CDATA[
905 struct mychip {
906 ....
907 };
908]]>
909 </programlisting>
910 </informalexample>
911 </para>
912
913 <para>
914 In general, there are two ways of allocating the chip record.
915 </para>
916
917 <section id="card-management-chip-specific-snd-card-new">
918 <title>1. Allocating via <function>snd_card_new()</function>.</title>
919 <para>
920 As mentioned above, you can pass the extra-data-length
921 to the 4th argument of <function>snd_card_new()</function>, i.e.
922
923 <informalexample>
924 <programlisting>
925<![CDATA[
926 card = snd_card_new(index[dev], id[dev], THIS_MODULE, sizeof(struct mychip));
927]]>
928 </programlisting>
929 </informalexample>
930
931 struct <structname>mychip</structname> is the type of the chip record.
932 </para>
933
934 <para>
935 In return, the allocated record can be accessed as
936
937 <informalexample>
938 <programlisting>
939<![CDATA[
940 struct mychip *chip = card->private_data;
941]]>
942 </programlisting>
943 </informalexample>
944
945 With this method, you don't have to allocate twice.
946 The record is released together with the card instance.
947 </para>
948 </section>
949
950 <section id="card-management-chip-specific-allocate-extra">
951 <title>2. Allocating an extra device.</title>
952
953 <para>
954 After allocating a card instance via
955 <function>snd_card_new()</function> (with
956 <constant>NULL</constant> on the 4th arg), call
957 <function>kzalloc()</function>.
958
959 <informalexample>
960 <programlisting>
961<![CDATA[
962 struct snd_card *card;
963 struct mychip *chip;
964 card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
965 .....
966 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
967]]>
968 </programlisting>
969 </informalexample>
970 </para>
971
972 <para>
973 The chip record should have the field to hold the card
974 pointer at least,
975
976 <informalexample>
977 <programlisting>
978<![CDATA[
979 struct mychip {
980 struct snd_card *card;
981 ....
982 };
983]]>
984 </programlisting>
985 </informalexample>
986 </para>
987
988 <para>
989 Then, set the card pointer in the returned chip instance.
990
991 <informalexample>
992 <programlisting>
993<![CDATA[
994 chip->card = card;
995]]>
996 </programlisting>
997 </informalexample>
998 </para>
999
1000 <para>
1001 Next, initialize the fields, and register this chip
1002 record as a low-level device with a specified
1003 <parameter>ops</parameter>,
1004
1005 <informalexample>
1006 <programlisting>
1007<![CDATA[
1008 static struct snd_device_ops ops = {
1009 .dev_free = snd_mychip_dev_free,
1010 };
1011 ....
1012 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1013]]>
1014 </programlisting>
1015 </informalexample>
1016
1017 <function>snd_mychip_dev_free()</function> is the
1018 device-destructor function, which will call the real
1019 destructor.
1020 </para>
1021
1022 <para>
1023 <informalexample>
1024 <programlisting>
1025<![CDATA[
1026 static int snd_mychip_dev_free(struct snd_device *device)
1027 {
1028 return snd_mychip_free(device->device_data);
1029 }
1030]]>
1031 </programlisting>
1032 </informalexample>
1033
1034 where <function>snd_mychip_free()</function> is the real destructor.
1035 </para>
1036 </section>
1037 </section>
1038
1039 <section id="card-management-registration">
1040 <title>Registration and Release</title>
1041 <para>
1042 After all components are assigned, register the card instance
1043 by calling <function>snd_card_register()</function>. Access
1044 to the device files is enabled at this point. That is, before
1045 <function>snd_card_register()</function> is called, the
1046 components are safely inaccessible from external side. If this
1047 call fails, exit the probe function after releasing the card via
1048 <function>snd_card_free()</function>.
1049 </para>
1050
1051 <para>
1052 For releasing the card instance, you can call simply
1053 <function>snd_card_free()</function>. As mentioned earlier, all
1054 components are released automatically by this call.
1055 </para>
1056
1057 <para>
1058 As further notes, the destructors (both
1059 <function>snd_mychip_dev_free</function> and
1060 <function>snd_mychip_free</function>) cannot be defined with
1061 the <parameter>__devexit</parameter> prefix, because they may be
1062 called from the constructor, too, at the false path.
1063 </para>
1064
1065 <para>
1066 For a device which allows hotplugging, you can use
1067 <function>snd_card_free_when_closed</function>. This one will
1068 postpone the destruction until all devices are closed.
1069 </para>
1070
1071 </section>
1072
1073 </chapter>
1074
1075
1076<!-- ****************************************************** -->
1077<!-- PCI Resource Management -->
1078<!-- ****************************************************** -->
1079 <chapter id="pci-resource">
1080 <title>PCI Resource Management</title>
1081
1082 <section id="pci-resource-example">
1083 <title>Full Code Example</title>
1084 <para>
1085 In this section, we'll complete the chip-specific constructor,
1086 destructor and PCI entries. Example code is shown first,
1087 below.
1088
1089 <example>
1090 <title>PCI Resource Management Example</title>
1091 <programlisting>
1092<![CDATA[
1093 struct mychip {
1094 struct snd_card *card;
1095 struct pci_dev *pci;
1096
1097 unsigned long port;
1098 int irq;
1099 };
1100
1101 static int snd_mychip_free(struct mychip *chip)
1102 {
1103 /* disable hardware here if any */
1104 .... /* (not implemented in this document) */
1105
1106 /* release the irq */
1107 if (chip->irq >= 0)
1108 free_irq(chip->irq, chip);
1109 /* release the I/O ports & memory */
1110 pci_release_regions(chip->pci);
1111 /* disable the PCI entry */
1112 pci_disable_device(chip->pci);
1113 /* release the data */
1114 kfree(chip);
1115 return 0;
1116 }
1117
1118 /* chip-specific constructor */
1119 static int __devinit snd_mychip_create(struct snd_card *card,
1120 struct pci_dev *pci,
1121 struct mychip **rchip)
1122 {
1123 struct mychip *chip;
1124 int err;
1125 static struct snd_device_ops ops = {
1126 .dev_free = snd_mychip_dev_free,
1127 };
1128
1129 *rchip = NULL;
1130
1131 /* initialize the PCI entry */
1132 err = pci_enable_device(pci);
1133 if (err < 0)
1134 return err;
1135 /* check PCI availability (28bit DMA) */
1136 if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 ||
1137 pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) {
1138 printk(KERN_ERR "error to set 28bit mask DMA\n");
1139 pci_disable_device(pci);
1140 return -ENXIO;
1141 }
1142
1143 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
1144 if (chip == NULL) {
1145 pci_disable_device(pci);
1146 return -ENOMEM;
1147 }
1148
1149 /* initialize the stuff */
1150 chip->card = card;
1151 chip->pci = pci;
1152 chip->irq = -1;
1153
1154 /* (1) PCI resource allocation */
1155 err = pci_request_regions(pci, "My Chip");
1156 if (err < 0) {
1157 kfree(chip);
1158 pci_disable_device(pci);
1159 return err;
1160 }
1161 chip->port = pci_resource_start(pci, 0);
1162 if (request_irq(pci->irq, snd_mychip_interrupt,
1163 IRQF_SHARED, "My Chip", chip)) {
1164 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1165 snd_mychip_free(chip);
1166 return -EBUSY;
1167 }
1168 chip->irq = pci->irq;
1169
1170 /* (2) initialization of the chip hardware */
1171 .... /* (not implemented in this document) */
1172
1173 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1174 if (err < 0) {
1175 snd_mychip_free(chip);
1176 return err;
1177 }
1178
1179 snd_card_set_dev(card, &pci->dev);
1180
1181 *rchip = chip;
1182 return 0;
1183 }
1184
1185 /* PCI IDs */
1186 static struct pci_device_id snd_mychip_ids[] = {
1187 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1188 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1189 ....
1190 { 0, }
1191 };
1192 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1193
1194 /* pci_driver definition */
1195 static struct pci_driver driver = {
1196 .name = "My Own Chip",
1197 .id_table = snd_mychip_ids,
1198 .probe = snd_mychip_probe,
1199 .remove = __devexit_p(snd_mychip_remove),
1200 };
1201
1202 /* module initialization */
1203 static int __init alsa_card_mychip_init(void)
1204 {
1205 return pci_register_driver(&driver);
1206 }
1207
1208 /* module clean up */
1209 static void __exit alsa_card_mychip_exit(void)
1210 {
1211 pci_unregister_driver(&driver);
1212 }
1213
1214 module_init(alsa_card_mychip_init)
1215 module_exit(alsa_card_mychip_exit)
1216
1217 EXPORT_NO_SYMBOLS; /* for old kernels only */
1218]]>
1219 </programlisting>
1220 </example>
1221 </para>
1222 </section>
1223
1224 <section id="pci-resource-some-haftas">
1225 <title>Some Hafta's</title>
1226 <para>
1227 The allocation of PCI resources is done in the
1228 <function>probe()</function> function, and usually an extra
1229 <function>xxx_create()</function> function is written for this
1230 purpose.
1231 </para>
1232
1233 <para>
1234 In the case of PCI devices, you first have to call
1235 the <function>pci_enable_device()</function> function before
1236 allocating resources. Also, you need to set the proper PCI DMA
1237 mask to limit the accessed I/O range. In some cases, you might
1238 need to call <function>pci_set_master()</function> function,
1239 too.
1240 </para>
1241
1242 <para>
1243 Suppose the 28bit mask, and the code to be added would be like:
1244
1245 <informalexample>
1246 <programlisting>
1247<![CDATA[
1248 err = pci_enable_device(pci);
1249 if (err < 0)
1250 return err;
1251 if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 ||
1252 pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) {
1253 printk(KERN_ERR "error to set 28bit mask DMA\n");
1254 pci_disable_device(pci);
1255 return -ENXIO;
1256 }
1257
1258]]>
1259 </programlisting>
1260 </informalexample>
1261 </para>
1262 </section>
1263
1264 <section id="pci-resource-resource-allocation">
1265 <title>Resource Allocation</title>
1266 <para>
1267 The allocation of I/O ports and irqs is done via standard kernel
1268 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1269 that. And these resources must be released in the destructor
1270 function (see below). Also, on ALSA 0.9.x, you don't need to
1271 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
1272 </para>
1273
1274 <para>
1275 Now assume that the PCI device has an I/O port with 8 bytes
1276 and an interrupt. Then struct <structname>mychip</structname> will have the
1277 following fields:
1278
1279 <informalexample>
1280 <programlisting>
1281<![CDATA[
1282 struct mychip {
1283 struct snd_card *card;
1284
1285 unsigned long port;
1286 int irq;
1287 };
1288]]>
1289 </programlisting>
1290 </informalexample>
1291 </para>
1292
1293 <para>
1294 For an I/O port (and also a memory region), you need to have
1295 the resource pointer for the standard resource management. For
1296 an irq, you have to keep only the irq number (integer). But you
1297 need to initialize this number as -1 before actual allocation,
1298 since irq 0 is valid. The port address and its resource pointer
1299 can be initialized as null by
1300 <function>kzalloc()</function> automatically, so you
1301 don't have to take care of resetting them.
1302 </para>
1303
1304 <para>
1305 The allocation of an I/O port is done like this:
1306
1307 <informalexample>
1308 <programlisting>
1309<![CDATA[
1310 err = pci_request_regions(pci, "My Chip");
1311 if (err < 0) {
1312 kfree(chip);
1313 pci_disable_device(pci);
1314 return err;
1315 }
1316 chip->port = pci_resource_start(pci, 0);
1317]]>
1318 </programlisting>
1319 </informalexample>
1320 </para>
1321
1322 <para>
1323 <!-- obsolete -->
1324 It will reserve the I/O port region of 8 bytes of the given
1325 PCI device. The returned value, chip-&gt;res_port, is allocated
1326 via <function>kmalloc()</function> by
1327 <function>request_region()</function>. The pointer must be
1328 released via <function>kfree()</function>, but there is a
1329 problem with this. This issue will be explained later.
1330 </para>
1331
1332 <para>
1333 The allocation of an interrupt source is done like this:
1334
1335 <informalexample>
1336 <programlisting>
1337<![CDATA[
1338 if (request_irq(pci->irq, snd_mychip_interrupt,
1339 IRQF_SHARED, "My Chip", chip)) {
1340 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1341 snd_mychip_free(chip);
1342 return -EBUSY;
1343 }
1344 chip->irq = pci->irq;
1345]]>
1346 </programlisting>
1347 </informalexample>
1348
1349 where <function>snd_mychip_interrupt()</function> is the
1350 interrupt handler defined <link
1351 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1352 Note that chip-&gt;irq should be defined
1353 only when <function>request_irq()</function> succeeded.
1354 </para>
1355
1356 <para>
1357 On the PCI bus, interrupts can be shared. Thus,
1358 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
1359 <function>request_irq()</function>.
1360 </para>
1361
1362 <para>
1363 The last argument of <function>request_irq()</function> is the
1364 data pointer passed to the interrupt handler. Usually, the
1365 chip-specific record is used for that, but you can use what you
1366 like, too.
1367 </para>
1368
1369 <para>
1370 I won't give details about the interrupt handler at this
1371 point, but at least its appearance can be explained now. The
1372 interrupt handler looks usually like the following:
1373
1374 <informalexample>
1375 <programlisting>
1376<![CDATA[
1377 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
1378 {
1379 struct mychip *chip = dev_id;
1380 ....
1381 return IRQ_HANDLED;
1382 }
1383]]>
1384 </programlisting>
1385 </informalexample>
1386 </para>
1387
1388 <para>
1389 Now let's write the corresponding destructor for the resources
1390 above. The role of destructor is simple: disable the hardware
1391 (if already activated) and release the resources. So far, we
1392 have no hardware part, so the disabling code is not written here.
1393 </para>
1394
1395 <para>
1396 To release the resources, the <quote>check-and-release</quote>
1397 method is a safer way. For the interrupt, do like this:
1398
1399 <informalexample>
1400 <programlisting>
1401<![CDATA[
1402 if (chip->irq >= 0)
1403 free_irq(chip->irq, chip);
1404]]>
1405 </programlisting>
1406 </informalexample>
1407
1408 Since the irq number can start from 0, you should initialize
1409 chip-&gt;irq with a negative value (e.g. -1), so that you can
1410 check the validity of the irq number as above.
1411 </para>
1412
1413 <para>
1414 When you requested I/O ports or memory regions via
1415 <function>pci_request_region()</function> or
1416 <function>pci_request_regions()</function> like in this example,
1417 release the resource(s) using the corresponding function,
1418 <function>pci_release_region()</function> or
1419 <function>pci_release_regions()</function>.
1420
1421 <informalexample>
1422 <programlisting>
1423<![CDATA[
1424 pci_release_regions(chip->pci);
1425]]>
1426 </programlisting>
1427 </informalexample>
1428 </para>
1429
1430 <para>
1431 When you requested manually via <function>request_region()</function>
1432 or <function>request_mem_region</function>, you can release it via
1433 <function>release_resource()</function>. Suppose that you keep
1434 the resource pointer returned from <function>request_region()</function>
1435 in chip-&gt;res_port, the release procedure looks like:
1436
1437 <informalexample>
1438 <programlisting>
1439<![CDATA[
1440 release_and_free_resource(chip->res_port);
1441]]>
1442 </programlisting>
1443 </informalexample>
1444 </para>
1445
1446 <para>
1447 Don't forget to call <function>pci_disable_device()</function>
1448 before the end.
1449 </para>
1450
1451 <para>
1452 And finally, release the chip-specific record.
1453
1454 <informalexample>
1455 <programlisting>
1456<![CDATA[
1457 kfree(chip);
1458]]>
1459 </programlisting>
1460 </informalexample>
1461 </para>
1462
1463 <para>
1464 Again, remember that you cannot
1465 use the <parameter>__devexit</parameter> prefix for this destructor.
1466 </para>
1467
1468 <para>
1469 We didn't implement the hardware disabling part in the above.
1470 If you need to do this, please note that the destructor may be
1471 called even before the initialization of the chip is completed.
1472 It would be better to have a flag to skip hardware disabling
1473 if the hardware was not initialized yet.
1474 </para>
1475
1476 <para>
1477 When the chip-data is assigned to the card using
1478 <function>snd_device_new()</function> with
1479 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1480 called at the last. That is, it is assured that all other
1481 components like PCMs and controls have already been released.
1482 You don't have to stop PCMs, etc. explicitly, but just
1483 call low-level hardware stopping.
1484 </para>
1485
1486 <para>
1487 The management of a memory-mapped region is almost as same as
1488 the management of an I/O port. You'll need three fields like
1489 the following:
1490
1491 <informalexample>
1492 <programlisting>
1493<![CDATA[
1494 struct mychip {
1495 ....
1496 unsigned long iobase_phys;
1497 void __iomem *iobase_virt;
1498 };
1499]]>
1500 </programlisting>
1501 </informalexample>
1502
1503 and the allocation would be like below:
1504
1505 <informalexample>
1506 <programlisting>
1507<![CDATA[
1508 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1509 kfree(chip);
1510 return err;
1511 }
1512 chip->iobase_phys = pci_resource_start(pci, 0);
1513 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1514 pci_resource_len(pci, 0));
1515]]>
1516 </programlisting>
1517 </informalexample>
1518
1519 and the corresponding destructor would be:
1520
1521 <informalexample>
1522 <programlisting>
1523<![CDATA[
1524 static int snd_mychip_free(struct mychip *chip)
1525 {
1526 ....
1527 if (chip->iobase_virt)
1528 iounmap(chip->iobase_virt);
1529 ....
1530 pci_release_regions(chip->pci);
1531 ....
1532 }
1533]]>
1534 </programlisting>
1535 </informalexample>
1536 </para>
1537
1538 </section>
1539
1540 <section id="pci-resource-device-struct">
1541 <title>Registration of Device Struct</title>
1542 <para>
1543 At some point, typically after calling <function>snd_device_new()</function>,
1544 you need to register the struct <structname>device</structname> of the chip
1545 you're handling for udev and co. ALSA provides a macro for compatibility with
1546 older kernels. Simply call like the following:
1547 <informalexample>
1548 <programlisting>
1549<![CDATA[
1550 snd_card_set_dev(card, &pci->dev);
1551]]>
1552 </programlisting>
1553 </informalexample>
1554 so that it stores the PCI's device pointer to the card. This will be
1555 referred by ALSA core functions later when the devices are registered.
1556 </para>
1557 <para>
1558 In the case of non-PCI, pass the proper device struct pointer of the BUS
1559 instead. (In the case of legacy ISA without PnP, you don't have to do
1560 anything.)
1561 </para>
1562 </section>
1563
1564 <section id="pci-resource-entries">
1565 <title>PCI Entries</title>
1566 <para>
1567 So far, so good. Let's finish the missing PCI
1568 stuff. At first, we need a
1569 <structname>pci_device_id</structname> table for this
1570 chipset. It's a table of PCI vendor/device ID number, and some
1571 masks.
1572 </para>
1573
1574 <para>
1575 For example,
1576
1577 <informalexample>
1578 <programlisting>
1579<![CDATA[
1580 static struct pci_device_id snd_mychip_ids[] = {
1581 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1582 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1583 ....
1584 { 0, }
1585 };
1586 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1587]]>
1588 </programlisting>
1589 </informalexample>
1590 </para>
1591
1592 <para>
1593 The first and second fields of
1594 the <structname>pci_device_id</structname> structure are the vendor and
1595 device IDs. If you have no reason to filter the matching
1596 devices, you can leave the remaining fields as above. The last
1597 field of the <structname>pci_device_id</structname> struct contains
1598 private data for this entry. You can specify any value here, for
1599 example, to define specific operations for supported device IDs.
1600 Such an example is found in the intel8x0 driver.
1601 </para>
1602
1603 <para>
1604 The last entry of this list is the terminator. You must
1605 specify this all-zero entry.
1606 </para>
1607
1608 <para>
1609 Then, prepare the <structname>pci_driver</structname> record:
1610
1611 <informalexample>
1612 <programlisting>
1613<![CDATA[
1614 static struct pci_driver driver = {
1615 .name = "My Own Chip",
1616 .id_table = snd_mychip_ids,
1617 .probe = snd_mychip_probe,
1618 .remove = __devexit_p(snd_mychip_remove),
1619 };
1620]]>
1621 </programlisting>
1622 </informalexample>
1623 </para>
1624
1625 <para>
1626 The <structfield>probe</structfield> and
1627 <structfield>remove</structfield> functions have already
1628 been defined in the previous sections.
1629 The <structfield>remove</structfield> function should
1630 be defined with the
1631 <function>__devexit_p()</function> macro, so that it's not
1632 defined for built-in (and non-hot-pluggable) case. The
1633 <structfield>name</structfield>
1634 field is the name string of this device. Note that you must not
1635 use a slash <quote>/</quote> in this string.
1636 </para>
1637
1638 <para>
1639 And at last, the module entries:
1640
1641 <informalexample>
1642 <programlisting>
1643<![CDATA[
1644 static int __init alsa_card_mychip_init(void)
1645 {
1646 return pci_register_driver(&driver);
1647 }
1648
1649 static void __exit alsa_card_mychip_exit(void)
1650 {
1651 pci_unregister_driver(&driver);
1652 }
1653
1654 module_init(alsa_card_mychip_init)
1655 module_exit(alsa_card_mychip_exit)
1656]]>
1657 </programlisting>
1658 </informalexample>
1659 </para>
1660
1661 <para>
1662 Note that these module entries are tagged with
1663 <parameter>__init</parameter> and
1664 <parameter>__exit</parameter> prefixes, not
1665 <parameter>__devinit</parameter> nor
1666 <parameter>__devexit</parameter>.
1667 </para>
1668
1669 <para>
1670 Oh, one thing was forgotten. If you have no exported symbols,
1671 you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1672
1673 <informalexample>
1674 <programlisting>
1675<![CDATA[
1676 EXPORT_NO_SYMBOLS;
1677]]>
1678 </programlisting>
1679 </informalexample>
1680
1681 That's all!
1682 </para>
1683 </section>
1684 </chapter>
1685
1686
1687<!-- ****************************************************** -->
1688<!-- PCM Interface -->
1689<!-- ****************************************************** -->
1690 <chapter id="pcm-interface">
1691 <title>PCM Interface</title>
1692
1693 <section id="pcm-interface-general">
1694 <title>General</title>
1695 <para>
1696 The PCM middle layer of ALSA is quite powerful and it is only
1697 necessary for each driver to implement the low-level functions
1698 to access its hardware.
1699 </para>
1700
1701 <para>
1702 For accessing to the PCM layer, you need to include
1703 <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
1704 <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
1705 if you access to some functions related with hw_param.
1706 </para>
1707
1708 <para>
1709 Each card device can have up to four pcm instances. A pcm
1710 instance corresponds to a pcm device file. The limitation of
1711 number of instances comes only from the available bit size of
1712 the Linux's device numbers. Once when 64bit device number is
1713 used, we'll have more pcm instances available.
1714 </para>
1715
1716 <para>
1717 A pcm instance consists of pcm playback and capture streams,
1718 and each pcm stream consists of one or more pcm substreams. Some
1719 soundcards support multiple playback functions. For example,
1720 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1721 each open, a free substream is (usually) automatically chosen
1722 and opened. Meanwhile, when only one substream exists and it was
1723 already opened, the successful open will either block
1724 or error with <constant>EAGAIN</constant> according to the
1725 file open mode. But you don't have to care about such details in your
1726 driver. The PCM middle layer will take care of such work.
1727 </para>
1728 </section>
1729
1730 <section id="pcm-interface-example">
1731 <title>Full Code Example</title>
1732 <para>
1733 The example code below does not include any hardware access
1734 routines but shows only the skeleton, how to build up the PCM
1735 interfaces.
1736
1737 <example>
1738 <title>PCM Example Code</title>
1739 <programlisting>
1740<![CDATA[
1741 #include <sound/pcm.h>
1742 ....
1743
1744 /* hardware definition */
1745 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1746 .info = (SNDRV_PCM_INFO_MMAP |
1747 SNDRV_PCM_INFO_INTERLEAVED |
1748 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1749 SNDRV_PCM_INFO_MMAP_VALID),
1750 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1751 .rates = SNDRV_PCM_RATE_8000_48000,
1752 .rate_min = 8000,
1753 .rate_max = 48000,
1754 .channels_min = 2,
1755 .channels_max = 2,
1756 .buffer_bytes_max = 32768,
1757 .period_bytes_min = 4096,
1758 .period_bytes_max = 32768,
1759 .periods_min = 1,
1760 .periods_max = 1024,
1761 };
1762
1763 /* hardware definition */
1764 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1765 .info = (SNDRV_PCM_INFO_MMAP |
1766 SNDRV_PCM_INFO_INTERLEAVED |
1767 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1768 SNDRV_PCM_INFO_MMAP_VALID),
1769 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1770 .rates = SNDRV_PCM_RATE_8000_48000,
1771 .rate_min = 8000,
1772 .rate_max = 48000,
1773 .channels_min = 2,
1774 .channels_max = 2,
1775 .buffer_bytes_max = 32768,
1776 .period_bytes_min = 4096,
1777 .period_bytes_max = 32768,
1778 .periods_min = 1,
1779 .periods_max = 1024,
1780 };
1781
1782 /* open callback */
1783 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1784 {
1785 struct mychip *chip = snd_pcm_substream_chip(substream);
1786 struct snd_pcm_runtime *runtime = substream->runtime;
1787
1788 runtime->hw = snd_mychip_playback_hw;
1789 /* more hardware-initialization will be done here */
1790 ....
1791 return 0;
1792 }
1793
1794 /* close callback */
1795 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1796 {
1797 struct mychip *chip = snd_pcm_substream_chip(substream);
1798 /* the hardware-specific codes will be here */
1799 ....
1800 return 0;
1801
1802 }
1803
1804 /* open callback */
1805 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1806 {
1807 struct mychip *chip = snd_pcm_substream_chip(substream);
1808 struct snd_pcm_runtime *runtime = substream->runtime;
1809
1810 runtime->hw = snd_mychip_capture_hw;
1811 /* more hardware-initialization will be done here */
1812 ....
1813 return 0;
1814 }
1815
1816 /* close callback */
1817 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1818 {
1819 struct mychip *chip = snd_pcm_substream_chip(substream);
1820 /* the hardware-specific codes will be here */
1821 ....
1822 return 0;
1823
1824 }
1825
1826 /* hw_params callback */
1827 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1828 struct snd_pcm_hw_params *hw_params)
1829 {
1830 return snd_pcm_lib_malloc_pages(substream,
1831 params_buffer_bytes(hw_params));
1832 }
1833
1834 /* hw_free callback */
1835 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1836 {
1837 return snd_pcm_lib_free_pages(substream);
1838 }
1839
1840 /* prepare callback */
1841 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1842 {
1843 struct mychip *chip = snd_pcm_substream_chip(substream);
1844 struct snd_pcm_runtime *runtime = substream->runtime;
1845
1846 /* set up the hardware with the current configuration
1847 * for example...
1848 */
1849 mychip_set_sample_format(chip, runtime->format);
1850 mychip_set_sample_rate(chip, runtime->rate);
1851 mychip_set_channels(chip, runtime->channels);
1852 mychip_set_dma_setup(chip, runtime->dma_addr,
1853 chip->buffer_size,
1854 chip->period_size);
1855 return 0;
1856 }
1857
1858 /* trigger callback */
1859 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1860 int cmd)
1861 {
1862 switch (cmd) {
1863 case SNDRV_PCM_TRIGGER_START:
1864 /* do something to start the PCM engine */
1865 ....
1866 break;
1867 case SNDRV_PCM_TRIGGER_STOP:
1868 /* do something to stop the PCM engine */
1869 ....
1870 break;
1871 default:
1872 return -EINVAL;
1873 }
1874 }
1875
1876 /* pointer callback */
1877 static snd_pcm_uframes_t
1878 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1879 {
1880 struct mychip *chip = snd_pcm_substream_chip(substream);
1881 unsigned int current_ptr;
1882
1883 /* get the current hardware pointer */
1884 current_ptr = mychip_get_hw_pointer(chip);
1885 return current_ptr;
1886 }
1887
1888 /* operators */
1889 static struct snd_pcm_ops snd_mychip_playback_ops = {
1890 .open = snd_mychip_playback_open,
1891 .close = snd_mychip_playback_close,
1892 .ioctl = snd_pcm_lib_ioctl,
1893 .hw_params = snd_mychip_pcm_hw_params,
1894 .hw_free = snd_mychip_pcm_hw_free,
1895 .prepare = snd_mychip_pcm_prepare,
1896 .trigger = snd_mychip_pcm_trigger,
1897 .pointer = snd_mychip_pcm_pointer,
1898 };
1899
1900 /* operators */
1901 static struct snd_pcm_ops snd_mychip_capture_ops = {
1902 .open = snd_mychip_capture_open,
1903 .close = snd_mychip_capture_close,
1904 .ioctl = snd_pcm_lib_ioctl,
1905 .hw_params = snd_mychip_pcm_hw_params,
1906 .hw_free = snd_mychip_pcm_hw_free,
1907 .prepare = snd_mychip_pcm_prepare,
1908 .trigger = snd_mychip_pcm_trigger,
1909 .pointer = snd_mychip_pcm_pointer,
1910 };
1911
1912 /*
1913 * definitions of capture are omitted here...
1914 */
1915
1916 /* create a pcm device */
1917 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
1918 {
1919 struct snd_pcm *pcm;
1920 int err;
1921
1922 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1923 if (err < 0)
1924 return err;
1925 pcm->private_data = chip;
1926 strcpy(pcm->name, "My Chip");
1927 chip->pcm = pcm;
1928 /* set operators */
1929 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1930 &snd_mychip_playback_ops);
1931 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1932 &snd_mychip_capture_ops);
1933 /* pre-allocation of buffers */
1934 /* NOTE: this may fail */
1935 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1936 snd_dma_pci_data(chip->pci),
1937 64*1024, 64*1024);
1938 return 0;
1939 }
1940]]>
1941 </programlisting>
1942 </example>
1943 </para>
1944 </section>
1945
1946 <section id="pcm-interface-constructor">
1947 <title>Constructor</title>
1948 <para>
1949 A pcm instance is allocated by the <function>snd_pcm_new()</function>
1950 function. It would be better to create a constructor for pcm,
1951 namely,
1952
1953 <informalexample>
1954 <programlisting>
1955<![CDATA[
1956 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
1957 {
1958 struct snd_pcm *pcm;
1959 int err;
1960
1961 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1962 if (err < 0)
1963 return err;
1964 pcm->private_data = chip;
1965 strcpy(pcm->name, "My Chip");
1966 chip->pcm = pcm;
1967 ....
1968 return 0;
1969 }
1970]]>
1971 </programlisting>
1972 </informalexample>
1973 </para>
1974
1975 <para>
1976 The <function>snd_pcm_new()</function> function takes four
1977 arguments. The first argument is the card pointer to which this
1978 pcm is assigned, and the second is the ID string.
1979 </para>
1980
1981 <para>
1982 The third argument (<parameter>index</parameter>, 0 in the
1983 above) is the index of this new pcm. It begins from zero. If
1984 you create more than one pcm instances, specify the
1985 different numbers in this argument. For example,
1986 <parameter>index</parameter> = 1 for the second PCM device.
1987 </para>
1988
1989 <para>
1990 The fourth and fifth arguments are the number of substreams
1991 for playback and capture, respectively. Here 1 is used for
1992 both arguments. When no playback or capture substreams are available,
1993 pass 0 to the corresponding argument.
1994 </para>
1995
1996 <para>
1997 If a chip supports multiple playbacks or captures, you can
1998 specify more numbers, but they must be handled properly in
1999 open/close, etc. callbacks. When you need to know which
2000 substream you are referring to, then it can be obtained from
2001 struct <structname>snd_pcm_substream</structname> data passed to each callback
2002 as follows:
2003
2004 <informalexample>
2005 <programlisting>
2006<![CDATA[
2007 struct snd_pcm_substream *substream;
2008 int index = substream->number;
2009]]>
2010 </programlisting>
2011 </informalexample>
2012 </para>
2013
2014 <para>
2015 After the pcm is created, you need to set operators for each
2016 pcm stream.
2017
2018 <informalexample>
2019 <programlisting>
2020<![CDATA[
2021 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
2022 &snd_mychip_playback_ops);
2023 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
2024 &snd_mychip_capture_ops);
2025]]>
2026 </programlisting>
2027 </informalexample>
2028 </para>
2029
2030 <para>
2031 The operators are defined typically like this:
2032
2033 <informalexample>
2034 <programlisting>
2035<![CDATA[
2036 static struct snd_pcm_ops snd_mychip_playback_ops = {
2037 .open = snd_mychip_pcm_open,
2038 .close = snd_mychip_pcm_close,
2039 .ioctl = snd_pcm_lib_ioctl,
2040 .hw_params = snd_mychip_pcm_hw_params,
2041 .hw_free = snd_mychip_pcm_hw_free,
2042 .prepare = snd_mychip_pcm_prepare,
2043 .trigger = snd_mychip_pcm_trigger,
2044 .pointer = snd_mychip_pcm_pointer,
2045 };
2046]]>
2047 </programlisting>
2048 </informalexample>
2049
2050 All the callbacks are described in the
2051 <link linkend="pcm-interface-operators"><citetitle>
2052 Operators</citetitle></link> subsection.
2053 </para>
2054
2055 <para>
2056 After setting the operators, you probably will want to
2057 pre-allocate the buffer. For the pre-allocation, simply call
2058 the following:
2059
2060 <informalexample>
2061 <programlisting>
2062<![CDATA[
2063 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2064 snd_dma_pci_data(chip->pci),
2065 64*1024, 64*1024);
2066]]>
2067 </programlisting>
2068 </informalexample>
2069
2070 It will allocate a buffer up to 64kB as default.
2071 Buffer management details will be described in the later section <link
2072 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2073 Management</citetitle></link>.
2074 </para>
2075
2076 <para>
2077 Additionally, you can set some extra information for this pcm
2078 in pcm-&gt;info_flags.
2079 The available values are defined as
2080 <constant>SNDRV_PCM_INFO_XXX</constant> in
2081 <filename>&lt;sound/asound.h&gt;</filename>, which is used for
2082 the hardware definition (described later). When your soundchip
2083 supports only half-duplex, specify like this:
2084
2085 <informalexample>
2086 <programlisting>
2087<![CDATA[
2088 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2089]]>
2090 </programlisting>
2091 </informalexample>
2092 </para>
2093 </section>
2094
2095 <section id="pcm-interface-destructor">
2096 <title>... And the Destructor?</title>
2097 <para>
2098 The destructor for a pcm instance is not always
2099 necessary. Since the pcm device will be released by the middle
2100 layer code automatically, you don't have to call the destructor
2101 explicitly.
2102 </para>
2103
2104 <para>
2105 The destructor would be necessary if you created
2106 special records internally and needed to release them. In such a
2107 case, set the destructor function to
2108 pcm-&gt;private_free:
2109
2110 <example>
2111 <title>PCM Instance with a Destructor</title>
2112 <programlisting>
2113<![CDATA[
2114 static void mychip_pcm_free(struct snd_pcm *pcm)
2115 {
2116 struct mychip *chip = snd_pcm_chip(pcm);
2117 /* free your own data */
2118 kfree(chip->my_private_pcm_data);
2119 /* do what you like else */
2120 ....
2121 }
2122
2123 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
2124 {
2125 struct snd_pcm *pcm;
2126 ....
2127 /* allocate your own data */
2128 chip->my_private_pcm_data = kmalloc(...);
2129 /* set the destructor */
2130 pcm->private_data = chip;
2131 pcm->private_free = mychip_pcm_free;
2132 ....
2133 }
2134]]>
2135 </programlisting>
2136 </example>
2137 </para>
2138 </section>
2139
2140 <section id="pcm-interface-runtime">
2141 <title>Runtime Pointer - The Chest of PCM Information</title>
2142 <para>
2143 When the PCM substream is opened, a PCM runtime instance is
2144 allocated and assigned to the substream. This pointer is
2145 accessible via <constant>substream-&gt;runtime</constant>.
2146 This runtime pointer holds most information you need
2147 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2148 pointers, mmap records, spinlocks, etc.
2149 </para>
2150
2151 <para>
2152 The definition of runtime instance is found in
2153 <filename>&lt;sound/pcm.h&gt;</filename>. Here are
2154 the contents of this file:
2155 <informalexample>
2156 <programlisting>
2157<![CDATA[
2158struct _snd_pcm_runtime {
2159 /* -- Status -- */
2160 struct snd_pcm_substream *trigger_master;
2161 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2162 int overrange;
2163 snd_pcm_uframes_t avail_max;
2164 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2165 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2166
2167 /* -- HW params -- */
2168 snd_pcm_access_t access; /* access mode */
2169 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2170 snd_pcm_subformat_t subformat; /* subformat */
2171 unsigned int rate; /* rate in Hz */
2172 unsigned int channels; /* channels */
2173 snd_pcm_uframes_t period_size; /* period size */
2174 unsigned int periods; /* periods */
2175 snd_pcm_uframes_t buffer_size; /* buffer size */
2176 unsigned int tick_time; /* tick time */
2177 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2178 size_t byte_align;
2179 unsigned int frame_bits;
2180 unsigned int sample_bits;
2181 unsigned int info;
2182 unsigned int rate_num;
2183 unsigned int rate_den;
2184
2185 /* -- SW params -- */
2186 struct timespec tstamp_mode; /* mmap timestamp is updated */
2187 unsigned int period_step;
2188 unsigned int sleep_min; /* min ticks to sleep */
2189 snd_pcm_uframes_t start_threshold;
2190 snd_pcm_uframes_t stop_threshold;
2191 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2192 noise is nearest than this */
2193 snd_pcm_uframes_t silence_size; /* Silence filling size */
2194 snd_pcm_uframes_t boundary; /* pointers wrap point */
2195
2196 snd_pcm_uframes_t silenced_start;
2197 snd_pcm_uframes_t silenced_size;
2198
2199 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2200
2201 /* -- mmap -- */
2202 volatile struct snd_pcm_mmap_status *status;
2203 volatile struct snd_pcm_mmap_control *control;
2204 atomic_t mmap_count;
2205
2206 /* -- locking / scheduling -- */
2207 spinlock_t lock;
2208 wait_queue_head_t sleep;
2209 struct timer_list tick_timer;
2210 struct fasync_struct *fasync;
2211
2212 /* -- private section -- */
2213 void *private_data;
2214 void (*private_free)(struct snd_pcm_runtime *runtime);
2215
2216 /* -- hardware description -- */
2217 struct snd_pcm_hardware hw;
2218 struct snd_pcm_hw_constraints hw_constraints;
2219
2220 /* -- interrupt callbacks -- */
2221 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2222 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
2223
2224 /* -- timer -- */
2225 unsigned int timer_resolution; /* timer resolution */
2226
2227 /* -- DMA -- */
2228 unsigned char *dma_area; /* DMA area */
2229 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2230 size_t dma_bytes; /* size of DMA area */
2231
2232 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2233
2234#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2235 /* -- OSS things -- */
2236 struct snd_pcm_oss_runtime oss;
2237#endif
2238};
2239]]>
2240 </programlisting>
2241 </informalexample>
2242 </para>
2243
2244 <para>
2245 For the operators (callbacks) of each sound driver, most of
2246 these records are supposed to be read-only. Only the PCM
2247 middle-layer changes / updates them. The exceptions are
2248 the hardware description (hw), interrupt callbacks
2249 (transfer_ack_xxx), DMA buffer information, and the private
2250 data. Besides, if you use the standard buffer allocation
2251 method via <function>snd_pcm_lib_malloc_pages()</function>,
2252 you don't need to set the DMA buffer information by yourself.
2253 </para>
2254
2255 <para>
2256 In the sections below, important records are explained.
2257 </para>
2258
2259 <section id="pcm-interface-runtime-hw">
2260 <title>Hardware Description</title>
2261 <para>
2262 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
2263 contains the definitions of the fundamental hardware
2264 configuration. Above all, you'll need to define this in
2265 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2266 the open callback</citetitle></link>.
2267 Note that the runtime instance holds the copy of the
2268 descriptor, not the pointer to the existing descriptor. That
2269 is, in the open callback, you can modify the copied descriptor
2270 (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
2271 number of channels is 1 only on some chip models, you can
2272 still use the same hardware descriptor and change the
2273 channels_max later:
2274 <informalexample>
2275 <programlisting>
2276<![CDATA[
2277 struct snd_pcm_runtime *runtime = substream->runtime;
2278 ...
2279 runtime->hw = snd_mychip_playback_hw; /* common definition */
2280 if (chip->model == VERY_OLD_ONE)
2281 runtime->hw.channels_max = 1;
2282]]>
2283 </programlisting>
2284 </informalexample>
2285 </para>
2286
2287 <para>
2288 Typically, you'll have a hardware descriptor as below:
2289 <informalexample>
2290 <programlisting>
2291<![CDATA[
2292 static struct snd_pcm_hardware snd_mychip_playback_hw = {
2293 .info = (SNDRV_PCM_INFO_MMAP |
2294 SNDRV_PCM_INFO_INTERLEAVED |
2295 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2296 SNDRV_PCM_INFO_MMAP_VALID),
2297 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2298 .rates = SNDRV_PCM_RATE_8000_48000,
2299 .rate_min = 8000,
2300 .rate_max = 48000,
2301 .channels_min = 2,
2302 .channels_max = 2,
2303 .buffer_bytes_max = 32768,
2304 .period_bytes_min = 4096,
2305 .period_bytes_max = 32768,
2306 .periods_min = 1,
2307 .periods_max = 1024,
2308 };
2309]]>
2310 </programlisting>
2311 </informalexample>
2312 </para>
2313
2314 <para>
2315 <itemizedlist>
2316 <listitem><para>
2317 The <structfield>info</structfield> field contains the type and
2318 capabilities of this pcm. The bit flags are defined in
2319 <filename>&lt;sound/asound.h&gt;</filename> as
2320 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2321 have to specify whether the mmap is supported and which
2322 interleaved format is supported.
2323 When the is supported, add the
2324 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2325 hardware supports the interleaved or the non-interleaved
2326 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2327 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2328 be set, respectively. If both are supported, you can set both,
2329 too.
2330 </para>
2331
2332 <para>
2333 In the above example, <constant>MMAP_VALID</constant> and
2334 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
2335 mode. Usually both are set. Of course,
2336 <constant>MMAP_VALID</constant> is set only if the mmap is
2337 really supported.
2338 </para>
2339
2340 <para>
2341 The other possible flags are
2342 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2343 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2344 <constant>PAUSE</constant> bit means that the pcm supports the
2345 <quote>pause</quote> operation, while the
2346 <constant>RESUME</constant> bit means that the pcm supports
2347 the full <quote>suspend/resume</quote> operation.
2348 If the <constant>PAUSE</constant> flag is set,
2349 the <structfield>trigger</structfield> callback below
2350 must handle the corresponding (pause push/release) commands.
2351 The suspend/resume trigger commands can be defined even without
2352 the <constant>RESUME</constant> flag. See <link
2353 linkend="power-management"><citetitle>
2354 Power Management</citetitle></link> section for details.
2355 </para>
2356
2357 <para>
2358 When the PCM substreams can be synchronized (typically,
2359 synchronized start/stop of a playback and a capture streams),
2360 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2361 too. In this case, you'll need to check the linked-list of
2362 PCM substreams in the trigger callback. This will be
2363 described in the later section.
2364 </para>
2365 </listitem>
2366
2367 <listitem>
2368 <para>
2369 <structfield>formats</structfield> field contains the bit-flags
2370 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2371 If the hardware supports more than one format, give all or'ed
2372 bits. In the example above, the signed 16bit little-endian
2373 format is specified.
2374 </para>
2375 </listitem>
2376
2377 <listitem>
2378 <para>
2379 <structfield>rates</structfield> field contains the bit-flags of
2380 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2381 When the chip supports continuous rates, pass
2382 <constant>CONTINUOUS</constant> bit additionally.
2383 The pre-defined rate bits are provided only for typical
2384 rates. If your chip supports unconventional rates, you need to add
2385 the <constant>KNOT</constant> bit and set up the hardware
2386 constraint manually (explained later).
2387 </para>
2388 </listitem>
2389
2390 <listitem>
2391 <para>
2392 <structfield>rate_min</structfield> and
2393 <structfield>rate_max</structfield> define the minimum and
2394 maximum sample rate. This should correspond somehow to
2395 <structfield>rates</structfield> bits.
2396 </para>
2397 </listitem>
2398
2399 <listitem>
2400 <para>
2401 <structfield>channel_min</structfield> and
2402 <structfield>channel_max</structfield>
2403 define, as you might already expected, the minimum and maximum
2404 number of channels.
2405 </para>
2406 </listitem>
2407
2408 <listitem>
2409 <para>
2410 <structfield>buffer_bytes_max</structfield> defines the
2411 maximum buffer size in bytes. There is no
2412 <structfield>buffer_bytes_min</structfield> field, since
2413 it can be calculated from the minimum period size and the
2414 minimum number of periods.
2415 Meanwhile, <structfield>period_bytes_min</structfield> and
2416 define the minimum and maximum size of the period in bytes.
2417 <structfield>periods_max</structfield> and
2418 <structfield>periods_min</structfield> define the maximum and
2419 minimum number of periods in the buffer.
2420 </para>
2421
2422 <para>
2423 The <quote>period</quote> is a term that corresponds to
2424 a fragment in the OSS world. The period defines the size at
2425 which a PCM interrupt is generated. This size strongly
2426 depends on the hardware.
2427 Generally, the smaller period size will give you more
2428 interrupts, that is, more controls.
2429 In the case of capture, this size defines the input latency.
2430 On the other hand, the whole buffer size defines the
2431 output latency for the playback direction.
2432 </para>
2433 </listitem>
2434
2435 <listitem>
2436 <para>
2437 There is also a field <structfield>fifo_size</structfield>.
2438 This specifies the size of the hardware FIFO, but currently it
2439 is neither used in the driver nor in the alsa-lib. So, you
2440 can ignore this field.
2441 </para>
2442 </listitem>
2443 </itemizedlist>
2444 </para>
2445 </section>
2446
2447 <section id="pcm-interface-runtime-config">
2448 <title>PCM Configurations</title>
2449 <para>
2450 Ok, let's go back again to the PCM runtime records.
2451 The most frequently referred records in the runtime instance are
2452 the PCM configurations.
2453 The PCM configurations are stored in the runtime instance
2454 after the application sends <type>hw_params</type> data via
2455 alsa-lib. There are many fields copied from hw_params and
2456 sw_params structs. For example,
2457 <structfield>format</structfield> holds the format type
2458 chosen by the application. This field contains the enum value
2459 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2460 </para>
2461
2462 <para>
2463 One thing to be noted is that the configured buffer and period
2464 sizes are stored in <quote>frames</quote> in the runtime.
2465 In the ALSA world, 1 frame = channels * samples-size.
2466 For conversion between frames and bytes, you can use the
2467 <function>frames_to_bytes()</function> and
2468 <function>bytes_to_frames()</function> helper functions.
2469 <informalexample>
2470 <programlisting>
2471<![CDATA[
2472 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2473]]>
2474 </programlisting>
2475 </informalexample>
2476 </para>
2477
2478 <para>
2479 Also, many software parameters (sw_params) are
2480 stored in frames, too. Please check the type of the field.
2481 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2482 integer while <type>snd_pcm_sframes_t</type> is for the frames
2483 as signed integer.
2484 </para>
2485 </section>
2486
2487 <section id="pcm-interface-runtime-dma">
2488 <title>DMA Buffer Information</title>
2489 <para>
2490 The DMA buffer is defined by the following four fields,
2491 <structfield>dma_area</structfield>,
2492 <structfield>dma_addr</structfield>,
2493 <structfield>dma_bytes</structfield> and
2494 <structfield>dma_private</structfield>.
2495 The <structfield>dma_area</structfield> holds the buffer
2496 pointer (the logical address). You can call
2497 <function>memcpy</function> from/to
2498 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2499 holds the physical address of the buffer. This field is
2500 specified only when the buffer is a linear buffer.
2501 <structfield>dma_bytes</structfield> holds the size of buffer
2502 in bytes. <structfield>dma_private</structfield> is used for
2503 the ALSA DMA allocator.
2504 </para>
2505
2506 <para>
2507 If you use a standard ALSA function,
2508 <function>snd_pcm_lib_malloc_pages()</function>, for
2509 allocating the buffer, these fields are set by the ALSA middle
2510 layer, and you should <emphasis>not</emphasis> change them by
2511 yourself. You can read them but not write them.
2512 On the other hand, if you want to allocate the buffer by
2513 yourself, you'll need to manage it in hw_params callback.
2514 At least, <structfield>dma_bytes</structfield> is mandatory.
2515 <structfield>dma_area</structfield> is necessary when the
2516 buffer is mmapped. If your driver doesn't support mmap, this
2517 field is not necessary. <structfield>dma_addr</structfield>
2518 is also optional. You can use
2519 <structfield>dma_private</structfield> as you like, too.
2520 </para>
2521 </section>
2522
2523 <section id="pcm-interface-runtime-status">
2524 <title>Running Status</title>
2525 <para>
2526 The running status can be referred via <constant>runtime-&gt;status</constant>.
2527 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
2528 record. For example, you can get the current DMA hardware
2529 pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2530 </para>
2531
2532 <para>
2533 The DMA application pointer can be referred via
2534 <constant>runtime-&gt;control</constant>, which points to the
2535 struct <structname>snd_pcm_mmap_control</structname> record.
2536 However, accessing directly to this value is not recommended.
2537 </para>
2538 </section>
2539
2540 <section id="pcm-interface-runtime-private">
2541 <title>Private Data</title>
2542 <para>
2543 You can allocate a record for the substream and store it in
2544 <constant>runtime-&gt;private_data</constant>. Usually, this
2545 is done in
2546 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2547 the open callback</citetitle></link>.
2548 Don't mix this with <constant>pcm-&gt;private_data</constant>.
2549 The <constant>pcm-&gt;private_data</constant> usually points to the
2550 chip instance assigned statically at the creation of PCM, while the
2551 <constant>runtime-&gt;private_data</constant> points to a dynamic
2552 data structure created at the PCM open callback.
2553
2554 <informalexample>
2555 <programlisting>
2556<![CDATA[
2557 static int snd_xxx_open(struct snd_pcm_substream *substream)
2558 {
2559 struct my_pcm_data *data;
2560 ....
2561 data = kmalloc(sizeof(*data), GFP_KERNEL);
2562 substream->runtime->private_data = data;
2563 ....
2564 }
2565]]>
2566 </programlisting>
2567 </informalexample>
2568 </para>
2569
2570 <para>
2571 The allocated object must be released in
2572 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2573 the close callback</citetitle></link>.
2574 </para>
2575 </section>
2576
2577 <section id="pcm-interface-runtime-intr">
2578 <title>Interrupt Callbacks</title>
2579 <para>
2580 The field <structfield>transfer_ack_begin</structfield> and
2581 <structfield>transfer_ack_end</structfield> are called at
2582 the beginning and at the end of
2583 <function>snd_pcm_period_elapsed()</function>, respectively.
2584 </para>
2585 </section>
2586
2587 </section>
2588
2589 <section id="pcm-interface-operators">
2590 <title>Operators</title>
2591 <para>
2592 OK, now let me give details about each pcm callback
2593 (<parameter>ops</parameter>). In general, every callback must
2594 return 0 if successful, or a negative error number
2595 such as <constant>-EINVAL</constant>. To choose an appropriate
2596 error number, it is advised to check what value other parts of
2597 the kernel return when the same kind of request fails.
2598 </para>
2599
2600 <para>
2601 The callback function takes at least the argument with
2602 <structname>snd_pcm_substream</structname> pointer. To retrieve
2603 the chip record from the given substream instance, you can use the
2604 following macro.
2605
2606 <informalexample>
2607 <programlisting>
2608<![CDATA[
2609 int xxx() {
2610 struct mychip *chip = snd_pcm_substream_chip(substream);
2611 ....
2612 }
2613]]>
2614 </programlisting>
2615 </informalexample>
2616
2617 The macro reads <constant>substream-&gt;private_data</constant>,
2618 which is a copy of <constant>pcm-&gt;private_data</constant>.
2619 You can override the former if you need to assign different data
2620 records per PCM substream. For example, the cmi8330 driver assigns
2621 different private_data for playback and capture directions,
2622 because it uses two different codecs (SB- and AD-compatible) for
2623 different directions.
2624 </para>
2625
2626 <section id="pcm-interface-operators-open-callback">
2627 <title>open callback</title>
2628 <para>
2629 <informalexample>
2630 <programlisting>
2631<![CDATA[
2632 static int snd_xxx_open(struct snd_pcm_substream *substream);
2633]]>
2634 </programlisting>
2635 </informalexample>
2636
2637 This is called when a pcm substream is opened.
2638 </para>
2639
2640 <para>
2641 At least, here you have to initialize the runtime-&gt;hw
2642 record. Typically, this is done by like this:
2643
2644 <informalexample>
2645 <programlisting>
2646<![CDATA[
2647 static int snd_xxx_open(struct snd_pcm_substream *substream)
2648 {
2649 struct mychip *chip = snd_pcm_substream_chip(substream);
2650 struct snd_pcm_runtime *runtime = substream->runtime;
2651
2652 runtime->hw = snd_mychip_playback_hw;
2653 return 0;
2654 }
2655]]>
2656 </programlisting>
2657 </informalexample>
2658
2659 where <parameter>snd_mychip_playback_hw</parameter> is the
2660 pre-defined hardware description.
2661 </para>
2662
2663 <para>
2664 You can allocate a private data in this callback, as described
2665 in <link linkend="pcm-interface-runtime-private"><citetitle>
2666 Private Data</citetitle></link> section.
2667 </para>
2668
2669 <para>
2670 If the hardware configuration needs more constraints, set the
2671 hardware constraints here, too.
2672 See <link linkend="pcm-interface-constraints"><citetitle>
2673 Constraints</citetitle></link> for more details.
2674 </para>
2675 </section>
2676
2677 <section id="pcm-interface-operators-close-callback">
2678 <title>close callback</title>
2679 <para>
2680 <informalexample>
2681 <programlisting>
2682<![CDATA[
2683 static int snd_xxx_close(struct snd_pcm_substream *substream);
2684]]>
2685 </programlisting>
2686 </informalexample>
2687
2688 Obviously, this is called when a pcm substream is closed.
2689 </para>
2690
2691 <para>
2692 Any private instance for a pcm substream allocated in the
2693 open callback will be released here.
2694
2695 <informalexample>
2696 <programlisting>
2697<![CDATA[
2698 static int snd_xxx_close(struct snd_pcm_substream *substream)
2699 {
2700 ....
2701 kfree(substream->runtime->private_data);
2702 ....
2703 }
2704]]>
2705 </programlisting>
2706 </informalexample>
2707 </para>
2708 </section>
2709
2710 <section id="pcm-interface-operators-ioctl-callback">
2711 <title>ioctl callback</title>
2712 <para>
2713 This is used for any special call to pcm ioctls. But
2714 usually you can pass a generic ioctl callback,
2715 <function>snd_pcm_lib_ioctl</function>.
2716 </para>
2717 </section>
2718
2719 <section id="pcm-interface-operators-hw-params-callback">
2720 <title>hw_params callback</title>
2721 <para>
2722 <informalexample>
2723 <programlisting>
2724<![CDATA[
2725 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2726 struct snd_pcm_hw_params *hw_params);
2727]]>
2728 </programlisting>
2729 </informalexample>
2730 </para>
2731
2732 <para>
2733 This is called when the hardware parameter
2734 (<structfield>hw_params</structfield>) is set
2735 up by the application,
2736 that is, once when the buffer size, the period size, the
2737 format, etc. are defined for the pcm substream.
2738 </para>
2739
2740 <para>
2741 Many hardware setups should be done in this callback,
2742 including the allocation of buffers.
2743 </para>
2744
2745 <para>
2746 Parameters to be initialized are retrieved by
2747 <function>params_xxx()</function> macros. To allocate
2748 buffer, you can call a helper function,
2749
2750 <informalexample>
2751 <programlisting>
2752<![CDATA[
2753 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2754]]>
2755 </programlisting>
2756 </informalexample>
2757
2758 <function>snd_pcm_lib_malloc_pages()</function> is available
2759 only when the DMA buffers have been pre-allocated.
2760 See the section <link
2761 linkend="buffer-and-memory-buffer-types"><citetitle>
2762 Buffer Types</citetitle></link> for more details.
2763 </para>
2764
2765 <para>
2766 Note that this and <structfield>prepare</structfield> callbacks
2767 may be called multiple times per initialization.
2768 For example, the OSS emulation may
2769 call these callbacks at each change via its ioctl.
2770 </para>
2771
2772 <para>
2773 Thus, you need to be careful not to allocate the same buffers
2774 many times, which will lead to memory leaks! Calling the
2775 helper function above many times is OK. It will release the
2776 previous buffer automatically when it was already allocated.
2777 </para>
2778
2779 <para>
2780 Another note is that this callback is non-atomic
2781 (schedulable). This is important, because the
2782 <structfield>trigger</structfield> callback
2783 is atomic (non-schedulable). That is, mutexes or any
2784 schedule-related functions are not available in
2785 <structfield>trigger</structfield> callback.
2786 Please see the subsection
2787 <link linkend="pcm-interface-atomicity"><citetitle>
2788 Atomicity</citetitle></link> for details.
2789 </para>
2790 </section>
2791
2792 <section id="pcm-interface-operators-hw-free-callback">
2793 <title>hw_free callback</title>
2794 <para>
2795 <informalexample>
2796 <programlisting>
2797<![CDATA[
2798 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2799]]>
2800 </programlisting>
2801 </informalexample>
2802 </para>
2803
2804 <para>
2805 This is called to release the resources allocated via
2806 <structfield>hw_params</structfield>. For example, releasing the
2807 buffer via
2808 <function>snd_pcm_lib_malloc_pages()</function> is done by
2809 calling the following:
2810
2811 <informalexample>
2812 <programlisting>
2813<![CDATA[
2814 snd_pcm_lib_free_pages(substream);
2815]]>
2816 </programlisting>
2817 </informalexample>
2818 </para>
2819
2820 <para>
2821 This function is always called before the close callback is called.
2822 Also, the callback may be called multiple times, too.
2823 Keep track whether the resource was already released.
2824 </para>
2825 </section>
2826
2827 <section id="pcm-interface-operators-prepare-callback">
2828 <title>prepare callback</title>
2829 <para>
2830 <informalexample>
2831 <programlisting>
2832<![CDATA[
2833 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2834]]>
2835 </programlisting>
2836 </informalexample>
2837 </para>
2838
2839 <para>
2840 This callback is called when the pcm is
2841 <quote>prepared</quote>. You can set the format type, sample
2842 rate, etc. here. The difference from
2843 <structfield>hw_params</structfield> is that the
2844 <structfield>prepare</structfield> callback will be called each
2845 time
2846 <function>snd_pcm_prepare()</function> is called, i.e. when
2847 recovering after underruns, etc.
2848 </para>
2849
2850 <para>
2851 Note that this callback is now non-atomic.
2852 You can use schedule-related functions safely in this callback.
2853 </para>
2854
2855 <para>
2856 In this and the following callbacks, you can refer to the
2857 values via the runtime record,
2858 substream-&gt;runtime.
2859 For example, to get the current
2860 rate, format or channels, access to
2861 runtime-&gt;rate,
2862 runtime-&gt;format or
2863 runtime-&gt;channels, respectively.
2864 The physical address of the allocated buffer is set to
2865 runtime-&gt;dma_area. The buffer and period sizes are
2866 in runtime-&gt;buffer_size and runtime-&gt;period_size,
2867 respectively.
2868 </para>
2869
2870 <para>
2871 Be careful that this callback will be called many times at
2872 each setup, too.
2873 </para>
2874 </section>
2875
2876 <section id="pcm-interface-operators-trigger-callback">
2877 <title>trigger callback</title>
2878 <para>
2879 <informalexample>
2880 <programlisting>
2881<![CDATA[
2882 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2883]]>
2884 </programlisting>
2885 </informalexample>
2886
2887 This is called when the pcm is started, stopped or paused.
2888 </para>
2889
2890 <para>
2891 Which action is specified in the second argument,
2892 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2893 <filename>&lt;sound/pcm.h&gt;</filename>. At least,
2894 the <constant>START</constant> and <constant>STOP</constant>
2895 commands must be defined in this callback.
2896
2897 <informalexample>
2898 <programlisting>
2899<![CDATA[
2900 switch (cmd) {
2901 case SNDRV_PCM_TRIGGER_START:
2902 /* do something to start the PCM engine */
2903 break;
2904 case SNDRV_PCM_TRIGGER_STOP:
2905 /* do something to stop the PCM engine */
2906 break;
2907 default:
2908 return -EINVAL;
2909 }
2910]]>
2911 </programlisting>
2912 </informalexample>
2913 </para>
2914
2915 <para>
2916 When the pcm supports the pause operation (given in the info
2917 field of the hardware table), the <constant>PAUSE_PUSE</constant>
2918 and <constant>PAUSE_RELEASE</constant> commands must be
2919 handled here, too. The former is the command to pause the pcm,
2920 and the latter to restart the pcm again.
2921 </para>
2922
2923 <para>
2924 When the pcm supports the suspend/resume operation,
2925 regardless of full or partial suspend/resume support,
2926 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2927 commands must be handled, too.
2928 These commands are issued when the power-management status is
2929 changed. Obviously, the <constant>SUSPEND</constant> and
2930 <constant>RESUME</constant> commands
2931 suspend and resume the pcm substream, and usually, they
2932 are identical to the <constant>STOP</constant> and
2933 <constant>START</constant> commands, respectively.
2934 See the <link linkend="power-management"><citetitle>
2935 Power Management</citetitle></link> section for details.
2936 </para>
2937
2938 <para>
2939 As mentioned, this callback is atomic. You cannot call
2940 functions which may sleep.
2941 The trigger callback should be as minimal as possible,
2942 just really triggering the DMA. The other stuff should be
2943 initialized hw_params and prepare callbacks properly
2944 beforehand.
2945 </para>
2946 </section>
2947
2948 <section id="pcm-interface-operators-pointer-callback">
2949 <title>pointer callback</title>
2950 <para>
2951 <informalexample>
2952 <programlisting>
2953<![CDATA[
2954 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2955]]>
2956 </programlisting>
2957 </informalexample>
2958
2959 This callback is called when the PCM middle layer inquires
2960 the current hardware position on the buffer. The position must
2961 be returned in frames,
2962 ranging from 0 to buffer_size - 1.
2963 </para>
2964
2965 <para>
2966 This is called usually from the buffer-update routine in the
2967 pcm middle layer, which is invoked when
2968 <function>snd_pcm_period_elapsed()</function> is called in the
2969 interrupt routine. Then the pcm middle layer updates the
2970 position and calculates the available space, and wakes up the
2971 sleeping poll threads, etc.
2972 </para>
2973
2974 <para>
2975 This callback is also atomic.
2976 </para>
2977 </section>
2978
2979 <section id="pcm-interface-operators-copy-silence">
2980 <title>copy and silence callbacks</title>
2981 <para>
2982 These callbacks are not mandatory, and can be omitted in
2983 most cases. These callbacks are used when the hardware buffer
2984 cannot be in the normal memory space. Some chips have their
2985 own buffer on the hardware which is not mappable. In such a
2986 case, you have to transfer the data manually from the memory
2987 buffer to the hardware buffer. Or, if the buffer is
2988 non-contiguous on both physical and virtual memory spaces,
2989 these callbacks must be defined, too.
2990 </para>
2991
2992 <para>
2993 If these two callbacks are defined, copy and set-silence
2994 operations are done by them. The detailed will be described in
2995 the later section <link
2996 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2997 Management</citetitle></link>.
2998 </para>
2999 </section>
3000
3001 <section id="pcm-interface-operators-ack">
3002 <title>ack callback</title>
3003 <para>
3004 This callback is also not mandatory. This callback is called
3005 when the appl_ptr is updated in read or write operations.
3006 Some drivers like emu10k1-fx and cs46xx need to track the
3007 current appl_ptr for the internal buffer, and this callback
3008 is useful only for such a purpose.
3009 </para>
3010 <para>
3011 This callback is atomic.
3012 </para>
3013 </section>
3014
3015 <section id="pcm-interface-operators-page-callback">
3016 <title>page callback</title>
3017
3018 <para>
3019 This callback is optional too. This callback is used
3020 mainly for non-contiguous buffers. The mmap calls this
3021 callback to get the page address. Some examples will be
3022 explained in the later section <link
3023 linkend="buffer-and-memory"><citetitle>Buffer and Memory
3024 Management</citetitle></link>, too.
3025 </para>
3026 </section>
3027 </section>
3028
3029 <section id="pcm-interface-interrupt-handler">
3030 <title>Interrupt Handler</title>
3031 <para>
3032 The rest of pcm stuff is the PCM interrupt handler. The
3033 role of PCM interrupt handler in the sound driver is to update
3034 the buffer position and to tell the PCM middle layer when the
3035 buffer position goes across the prescribed period size. To
3036 inform this, call the <function>snd_pcm_period_elapsed()</function>
3037 function.
3038 </para>
3039
3040 <para>
3041 There are several types of sound chips to generate the interrupts.
3042 </para>
3043
3044 <section id="pcm-interface-interrupt-handler-boundary">
3045 <title>Interrupts at the period (fragment) boundary</title>
3046 <para>
3047 This is the most frequently found type: the hardware
3048 generates an interrupt at each period boundary.
3049 In this case, you can call
3050 <function>snd_pcm_period_elapsed()</function> at each
3051 interrupt.
3052 </para>
3053
3054 <para>
3055 <function>snd_pcm_period_elapsed()</function> takes the
3056 substream pointer as its argument. Thus, you need to keep the
3057 substream pointer accessible from the chip instance. For
3058 example, define substream field in the chip record to hold the
3059 current running substream pointer, and set the pointer value
3060 at open callback (and reset at close callback).
3061 </para>
3062
3063 <para>
3064 If you acquire a spinlock in the interrupt handler, and the
3065 lock is used in other pcm callbacks, too, then you have to
3066 release the lock before calling
3067 <function>snd_pcm_period_elapsed()</function>, because
3068 <function>snd_pcm_period_elapsed()</function> calls other pcm
3069 callbacks inside.
3070 </para>
3071
3072 <para>
3073 Typical code would be like:
3074
3075 <example>
3076 <title>Interrupt Handler Case #1</title>
3077 <programlisting>
3078<![CDATA[
3079 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3080 {
3081 struct mychip *chip = dev_id;
3082 spin_lock(&chip->lock);
3083 ....
3084 if (pcm_irq_invoked(chip)) {
3085 /* call updater, unlock before it */
3086 spin_unlock(&chip->lock);
3087 snd_pcm_period_elapsed(chip->substream);
3088 spin_lock(&chip->lock);
3089 /* acknowledge the interrupt if necessary */
3090 }
3091 ....
3092 spin_unlock(&chip->lock);
3093 return IRQ_HANDLED;
3094 }
3095]]>
3096 </programlisting>
3097 </example>
3098 </para>
3099 </section>
3100
3101 <section id="pcm-interface-interrupt-handler-timer">
3102 <title>High frequency timer interrupts</title>
3103 <para>
3104 This happense when the hardware doesn't generate interrupts
3105 at the period boundary but issues timer interrupts at a fixed
3106 timer rate (e.g. es1968 or ymfpci drivers).
3107 In this case, you need to check the current hardware
3108 position and accumulate the processed sample length at each
3109 interrupt. When the accumulated size exceeds the period
3110 size, call
3111 <function>snd_pcm_period_elapsed()</function> and reset the
3112 accumulator.
3113 </para>
3114
3115 <para>
3116 Typical code would be like the following.
3117
3118 <example>
3119 <title>Interrupt Handler Case #2</title>
3120 <programlisting>
3121<![CDATA[
3122 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3123 {
3124 struct mychip *chip = dev_id;
3125 spin_lock(&chip->lock);
3126 ....
3127 if (pcm_irq_invoked(chip)) {
3128 unsigned int last_ptr, size;
3129 /* get the current hardware pointer (in frames) */
3130 last_ptr = get_hw_ptr(chip);
3131 /* calculate the processed frames since the
3132 * last update
3133 */
3134 if (last_ptr < chip->last_ptr)
3135 size = runtime->buffer_size + last_ptr
3136 - chip->last_ptr;
3137 else
3138 size = last_ptr - chip->last_ptr;
3139 /* remember the last updated point */
3140 chip->last_ptr = last_ptr;
3141 /* accumulate the size */
3142 chip->size += size;
3143 /* over the period boundary? */
3144 if (chip->size >= runtime->period_size) {
3145 /* reset the accumulator */
3146 chip->size %= runtime->period_size;
3147 /* call updater */
3148 spin_unlock(&chip->lock);
3149 snd_pcm_period_elapsed(substream);
3150 spin_lock(&chip->lock);
3151 }
3152 /* acknowledge the interrupt if necessary */
3153 }
3154 ....
3155 spin_unlock(&chip->lock);
3156 return IRQ_HANDLED;
3157 }
3158]]>
3159 </programlisting>
3160 </example>
3161 </para>
3162 </section>
3163
3164 <section id="pcm-interface-interrupt-handler-both">
3165 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3166 <para>
3167 In both cases, even if more than one period are elapsed, you
3168 don't have to call
3169 <function>snd_pcm_period_elapsed()</function> many times. Call
3170 only once. And the pcm layer will check the current hardware
3171 pointer and update to the latest status.
3172 </para>
3173 </section>
3174 </section>
3175
3176 <section id="pcm-interface-atomicity">
3177 <title>Atomicity</title>
3178 <para>
3179 One of the most important (and thus difficult to debug) problems
3180 in kernel programming are race conditions.
3181 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3182 or semaphores. In general, if a race condition can happen
3183 in an interrupt handler, it has to be managed atomically, and you
3184 have to use a spinlock to protect the critical session. If the
3185 critical section is not in interrupt handler code and
3186 if taking a relatively long time to execute is acceptable, you
3187 should use mutexes or semaphores instead.
3188 </para>
3189
3190 <para>
3191 As already seen, some pcm callbacks are atomic and some are
3192 not. For example, the <parameter>hw_params</parameter> callback is
3193 non-atomic, while <parameter>trigger</parameter> callback is
3194 atomic. This means, the latter is called already in a spinlock
3195 held by the PCM middle layer. Please take this atomicity into
3196 account when you choose a locking scheme in the callbacks.
3197 </para>
3198
3199 <para>
3200 In the atomic callbacks, you cannot use functions which may call
3201 <function>schedule</function> or go to
3202 <function>sleep</function>. Semaphores and mutexes can sleep,
3203 and hence they cannot be used inside the atomic callbacks
3204 (e.g. <parameter>trigger</parameter> callback).
3205 To implement some delay in such a callback, please use
3206 <function>udelay()</function> or <function>mdelay()</function>.
3207 </para>
3208
3209 <para>
3210 All three atomic callbacks (trigger, pointer, and ack) are
3211 called with local interrupts disabled.
3212 </para>
3213
3214 </section>
3215 <section id="pcm-interface-constraints">
3216 <title>Constraints</title>
3217 <para>
3218 If your chip supports unconventional sample rates, or only the
3219 limited samples, you need to set a constraint for the
3220 condition.
3221 </para>
3222
3223 <para>
3224 For example, in order to restrict the sample rates in the some
3225 supported values, use
3226 <function>snd_pcm_hw_constraint_list()</function>.
3227 You need to call this function in the open callback.
3228
3229 <example>
3230 <title>Example of Hardware Constraints</title>
3231 <programlisting>
3232<![CDATA[
3233 static unsigned int rates[] =
3234 {4000, 10000, 22050, 44100};
3235 static struct snd_pcm_hw_constraint_list constraints_rates = {
3236 .count = ARRAY_SIZE(rates),
3237 .list = rates,
3238 .mask = 0,
3239 };
3240
3241 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3242 {
3243 int err;
3244 ....
3245 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3246 SNDRV_PCM_HW_PARAM_RATE,
3247 &constraints_rates);
3248 if (err < 0)
3249 return err;
3250 ....
3251 }
3252]]>
3253 </programlisting>
3254 </example>
3255 </para>
3256
3257 <para>
3258 There are many different constraints.
3259 Look at <filename>sound/pcm.h</filename> for a complete list.
3260 You can even define your own constraint rules.
3261 For example, let's suppose my_chip can manage a substream of 1 channel
3262 if and only if the format is S16_LE, otherwise it supports any format
3263 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3264 other constraint_list). You can build a rule like this:
3265
3266 <example>
3267 <title>Example of Hardware Constraints for Channels</title>
3268 <programlisting>
3269<![CDATA[
3270 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3271 struct snd_pcm_hw_rule *rule)
3272 {
3273 struct snd_interval *c = hw_param_interval(params,
3274 SNDRV_PCM_HW_PARAM_CHANNELS);
3275 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3276 struct snd_mask fmt;
3277
3278 snd_mask_any(&fmt); /* Init the struct */
3279 if (c->min < 2) {
3280 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3281 return snd_mask_refine(f, &fmt);
3282 }
3283 return 0;
3284 }
3285]]>
3286 </programlisting>
3287 </example>
3288 </para>
3289
3290 <para>
3291 Then you need to call this function to add your rule:
3292
3293 <informalexample>
3294 <programlisting>
3295<![CDATA[
3296 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3297 hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3298 -1);
3299]]>
3300 </programlisting>
3301 </informalexample>
3302 </para>
3303
3304 <para>
3305 The rule function is called when an application sets the number of
3306 channels. But an application can set the format before the number of
3307 channels. Thus you also need to define the inverse rule:
3308
3309 <example>
3310 <title>Example of Hardware Constraints for Channels</title>
3311 <programlisting>
3312<![CDATA[
3313 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3314 struct snd_pcm_hw_rule *rule)
3315 {
3316 struct snd_interval *c = hw_param_interval(params,
3317 SNDRV_PCM_HW_PARAM_CHANNELS);
3318 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3319 struct snd_interval ch;
3320
3321 snd_interval_any(&ch);
3322 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3323 ch.min = ch.max = 1;
3324 ch.integer = 1;
3325 return snd_interval_refine(c, &ch);
3326 }
3327 return 0;
3328 }
3329]]>
3330 </programlisting>
3331 </example>
3332 </para>
3333
3334 <para>
3335 ...and in the open callback:
3336 <informalexample>
3337 <programlisting>
3338<![CDATA[
3339 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3340 hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3341 -1);
3342]]>
3343 </programlisting>
3344 </informalexample>
3345 </para>
3346
3347 <para>
3348 I won't give more details here, rather I
3349 would like to say, <quote>Luke, use the source.</quote>
3350 </para>
3351 </section>
3352
3353 </chapter>
3354
3355
3356<!-- ****************************************************** -->
3357<!-- Control Interface -->
3358<!-- ****************************************************** -->
3359 <chapter id="control-interface">
3360 <title>Control Interface</title>
3361
3362 <section id="control-interface-general">
3363 <title>General</title>
3364 <para>
3365 The control interface is used widely for many switches,
3366 sliders, etc. which are accessed from user-space. Its most
3367 important use is the mixer interface. In other words, since ALSA
3368 0.9.x, all the mixer stuff is implemented on the control kernel API.
3369 </para>
3370
3371 <para>
3372 ALSA has a well-defined AC97 control module. If your chip
3373 supports only the AC97 and nothing else, you can skip this
3374 section.
3375 </para>
3376
3377 <para>
3378 The control API is defined in
3379 <filename>&lt;sound/control.h&gt;</filename>.
3380 Include this file if you want to add your own controls.
3381 </para>
3382 </section>
3383
3384 <section id="control-interface-definition">
3385 <title>Definition of Controls</title>
3386 <para>
3387 To create a new control, you need to define the
3388 following three
3389 callbacks: <structfield>info</structfield>,
3390 <structfield>get</structfield> and
3391 <structfield>put</structfield>. Then, define a
3392 struct <structname>snd_kcontrol_new</structname> record, such as:
3393
3394 <example>
3395 <title>Definition of a Control</title>
3396 <programlisting>
3397<![CDATA[
3398 static struct snd_kcontrol_new my_control __devinitdata = {
3399 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3400 .name = "PCM Playback Switch",
3401 .index = 0,
3402 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3403 .private_value = 0xffff,
3404 .info = my_control_info,
3405 .get = my_control_get,
3406 .put = my_control_put
3407 };
3408]]>
3409 </programlisting>
3410 </example>
3411 </para>
3412
3413 <para>
3414 Most likely the control is created via
3415 <function>snd_ctl_new1()</function>, and in such a case, you can
3416 add the <parameter>__devinitdata</parameter> prefix to the
3417 definition as above.
3418 </para>
3419
3420 <para>
3421 The <structfield>iface</structfield> field specifies the control
3422 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3423 is usually <constant>MIXER</constant>.
3424 Use <constant>CARD</constant> for global controls that are not
3425 logically part of the mixer.
3426 If the control is closely associated with some specific device on
3427 the sound card, use <constant>HWDEP</constant>,
3428 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3429 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3430 specify the device number with the
3431 <structfield>device</structfield> and
3432 <structfield>subdevice</structfield> fields.
3433 </para>
3434
3435 <para>
3436 The <structfield>name</structfield> is the name identifier
3437 string. Since ALSA 0.9.x, the control name is very important,
3438 because its role is classified from its name. There are
3439 pre-defined standard control names. The details are described in
3440 the <link linkend="control-interface-control-names"><citetitle>
3441 Control Names</citetitle></link> subsection.
3442 </para>
3443
3444 <para>
3445 The <structfield>index</structfield> field holds the index number
3446 of this control. If there are several different controls with
3447 the same name, they can be distinguished by the index
3448 number. This is the case when
3449 several codecs exist on the card. If the index is zero, you can
3450 omit the definition above.
3451 </para>
3452
3453 <para>
3454 The <structfield>access</structfield> field contains the access
3455 type of this control. Give the combination of bit masks,
3456 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3457 The details will be explained in
3458 the <link linkend="control-interface-access-flags"><citetitle>
3459 Access Flags</citetitle></link> subsection.
3460 </para>
3461
3462 <para>
3463 The <structfield>private_value</structfield> field contains
3464 an arbitrary long integer value for this record. When using
3465 the generic <structfield>info</structfield>,
3466 <structfield>get</structfield> and
3467 <structfield>put</structfield> callbacks, you can pass a value
3468 through this field. If several small numbers are necessary, you can
3469 combine them in bitwise. Or, it's possible to give a pointer
3470 (casted to unsigned long) of some record to this field, too.
3471 </para>
3472
3473 <para>
3474 The <structfield>tlv</structfield> field can be used to provide
3475 metadata about the control; see the
3476 <link linkend="control-interface-tlv">
3477 <citetitle>Metadata</citetitle></link> subsection.
3478 </para>
3479
3480 <para>
3481 The other three are
3482 <link linkend="control-interface-callbacks"><citetitle>
3483 callback functions</citetitle></link>.
3484 </para>
3485 </section>
3486
3487 <section id="control-interface-control-names">
3488 <title>Control Names</title>
3489 <para>
3490 There are some standards to define the control names. A
3491 control is usually defined from the three parts as
3492 <quote>SOURCE DIRECTION FUNCTION</quote>.
3493 </para>
3494
3495 <para>
3496 The first, <constant>SOURCE</constant>, specifies the source
3497 of the control, and is a string such as <quote>Master</quote>,
3498 <quote>PCM</quote>, <quote>CD</quote> and
3499 <quote>Line</quote>. There are many pre-defined sources.
3500 </para>
3501
3502 <para>
3503 The second, <constant>DIRECTION</constant>, is one of the
3504 following strings according to the direction of the control:
3505 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3506 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3507 be omitted, meaning both playback and capture directions.
3508 </para>
3509
3510 <para>
3511 The third, <constant>FUNCTION</constant>, is one of the
3512 following strings according to the function of the control:
3513 <quote>Switch</quote>, <quote>Volume</quote> and
3514 <quote>Route</quote>.
3515 </para>
3516
3517 <para>
3518 The example of control names are, thus, <quote>Master Capture
3519 Switch</quote> or <quote>PCM Playback Volume</quote>.
3520 </para>
3521
3522 <para>
3523 There are some exceptions:
3524 </para>
3525
3526 <section id="control-interface-control-names-global">
3527 <title>Global capture and playback</title>
3528 <para>
3529 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3530 and <quote>Capture Volume</quote> are used for the global
3531 capture (input) source, switch and volume. Similarly,
3532 <quote>Playback Switch</quote> and <quote>Playback
3533 Volume</quote> are used for the global output gain switch and
3534 volume.
3535 </para>
3536 </section>
3537
3538 <section id="control-interface-control-names-tone">
3539 <title>Tone-controls</title>
3540 <para>
3541 tone-control switch and volumes are specified like
3542 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3543 Switch</quote>, <quote>Tone Control - Bass</quote>,
3544 <quote>Tone Control - Center</quote>.
3545 </para>
3546 </section>
3547
3548 <section id="control-interface-control-names-3d">
3549 <title>3D controls</title>
3550 <para>
3551 3D-control switches and volumes are specified like <quote>3D
3552 Control - XXX</quote>, e.g. <quote>3D Control -
3553 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3554 Control - Space</quote>.
3555 </para>
3556 </section>
3557
3558 <section id="control-interface-control-names-mic">
3559 <title>Mic boost</title>
3560 <para>
3561 Mic-boost switch is set as <quote>Mic Boost</quote> or
3562 <quote>Mic Boost (6dB)</quote>.
3563 </para>
3564
3565 <para>
3566 More precise information can be found in
3567 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3568 </para>
3569 </section>
3570 </section>
3571
3572 <section id="control-interface-access-flags">
3573 <title>Access Flags</title>
3574
3575 <para>
3576 The access flag is the bitmask which specifies the access type
3577 of the given control. The default access type is
3578 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3579 which means both read and write are allowed to this control.
3580 When the access flag is omitted (i.e. = 0), it is
3581 considered as <constant>READWRITE</constant> access as default.
3582 </para>
3583
3584 <para>
3585 When the control is read-only, pass
3586 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3587 In this case, you don't have to define
3588 the <structfield>put</structfield> callback.
3589 Similarly, when the control is write-only (although it's a rare
3590 case), you can use the <constant>WRITE</constant> flag instead, and
3591 you don't need the <structfield>get</structfield> callback.
3592 </para>
3593
3594 <para>
3595 If the control value changes frequently (e.g. the VU meter),
3596 <constant>VOLATILE</constant> flag should be given. This means
3597 that the control may be changed without
3598 <link linkend="control-interface-change-notification"><citetitle>
3599 notification</citetitle></link>. Applications should poll such
3600 a control constantly.
3601 </para>
3602
3603 <para>
3604 When the control is inactive, set
3605 the <constant>INACTIVE</constant> flag, too.
3606 There are <constant>LOCK</constant> and
3607 <constant>OWNER</constant> flags to change the write
3608 permissions.
3609 </para>
3610
3611 </section>
3612
3613 <section id="control-interface-callbacks">
3614 <title>Callbacks</title>
3615
3616 <section id="control-interface-callbacks-info">
3617 <title>info callback</title>
3618 <para>
3619 The <structfield>info</structfield> callback is used to get
3620 detailed information on this control. This must store the
3621 values of the given struct <structname>snd_ctl_elem_info</structname>
3622 object. For example, for a boolean control with a single
3623 element:
3624
3625 <example>
3626 <title>Example of info callback</title>
3627 <programlisting>
3628<![CDATA[
3629 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3630 struct snd_ctl_elem_info *uinfo)
3631 {
3632 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3633 uinfo->count = 1;
3634 uinfo->value.integer.min = 0;
3635 uinfo->value.integer.max = 1;
3636 return 0;
3637 }
3638]]>
3639 </programlisting>
3640 </example>
3641 </para>
3642
3643 <para>
3644 The <structfield>type</structfield> field specifies the type
3645 of the control. There are <constant>BOOLEAN</constant>,
3646 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3647 <constant>BYTES</constant>, <constant>IEC958</constant> and
3648 <constant>INTEGER64</constant>. The
3649 <structfield>count</structfield> field specifies the
3650 number of elements in this control. For example, a stereo
3651 volume would have count = 2. The
3652 <structfield>value</structfield> field is a union, and
3653 the values stored are depending on the type. The boolean and
3654 integer types are identical.
3655 </para>
3656
3657 <para>
3658 The enumerated type is a bit different from others. You'll
3659 need to set the string for the currently given item index.
3660
3661 <informalexample>
3662 <programlisting>
3663<![CDATA[
3664 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3665 struct snd_ctl_elem_info *uinfo)
3666 {
3667 static char *texts[4] = {
3668 "First", "Second", "Third", "Fourth"
3669 };
3670 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3671 uinfo->count = 1;
3672 uinfo->value.enumerated.items = 4;
3673 if (uinfo->value.enumerated.item > 3)
3674 uinfo->value.enumerated.item = 3;
3675 strcpy(uinfo->value.enumerated.name,
3676 texts[uinfo->value.enumerated.item]);
3677 return 0;
3678 }
3679]]>
3680 </programlisting>
3681 </informalexample>
3682 </para>
3683
3684 <para>
3685 Some common info callbacks are available for your convenience:
3686 <function>snd_ctl_boolean_mono_info()</function> and
3687 <function>snd_ctl_boolean_stereo_info()</function>.
3688 Obviously, the former is an info callback for a mono channel
3689 boolean item, just like <function>snd_myctl_mono_info</function>
3690 above, and the latter is for a stereo channel boolean item.
3691 </para>
3692
3693 </section>
3694
3695 <section id="control-interface-callbacks-get">
3696 <title>get callback</title>
3697
3698 <para>
3699 This callback is used to read the current value of the
3700 control and to return to user-space.
3701 </para>
3702
3703 <para>
3704 For example,
3705
3706 <example>
3707 <title>Example of get callback</title>
3708 <programlisting>
3709<![CDATA[
3710 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3711 struct snd_ctl_elem_value *ucontrol)
3712 {
3713 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3714 ucontrol->value.integer.value[0] = get_some_value(chip);
3715 return 0;
3716 }
3717]]>
3718 </programlisting>
3719 </example>
3720 </para>
3721
3722 <para>
3723 The <structfield>value</structfield> field depends on
3724 the type of control as well as on the info callback. For example,
3725 the sb driver uses this field to store the register offset,
3726 the bit-shift and the bit-mask. The
3727 <structfield>private_value</structfield> field is set as follows:
3728 <informalexample>
3729 <programlisting>
3730<![CDATA[
3731 .private_value = reg | (shift << 16) | (mask << 24)
3732]]>
3733 </programlisting>
3734 </informalexample>
3735 and is retrieved in callbacks like
3736 <informalexample>
3737 <programlisting>
3738<![CDATA[
3739 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3740 struct snd_ctl_elem_value *ucontrol)
3741 {
3742 int reg = kcontrol->private_value & 0xff;
3743 int shift = (kcontrol->private_value >> 16) & 0xff;
3744 int mask = (kcontrol->private_value >> 24) & 0xff;
3745 ....
3746 }
3747]]>
3748 </programlisting>
3749 </informalexample>
3750 </para>
3751
3752 <para>
3753 In the <structfield>get</structfield> callback,
3754 you have to fill all the elements if the
3755 control has more than one elements,
3756 i.e. <structfield>count</structfield> &gt; 1.
3757 In the example above, we filled only one element
3758 (<structfield>value.integer.value[0]</structfield>) since it's
3759 assumed as <structfield>count</structfield> = 1.
3760 </para>
3761 </section>
3762
3763 <section id="control-interface-callbacks-put">
3764 <title>put callback</title>
3765
3766 <para>
3767 This callback is used to write a value from user-space.
3768 </para>
3769
3770 <para>
3771 For example,
3772
3773 <example>
3774 <title>Example of put callback</title>
3775 <programlisting>
3776<![CDATA[
3777 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3778 struct snd_ctl_elem_value *ucontrol)
3779 {
3780 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3781 int changed = 0;
3782 if (chip->current_value !=
3783 ucontrol->value.integer.value[0]) {
3784 change_current_value(chip,
3785 ucontrol->value.integer.value[0]);
3786 changed = 1;
3787 }
3788 return changed;
3789 }
3790]]>
3791 </programlisting>
3792 </example>
3793
3794 As seen above, you have to return 1 if the value is
3795 changed. If the value is not changed, return 0 instead.
3796 If any fatal error happens, return a negative error code as
3797 usual.
3798 </para>
3799
3800 <para>
3801 As in the <structfield>get</structfield> callback,
3802 when the control has more than one elements,
3803 all elements must be evaluated in this callback, too.
3804 </para>
3805 </section>
3806
3807 <section id="control-interface-callbacks-all">
3808 <title>Callbacks are not atomic</title>
3809 <para>
3810 All these three callbacks are basically not atomic.
3811 </para>
3812 </section>
3813 </section>
3814
3815 <section id="control-interface-constructor">
3816 <title>Constructor</title>
3817 <para>
3818 When everything is ready, finally we can create a new
3819 control. To create a control, there are two functions to be
3820 called, <function>snd_ctl_new1()</function> and
3821 <function>snd_ctl_add()</function>.
3822 </para>
3823
3824 <para>
3825 In the simplest way, you can do like this:
3826
3827 <informalexample>
3828 <programlisting>
3829<![CDATA[
3830 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3831 if (err < 0)
3832 return err;
3833]]>
3834 </programlisting>
3835 </informalexample>
3836
3837 where <parameter>my_control</parameter> is the
3838 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3839 is the object pointer to be passed to
3840 kcontrol-&gt;private_data
3841 which can be referred to in callbacks.
3842 </para>
3843
3844 <para>
3845 <function>snd_ctl_new1()</function> allocates a new
3846 <structname>snd_kcontrol</structname> instance (that's why the definition
3847 of <parameter>my_control</parameter> can be with
3848 the <parameter>__devinitdata</parameter>
3849 prefix), and <function>snd_ctl_add</function> assigns the given
3850 control component to the card.
3851 </para>
3852 </section>
3853
3854 <section id="control-interface-change-notification">
3855 <title>Change Notification</title>
3856 <para>
3857 If you need to change and update a control in the interrupt
3858 routine, you can call <function>snd_ctl_notify()</function>. For
3859 example,
3860
3861 <informalexample>
3862 <programlisting>
3863<![CDATA[
3864 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3865]]>
3866 </programlisting>
3867 </informalexample>
3868
3869 This function takes the card pointer, the event-mask, and the
3870 control id pointer for the notification. The event-mask
3871 specifies the types of notification, for example, in the above
3872 example, the change of control values is notified.
3873 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3874 to be notified.
3875 You can find some examples in <filename>es1938.c</filename> or
3876 <filename>es1968.c</filename> for hardware volume interrupts.
3877 </para>
3878 </section>
3879
3880 <section id="control-interface-tlv">
3881 <title>Metadata</title>
3882 <para>
3883 To provide information about the dB values of a mixer control, use
3884 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3885 <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3886 containing this information, set the<structfield>tlv.p
3887 </structfield> field to point to this variable, and include the
3888 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3889 <structfield>access</structfield> field; like this:
3890 <informalexample>
3891 <programlisting>
3892<![CDATA[
3893 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3894
3895 static struct snd_kcontrol_new my_control __devinitdata = {
3896 ...
3897 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3898 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3899 ...
3900 .tlv.p = db_scale_my_control,
3901 };
3902]]>
3903 </programlisting>
3904 </informalexample>
3905 </para>
3906
3907 <para>
3908 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3909 information about a mixer control where each step in the control's
3910 value changes the dB value by a constant dB amount.
3911 The first parameter is the name of the variable to be defined.
3912 The second parameter is the minimum value, in units of 0.01 dB.
3913 The third parameter is the step size, in units of 0.01 dB.
3914 Set the fourth parameter to 1 if the minimum value actually mutes
3915 the control.
3916 </para>
3917
3918 <para>
3919 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3920 information about a mixer control where the control's value affects
3921 the output linearly.
3922 The first parameter is the name of the variable to be defined.
3923 The second parameter is the minimum value, in units of 0.01 dB.
3924 The third parameter is the maximum value, in units of 0.01 dB.
3925 If the minimum value mutes the control, set the second parameter to
3926 <constant>TLV_DB_GAIN_MUTE</constant>.
3927 </para>
3928 </section>
3929
3930 </chapter>
3931
3932
3933<!-- ****************************************************** -->
3934<!-- API for AC97 Codec -->
3935<!-- ****************************************************** -->
3936 <chapter id="api-ac97">
3937 <title>API for AC97 Codec</title>
3938
3939 <section>
3940 <title>General</title>
3941 <para>
3942 The ALSA AC97 codec layer is a well-defined one, and you don't
3943 have to write much code to control it. Only low-level control
3944 routines are necessary. The AC97 codec API is defined in
3945 <filename>&lt;sound/ac97_codec.h&gt;</filename>.
3946 </para>
3947 </section>
3948
3949 <section id="api-ac97-example">
3950 <title>Full Code Example</title>
3951 <para>
3952 <example>
3953 <title>Example of AC97 Interface</title>
3954 <programlisting>
3955<![CDATA[
3956 struct mychip {
3957 ....
3958 struct snd_ac97 *ac97;
3959 ....
3960 };
3961
3962 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3963 unsigned short reg)
3964 {
3965 struct mychip *chip = ac97->private_data;
3966 ....
3967 /* read a register value here from the codec */
3968 return the_register_value;
3969 }
3970
3971 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3972 unsigned short reg, unsigned short val)
3973 {
3974 struct mychip *chip = ac97->private_data;
3975 ....
3976 /* write the given register value to the codec */
3977 }
3978
3979 static int snd_mychip_ac97(struct mychip *chip)
3980 {
3981 struct snd_ac97_bus *bus;
3982 struct snd_ac97_template ac97;
3983 int err;
3984 static struct snd_ac97_bus_ops ops = {
3985 .write = snd_mychip_ac97_write,
3986 .read = snd_mychip_ac97_read,
3987 };
3988
3989 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3990 if (err < 0)
3991 return err;
3992 memset(&ac97, 0, sizeof(ac97));
3993 ac97.private_data = chip;
3994 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3995 }
3996
3997]]>
3998 </programlisting>
3999 </example>
4000 </para>
4001 </section>
4002
4003 <section id="api-ac97-constructor">
4004 <title>Constructor</title>
4005 <para>
4006 To create an ac97 instance, first call <function>snd_ac97_bus</function>
4007 with an <type>ac97_bus_ops_t</type> record with callback functions.
4008
4009 <informalexample>
4010 <programlisting>
4011<![CDATA[
4012 struct snd_ac97_bus *bus;
4013 static struct snd_ac97_bus_ops ops = {
4014 .write = snd_mychip_ac97_write,
4015 .read = snd_mychip_ac97_read,
4016 };
4017
4018 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
4019]]>
4020 </programlisting>
4021 </informalexample>
4022
4023 The bus record is shared among all belonging ac97 instances.
4024 </para>
4025
4026 <para>
4027 And then call <function>snd_ac97_mixer()</function> with an
4028 struct <structname>snd_ac97_template</structname>
4029 record together with the bus pointer created above.
4030
4031 <informalexample>
4032 <programlisting>
4033<![CDATA[
4034 struct snd_ac97_template ac97;
4035 int err;
4036
4037 memset(&ac97, 0, sizeof(ac97));
4038 ac97.private_data = chip;
4039 snd_ac97_mixer(bus, &ac97, &chip->ac97);
4040]]>
4041 </programlisting>
4042 </informalexample>
4043
4044 where chip-&gt;ac97 is a pointer to a newly created
4045 <type>ac97_t</type> instance.
4046 In this case, the chip pointer is set as the private data, so that
4047 the read/write callback functions can refer to this chip instance.
4048 This instance is not necessarily stored in the chip
4049 record. If you need to change the register values from the
4050 driver, or need the suspend/resume of ac97 codecs, keep this
4051 pointer to pass to the corresponding functions.
4052 </para>
4053 </section>
4054
4055 <section id="api-ac97-callbacks">
4056 <title>Callbacks</title>
4057 <para>
4058 The standard callbacks are <structfield>read</structfield> and
4059 <structfield>write</structfield>. Obviously they
4060 correspond to the functions for read and write accesses to the
4061 hardware low-level codes.
4062 </para>
4063
4064 <para>
4065 The <structfield>read</structfield> callback returns the
4066 register value specified in the argument.
4067
4068 <informalexample>
4069 <programlisting>
4070<![CDATA[
4071 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4072 unsigned short reg)
4073 {
4074 struct mychip *chip = ac97->private_data;
4075 ....
4076 return the_register_value;
4077 }
4078]]>
4079 </programlisting>
4080 </informalexample>
4081
4082 Here, the chip can be cast from ac97-&gt;private_data.
4083 </para>
4084
4085 <para>
4086 Meanwhile, the <structfield>write</structfield> callback is
4087 used to set the register value.
4088
4089 <informalexample>
4090 <programlisting>
4091<![CDATA[
4092 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4093 unsigned short reg, unsigned short val)
4094]]>
4095 </programlisting>
4096 </informalexample>
4097 </para>
4098
4099 <para>
4100 These callbacks are non-atomic like the control API callbacks.
4101 </para>
4102
4103 <para>
4104 There are also other callbacks:
4105 <structfield>reset</structfield>,
4106 <structfield>wait</structfield> and
4107 <structfield>init</structfield>.
4108 </para>
4109
4110 <para>
4111 The <structfield>reset</structfield> callback is used to reset
4112 the codec. If the chip requires a special kind of reset, you can
4113 define this callback.
4114 </para>
4115
4116 <para>
4117 The <structfield>wait</structfield> callback is used to
4118 add some waiting time in the standard initialization of the codec. If the
4119 chip requires the extra waiting time, define this callback.
4120 </para>
4121
4122 <para>
4123 The <structfield>init</structfield> callback is used for
4124 additional initialization of the codec.
4125 </para>
4126 </section>
4127
4128 <section id="api-ac97-updating-registers">
4129 <title>Updating Registers in The Driver</title>
4130 <para>
4131 If you need to access to the codec from the driver, you can
4132 call the following functions:
4133 <function>snd_ac97_write()</function>,
4134 <function>snd_ac97_read()</function>,
4135 <function>snd_ac97_update()</function> and
4136 <function>snd_ac97_update_bits()</function>.
4137 </para>
4138
4139 <para>
4140 Both <function>snd_ac97_write()</function> and
4141 <function>snd_ac97_update()</function> functions are used to
4142 set a value to the given register
4143 (<constant>AC97_XXX</constant>). The difference between them is
4144 that <function>snd_ac97_update()</function> doesn't write a
4145 value if the given value has been already set, while
4146 <function>snd_ac97_write()</function> always rewrites the
4147 value.
4148
4149 <informalexample>
4150 <programlisting>
4151<![CDATA[
4152 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4153 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4154]]>
4155 </programlisting>
4156 </informalexample>
4157 </para>
4158
4159 <para>
4160 <function>snd_ac97_read()</function> is used to read the value
4161 of the given register. For example,
4162
4163 <informalexample>
4164 <programlisting>
4165<![CDATA[
4166 value = snd_ac97_read(ac97, AC97_MASTER);
4167]]>
4168 </programlisting>
4169 </informalexample>
4170 </para>
4171
4172 <para>
4173 <function>snd_ac97_update_bits()</function> is used to update
4174 some bits in the given register.
4175
4176 <informalexample>
4177 <programlisting>
4178<![CDATA[
4179 snd_ac97_update_bits(ac97, reg, mask, value);
4180]]>
4181 </programlisting>
4182 </informalexample>
4183 </para>
4184
4185 <para>
4186 Also, there is a function to change the sample rate (of a
4187 given register such as
4188 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4189 DRA is supported by the codec:
4190 <function>snd_ac97_set_rate()</function>.
4191
4192 <informalexample>
4193 <programlisting>
4194<![CDATA[
4195 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4196]]>
4197 </programlisting>
4198 </informalexample>
4199 </para>
4200
4201 <para>
4202 The following registers are available to set the rate:
4203 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4204 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4205 <constant>AC97_PCM_LR_ADC_RATE</constant>,
4206 <constant>AC97_SPDIF</constant>. When
4207 <constant>AC97_SPDIF</constant> is specified, the register is
4208 not really changed but the corresponding IEC958 status bits will
4209 be updated.
4210 </para>
4211 </section>
4212
4213 <section id="api-ac97-clock-adjustment">
4214 <title>Clock Adjustment</title>
4215 <para>
4216 In some chips, the clock of the codec isn't 48000 but using a
4217 PCI clock (to save a quartz!). In this case, change the field
4218 bus-&gt;clock to the corresponding
4219 value. For example, intel8x0
4220 and es1968 drivers have their own function to read from the clock.
4221 </para>
4222 </section>
4223
4224 <section id="api-ac97-proc-files">
4225 <title>Proc Files</title>
4226 <para>
4227 The ALSA AC97 interface will create a proc file such as
4228 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4229 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4230 see the current status and registers of the codec.
4231 </para>
4232 </section>
4233
4234 <section id="api-ac97-multiple-codecs">
4235 <title>Multiple Codecs</title>
4236 <para>
4237 When there are several codecs on the same card, you need to
4238 call <function>snd_ac97_mixer()</function> multiple times with
4239 ac97.num=1 or greater. The <structfield>num</structfield> field
4240 specifies the codec number.
4241 </para>
4242
4243 <para>
4244 If you set up multiple codecs, you either need to write
4245 different callbacks for each codec or check
4246 ac97-&gt;num in the callback routines.
4247 </para>
4248 </section>
4249
4250 </chapter>
4251
4252
4253<!-- ****************************************************** -->
4254<!-- MIDI (MPU401-UART) Interface -->
4255<!-- ****************************************************** -->
4256 <chapter id="midi-interface">
4257 <title>MIDI (MPU401-UART) Interface</title>
4258
4259 <section id="midi-interface-general">
4260 <title>General</title>
4261 <para>
4262 Many soundcards have built-in MIDI (MPU401-UART)
4263 interfaces. When the soundcard supports the standard MPU401-UART
4264 interface, most likely you can use the ALSA MPU401-UART API. The
4265 MPU401-UART API is defined in
4266 <filename>&lt;sound/mpu401.h&gt;</filename>.
4267 </para>
4268
4269 <para>
4270 Some soundchips have a similar but slightly different
4271 implementation of mpu401 stuff. For example, emu10k1 has its own
4272 mpu401 routines.
4273 </para>
4274 </section>
4275
4276 <section id="midi-interface-constructor">
4277 <title>Constructor</title>
4278 <para>
4279 To create a rawmidi object, call
4280 <function>snd_mpu401_uart_new()</function>.
4281
4282 <informalexample>
4283 <programlisting>
4284<![CDATA[
4285 struct snd_rawmidi *rmidi;
4286 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4287 irq, irq_flags, &rmidi);
4288]]>
4289 </programlisting>
4290 </informalexample>
4291 </para>
4292
4293 <para>
4294 The first argument is the card pointer, and the second is the
4295 index of this component. You can create up to 8 rawmidi
4296 devices.
4297 </para>
4298
4299 <para>
4300 The third argument is the type of the hardware,
4301 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4302 you can use <constant>MPU401_HW_MPU401</constant>.
4303 </para>
4304
4305 <para>
4306 The 4th argument is the I/O port address. Many
4307 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4308 might be a part of its own PCI I/O region. It depends on the
4309 chip design.
4310 </para>
4311
4312 <para>
4313 The 5th argument is a bitflag for additional information.
4314 When the I/O port address above is part of the PCI I/O
4315 region, the MPU401 I/O port might have been already allocated
4316 (reserved) by the driver itself. In such a case, pass a bit flag
4317 <constant>MPU401_INFO_INTEGRATED</constant>,
4318 and the mpu401-uart layer will allocate the I/O ports by itself.
4319 </para>
4320
4321 <para>
4322 When the controller supports only the input or output MIDI stream,
4323 pass the <constant>MPU401_INFO_INPUT</constant> or
4324 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4325 Then the rawmidi instance is created as a single stream.
4326 </para>
4327
4328 <para>
4329 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4330 the access method to MMIO (via readb and writeb) instead of
4331 iob and outb. In this case, you have to pass the iomapped address
4332 to <function>snd_mpu401_uart_new()</function>.
4333 </para>
4334
4335 <para>
4336 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4337 stream isn't checked in the default interrupt handler. The driver
4338 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4339 by itself to start processing the output stream in the irq handler.
4340 </para>
4341
4342 <para>
4343 Usually, the port address corresponds to the command port and
4344 port + 1 corresponds to the data port. If not, you may change
4345 the <structfield>cport</structfield> field of
4346 struct <structname>snd_mpu401</structname> manually
4347 afterward. However, <structname>snd_mpu401</structname> pointer is not
4348 returned explicitly by
4349 <function>snd_mpu401_uart_new()</function>. You need to cast
4350 rmidi-&gt;private_data to
4351 <structname>snd_mpu401</structname> explicitly,
4352
4353 <informalexample>
4354 <programlisting>
4355<![CDATA[
4356 struct snd_mpu401 *mpu;
4357 mpu = rmidi->private_data;
4358]]>
4359 </programlisting>
4360 </informalexample>
4361
4362 and reset the cport as you like:
4363
4364 <informalexample>
4365 <programlisting>
4366<![CDATA[
4367 mpu->cport = my_own_control_port;
4368]]>
4369 </programlisting>
4370 </informalexample>
4371 </para>
4372
4373 <para>
4374 The 6th argument specifies the irq number for UART. If the irq
4375 is already allocated, pass 0 to the 7th argument
4376 (<parameter>irq_flags</parameter>). Otherwise, pass the flags
4377 for irq allocation
4378 (<constant>SA_XXX</constant> bits) to it, and the irq will be
4379 reserved by the mpu401-uart layer. If the card doesn't generate
4380 UART interrupts, pass -1 as the irq number. Then a timer
4381 interrupt will be invoked for polling.
4382 </para>
4383 </section>
4384
4385 <section id="midi-interface-interrupt-handler">
4386 <title>Interrupt Handler</title>
4387 <para>
4388 When the interrupt is allocated in
4389 <function>snd_mpu401_uart_new()</function>, the private
4390 interrupt handler is used, hence you don't have anything else to do
4391 than creating the mpu401 stuff. Otherwise, you have to call
4392 <function>snd_mpu401_uart_interrupt()</function> explicitly when
4393 a UART interrupt is invoked and checked in your own interrupt
4394 handler.
4395 </para>
4396
4397 <para>
4398 In this case, you need to pass the private_data of the
4399 returned rawmidi object from
4400 <function>snd_mpu401_uart_new()</function> as the second
4401 argument of <function>snd_mpu401_uart_interrupt()</function>.
4402
4403 <informalexample>
4404 <programlisting>
4405<![CDATA[
4406 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4407]]>
4408 </programlisting>
4409 </informalexample>
4410 </para>
4411 </section>
4412
4413 </chapter>
4414
4415
4416<!-- ****************************************************** -->
4417<!-- RawMIDI Interface -->
4418<!-- ****************************************************** -->
4419 <chapter id="rawmidi-interface">
4420 <title>RawMIDI Interface</title>
4421
4422 <section id="rawmidi-interface-overview">
4423 <title>Overview</title>
4424
4425 <para>
4426 The raw MIDI interface is used for hardware MIDI ports that can
4427 be accessed as a byte stream. It is not used for synthesizer
4428 chips that do not directly understand MIDI.
4429 </para>
4430
4431 <para>
4432 ALSA handles file and buffer management. All you have to do is
4433 to write some code to move data between the buffer and the
4434 hardware.
4435 </para>
4436
4437 <para>
4438 The rawmidi API is defined in
4439 <filename>&lt;sound/rawmidi.h&gt;</filename>.
4440 </para>
4441 </section>
4442
4443 <section id="rawmidi-interface-constructor">
4444 <title>Constructor</title>
4445
4446 <para>
4447 To create a rawmidi device, call the
4448 <function>snd_rawmidi_new</function> function:
4449 <informalexample>
4450 <programlisting>
4451<![CDATA[
4452 struct snd_rawmidi *rmidi;
4453 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4454 if (err < 0)
4455 return err;
4456 rmidi->private_data = chip;
4457 strcpy(rmidi->name, "My MIDI");
4458 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4459 SNDRV_RAWMIDI_INFO_INPUT |
4460 SNDRV_RAWMIDI_INFO_DUPLEX;
4461]]>
4462 </programlisting>
4463 </informalexample>
4464 </para>
4465
4466 <para>
4467 The first argument is the card pointer, the second argument is
4468 the ID string.
4469 </para>
4470
4471 <para>
4472 The third argument is the index of this component. You can
4473 create up to 8 rawmidi devices.
4474 </para>
4475
4476 <para>
4477 The fourth and fifth arguments are the number of output and
4478 input substreams, respectively, of this device (a substream is
4479 the equivalent of a MIDI port).
4480 </para>
4481
4482 <para>
4483 Set the <structfield>info_flags</structfield> field to specify
4484 the capabilities of the device.
4485 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4486 at least one output port,
4487 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4488 least one input port,
4489 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4490 can handle output and input at the same time.
4491 </para>
4492
4493 <para>
4494 After the rawmidi device is created, you need to set the
4495 operators (callbacks) for each substream. There are helper
4496 functions to set the operators for all the substreams of a device:
4497 <informalexample>
4498 <programlisting>
4499<![CDATA[
4500 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4501 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4502]]>
4503 </programlisting>
4504 </informalexample>
4505 </para>
4506
4507 <para>
4508 The operators are usually defined like this:
4509 <informalexample>
4510 <programlisting>
4511<![CDATA[
4512 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4513 .open = snd_mymidi_output_open,
4514 .close = snd_mymidi_output_close,
4515 .trigger = snd_mymidi_output_trigger,
4516 };
4517]]>
4518 </programlisting>
4519 </informalexample>
4520 These callbacks are explained in the <link
4521 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4522 section.
4523 </para>
4524
4525 <para>
4526 If there are more than one substream, you should give a
4527 unique name to each of them:
4528 <informalexample>
4529 <programlisting>
4530<![CDATA[
4531 struct snd_rawmidi_substream *substream;
4532 list_for_each_entry(substream,
4533 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4534 list {
4535 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4536 }
4537 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4538]]>
4539 </programlisting>
4540 </informalexample>
4541 </para>
4542 </section>
4543
4544 <section id="rawmidi-interface-callbacks">
4545 <title>Callbacks</title>
4546
4547 <para>
4548 In all the callbacks, the private data that you've set for the
4549 rawmidi device can be accessed as
4550 substream-&gt;rmidi-&gt;private_data.
4551 <!-- <code> isn't available before DocBook 4.3 -->
4552 </para>
4553
4554 <para>
4555 If there is more than one port, your callbacks can determine the
4556 port index from the struct snd_rawmidi_substream data passed to each
4557 callback:
4558 <informalexample>
4559 <programlisting>
4560<![CDATA[
4561 struct snd_rawmidi_substream *substream;
4562 int index = substream->number;
4563]]>
4564 </programlisting>
4565 </informalexample>
4566 </para>
4567
4568 <section id="rawmidi-interface-op-open">
4569 <title><function>open</function> callback</title>
4570
4571 <informalexample>
4572 <programlisting>
4573<![CDATA[
4574 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4575]]>
4576 </programlisting>
4577 </informalexample>
4578
4579 <para>
4580 This is called when a substream is opened.
4581 You can initialize the hardware here, but you shouldn't
4582 start transmitting/receiving data yet.
4583 </para>
4584 </section>
4585
4586 <section id="rawmidi-interface-op-close">
4587 <title><function>close</function> callback</title>
4588
4589 <informalexample>
4590 <programlisting>
4591<![CDATA[
4592 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4593]]>
4594 </programlisting>
4595 </informalexample>
4596
4597 <para>
4598 Guess what.
4599 </para>
4600
4601 <para>
4602 The <function>open</function> and <function>close</function>
4603 callbacks of a rawmidi device are serialized with a mutex,
4604 and can sleep.
4605 </para>
4606 </section>
4607
4608 <section id="rawmidi-interface-op-trigger-out">
4609 <title><function>trigger</function> callback for output
4610 substreams</title>
4611
4612 <informalexample>
4613 <programlisting>
4614<![CDATA[
4615 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4616]]>
4617 </programlisting>
4618 </informalexample>
4619
4620 <para>
4621 This is called with a nonzero <parameter>up</parameter>
4622 parameter when there is some data in the substream buffer that
4623 must be transmitted.
4624 </para>
4625
4626 <para>
4627 To read data from the buffer, call
4628 <function>snd_rawmidi_transmit_peek</function>. It will
4629 return the number of bytes that have been read; this will be
4630 less than the number of bytes requested when there are no more
4631 data in the buffer.
4632 After the data have been transmitted successfully, call
4633 <function>snd_rawmidi_transmit_ack</function> to remove the
4634 data from the substream buffer:
4635 <informalexample>
4636 <programlisting>
4637<![CDATA[
4638 unsigned char data;
4639 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4640 if (snd_mychip_try_to_transmit(data))
4641 snd_rawmidi_transmit_ack(substream, 1);
4642 else
4643 break; /* hardware FIFO full */
4644 }
4645]]>
4646 </programlisting>
4647 </informalexample>
4648 </para>
4649
4650 <para>
4651 If you know beforehand that the hardware will accept data, you
4652 can use the <function>snd_rawmidi_transmit</function> function
4653 which reads some data and removes them from the buffer at once:
4654 <informalexample>
4655 <programlisting>
4656<![CDATA[
4657 while (snd_mychip_transmit_possible()) {
4658 unsigned char data;
4659 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4660 break; /* no more data */
4661 snd_mychip_transmit(data);
4662 }
4663]]>
4664 </programlisting>
4665 </informalexample>
4666 </para>
4667
4668 <para>
4669 If you know beforehand how many bytes you can accept, you can
4670 use a buffer size greater than one with the
4671 <function>snd_rawmidi_transmit*</function> functions.
4672 </para>
4673
4674 <para>
4675 The <function>trigger</function> callback must not sleep. If
4676 the hardware FIFO is full before the substream buffer has been
4677 emptied, you have to continue transmitting data later, either
4678 in an interrupt handler, or with a timer if the hardware
4679 doesn't have a MIDI transmit interrupt.
4680 </para>
4681
4682 <para>
4683 The <function>trigger</function> callback is called with a
4684 zero <parameter>up</parameter> parameter when the transmission
4685 of data should be aborted.
4686 </para>
4687 </section>
4688
4689 <section id="rawmidi-interface-op-trigger-in">
4690 <title><function>trigger</function> callback for input
4691 substreams</title>
4692
4693 <informalexample>
4694 <programlisting>
4695<![CDATA[
4696 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4697]]>
4698 </programlisting>
4699 </informalexample>
4700
4701 <para>
4702 This is called with a nonzero <parameter>up</parameter>
4703 parameter to enable receiving data, or with a zero
4704 <parameter>up</parameter> parameter do disable receiving data.
4705 </para>
4706
4707 <para>
4708 The <function>trigger</function> callback must not sleep; the
4709 actual reading of data from the device is usually done in an
4710 interrupt handler.
4711 </para>
4712
4713 <para>
4714 When data reception is enabled, your interrupt handler should
4715 call <function>snd_rawmidi_receive</function> for all received
4716 data:
4717 <informalexample>
4718 <programlisting>
4719<![CDATA[
4720 void snd_mychip_midi_interrupt(...)
4721 {
4722 while (mychip_midi_available()) {
4723 unsigned char data;
4724 data = mychip_midi_read();
4725 snd_rawmidi_receive(substream, &data, 1);
4726 }
4727 }
4728]]>
4729 </programlisting>
4730 </informalexample>
4731 </para>
4732 </section>
4733
4734 <section id="rawmidi-interface-op-drain">
4735 <title><function>drain</function> callback</title>
4736
4737 <informalexample>
4738 <programlisting>
4739<![CDATA[
4740 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4741]]>
4742 </programlisting>
4743 </informalexample>
4744
4745 <para>
4746 This is only used with output substreams. This function should wait
4747 until all data read from the substream buffer have been transmitted.
4748 This ensures that the device can be closed and the driver unloaded
4749 without losing data.
4750 </para>
4751
4752 <para>
4753 This callback is optional. If you do not set
4754 <structfield>drain</structfield> in the struct snd_rawmidi_ops
4755 structure, ALSA will simply wait for 50&nbsp;milliseconds
4756 instead.
4757 </para>
4758 </section>
4759 </section>
4760
4761 </chapter>
4762
4763
4764<!-- ****************************************************** -->
4765<!-- Miscellaneous Devices -->
4766<!-- ****************************************************** -->
4767 <chapter id="misc-devices">
4768 <title>Miscellaneous Devices</title>
4769
4770 <section id="misc-devices-opl3">
4771 <title>FM OPL3</title>
4772 <para>
4773 The FM OPL3 is still used in many chips (mainly for backward
4774 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4775 OPL3 API is defined in
4776 <filename>&lt;sound/opl3.h&gt;</filename>.
4777 </para>
4778
4779 <para>
4780 FM registers can be directly accessed through the direct-FM API,
4781 defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4782 ALSA native mode, FM registers are accessed through
4783 the Hardware-Dependant Device direct-FM extension API, whereas in
4784 OSS compatible mode, FM registers can be accessed with the OSS
4785 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
4786 </para>
4787
4788 <para>
4789 To create the OPL3 component, you have two functions to
4790 call. The first one is a constructor for the <type>opl3_t</type>
4791 instance.
4792
4793 <informalexample>
4794 <programlisting>
4795<![CDATA[
4796 struct snd_opl3 *opl3;
4797 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4798 integrated, &opl3);
4799]]>
4800 </programlisting>
4801 </informalexample>
4802 </para>
4803
4804 <para>
4805 The first argument is the card pointer, the second one is the
4806 left port address, and the third is the right port address. In
4807 most cases, the right port is placed at the left port + 2.
4808 </para>
4809
4810 <para>
4811 The fourth argument is the hardware type.
4812 </para>
4813
4814 <para>
4815 When the left and right ports have been already allocated by
4816 the card driver, pass non-zero to the fifth argument
4817 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4818 allocate the specified ports by itself.
4819 </para>
4820
4821 <para>
4822 When the accessing the hardware requires special method
4823 instead of the standard I/O access, you can create opl3 instance
4824 separately with <function>snd_opl3_new()</function>.
4825
4826 <informalexample>
4827 <programlisting>
4828<![CDATA[
4829 struct snd_opl3 *opl3;
4830 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4831]]>
4832 </programlisting>
4833 </informalexample>
4834 </para>
4835
4836 <para>
4837 Then set <structfield>command</structfield>,
4838 <structfield>private_data</structfield> and
4839 <structfield>private_free</structfield> for the private
4840 access function, the private data and the destructor.
4841 The l_port and r_port are not necessarily set. Only the
4842 command must be set properly. You can retrieve the data
4843 from the opl3-&gt;private_data field.
4844 </para>
4845
4846 <para>
4847 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4848 call <function>snd_opl3_init()</function> to initialize the chip to the
4849 proper state. Note that <function>snd_opl3_create()</function> always
4850 calls it internally.
4851 </para>
4852
4853 <para>
4854 If the opl3 instance is created successfully, then create a
4855 hwdep device for this opl3.
4856
4857 <informalexample>
4858 <programlisting>
4859<![CDATA[
4860 struct snd_hwdep *opl3hwdep;
4861 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4862]]>
4863 </programlisting>
4864 </informalexample>
4865 </para>
4866
4867 <para>
4868 The first argument is the <type>opl3_t</type> instance you
4869 created, and the second is the index number, usually 0.
4870 </para>
4871
4872 <para>
4873 The third argument is the index-offset for the sequencer
4874 client assigned to the OPL3 port. When there is an MPU401-UART,
4875 give 1 for here (UART always takes 0).
4876 </para>
4877 </section>
4878
4879 <section id="misc-devices-hardware-dependent">
4880 <title>Hardware-Dependent Devices</title>
4881 <para>
4882 Some chips need user-space access for special
4883 controls or for loading the micro code. In such a case, you can
4884 create a hwdep (hardware-dependent) device. The hwdep API is
4885 defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4886 find examples in opl3 driver or
4887 <filename>isa/sb/sb16_csp.c</filename>.
4888 </para>
4889
4890 <para>
4891 The creation of the <type>hwdep</type> instance is done via
4892 <function>snd_hwdep_new()</function>.
4893
4894 <informalexample>
4895 <programlisting>
4896<![CDATA[
4897 struct snd_hwdep *hw;
4898 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4899]]>
4900 </programlisting>
4901 </informalexample>
4902
4903 where the third argument is the index number.
4904 </para>
4905
4906 <para>
4907 You can then pass any pointer value to the
4908 <parameter>private_data</parameter>.
4909 If you assign a private data, you should define the
4910 destructor, too. The destructor function is set in
4911 the <structfield>private_free</structfield> field.
4912
4913 <informalexample>
4914 <programlisting>
4915<![CDATA[
4916 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4917 hw->private_data = p;
4918 hw->private_free = mydata_free;
4919]]>
4920 </programlisting>
4921 </informalexample>
4922
4923 and the implementation of the destructor would be:
4924
4925 <informalexample>
4926 <programlisting>
4927<![CDATA[
4928 static void mydata_free(struct snd_hwdep *hw)
4929 {
4930 struct mydata *p = hw->private_data;
4931 kfree(p);
4932 }
4933]]>
4934 </programlisting>
4935 </informalexample>
4936 </para>
4937
4938 <para>
4939 The arbitrary file operations can be defined for this
4940 instance. The file operators are defined in
4941 the <parameter>ops</parameter> table. For example, assume that
4942 this chip needs an ioctl.
4943
4944 <informalexample>
4945 <programlisting>
4946<![CDATA[
4947 hw->ops.open = mydata_open;
4948 hw->ops.ioctl = mydata_ioctl;
4949 hw->ops.release = mydata_release;
4950]]>
4951 </programlisting>
4952 </informalexample>
4953
4954 And implement the callback functions as you like.
4955 </para>
4956 </section>
4957
4958 <section id="misc-devices-IEC958">
4959 <title>IEC958 (S/PDIF)</title>
4960 <para>
4961 Usually the controls for IEC958 devices are implemented via
4962 the control interface. There is a macro to compose a name string for
4963 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4964 defined in <filename>&lt;include/asound.h&gt;</filename>.
4965 </para>
4966
4967 <para>
4968 There are some standard controls for IEC958 status bits. These
4969 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4970 and the size of element is fixed as 4 bytes array
4971 (value.iec958.status[x]). For the <structfield>info</structfield>
4972 callback, you don't specify
4973 the value field for this type (the count field must be set,
4974 though).
4975 </para>
4976
4977 <para>
4978 <quote>IEC958 Playback Con Mask</quote> is used to return the
4979 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4980 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4981 professional mode. They are read-only controls, and are defined
4982 as MIXER controls (iface =
4983 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4984 </para>
4985
4986 <para>
4987 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4988 defined for getting and setting the current default IEC958
4989 bits. Note that this one is usually defined as a PCM control
4990 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4991 although in some places it's defined as a MIXER control.
4992 </para>
4993
4994 <para>
4995 In addition, you can define the control switches to
4996 enable/disable or to set the raw bit mode. The implementation
4997 will depend on the chip, but the control should be named as
4998 <quote>IEC958 xxx</quote>, preferably using
4999 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
5000 </para>
5001
5002 <para>
5003 You can find several cases, for example,
5004 <filename>pci/emu10k1</filename>,
5005 <filename>pci/ice1712</filename>, or
5006 <filename>pci/cmipci.c</filename>.
5007 </para>
5008 </section>
5009
5010 </chapter>
5011
5012
5013<!-- ****************************************************** -->
5014<!-- Buffer and Memory Management -->
5015<!-- ****************************************************** -->
5016 <chapter id="buffer-and-memory">
5017 <title>Buffer and Memory Management</title>
5018
5019 <section id="buffer-and-memory-buffer-types">
5020 <title>Buffer Types</title>
5021 <para>
5022 ALSA provides several different buffer allocation functions
5023 depending on the bus and the architecture. All these have a
5024 consistent API. The allocation of physically-contiguous pages is
5025 done via
5026 <function>snd_malloc_xxx_pages()</function> function, where xxx
5027 is the bus type.
5028 </para>
5029
5030 <para>
5031 The allocation of pages with fallback is
5032 <function>snd_malloc_xxx_pages_fallback()</function>. This
5033 function tries to allocate the specified pages but if the pages
5034 are not available, it tries to reduce the page sizes until
5035 enough space is found.
5036 </para>
5037
5038 <para>
5039 The release the pages, call
5040 <function>snd_free_xxx_pages()</function> function.
5041 </para>
5042
5043 <para>
5044 Usually, ALSA drivers try to allocate and reserve
5045 a large contiguous physical space
5046 at the time the module is loaded for the later use.
5047 This is called <quote>pre-allocation</quote>.
5048 As already written, you can call the following function at
5049 pcm instance construction time (in the case of PCI bus).
5050
5051 <informalexample>
5052 <programlisting>
5053<![CDATA[
5054 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5055 snd_dma_pci_data(pci), size, max);
5056]]>
5057 </programlisting>
5058 </informalexample>
5059
5060 where <parameter>size</parameter> is the byte size to be
5061 pre-allocated and the <parameter>max</parameter> is the maximum
5062 size to be changed via the <filename>prealloc</filename> proc file.
5063 The allocator will try to get an area as large as possible
5064 within the given size.
5065 </para>
5066
5067 <para>
5068 The second argument (type) and the third argument (device pointer)
5069 are dependent on the bus.
5070 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5071 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5072 For the continuous buffer unrelated to the bus can be pre-allocated
5073 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5074 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5075 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5076 use.
5077 For the PCI scatter-gather buffers, use
5078 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5079 <function>snd_dma_pci_data(pci)</function>
5080 (see the
5081 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5082 </citetitle></link> section).
5083 </para>
5084
5085 <para>
5086 Once the buffer is pre-allocated, you can use the
5087 allocator in the <structfield>hw_params</structfield> callback:
5088
5089 <informalexample>
5090 <programlisting>
5091<![CDATA[
5092 snd_pcm_lib_malloc_pages(substream, size);
5093]]>
5094 </programlisting>
5095 </informalexample>
5096
5097 Note that you have to pre-allocate to use this function.
5098 </para>
5099 </section>
5100
5101 <section id="buffer-and-memory-external-hardware">
5102 <title>External Hardware Buffers</title>
5103 <para>
5104 Some chips have their own hardware buffers and the DMA
5105 transfer from the host memory is not available. In such a case,
5106 you need to either 1) copy/set the audio data directly to the
5107 external hardware buffer, or 2) make an intermediate buffer and
5108 copy/set the data from it to the external hardware buffer in
5109 interrupts (or in tasklets, preferably).
5110 </para>
5111
5112 <para>
5113 The first case works fine if the external hardware buffer is large
5114 enough. This method doesn't need any extra buffers and thus is
5115 more effective. You need to define the
5116 <structfield>copy</structfield> and
5117 <structfield>silence</structfield> callbacks for
5118 the data transfer. However, there is a drawback: it cannot
5119 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5120 wavetable PCM.
5121 </para>
5122
5123 <para>
5124 The second case allows for mmap on the buffer, although you have
5125 to handle an interrupt or a tasklet to transfer the data
5126 from the intermediate buffer to the hardware buffer. You can find an
5127 example in the vxpocket driver.
5128 </para>
5129
5130 <para>
5131 Another case is when the chip uses a PCI memory-map
5132 region for the buffer instead of the host memory. In this case,
5133 mmap is available only on certain architectures like the Intel one.
5134 In non-mmap mode, the data cannot be transferred as in the normal
5135 way. Thus you need to define the <structfield>copy</structfield> and
5136 <structfield>silence</structfield> callbacks as well,
5137 as in the cases above. The examples are found in
5138 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5139 </para>
5140
5141 <para>
5142 The implementation of the <structfield>copy</structfield> and
5143 <structfield>silence</structfield> callbacks depends upon
5144 whether the hardware supports interleaved or non-interleaved
5145 samples. The <structfield>copy</structfield> callback is
5146 defined like below, a bit
5147 differently depending whether the direction is playback or
5148 capture:
5149
5150 <informalexample>
5151 <programlisting>
5152<![CDATA[
5153 static int playback_copy(struct snd_pcm_substream *substream, int channel,
5154 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5155 static int capture_copy(struct snd_pcm_substream *substream, int channel,
5156 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5157]]>
5158 </programlisting>
5159 </informalexample>
5160 </para>
5161
5162 <para>
5163 In the case of interleaved samples, the second argument
5164 (<parameter>channel</parameter>) is not used. The third argument
5165 (<parameter>pos</parameter>) points the
5166 current position offset in frames.
5167 </para>
5168
5169 <para>
5170 The meaning of the fourth argument is different between
5171 playback and capture. For playback, it holds the source data
5172 pointer, and for capture, it's the destination data pointer.
5173 </para>
5174
5175 <para>
5176 The last argument is the number of frames to be copied.
5177 </para>
5178
5179 <para>
5180 What you have to do in this callback is again different
5181 between playback and capture directions. In the
5182 playback case, you copy the given amount of data
5183 (<parameter>count</parameter>) at the specified pointer
5184 (<parameter>src</parameter>) to the specified offset
5185 (<parameter>pos</parameter>) on the hardware buffer. When
5186 coded like memcpy-like way, the copy would be like:
5187
5188 <informalexample>
5189 <programlisting>
5190<![CDATA[
5191 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5192 frames_to_bytes(runtime, count));
5193]]>
5194 </programlisting>
5195 </informalexample>
5196 </para>
5197
5198 <para>
5199 For the capture direction, you copy the given amount of
5200 data (<parameter>count</parameter>) at the specified offset
5201 (<parameter>pos</parameter>) on the hardware buffer to the
5202 specified pointer (<parameter>dst</parameter>).
5203
5204 <informalexample>
5205 <programlisting>
5206<![CDATA[
5207 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5208 frames_to_bytes(runtime, count));
5209]]>
5210 </programlisting>
5211 </informalexample>
5212
5213 Note that both the position and the amount of data are given
5214 in frames.
5215 </para>
5216
5217 <para>
5218 In the case of non-interleaved samples, the implementation
5219 will be a bit more complicated.
5220 </para>
5221
5222 <para>
5223 You need to check the channel argument, and if it's -1, copy
5224 the whole channels. Otherwise, you have to copy only the
5225 specified channel. Please check
5226 <filename>isa/gus/gus_pcm.c</filename> as an example.
5227 </para>
5228
5229 <para>
5230 The <structfield>silence</structfield> callback is also
5231 implemented in a similar way.
5232
5233 <informalexample>
5234 <programlisting>
5235<![CDATA[
5236 static int silence(struct snd_pcm_substream *substream, int channel,
5237 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5238]]>
5239 </programlisting>
5240 </informalexample>
5241 </para>
5242
5243 <para>
5244 The meanings of arguments are the same as in the
5245 <structfield>copy</structfield>
5246 callback, although there is no <parameter>src/dst</parameter>
5247 argument. In the case of interleaved samples, the channel
5248 argument has no meaning, as well as on
5249 <structfield>copy</structfield> callback.
5250 </para>
5251
5252 <para>
5253 The role of <structfield>silence</structfield> callback is to
5254 set the given amount
5255 (<parameter>count</parameter>) of silence data at the
5256 specified offset (<parameter>pos</parameter>) on the hardware
5257 buffer. Suppose that the data format is signed (that is, the
5258 silent-data is 0), and the implementation using a memset-like
5259 function would be like:
5260
5261 <informalexample>
5262 <programlisting>
5263<![CDATA[
5264 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5265 frames_to_bytes(runtime, count));
5266]]>
5267 </programlisting>
5268 </informalexample>
5269 </para>
5270
5271 <para>
5272 In the case of non-interleaved samples, again, the
5273 implementation becomes a bit more complicated. See, for example,
5274 <filename>isa/gus/gus_pcm.c</filename>.
5275 </para>
5276 </section>
5277
5278 <section id="buffer-and-memory-non-contiguous">
5279 <title>Non-Contiguous Buffers</title>
5280 <para>
5281 If your hardware supports the page table as in emu10k1 or the
5282 buffer descriptors as in via82xx, you can use the scatter-gather
5283 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5284 The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
5285 </para>
5286
5287 <para>
5288 For creating the SG-buffer handler, call
5289 <function>snd_pcm_lib_preallocate_pages()</function> or
5290 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5291 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5292 in the PCM constructor like other PCI pre-allocator.
5293 You need to pass <function>snd_dma_pci_data(pci)</function>,
5294 where pci is the struct <structname>pci_dev</structname> pointer
5295 of the chip as well.
5296 The <type>struct snd_sg_buf</type> instance is created as
5297 substream-&gt;dma_private. You can cast
5298 the pointer like:
5299
5300 <informalexample>
5301 <programlisting>
5302<![CDATA[
5303 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5304]]>
5305 </programlisting>
5306 </informalexample>
5307 </para>
5308
5309 <para>
5310 Then call <function>snd_pcm_lib_malloc_pages()</function>
5311 in the <structfield>hw_params</structfield> callback
5312 as well as in the case of normal PCI buffer.
5313 The SG-buffer handler will allocate the non-contiguous kernel
5314 pages of the given size and map them onto the virtually contiguous
5315 memory. The virtual pointer is addressed in runtime-&gt;dma_area.
5316 The physical address (runtime-&gt;dma_addr) is set to zero,
5317 because the buffer is physically non-contigous.
5318 The physical address table is set up in sgbuf-&gt;table.
5319 You can get the physical address at a certain offset via
5320 <function>snd_pcm_sgbuf_get_addr()</function>.
5321 </para>
5322
5323 <para>
5324 When a SG-handler is used, you need to set
5325 <function>snd_pcm_sgbuf_ops_page</function> as
5326 the <structfield>page</structfield> callback.
5327 (See <link linkend="pcm-interface-operators-page-callback">
5328 <citetitle>page callback section</citetitle></link>.)
5329 </para>
5330
5331 <para>
5332 To release the data, call
5333 <function>snd_pcm_lib_free_pages()</function> in the
5334 <structfield>hw_free</structfield> callback as usual.
5335 </para>
5336 </section>
5337
5338 <section id="buffer-and-memory-vmalloced">
5339 <title>Vmalloc'ed Buffers</title>
5340 <para>
5341 It's possible to use a buffer allocated via
5342 <function>vmalloc</function>, for example, for an intermediate
5343 buffer. Since the allocated pages are not contiguous, you need
5344 to set the <structfield>page</structfield> callback to obtain
5345 the physical address at every offset.
5346 </para>
5347
5348 <para>
5349 The implementation of <structfield>page</structfield> callback
5350 would be like this:
5351
5352 <informalexample>
5353 <programlisting>
5354<![CDATA[
5355 #include <linux/vmalloc.h>
5356
5357 /* get the physical page pointer on the given offset */
5358 static struct page *mychip_page(struct snd_pcm_substream *substream,
5359 unsigned long offset)
5360 {
5361 void *pageptr = substream->runtime->dma_area + offset;
5362 return vmalloc_to_page(pageptr);
5363 }
5364]]>
5365 </programlisting>
5366 </informalexample>
5367 </para>
5368 </section>
5369
5370 </chapter>
5371
5372
5373<!-- ****************************************************** -->
5374<!-- Proc Interface -->
5375<!-- ****************************************************** -->
5376 <chapter id="proc-interface">
5377 <title>Proc Interface</title>
5378 <para>
5379 ALSA provides an easy interface for procfs. The proc files are
5380 very useful for debugging. I recommend you set up proc files if
5381 you write a driver and want to get a running status or register
5382 dumps. The API is found in
5383 <filename>&lt;sound/info.h&gt;</filename>.
5384 </para>
5385
5386 <para>
5387 To create a proc file, call
5388 <function>snd_card_proc_new()</function>.
5389
5390 <informalexample>
5391 <programlisting>
5392<![CDATA[
5393 struct snd_info_entry *entry;
5394 int err = snd_card_proc_new(card, "my-file", &entry);
5395]]>
5396 </programlisting>
5397 </informalexample>
5398
5399 where the second argument specifies the name of the proc file to be
5400 created. The above example will create a file
5401 <filename>my-file</filename> under the card directory,
5402 e.g. <filename>/proc/asound/card0/my-file</filename>.
5403 </para>
5404
5405 <para>
5406 Like other components, the proc entry created via
5407 <function>snd_card_proc_new()</function> will be registered and
5408 released automatically in the card registration and release
5409 functions.
5410 </para>
5411
5412 <para>
5413 When the creation is successful, the function stores a new
5414 instance in the pointer given in the third argument.
5415 It is initialized as a text proc file for read only. To use
5416 this proc file as a read-only text file as it is, set the read
5417 callback with a private data via
5418 <function>snd_info_set_text_ops()</function>.
5419
5420 <informalexample>
5421 <programlisting>
5422<![CDATA[
5423 snd_info_set_text_ops(entry, chip, my_proc_read);
5424]]>
5425 </programlisting>
5426 </informalexample>
5427
5428 where the second argument (<parameter>chip</parameter>) is the
5429 private data to be used in the callbacks. The third parameter
5430 specifies the read buffer size and the fourth
5431 (<parameter>my_proc_read</parameter>) is the callback function, which
5432 is defined like
5433
5434 <informalexample>
5435 <programlisting>
5436<![CDATA[
5437 static void my_proc_read(struct snd_info_entry *entry,
5438 struct snd_info_buffer *buffer);
5439]]>
5440 </programlisting>
5441 </informalexample>
5442
5443 </para>
5444
5445 <para>
5446 In the read callback, use <function>snd_iprintf()</function> for
5447 output strings, which works just like normal
5448 <function>printf()</function>. For example,
5449
5450 <informalexample>
5451 <programlisting>
5452<![CDATA[
5453 static void my_proc_read(struct snd_info_entry *entry,
5454 struct snd_info_buffer *buffer)
5455 {
5456 struct my_chip *chip = entry->private_data;
5457
5458 snd_iprintf(buffer, "This is my chip!\n");
5459 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5460 }
5461]]>
5462 </programlisting>
5463 </informalexample>
5464 </para>
5465
5466 <para>
5467 The file permissions can be changed afterwards. As default, it's
5468 set as read only for all users. If you want to add write
5469 permission for the user (root as default), do as follows:
5470
5471 <informalexample>
5472 <programlisting>
5473<![CDATA[
5474 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5475]]>
5476 </programlisting>
5477 </informalexample>
5478
5479 and set the write buffer size and the callback
5480
5481 <informalexample>
5482 <programlisting>
5483<![CDATA[
5484 entry->c.text.write = my_proc_write;
5485]]>
5486 </programlisting>
5487 </informalexample>
5488 </para>
5489
5490 <para>
5491 For the write callback, you can use
5492 <function>snd_info_get_line()</function> to get a text line, and
5493 <function>snd_info_get_str()</function> to retrieve a string from
5494 the line. Some examples are found in
5495 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5496 <filename>pcm_oss.c</filename>.
5497 </para>
5498
5499 <para>
5500 For a raw-data proc-file, set the attributes as follows:
5501
5502 <informalexample>
5503 <programlisting>
5504<![CDATA[
5505 static struct snd_info_entry_ops my_file_io_ops = {
5506 .read = my_file_io_read,
5507 };
5508
5509 entry->content = SNDRV_INFO_CONTENT_DATA;
5510 entry->private_data = chip;
5511 entry->c.ops = &my_file_io_ops;
5512 entry->size = 4096;
5513 entry->mode = S_IFREG | S_IRUGO;
5514]]>
5515 </programlisting>
5516 </informalexample>
5517 </para>
5518
5519 <para>
5520 The callback is much more complicated than the text-file
5521 version. You need to use a low-level I/O functions such as
5522 <function>copy_from/to_user()</function> to transfer the
5523 data.
5524
5525 <informalexample>
5526 <programlisting>
5527<![CDATA[
5528 static long my_file_io_read(struct snd_info_entry *entry,
5529 void *file_private_data,
5530 struct file *file,
5531 char *buf,
5532 unsigned long count,
5533 unsigned long pos)
5534 {
5535 long size = count;
5536 if (pos + size > local_max_size)
5537 size = local_max_size - pos;
5538 if (copy_to_user(buf, local_data + pos, size))
5539 return -EFAULT;
5540 return size;
5541 }
5542]]>
5543 </programlisting>
5544 </informalexample>
5545 </para>
5546
5547 </chapter>
5548
5549
5550<!-- ****************************************************** -->
5551<!-- Power Management -->
5552<!-- ****************************************************** -->
5553 <chapter id="power-management">
5554 <title>Power Management</title>
5555 <para>
5556 If the chip is supposed to work with suspend/resume
5557 functions, you need to add power-management code to the
5558 driver. The additional code for power-management should be
5559 <function>ifdef</function>'ed with
5560 <constant>CONFIG_PM</constant>.
5561 </para>
5562
5563 <para>
5564 If the driver <emphasis>fully</emphasis> supports suspend/resume
5565 that is, the device can be
5566 properly resumed to its state when suspend was called,
5567 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5568 in the pcm info field. Usually, this is possible when the
5569 registers of the chip can be safely saved and restored to
5570 RAM. If this is set, the trigger callback is called with
5571 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5572 callback completes.
5573 </para>
5574
5575 <para>
5576 Even if the driver doesn't support PM fully but
5577 partial suspend/resume is still possible, it's still worthy to
5578 implement suspend/resume callbacks. In such a case, applications
5579 would reset the status by calling
5580 <function>snd_pcm_prepare()</function> and restart the stream
5581 appropriately. Hence, you can define suspend/resume callbacks
5582 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5583 info flag to the PCM.
5584 </para>
5585
5586 <para>
5587 Note that the trigger with SUSPEND can always be called when
5588 <function>snd_pcm_suspend_all</function> is called,
5589 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5590 The <constant>RESUME</constant> flag affects only the behavior
5591 of <function>snd_pcm_resume()</function>.
5592 (Thus, in theory,
5593 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5594 to be handled in the trigger callback when no
5595 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
5596 it's better to keep it for compatibility reasons.)
5597 </para>
5598 <para>
5599 In the earlier version of ALSA drivers, a common
5600 power-management layer was provided, but it has been removed.
5601 The driver needs to define the suspend/resume hooks according to
5602 the bus the device is connected to. In the case of PCI drivers, the
5603 callbacks look like below:
5604
5605 <informalexample>
5606 <programlisting>
5607<![CDATA[
5608 #ifdef CONFIG_PM
5609 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5610 {
5611 .... /* do things for suspend */
5612 return 0;
5613 }
5614 static int snd_my_resume(struct pci_dev *pci)
5615 {
5616 .... /* do things for suspend */
5617 return 0;
5618 }
5619 #endif
5620]]>
5621 </programlisting>
5622 </informalexample>
5623 </para>
5624
5625 <para>
5626 The scheme of the real suspend job is as follows.
5627
5628 <orderedlist>
5629 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5630 <listitem><para>Call <function>snd_power_change_state()</function> with
5631 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5632 power status.</para></listitem>
5633 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5634 <listitem><para>If AC97 codecs are used, call
5635 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5636 <listitem><para>Save the register values if necessary.</para></listitem>
5637 <listitem><para>Stop the hardware if necessary.</para></listitem>
5638 <listitem><para>Disable the PCI device by calling
5639 <function>pci_disable_device()</function>. Then, call
5640 <function>pci_save_state()</function> at last.</para></listitem>
5641 </orderedlist>
5642 </para>
5643
5644 <para>
5645 A typical code would be like:
5646
5647 <informalexample>
5648 <programlisting>
5649<![CDATA[
5650 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5651 {
5652 /* (1) */
5653 struct snd_card *card = pci_get_drvdata(pci);
5654 struct mychip *chip = card->private_data;
5655 /* (2) */
5656 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5657 /* (3) */
5658 snd_pcm_suspend_all(chip->pcm);
5659 /* (4) */
5660 snd_ac97_suspend(chip->ac97);
5661 /* (5) */
5662 snd_mychip_save_registers(chip);
5663 /* (6) */
5664 snd_mychip_stop_hardware(chip);
5665 /* (7) */
5666 pci_disable_device(pci);
5667 pci_save_state(pci);
5668 return 0;
5669 }
5670]]>
5671 </programlisting>
5672 </informalexample>
5673 </para>
5674
5675 <para>
5676 The scheme of the real resume job is as follows.
5677
5678 <orderedlist>
5679 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5680 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5681 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5682 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5683 <listitem><para>Re-initialize the chip.</para></listitem>
5684 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5685 <listitem><para>Resume the mixer, e.g. calling
5686 <function>snd_ac97_resume()</function>.</para></listitem>
5687 <listitem><para>Restart the hardware (if any).</para></listitem>
5688 <listitem><para>Call <function>snd_power_change_state()</function> with
5689 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5690 </orderedlist>
5691 </para>
5692
5693 <para>
5694 A typical code would be like:
5695
5696 <informalexample>
5697 <programlisting>
5698<![CDATA[
5699 static int mychip_resume(struct pci_dev *pci)
5700 {
5701 /* (1) */
5702 struct snd_card *card = pci_get_drvdata(pci);
5703 struct mychip *chip = card->private_data;
5704 /* (2) */
5705 pci_restore_state(pci);
5706 pci_enable_device(pci);
5707 pci_set_master(pci);
5708 /* (3) */
5709 snd_mychip_reinit_chip(chip);
5710 /* (4) */
5711 snd_mychip_restore_registers(chip);
5712 /* (5) */
5713 snd_ac97_resume(chip->ac97);
5714 /* (6) */
5715 snd_mychip_restart_chip(chip);
5716 /* (7) */
5717 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5718 return 0;
5719 }
5720]]>
5721 </programlisting>
5722 </informalexample>
5723 </para>
5724
5725 <para>
5726 As shown in the above, it's better to save registers after
5727 suspending the PCM operations via
5728 <function>snd_pcm_suspend_all()</function> or
5729 <function>snd_pcm_suspend()</function>. It means that the PCM
5730 streams are already stoppped when the register snapshot is
5731 taken. But, remember that you don't have to restart the PCM
5732 stream in the resume callback. It'll be restarted via
5733 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5734 when necessary.
5735 </para>
5736
5737 <para>
5738 OK, we have all callbacks now. Let's set them up. In the
5739 initialization of the card, make sure that you can get the chip
5740 data from the card instance, typically via
5741 <structfield>private_data</structfield> field, in case you
5742 created the chip data individually.
5743
5744 <informalexample>
5745 <programlisting>
5746<![CDATA[
5747 static int __devinit snd_mychip_probe(struct pci_dev *pci,
5748 const struct pci_device_id *pci_id)
5749 {
5750 ....
5751 struct snd_card *card;
5752 struct mychip *chip;
5753 ....
5754 card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
5755 ....
5756 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5757 ....
5758 card->private_data = chip;
5759 ....
5760 }
5761]]>
5762 </programlisting>
5763 </informalexample>
5764
5765 When you created the chip data with
5766 <function>snd_card_new()</function>, it's anyway accessible
5767 via <structfield>private_data</structfield> field.
5768
5769 <informalexample>
5770 <programlisting>
5771<![CDATA[
5772 static int __devinit snd_mychip_probe(struct pci_dev *pci,
5773 const struct pci_device_id *pci_id)
5774 {
5775 ....
5776 struct snd_card *card;
5777 struct mychip *chip;
5778 ....
5779 card = snd_card_new(index[dev], id[dev], THIS_MODULE,
5780 sizeof(struct mychip));
5781 ....
5782 chip = card->private_data;
5783 ....
5784 }
5785]]>
5786 </programlisting>
5787 </informalexample>
5788
5789 </para>
5790
5791 <para>
5792 If you need a space to save the registers, allocate the
5793 buffer for it here, too, since it would be fatal
5794 if you cannot allocate a memory in the suspend phase.
5795 The allocated buffer should be released in the corresponding
5796 destructor.
5797 </para>
5798
5799 <para>
5800 And next, set suspend/resume callbacks to the pci_driver.
5801
5802 <informalexample>
5803 <programlisting>
5804<![CDATA[
5805 static struct pci_driver driver = {
5806 .name = "My Chip",
5807 .id_table = snd_my_ids,
5808 .probe = snd_my_probe,
5809 .remove = __devexit_p(snd_my_remove),
5810 #ifdef CONFIG_PM
5811 .suspend = snd_my_suspend,
5812 .resume = snd_my_resume,
5813 #endif
5814 };
5815]]>
5816 </programlisting>
5817 </informalexample>
5818 </para>
5819
5820 </chapter>
5821
5822
5823<!-- ****************************************************** -->
5824<!-- Module Parameters -->
5825<!-- ****************************************************** -->
5826 <chapter id="module-parameters">
5827 <title>Module Parameters</title>
5828 <para>
5829 There are standard module options for ALSA. At least, each
5830 module should have the <parameter>index</parameter>,
5831 <parameter>id</parameter> and <parameter>enable</parameter>
5832 options.
5833 </para>
5834
5835 <para>
5836 If the module supports multiple cards (usually up to
5837 8 = <constant>SNDRV_CARDS</constant> cards), they should be
5838 arrays. The default initial values are defined already as
5839 constants for easier programming:
5840
5841 <informalexample>
5842 <programlisting>
5843<![CDATA[
5844 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5845 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5846 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5847]]>
5848 </programlisting>
5849 </informalexample>
5850 </para>
5851
5852 <para>
5853 If the module supports only a single card, they could be single
5854 variables, instead. <parameter>enable</parameter> option is not
5855 always necessary in this case, but it would be better to have a
5856 dummy option for compatibility.
5857 </para>
5858
5859 <para>
5860 The module parameters must be declared with the standard
5861 <function>module_param()()</function>,
5862 <function>module_param_array()()</function> and
5863 <function>MODULE_PARM_DESC()</function> macros.
5864 </para>
5865
5866 <para>
5867 The typical coding would be like below:
5868
5869 <informalexample>
5870 <programlisting>
5871<![CDATA[
5872 #define CARD_NAME "My Chip"
5873
5874 module_param_array(index, int, NULL, 0444);
5875 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5876 module_param_array(id, charp, NULL, 0444);
5877 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5878 module_param_array(enable, bool, NULL, 0444);
5879 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5880]]>
5881 </programlisting>
5882 </informalexample>
5883 </para>
5884
5885 <para>
5886 Also, don't forget to define the module description, classes,
5887 license and devices. Especially, the recent modprobe requires to
5888 define the module license as GPL, etc., otherwise the system is
5889 shown as <quote>tainted</quote>.
5890
5891 <informalexample>
5892 <programlisting>
5893<![CDATA[
5894 MODULE_DESCRIPTION("My Chip");
5895 MODULE_LICENSE("GPL");
5896 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5897]]>
5898 </programlisting>
5899 </informalexample>
5900 </para>
5901
5902 </chapter>
5903
5904
5905<!-- ****************************************************** -->
5906<!-- How To Put Your Driver -->
5907<!-- ****************************************************** -->
5908 <chapter id="how-to-put-your-driver">
5909 <title>How To Put Your Driver Into ALSA Tree</title>
5910 <section>
5911 <title>General</title>
5912 <para>
5913 So far, you've learned how to write the driver codes.
5914 And you might have a question now: how to put my own
5915 driver into the ALSA driver tree?
5916 Here (finally :) the standard procedure is described briefly.
5917 </para>
5918
5919 <para>
5920 Suppose that you create a new PCI driver for the card
5921 <quote>xyz</quote>. The card module name would be
5922 snd-xyz. The new driver is usually put into the alsa-driver
5923 tree, <filename>alsa-driver/pci</filename> directory in
5924 the case of PCI cards.
5925 Then the driver is evaluated, audited and tested
5926 by developers and users. After a certain time, the driver
5927 will go to the alsa-kernel tree (to the corresponding directory,
5928 such as <filename>alsa-kernel/pci</filename>) and eventually
5929 will be integrated into the Linux 2.6 tree (the directory would be
5930 <filename>linux/sound/pci</filename>).
5931 </para>
5932
5933 <para>
5934 In the following sections, the driver code is supposed
5935 to be put into alsa-driver tree. The two cases are covered:
5936 a driver consisting of a single source file and one consisting
5937 of several source files.
5938 </para>
5939 </section>
5940
5941 <section>
5942 <title>Driver with A Single Source File</title>
5943 <para>
5944 <orderedlist>
5945 <listitem>
5946 <para>
5947 Modify alsa-driver/pci/Makefile
5948 </para>
5949
5950 <para>
5951 Suppose you have a file xyz.c. Add the following
5952 two lines
5953 <informalexample>
5954 <programlisting>
5955<![CDATA[
5956 snd-xyz-objs := xyz.o
5957 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5958]]>
5959 </programlisting>
5960 </informalexample>
5961 </para>
5962 </listitem>
5963
5964 <listitem>
5965 <para>
5966 Create the Kconfig entry
5967 </para>
5968
5969 <para>
5970 Add the new entry of Kconfig for your xyz driver.
5971 <informalexample>
5972 <programlisting>
5973<![CDATA[
5974 config SND_XYZ
5975 tristate "Foobar XYZ"
5976 depends on SND
5977 select SND_PCM
5978 help
5979 Say Y here to include support for Foobar XYZ soundcard.
5980
5981 To compile this driver as a module, choose M here: the module
5982 will be called snd-xyz.
5983]]>
5984 </programlisting>
5985 </informalexample>
5986
5987 the line, select SND_PCM, specifies that the driver xyz supports
5988 PCM. In addition to SND_PCM, the following components are
5989 supported for select command:
5990 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5991 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5992 Add the select command for each supported component.
5993 </para>
5994
5995 <para>
5996 Note that some selections imply the lowlevel selections.
5997 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5998 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5999 You don't need to give the lowlevel selections again.
6000 </para>
6001
6002 <para>
6003 For the details of Kconfig script, refer to the kbuild
6004 documentation.
6005 </para>
6006
6007 </listitem>
6008
6009 <listitem>
6010 <para>
6011 Run cvscompile script to re-generate the configure script and
6012 build the whole stuff again.
6013 </para>
6014 </listitem>
6015 </orderedlist>
6016 </para>
6017 </section>
6018
6019 <section>
6020 <title>Drivers with Several Source Files</title>
6021 <para>
6022 Suppose that the driver snd-xyz have several source files.
6023 They are located in the new subdirectory,
6024 pci/xyz.
6025
6026 <orderedlist>
6027 <listitem>
6028 <para>
6029 Add a new directory (<filename>xyz</filename>) in
6030 <filename>alsa-driver/pci/Makefile</filename> as below
6031
6032 <informalexample>
6033 <programlisting>
6034<![CDATA[
6035 obj-$(CONFIG_SND) += xyz/
6036]]>
6037 </programlisting>
6038 </informalexample>
6039 </para>
6040 </listitem>
6041
6042 <listitem>
6043 <para>
6044 Under the directory <filename>xyz</filename>, create a Makefile
6045
6046 <example>
6047 <title>Sample Makefile for a driver xyz</title>
6048 <programlisting>
6049<![CDATA[
6050 ifndef SND_TOPDIR
6051 SND_TOPDIR=../..
6052 endif
6053
6054 include $(SND_TOPDIR)/toplevel.config
6055 include $(SND_TOPDIR)/Makefile.conf
6056
6057 snd-xyz-objs := xyz.o abc.o def.o
6058
6059 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6060
6061 include $(SND_TOPDIR)/Rules.make
6062]]>
6063 </programlisting>
6064 </example>
6065 </para>
6066 </listitem>
6067
6068 <listitem>
6069 <para>
6070 Create the Kconfig entry
6071 </para>
6072
6073 <para>
6074 This procedure is as same as in the last section.
6075 </para>
6076 </listitem>
6077
6078 <listitem>
6079 <para>
6080 Run cvscompile script to re-generate the configure script and
6081 build the whole stuff again.
6082 </para>
6083 </listitem>
6084 </orderedlist>
6085 </para>
6086 </section>
6087
6088 </chapter>
6089
6090<!-- ****************************************************** -->
6091<!-- Useful Functions -->
6092<!-- ****************************************************** -->
6093 <chapter id="useful-functions">
6094 <title>Useful Functions</title>
6095
6096 <section id="useful-functions-snd-printk">
6097 <title><function>snd_printk()</function> and friends</title>
6098 <para>
6099 ALSA provides a verbose version of the
6100 <function>printk()</function> function. If a kernel config
6101 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6102 function prints the given message together with the file name
6103 and the line of the caller. The <constant>KERN_XXX</constant>
6104 prefix is processed as
6105 well as the original <function>printk()</function> does, so it's
6106 recommended to add this prefix, e.g.
6107
6108 <informalexample>
6109 <programlisting>
6110<![CDATA[
6111 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6112]]>
6113 </programlisting>
6114 </informalexample>
6115 </para>
6116
6117 <para>
6118 There are also <function>printk()</function>'s for
6119 debugging. <function>snd_printd()</function> can be used for
6120 general debugging purposes. If
6121 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6122 compiled, and works just like
6123 <function>snd_printk()</function>. If the ALSA is compiled
6124 without the debugging flag, it's ignored.
6125 </para>
6126
6127 <para>
6128 <function>snd_printdd()</function> is compiled in only when
6129 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6130 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6131 even if you configure the alsa-driver with
6132 <option>--with-debug=full</option> option. You need to give
6133 explicitly <option>--with-debug=detect</option> option instead.
6134 </para>
6135 </section>
6136
6137 <section id="useful-functions-snd-bug">
6138 <title><function>snd_BUG()</function></title>
6139 <para>
6140 It shows the <computeroutput>BUG?</computeroutput> message and
6141 stack trace as well as <function>snd_BUG_ON</function> at the point.
6142 It's useful to show that a fatal error happens there.
6143 </para>
6144 <para>
6145 When no debug flag is set, this macro is ignored.
6146 </para>
6147 </section>
6148
6149 <section id="useful-functions-snd-bug-on">
6150 <title><function>snd_BUG_ON()</function></title>
6151 <para>
6152 <function>snd_BUG_ON()</function> macro is similar with
6153 <function>WARN_ON()</function> macro. For example,
6154
6155 <informalexample>
6156 <programlisting>
6157<![CDATA[
6158 snd_BUG_ON(!pointer);
6159]]>
6160 </programlisting>
6161 </informalexample>
6162
6163 or it can be used as the condition,
6164 <informalexample>
6165 <programlisting>
6166<![CDATA[
6167 if (snd_BUG_ON(non_zero_is_bug))
6168 return -EINVAL;
6169]]>
6170 </programlisting>
6171 </informalexample>
6172
6173 </para>
6174
6175 <para>
6176 The macro takes an conditional expression to evaluate.
6177 When <constant>CONFIG_SND_DEBUG</constant>, is set, the
6178 expression is actually evaluated. If it's non-zero, it shows
6179 the warning message such as
6180 <computeroutput>BUG? (xxx)</computeroutput>
6181 normally followed by stack trace. It returns the evaluated
6182 value.
6183 When no <constant>CONFIG_SND_DEBUG</constant> is set, this
6184 macro always returns zero.
6185 </para>
6186
6187 </section>
6188
6189 </chapter>
6190
6191
6192<!-- ****************************************************** -->
6193<!-- Acknowledgments -->
6194<!-- ****************************************************** -->
6195 <chapter id="acknowledgments">
6196 <title>Acknowledgments</title>
6197 <para>
6198 I would like to thank Phil Kerr for his help for improvement and
6199 corrections of this document.
6200 </para>
6201 <para>
6202 Kevin Conder reformatted the original plain-text to the
6203 DocBook format.
6204 </para>
6205 <para>
6206 Giuliano Pochini corrected typos and contributed the example codes
6207 in the hardware constraints section.
6208 </para>
6209 </chapter>
6210</book>
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
index 46f9684d0b29..9e6763264a2e 100644
--- a/Documentation/sound/alsa/soc/dapm.txt
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -116,6 +116,9 @@ SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
116SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, 116SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
117 ARRAY_SIZE(wm8731_output_mixer_controls)), 117 ARRAY_SIZE(wm8731_output_mixer_controls)),
118 118
119If you dont want the mixer elements prefixed with the name of the mixer widget,
120you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
121as for SND_SOC_DAPM_MIXER.
119 122
1202.3 Platform/Machine domain Widgets 1232.3 Platform/Machine domain Widgets
121----------------------------------- 124-----------------------------------
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-27 13:03:59 -0500