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