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