1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <!-- ****************************************************** -->
6 <!-- Header -->
7 <!-- ****************************************************** -->
8 <book id="Writing-an-ALSA-Driver">
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 bool 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 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 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 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
496 if (err < 0)
497 return err;
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 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 cannot be used with
546 the <parameter>__init</parameter> prefix
547 because any PCI device could be a hotplug device.
548 </para>
550 <para>
551 In the <function>probe</function> callback, the following scheme is often used.
552 </para>
554 <section id="basic-flow-constructor-device-index">
555 <title>1) Check and increment the device index.</title>
556 <para>
557 <informalexample>
558 <programlisting>
559 <![CDATA[
560 static int dev;
561 ....
562 if (dev >= SNDRV_CARDS)
563 return -ENODEV;
564 if (!enable[dev]) {
565 dev++;
566 return -ENOENT;
567 }
568 ]]>
569 </programlisting>
570 </informalexample>
572 where enable[dev] is the module option.
573 </para>
575 <para>
576 Each time the <function>probe</function> callback is called, check the
577 availability of the device. If not available, simply increment
578 the device index and returns. dev will be incremented also
579 later (<link
580 linkend="basic-flow-constructor-set-pci"><citetitle>step
581 7</citetitle></link>).
582 </para>
583 </section>
585 <section id="basic-flow-constructor-create-card">
586 <title>2) Create a card instance</title>
587 <para>
588 <informalexample>
589 <programlisting>
590 <![CDATA[
591 struct snd_card *card;
592 int err;
593 ....
594 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
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 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_create()</function>.
814 <informalexample>
815 <programlisting>
816 <![CDATA[
817 struct snd_card *card;
818 int err;
819 err = snd_card_create(index, id, module, extra_size, &card);
820 ]]>
821 </programlisting>
822 </informalexample>
823 </para>
825 <para>
826 The function takes five arguments, the card-index number, the
827 id string, the module pointer (usually
828 <constant>THIS_MODULE</constant>),
829 the size of extra-data space, and the pointer to return the
830 card instance. The extra_size argument is used to
831 allocate card->private_data for the
832 chip-specific data. Note that these data
833 are allocated by <function>snd_card_create()</function>.
834 </para>
835 </section>
837 <section id="card-management-component">
838 <title>Components</title>
839 <para>
840 After the card is created, you can attach the components
841 (devices) to the card instance. In an ALSA driver, a component is
842 represented as a struct <structname>snd_device</structname> object.
843 A component can be a PCM instance, a control interface, a raw
844 MIDI interface, etc. Each such instance has one component
845 entry.
846 </para>
848 <para>
849 A component can be created via
850 <function>snd_device_new()</function> function.
852 <informalexample>
853 <programlisting>
854 <![CDATA[
855 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
856 ]]>
857 </programlisting>
858 </informalexample>
859 </para>
861 <para>
862 This takes the card pointer, the device-level
863 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
864 callback pointers (<parameter>&ops</parameter>). The
865 device-level defines the type of components and the order of
866 registration and de-registration. For most components, the
867 device-level is already defined. For a user-defined component,
868 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
869 </para>
871 <para>
872 This function itself doesn't allocate the data space. The data
873 must be allocated manually beforehand, and its pointer is passed
874 as the argument. This pointer is used as the
875 (<parameter>chip</parameter> identifier in the above example)
876 for the instance.
877 </para>
879 <para>
880 Each pre-defined ALSA component such as ac97 and pcm calls
881 <function>snd_device_new()</function> inside its
882 constructor. The destructor for each component is defined in the
883 callback pointers. Hence, you don't need to take care of
884 calling a destructor for such a component.
885 </para>
887 <para>
888 If you wish to create your own component, you need to
889 set the destructor function to the dev_free callback in
890 the <parameter>ops</parameter>, so that it can be released
891 automatically via <function>snd_card_free()</function>.
892 The next example will show an implementation of chip-specific
893 data.
894 </para>
895 </section>
897 <section id="card-management-chip-specific">
898 <title>Chip-Specific Data</title>
899 <para>
900 Chip-specific information, e.g. the I/O port address, its
901 resource pointer, or the irq number, is stored in the
902 chip-specific record.
904 <informalexample>
905 <programlisting>
906 <![CDATA[
907 struct mychip {
908 ....
909 };
910 ]]>
911 </programlisting>
912 </informalexample>
913 </para>
915 <para>
916 In general, there are two ways of allocating the chip record.
917 </para>
919 <section id="card-management-chip-specific-snd-card-new">
920 <title>1. Allocating via <function>snd_card_create()</function>.</title>
921 <para>
922 As mentioned above, you can pass the extra-data-length
923 to the 4th argument of <function>snd_card_create()</function>, i.e.
925 <informalexample>
926 <programlisting>
927 <![CDATA[
928 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
929 sizeof(struct mychip), &card);
930 ]]>
931 </programlisting>
932 </informalexample>
934 struct <structname>mychip</structname> is the type of the chip record.
935 </para>
937 <para>
938 In return, the allocated record can be accessed as
940 <informalexample>
941 <programlisting>
942 <![CDATA[
943 struct mychip *chip = card->private_data;
944 ]]>
945 </programlisting>
946 </informalexample>
948 With this method, you don't have to allocate twice.
949 The record is released together with the card instance.
950 </para>
951 </section>
953 <section id="card-management-chip-specific-allocate-extra">
954 <title>2. Allocating an extra device.</title>
956 <para>
957 After allocating a card instance via
958 <function>snd_card_create()</function> (with
959 <constant>0</constant> on the 4th arg), call
960 <function>kzalloc()</function>.
962 <informalexample>
963 <programlisting>
964 <![CDATA[
965 struct snd_card *card;
966 struct mychip *chip;
967 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
968 .....
969 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
970 ]]>
971 </programlisting>
972 </informalexample>
973 </para>
975 <para>
976 The chip record should have the field to hold the card
977 pointer at least,
979 <informalexample>
980 <programlisting>
981 <![CDATA[
982 struct mychip {
983 struct snd_card *card;
984 ....
985 };
986 ]]>
987 </programlisting>
988 </informalexample>
989 </para>
991 <para>
992 Then, set the card pointer in the returned chip instance.
994 <informalexample>
995 <programlisting>
996 <![CDATA[
997 chip->card = card;
998 ]]>
999 </programlisting>
1000 </informalexample>
1001 </para>
1003 <para>
1004 Next, initialize the fields, and register this chip
1005 record as a low-level device with a specified
1006 <parameter>ops</parameter>,
1008 <informalexample>
1009 <programlisting>
1010 <![CDATA[
1011 static struct snd_device_ops ops = {
1012 .dev_free = snd_mychip_dev_free,
1013 };
1014 ....
1015 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1016 ]]>
1017 </programlisting>
1018 </informalexample>
1020 <function>snd_mychip_dev_free()</function> is the
1021 device-destructor function, which will call the real
1022 destructor.
1023 </para>
1025 <para>
1026 <informalexample>
1027 <programlisting>
1028 <![CDATA[
1029 static int snd_mychip_dev_free(struct snd_device *device)
1030 {
1031 return snd_mychip_free(device->device_data);
1032 }
1033 ]]>
1034 </programlisting>
1035 </informalexample>
1037 where <function>snd_mychip_free()</function> is the real destructor.
1038 </para>
1039 </section>
1040 </section>
1042 <section id="card-management-registration">
1043 <title>Registration and Release</title>
1044 <para>
1045 After all components are assigned, register the card instance
1046 by calling <function>snd_card_register()</function>. Access
1047 to the device files is enabled at this point. That is, before
1048 <function>snd_card_register()</function> is called, the
1049 components are safely inaccessible from external side. If this
1050 call fails, exit the probe function after releasing the card via
1051 <function>snd_card_free()</function>.
1052 </para>
1054 <para>
1055 For releasing the card instance, you can call simply
1056 <function>snd_card_free()</function>. As mentioned earlier, all
1057 components are released automatically by this call.
1058 </para>
1060 <para>
1061 For a device which allows hotplugging, you can use
1062 <function>snd_card_free_when_closed</function>. This one will
1063 postpone the destruction until all devices are closed.
1064 </para>
1066 </section>
1068 </chapter>
1071 <!-- ****************************************************** -->
1072 <!-- PCI Resource Management -->
1073 <!-- ****************************************************** -->
1074 <chapter id="pci-resource">
1075 <title>PCI Resource Management</title>
1077 <section id="pci-resource-example">
1078 <title>Full Code Example</title>
1079 <para>
1080 In this section, we'll complete the chip-specific constructor,
1081 destructor and PCI entries. Example code is shown first,
1082 below.
1084 <example>
1085 <title>PCI Resource Management Example</title>
1086 <programlisting>
1087 <![CDATA[
1088 struct mychip {
1089 struct snd_card *card;
1090 struct pci_dev *pci;
1092 unsigned long port;
1093 int irq;
1094 };
1096 static int snd_mychip_free(struct mychip *chip)
1097 {
1098 /* disable hardware here if any */
1099 .... /* (not implemented in this document) */
1101 /* release the irq */
1102 if (chip->irq >= 0)
1103 free_irq(chip->irq, chip);
1104 /* release the I/O ports & memory */
1105 pci_release_regions(chip->pci);
1106 /* disable the PCI entry */
1107 pci_disable_device(chip->pci);
1108 /* release the data */
1109 kfree(chip);
1110 return 0;
1111 }
1113 /* chip-specific constructor */
1114 static int snd_mychip_create(struct snd_card *card,
1115 struct pci_dev *pci,
1116 struct mychip **rchip)
1117 {
1118 struct mychip *chip;
1119 int err;
1120 static struct snd_device_ops ops = {
1121 .dev_free = snd_mychip_dev_free,
1122 };
1124 *rchip = NULL;
1126 /* initialize the PCI entry */
1127 err = pci_enable_device(pci);
1128 if (err < 0)
1129 return err;
1130 /* check PCI availability (28bit DMA) */
1131 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1132 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1133 printk(KERN_ERR "error to set 28bit mask DMA\n");
1134 pci_disable_device(pci);
1135 return -ENXIO;
1136 }
1138 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
1139 if (chip == NULL) {
1140 pci_disable_device(pci);
1141 return -ENOMEM;
1142 }
1144 /* initialize the stuff */
1145 chip->card = card;
1146 chip->pci = pci;
1147 chip->irq = -1;
1149 /* (1) PCI resource allocation */
1150 err = pci_request_regions(pci, "My Chip");
1151 if (err < 0) {
1152 kfree(chip);
1153 pci_disable_device(pci);
1154 return err;
1155 }
1156 chip->port = pci_resource_start(pci, 0);
1157 if (request_irq(pci->irq, snd_mychip_interrupt,
1158 IRQF_SHARED, KBUILD_MODNAME, chip)) {
1159 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1160 snd_mychip_free(chip);
1161 return -EBUSY;
1162 }
1163 chip->irq = pci->irq;
1165 /* (2) initialization of the chip hardware */
1166 .... /* (not implemented in this document) */
1168 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1169 if (err < 0) {
1170 snd_mychip_free(chip);
1171 return err;
1172 }
1174 snd_card_set_dev(card, &pci->dev);
1176 *rchip = chip;
1177 return 0;
1178 }
1180 /* PCI IDs */
1181 static struct pci_device_id snd_mychip_ids[] = {
1182 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1183 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1184 ....
1185 { 0, }
1186 };
1187 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1189 /* pci_driver definition */
1190 static struct pci_driver driver = {
1191 .name = KBUILD_MODNAME,
1192 .id_table = snd_mychip_ids,
1193 .probe = snd_mychip_probe,
1194 .remove = snd_mychip_remove,
1195 };
1197 /* module initialization */
1198 static int __init alsa_card_mychip_init(void)
1199 {
1200 return pci_register_driver(&driver);
1201 }
1203 /* module clean up */
1204 static void __exit alsa_card_mychip_exit(void)
1205 {
1206 pci_unregister_driver(&driver);
1207 }
1209 module_init(alsa_card_mychip_init)
1210 module_exit(alsa_card_mychip_exit)
1212 EXPORT_NO_SYMBOLS; /* for old kernels only */
1213 ]]>
1214 </programlisting>
1215 </example>
1216 </para>
1217 </section>
1219 <section id="pci-resource-some-haftas">
1220 <title>Some Hafta's</title>
1221 <para>
1222 The allocation of PCI resources is done in the
1223 <function>probe()</function> function, and usually an extra
1224 <function>xxx_create()</function> function is written for this
1225 purpose.
1226 </para>
1228 <para>
1229 In the case of PCI devices, you first have to call
1230 the <function>pci_enable_device()</function> function before
1231 allocating resources. Also, you need to set the proper PCI DMA
1232 mask to limit the accessed I/O range. In some cases, you might
1233 need to call <function>pci_set_master()</function> function,
1234 too.
1235 </para>
1237 <para>
1238 Suppose the 28bit mask, and the code to be added would be like:
1240 <informalexample>
1241 <programlisting>
1242 <![CDATA[
1243 err = pci_enable_device(pci);
1244 if (err < 0)
1245 return err;
1246 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1247 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1248 printk(KERN_ERR "error to set 28bit mask DMA\n");
1249 pci_disable_device(pci);
1250 return -ENXIO;
1251 }
1253 ]]>
1254 </programlisting>
1255 </informalexample>
1256 </para>
1257 </section>
1259 <section id="pci-resource-resource-allocation">
1260 <title>Resource Allocation</title>
1261 <para>
1262 The allocation of I/O ports and irqs is done via standard kernel
1263 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1264 that. And these resources must be released in the destructor
1265 function (see below). Also, on ALSA 0.9.x, you don't need to
1266 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
1267 </para>
1269 <para>
1270 Now assume that the PCI device has an I/O port with 8 bytes
1271 and an interrupt. Then struct <structname>mychip</structname> will have the
1272 following fields:
1274 <informalexample>
1275 <programlisting>
1276 <![CDATA[
1277 struct mychip {
1278 struct snd_card *card;
1280 unsigned long port;
1281 int irq;
1282 };
1283 ]]>
1284 </programlisting>
1285 </informalexample>
1286 </para>
1288 <para>
1289 For an I/O port (and also a memory region), you need to have
1290 the resource pointer for the standard resource management. For
1291 an irq, you have to keep only the irq number (integer). But you
1292 need to initialize this number as -1 before actual allocation,
1293 since irq 0 is valid. The port address and its resource pointer
1294 can be initialized as null by
1295 <function>kzalloc()</function> automatically, so you
1296 don't have to take care of resetting them.
1297 </para>
1299 <para>
1300 The allocation of an I/O port is done like this:
1302 <informalexample>
1303 <programlisting>
1304 <![CDATA[
1305 err = pci_request_regions(pci, "My Chip");
1306 if (err < 0) {
1307 kfree(chip);
1308 pci_disable_device(pci);
1309 return err;
1310 }
1311 chip->port = pci_resource_start(pci, 0);
1312 ]]>
1313 </programlisting>
1314 </informalexample>
1315 </para>
1317 <para>
1318 <!-- obsolete -->
1319 It will reserve the I/O port region of 8 bytes of the given
1320 PCI device. The returned value, chip->res_port, is allocated
1321 via <function>kmalloc()</function> by
1322 <function>request_region()</function>. The pointer must be
1323 released via <function>kfree()</function>, but there is a
1324 problem with this. This issue will be explained later.
1325 </para>
1327 <para>
1328 The allocation of an interrupt source is done like this:
1330 <informalexample>
1331 <programlisting>
1332 <![CDATA[
1333 if (request_irq(pci->irq, snd_mychip_interrupt,
1334 IRQF_SHARED, KBUILD_MODNAME, chip)) {
1335 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1336 snd_mychip_free(chip);
1337 return -EBUSY;
1338 }
1339 chip->irq = pci->irq;
1340 ]]>
1341 </programlisting>
1342 </informalexample>
1344 where <function>snd_mychip_interrupt()</function> is the
1345 interrupt handler defined <link
1346 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1347 Note that chip->irq should be defined
1348 only when <function>request_irq()</function> succeeded.
1349 </para>
1351 <para>
1352 On the PCI bus, interrupts can be shared. Thus,
1353 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
1354 <function>request_irq()</function>.
1355 </para>
1357 <para>
1358 The last argument of <function>request_irq()</function> is the
1359 data pointer passed to the interrupt handler. Usually, the
1360 chip-specific record is used for that, but you can use what you
1361 like, too.
1362 </para>
1364 <para>
1365 I won't give details about the interrupt handler at this
1366 point, but at least its appearance can be explained now. The
1367 interrupt handler looks usually like the following:
1369 <informalexample>
1370 <programlisting>
1371 <![CDATA[
1372 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
1373 {
1374 struct mychip *chip = dev_id;
1375 ....
1376 return IRQ_HANDLED;
1377 }
1378 ]]>
1379 </programlisting>
1380 </informalexample>
1381 </para>
1383 <para>
1384 Now let's write the corresponding destructor for the resources
1385 above. The role of destructor is simple: disable the hardware
1386 (if already activated) and release the resources. So far, we
1387 have no hardware part, so the disabling code is not written here.
1388 </para>
1390 <para>
1391 To release the resources, the <quote>check-and-release</quote>
1392 method is a safer way. For the interrupt, do like this:
1394 <informalexample>
1395 <programlisting>
1396 <![CDATA[
1397 if (chip->irq >= 0)
1398 free_irq(chip->irq, chip);
1399 ]]>
1400 </programlisting>
1401 </informalexample>
1403 Since the irq number can start from 0, you should initialize
1404 chip->irq with a negative value (e.g. -1), so that you can
1405 check the validity of the irq number as above.
1406 </para>
1408 <para>
1409 When you requested I/O ports or memory regions via
1410 <function>pci_request_region()</function> or
1411 <function>pci_request_regions()</function> like in this example,
1412 release the resource(s) using the corresponding function,
1413 <function>pci_release_region()</function> or
1414 <function>pci_release_regions()</function>.
1416 <informalexample>
1417 <programlisting>
1418 <![CDATA[
1419 pci_release_regions(chip->pci);
1420 ]]>
1421 </programlisting>
1422 </informalexample>
1423 </para>
1425 <para>
1426 When you requested manually via <function>request_region()</function>
1427 or <function>request_mem_region</function>, you can release it via
1428 <function>release_resource()</function>. Suppose that you keep
1429 the resource pointer returned from <function>request_region()</function>
1430 in chip->res_port, the release procedure looks like:
1432 <informalexample>
1433 <programlisting>
1434 <![CDATA[
1435 release_and_free_resource(chip->res_port);
1436 ]]>
1437 </programlisting>
1438 </informalexample>
1439 </para>
1441 <para>
1442 Don't forget to call <function>pci_disable_device()</function>
1443 before the end.
1444 </para>
1446 <para>
1447 And finally, release the chip-specific record.
1449 <informalexample>
1450 <programlisting>
1451 <![CDATA[
1452 kfree(chip);
1453 ]]>
1454 </programlisting>
1455 </informalexample>
1456 </para>
1458 <para>
1459 We didn't implement the hardware disabling part in the above.
1460 If you need to do this, please note that the destructor may be
1461 called even before the initialization of the chip is completed.
1462 It would be better to have a flag to skip hardware disabling
1463 if the hardware was not initialized yet.
1464 </para>
1466 <para>
1467 When the chip-data is assigned to the card using
1468 <function>snd_device_new()</function> with
1469 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1470 called at the last. That is, it is assured that all other
1471 components like PCMs and controls have already been released.
1472 You don't have to stop PCMs, etc. explicitly, but just
1473 call low-level hardware stopping.
1474 </para>
1476 <para>
1477 The management of a memory-mapped region is almost as same as
1478 the management of an I/O port. You'll need three fields like
1479 the following:
1481 <informalexample>
1482 <programlisting>
1483 <![CDATA[
1484 struct mychip {
1485 ....
1486 unsigned long iobase_phys;
1487 void __iomem *iobase_virt;
1488 };
1489 ]]>
1490 </programlisting>
1491 </informalexample>
1493 and the allocation would be like below:
1495 <informalexample>
1496 <programlisting>
1497 <![CDATA[
1498 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1499 kfree(chip);
1500 return err;
1501 }
1502 chip->iobase_phys = pci_resource_start(pci, 0);
1503 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1504 pci_resource_len(pci, 0));
1505 ]]>
1506 </programlisting>
1507 </informalexample>
1509 and the corresponding destructor would be:
1511 <informalexample>
1512 <programlisting>
1513 <![CDATA[
1514 static int snd_mychip_free(struct mychip *chip)
1515 {
1516 ....
1517 if (chip->iobase_virt)
1518 iounmap(chip->iobase_virt);
1519 ....
1520 pci_release_regions(chip->pci);
1521 ....
1522 }
1523 ]]>
1524 </programlisting>
1525 </informalexample>
1526 </para>
1528 </section>
1530 <section id="pci-resource-device-struct">
1531 <title>Registration of Device Struct</title>
1532 <para>
1533 At some point, typically after calling <function>snd_device_new()</function>,
1534 you need to register the struct <structname>device</structname> of the chip
1535 you're handling for udev and co. ALSA provides a macro for compatibility with
1536 older kernels. Simply call like the following:
1537 <informalexample>
1538 <programlisting>
1539 <![CDATA[
1540 snd_card_set_dev(card, &pci->dev);
1541 ]]>
1542 </programlisting>
1543 </informalexample>
1544 so that it stores the PCI's device pointer to the card. This will be
1545 referred by ALSA core functions later when the devices are registered.
1546 </para>
1547 <para>
1548 In the case of non-PCI, pass the proper device struct pointer of the BUS
1549 instead. (In the case of legacy ISA without PnP, you don't have to do
1550 anything.)
1551 </para>
1552 </section>
1554 <section id="pci-resource-entries">
1555 <title>PCI Entries</title>
1556 <para>
1557 So far, so good. Let's finish the missing PCI
1558 stuff. At first, we need a
1559 <structname>pci_device_id</structname> table for this
1560 chipset. It's a table of PCI vendor/device ID number, and some
1561 masks.
1562 </para>
1564 <para>
1565 For example,
1567 <informalexample>
1568 <programlisting>
1569 <![CDATA[
1570 static struct pci_device_id snd_mychip_ids[] = {
1571 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1572 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1573 ....
1574 { 0, }
1575 };
1576 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1577 ]]>
1578 </programlisting>
1579 </informalexample>
1580 </para>
1582 <para>
1583 The first and second fields of
1584 the <structname>pci_device_id</structname> structure are the vendor and
1585 device IDs. If you have no reason to filter the matching
1586 devices, you can leave the remaining fields as above. The last
1587 field of the <structname>pci_device_id</structname> struct contains
1588 private data for this entry. You can specify any value here, for
1589 example, to define specific operations for supported device IDs.
1590 Such an example is found in the intel8x0 driver.
1591 </para>
1593 <para>
1594 The last entry of this list is the terminator. You must
1595 specify this all-zero entry.
1596 </para>
1598 <para>
1599 Then, prepare the <structname>pci_driver</structname> record:
1601 <informalexample>
1602 <programlisting>
1603 <![CDATA[
1604 static struct pci_driver driver = {
1605 .name = KBUILD_MODNAME,
1606 .id_table = snd_mychip_ids,
1607 .probe = snd_mychip_probe,
1608 .remove = snd_mychip_remove,
1609 };
1610 ]]>
1611 </programlisting>
1612 </informalexample>
1613 </para>
1615 <para>
1616 The <structfield>probe</structfield> and
1617 <structfield>remove</structfield> functions have already
1618 been defined in the previous sections.
1619 The <structfield>name</structfield>
1620 field is the name string of this device. Note that you must not
1621 use a slash <quote>/</quote> in this string.
1622 </para>
1624 <para>
1625 And at last, the module entries:
1627 <informalexample>
1628 <programlisting>
1629 <![CDATA[
1630 static int __init alsa_card_mychip_init(void)
1631 {
1632 return pci_register_driver(&driver);
1633 }
1635 static void __exit alsa_card_mychip_exit(void)
1636 {
1637 pci_unregister_driver(&driver);
1638 }
1640 module_init(alsa_card_mychip_init)
1641 module_exit(alsa_card_mychip_exit)
1642 ]]>
1643 </programlisting>
1644 </informalexample>
1645 </para>
1647 <para>
1648 Note that these module entries are tagged with
1649 <parameter>__init</parameter> and
1650 <parameter>__exit</parameter> prefixes.
1651 </para>
1653 <para>
1654 Oh, one thing was forgotten. If you have no exported symbols,
1655 you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1657 <informalexample>
1658 <programlisting>
1659 <![CDATA[
1660 EXPORT_NO_SYMBOLS;
1661 ]]>
1662 </programlisting>
1663 </informalexample>
1665 That's all!
1666 </para>
1667 </section>
1668 </chapter>
1671 <!-- ****************************************************** -->
1672 <!-- PCM Interface -->
1673 <!-- ****************************************************** -->
1674 <chapter id="pcm-interface">
1675 <title>PCM Interface</title>
1677 <section id="pcm-interface-general">
1678 <title>General</title>
1679 <para>
1680 The PCM middle layer of ALSA is quite powerful and it is only
1681 necessary for each driver to implement the low-level functions
1682 to access its hardware.
1683 </para>
1685 <para>
1686 For accessing to the PCM layer, you need to include
1687 <filename><sound/pcm.h></filename> first. In addition,
1688 <filename><sound/pcm_params.h></filename> might be needed
1689 if you access to some functions related with hw_param.
1690 </para>
1692 <para>
1693 Each card device can have up to four pcm instances. A pcm
1694 instance corresponds to a pcm device file. The limitation of
1695 number of instances comes only from the available bit size of
1696 the Linux's device numbers. Once when 64bit device number is
1697 used, we'll have more pcm instances available.
1698 </para>
1700 <para>
1701 A pcm instance consists of pcm playback and capture streams,
1702 and each pcm stream consists of one or more pcm substreams. Some
1703 soundcards support multiple playback functions. For example,
1704 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1705 each open, a free substream is (usually) automatically chosen
1706 and opened. Meanwhile, when only one substream exists and it was
1707 already opened, the successful open will either block
1708 or error with <constant>EAGAIN</constant> according to the
1709 file open mode. But you don't have to care about such details in your
1710 driver. The PCM middle layer will take care of such work.
1711 </para>
1712 </section>
1714 <section id="pcm-interface-example">
1715 <title>Full Code Example</title>
1716 <para>
1717 The example code below does not include any hardware access
1718 routines but shows only the skeleton, how to build up the PCM
1719 interfaces.
1721 <example>
1722 <title>PCM Example Code</title>
1723 <programlisting>
1724 <![CDATA[
1725 #include <sound/pcm.h>
1726 ....
1728 /* hardware definition */
1729 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1730 .info = (SNDRV_PCM_INFO_MMAP |
1731 SNDRV_PCM_INFO_INTERLEAVED |
1732 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1733 SNDRV_PCM_INFO_MMAP_VALID),
1734 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1735 .rates = SNDRV_PCM_RATE_8000_48000,
1736 .rate_min = 8000,
1737 .rate_max = 48000,
1738 .channels_min = 2,
1739 .channels_max = 2,
1740 .buffer_bytes_max = 32768,
1741 .period_bytes_min = 4096,
1742 .period_bytes_max = 32768,
1743 .periods_min = 1,
1744 .periods_max = 1024,
1745 };
1747 /* hardware definition */
1748 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1749 .info = (SNDRV_PCM_INFO_MMAP |
1750 SNDRV_PCM_INFO_INTERLEAVED |
1751 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1752 SNDRV_PCM_INFO_MMAP_VALID),
1753 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1754 .rates = SNDRV_PCM_RATE_8000_48000,
1755 .rate_min = 8000,
1756 .rate_max = 48000,
1757 .channels_min = 2,
1758 .channels_max = 2,
1759 .buffer_bytes_max = 32768,
1760 .period_bytes_min = 4096,
1761 .period_bytes_max = 32768,
1762 .periods_min = 1,
1763 .periods_max = 1024,
1764 };
1766 /* open callback */
1767 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1768 {
1769 struct mychip *chip = snd_pcm_substream_chip(substream);
1770 struct snd_pcm_runtime *runtime = substream->runtime;
1772 runtime->hw = snd_mychip_playback_hw;
1773 /* more hardware-initialization will be done here */
1774 ....
1775 return 0;
1776 }
1778 /* close callback */
1779 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1780 {
1781 struct mychip *chip = snd_pcm_substream_chip(substream);
1782 /* the hardware-specific codes will be here */
1783 ....
1784 return 0;
1786 }
1788 /* open callback */
1789 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1790 {
1791 struct mychip *chip = snd_pcm_substream_chip(substream);
1792 struct snd_pcm_runtime *runtime = substream->runtime;
1794 runtime->hw = snd_mychip_capture_hw;
1795 /* more hardware-initialization will be done here */
1796 ....
1797 return 0;
1798 }
1800 /* close callback */
1801 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1802 {
1803 struct mychip *chip = snd_pcm_substream_chip(substream);
1804 /* the hardware-specific codes will be here */
1805 ....
1806 return 0;
1808 }
1810 /* hw_params callback */
1811 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1812 struct snd_pcm_hw_params *hw_params)
1813 {
1814 return snd_pcm_lib_malloc_pages(substream,
1815 params_buffer_bytes(hw_params));
1816 }
1818 /* hw_free callback */
1819 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1820 {
1821 return snd_pcm_lib_free_pages(substream);
1822 }
1824 /* prepare callback */
1825 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1826 {
1827 struct mychip *chip = snd_pcm_substream_chip(substream);
1828 struct snd_pcm_runtime *runtime = substream->runtime;
1830 /* set up the hardware with the current configuration
1831 * for example...
1832 */
1833 mychip_set_sample_format(chip, runtime->format);
1834 mychip_set_sample_rate(chip, runtime->rate);
1835 mychip_set_channels(chip, runtime->channels);
1836 mychip_set_dma_setup(chip, runtime->dma_addr,
1837 chip->buffer_size,
1838 chip->period_size);
1839 return 0;
1840 }
1842 /* trigger callback */
1843 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1844 int cmd)
1845 {
1846 switch (cmd) {
1847 case SNDRV_PCM_TRIGGER_START:
1848 /* do something to start the PCM engine */
1849 ....
1850 break;
1851 case SNDRV_PCM_TRIGGER_STOP:
1852 /* do something to stop the PCM engine */
1853 ....
1854 break;
1855 default:
1856 return -EINVAL;
1857 }
1858 }
1860 /* pointer callback */
1861 static snd_pcm_uframes_t
1862 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1863 {
1864 struct mychip *chip = snd_pcm_substream_chip(substream);
1865 unsigned int current_ptr;
1867 /* get the current hardware pointer */
1868 current_ptr = mychip_get_hw_pointer(chip);
1869 return current_ptr;
1870 }
1872 /* operators */
1873 static struct snd_pcm_ops snd_mychip_playback_ops = {
1874 .open = snd_mychip_playback_open,
1875 .close = snd_mychip_playback_close,
1876 .ioctl = snd_pcm_lib_ioctl,
1877 .hw_params = snd_mychip_pcm_hw_params,
1878 .hw_free = snd_mychip_pcm_hw_free,
1879 .prepare = snd_mychip_pcm_prepare,
1880 .trigger = snd_mychip_pcm_trigger,
1881 .pointer = snd_mychip_pcm_pointer,
1882 };
1884 /* operators */
1885 static struct snd_pcm_ops snd_mychip_capture_ops = {
1886 .open = snd_mychip_capture_open,
1887 .close = snd_mychip_capture_close,
1888 .ioctl = snd_pcm_lib_ioctl,
1889 .hw_params = snd_mychip_pcm_hw_params,
1890 .hw_free = snd_mychip_pcm_hw_free,
1891 .prepare = snd_mychip_pcm_prepare,
1892 .trigger = snd_mychip_pcm_trigger,
1893 .pointer = snd_mychip_pcm_pointer,
1894 };
1896 /*
1897 * definitions of capture are omitted here...
1898 */
1900 /* create a pcm device */
1901 static int snd_mychip_new_pcm(struct mychip *chip)
1902 {
1903 struct snd_pcm *pcm;
1904 int err;
1906 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1907 if (err < 0)
1908 return err;
1909 pcm->private_data = chip;
1910 strcpy(pcm->name, "My Chip");
1911 chip->pcm = pcm;
1912 /* set operators */
1913 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1914 &snd_mychip_playback_ops);
1915 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1916 &snd_mychip_capture_ops);
1917 /* pre-allocation of buffers */
1918 /* NOTE: this may fail */
1919 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1920 snd_dma_pci_data(chip->pci),
1921 64*1024, 64*1024);
1922 return 0;
1923 }
1924 ]]>
1925 </programlisting>
1926 </example>
1927 </para>
1928 </section>
1930 <section id="pcm-interface-constructor">
1931 <title>Constructor</title>
1932 <para>
1933 A pcm instance is allocated by the <function>snd_pcm_new()</function>
1934 function. It would be better to create a constructor for pcm,
1935 namely,
1937 <informalexample>
1938 <programlisting>
1939 <![CDATA[
1940 static int snd_mychip_new_pcm(struct mychip *chip)
1941 {
1942 struct snd_pcm *pcm;
1943 int err;
1945 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1946 if (err < 0)
1947 return err;
1948 pcm->private_data = chip;
1949 strcpy(pcm->name, "My Chip");
1950 chip->pcm = pcm;
1951 ....
1952 return 0;
1953 }
1954 ]]>
1955 </programlisting>
1956 </informalexample>
1957 </para>
1959 <para>
1960 The <function>snd_pcm_new()</function> function takes four
1961 arguments. The first argument is the card pointer to which this
1962 pcm is assigned, and the second is the ID string.
1963 </para>
1965 <para>
1966 The third argument (<parameter>index</parameter>, 0 in the
1967 above) is the index of this new pcm. It begins from zero. If
1968 you create more than one pcm instances, specify the
1969 different numbers in this argument. For example,
1970 <parameter>index</parameter> = 1 for the second PCM device.
1971 </para>
1973 <para>
1974 The fourth and fifth arguments are the number of substreams
1975 for playback and capture, respectively. Here 1 is used for
1976 both arguments. When no playback or capture substreams are available,
1977 pass 0 to the corresponding argument.
1978 </para>
1980 <para>
1981 If a chip supports multiple playbacks or captures, you can
1982 specify more numbers, but they must be handled properly in
1983 open/close, etc. callbacks. When you need to know which
1984 substream you are referring to, then it can be obtained from
1985 struct <structname>snd_pcm_substream</structname> data passed to each callback
1986 as follows:
1988 <informalexample>
1989 <programlisting>
1990 <![CDATA[
1991 struct snd_pcm_substream *substream;
1992 int index = substream->number;
1993 ]]>
1994 </programlisting>
1995 </informalexample>
1996 </para>
1998 <para>
1999 After the pcm is created, you need to set operators for each
2000 pcm stream.
2002 <informalexample>
2003 <programlisting>
2004 <![CDATA[
2005 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
2006 &snd_mychip_playback_ops);
2007 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
2008 &snd_mychip_capture_ops);
2009 ]]>
2010 </programlisting>
2011 </informalexample>
2012 </para>
2014 <para>
2015 The operators are defined typically like this:
2017 <informalexample>
2018 <programlisting>
2019 <![CDATA[
2020 static struct snd_pcm_ops snd_mychip_playback_ops = {
2021 .open = snd_mychip_pcm_open,
2022 .close = snd_mychip_pcm_close,
2023 .ioctl = snd_pcm_lib_ioctl,
2024 .hw_params = snd_mychip_pcm_hw_params,
2025 .hw_free = snd_mychip_pcm_hw_free,
2026 .prepare = snd_mychip_pcm_prepare,
2027 .trigger = snd_mychip_pcm_trigger,
2028 .pointer = snd_mychip_pcm_pointer,
2029 };
2030 ]]>
2031 </programlisting>
2032 </informalexample>
2034 All the callbacks are described in the
2035 <link linkend="pcm-interface-operators"><citetitle>
2036 Operators</citetitle></link> subsection.
2037 </para>
2039 <para>
2040 After setting the operators, you probably will want to
2041 pre-allocate the buffer. For the pre-allocation, simply call
2042 the following:
2044 <informalexample>
2045 <programlisting>
2046 <![CDATA[
2047 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2048 snd_dma_pci_data(chip->pci),
2049 64*1024, 64*1024);
2050 ]]>
2051 </programlisting>
2052 </informalexample>
2054 It will allocate a buffer up to 64kB as default.
2055 Buffer management details will be described in the later section <link
2056 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2057 Management</citetitle></link>.
2058 </para>
2060 <para>
2061 Additionally, you can set some extra information for this pcm
2062 in pcm->info_flags.
2063 The available values are defined as
2064 <constant>SNDRV_PCM_INFO_XXX</constant> in
2065 <filename><sound/asound.h></filename>, which is used for
2066 the hardware definition (described later). When your soundchip
2067 supports only half-duplex, specify like this:
2069 <informalexample>
2070 <programlisting>
2071 <![CDATA[
2072 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2073 ]]>
2074 </programlisting>
2075 </informalexample>
2076 </para>
2077 </section>
2079 <section id="pcm-interface-destructor">
2080 <title>... And the Destructor?</title>
2081 <para>
2082 The destructor for a pcm instance is not always
2083 necessary. Since the pcm device will be released by the middle
2084 layer code automatically, you don't have to call the destructor
2085 explicitly.
2086 </para>
2088 <para>
2089 The destructor would be necessary if you created
2090 special records internally and needed to release them. In such a
2091 case, set the destructor function to
2092 pcm->private_free:
2094 <example>
2095 <title>PCM Instance with a Destructor</title>
2096 <programlisting>
2097 <![CDATA[
2098 static void mychip_pcm_free(struct snd_pcm *pcm)
2099 {
2100 struct mychip *chip = snd_pcm_chip(pcm);
2101 /* free your own data */
2102 kfree(chip->my_private_pcm_data);
2103 /* do what you like else */
2104 ....
2105 }
2107 static int snd_mychip_new_pcm(struct mychip *chip)
2108 {
2109 struct snd_pcm *pcm;
2110 ....
2111 /* allocate your own data */
2112 chip->my_private_pcm_data = kmalloc(...);
2113 /* set the destructor */
2114 pcm->private_data = chip;
2115 pcm->private_free = mychip_pcm_free;
2116 ....
2117 }
2118 ]]>
2119 </programlisting>
2120 </example>
2121 </para>
2122 </section>
2124 <section id="pcm-interface-runtime">
2125 <title>Runtime Pointer - The Chest of PCM Information</title>
2126 <para>
2127 When the PCM substream is opened, a PCM runtime instance is
2128 allocated and assigned to the substream. This pointer is
2129 accessible via <constant>substream->runtime</constant>.
2130 This runtime pointer holds most information you need
2131 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2132 pointers, mmap records, spinlocks, etc.
2133 </para>
2135 <para>
2136 The definition of runtime instance is found in
2137 <filename><sound/pcm.h></filename>. Here are
2138 the contents of this file:
2139 <informalexample>
2140 <programlisting>
2141 <![CDATA[
2142 struct _snd_pcm_runtime {
2143 /* -- Status -- */
2144 struct snd_pcm_substream *trigger_master;
2145 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2146 int overrange;
2147 snd_pcm_uframes_t avail_max;
2148 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2149 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2151 /* -- HW params -- */
2152 snd_pcm_access_t access; /* access mode */
2153 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2154 snd_pcm_subformat_t subformat; /* subformat */
2155 unsigned int rate; /* rate in Hz */
2156 unsigned int channels; /* channels */
2157 snd_pcm_uframes_t period_size; /* period size */
2158 unsigned int periods; /* periods */
2159 snd_pcm_uframes_t buffer_size; /* buffer size */
2160 unsigned int tick_time; /* tick time */
2161 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2162 size_t byte_align;
2163 unsigned int frame_bits;
2164 unsigned int sample_bits;
2165 unsigned int info;
2166 unsigned int rate_num;
2167 unsigned int rate_den;
2169 /* -- SW params -- */
2170 struct timespec tstamp_mode; /* mmap timestamp is updated */
2171 unsigned int period_step;
2172 unsigned int sleep_min; /* min ticks to sleep */
2173 snd_pcm_uframes_t start_threshold;
2174 snd_pcm_uframes_t stop_threshold;
2175 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2176 noise is nearest than this */
2177 snd_pcm_uframes_t silence_size; /* Silence filling size */
2178 snd_pcm_uframes_t boundary; /* pointers wrap point */
2180 snd_pcm_uframes_t silenced_start;
2181 snd_pcm_uframes_t silenced_size;
2183 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2185 /* -- mmap -- */
2186 volatile struct snd_pcm_mmap_status *status;
2187 volatile struct snd_pcm_mmap_control *control;
2188 atomic_t mmap_count;
2190 /* -- locking / scheduling -- */
2191 spinlock_t lock;
2192 wait_queue_head_t sleep;
2193 struct timer_list tick_timer;
2194 struct fasync_struct *fasync;
2196 /* -- private section -- */
2197 void *private_data;
2198 void (*private_free)(struct snd_pcm_runtime *runtime);
2200 /* -- hardware description -- */
2201 struct snd_pcm_hardware hw;
2202 struct snd_pcm_hw_constraints hw_constraints;
2204 /* -- interrupt callbacks -- */
2205 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2206 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
2208 /* -- timer -- */
2209 unsigned int timer_resolution; /* timer resolution */
2211 /* -- DMA -- */
2212 unsigned char *dma_area; /* DMA area */
2213 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2214 size_t dma_bytes; /* size of DMA area */
2216 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2218 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2219 /* -- OSS things -- */
2220 struct snd_pcm_oss_runtime oss;
2221 #endif
2222 };
2223 ]]>
2224 </programlisting>
2225 </informalexample>
2226 </para>
2228 <para>
2229 For the operators (callbacks) of each sound driver, most of
2230 these records are supposed to be read-only. Only the PCM
2231 middle-layer changes / updates them. The exceptions are
2232 the hardware description (hw), interrupt callbacks
2233 (transfer_ack_xxx), DMA buffer information, and the private
2234 data. Besides, if you use the standard buffer allocation
2235 method via <function>snd_pcm_lib_malloc_pages()</function>,
2236 you don't need to set the DMA buffer information by yourself.
2237 </para>
2239 <para>
2240 In the sections below, important records are explained.
2241 </para>
2243 <section id="pcm-interface-runtime-hw">
2244 <title>Hardware Description</title>
2245 <para>
2246 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
2247 contains the definitions of the fundamental hardware
2248 configuration. Above all, you'll need to define this in
2249 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2250 the open callback</citetitle></link>.
2251 Note that the runtime instance holds the copy of the
2252 descriptor, not the pointer to the existing descriptor. That
2253 is, in the open callback, you can modify the copied descriptor
2254 (<constant>runtime->hw</constant>) as you need. For example, if the maximum
2255 number of channels is 1 only on some chip models, you can
2256 still use the same hardware descriptor and change the
2257 channels_max later:
2258 <informalexample>
2259 <programlisting>
2260 <![CDATA[
2261 struct snd_pcm_runtime *runtime = substream->runtime;
2262 ...
2263 runtime->hw = snd_mychip_playback_hw; /* common definition */
2264 if (chip->model == VERY_OLD_ONE)
2265 runtime->hw.channels_max = 1;
2266 ]]>
2267 </programlisting>
2268 </informalexample>
2269 </para>
2271 <para>
2272 Typically, you'll have a hardware descriptor as below:
2273 <informalexample>
2274 <programlisting>
2275 <![CDATA[
2276 static struct snd_pcm_hardware snd_mychip_playback_hw = {
2277 .info = (SNDRV_PCM_INFO_MMAP |
2278 SNDRV_PCM_INFO_INTERLEAVED |
2279 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2280 SNDRV_PCM_INFO_MMAP_VALID),
2281 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2282 .rates = SNDRV_PCM_RATE_8000_48000,
2283 .rate_min = 8000,
2284 .rate_max = 48000,
2285 .channels_min = 2,
2286 .channels_max = 2,
2287 .buffer_bytes_max = 32768,
2288 .period_bytes_min = 4096,
2289 .period_bytes_max = 32768,
2290 .periods_min = 1,
2291 .periods_max = 1024,
2292 };
2293 ]]>
2294 </programlisting>
2295 </informalexample>
2296 </para>
2298 <para>
2299 <itemizedlist>
2300 <listitem><para>
2301 The <structfield>info</structfield> field contains the type and
2302 capabilities of this pcm. The bit flags are defined in
2303 <filename><sound/asound.h></filename> as
2304 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2305 have to specify whether the mmap is supported and which
2306 interleaved format is supported.
2307 When the is supported, add the
2308 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2309 hardware supports the interleaved or the non-interleaved
2310 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2311 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2312 be set, respectively. If both are supported, you can set both,
2313 too.
2314 </para>
2316 <para>
2317 In the above example, <constant>MMAP_VALID</constant> and
2318 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
2319 mode. Usually both are set. Of course,
2320 <constant>MMAP_VALID</constant> is set only if the mmap is
2321 really supported.
2322 </para>
2324 <para>
2325 The other possible flags are
2326 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2327 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2328 <constant>PAUSE</constant> bit means that the pcm supports the
2329 <quote>pause</quote> operation, while the
2330 <constant>RESUME</constant> bit means that the pcm supports
2331 the full <quote>suspend/resume</quote> operation.
2332 If the <constant>PAUSE</constant> flag is set,
2333 the <structfield>trigger</structfield> callback below
2334 must handle the corresponding (pause push/release) commands.
2335 The suspend/resume trigger commands can be defined even without
2336 the <constant>RESUME</constant> flag. See <link
2337 linkend="power-management"><citetitle>
2338 Power Management</citetitle></link> section for details.
2339 </para>
2341 <para>
2342 When the PCM substreams can be synchronized (typically,
2343 synchronized start/stop of a playback and a capture streams),
2344 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2345 too. In this case, you'll need to check the linked-list of
2346 PCM substreams in the trigger callback. This will be
2347 described in the later section.
2348 </para>
2349 </listitem>
2351 <listitem>
2352 <para>
2353 <structfield>formats</structfield> field contains the bit-flags
2354 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2355 If the hardware supports more than one format, give all or'ed
2356 bits. In the example above, the signed 16bit little-endian
2357 format is specified.
2358 </para>
2359 </listitem>
2361 <listitem>
2362 <para>
2363 <structfield>rates</structfield> field contains the bit-flags of
2364 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2365 When the chip supports continuous rates, pass
2366 <constant>CONTINUOUS</constant> bit additionally.
2367 The pre-defined rate bits are provided only for typical
2368 rates. If your chip supports unconventional rates, you need to add
2369 the <constant>KNOT</constant> bit and set up the hardware
2370 constraint manually (explained later).
2371 </para>
2372 </listitem>
2374 <listitem>
2375 <para>
2376 <structfield>rate_min</structfield> and
2377 <structfield>rate_max</structfield> define the minimum and
2378 maximum sample rate. This should correspond somehow to
2379 <structfield>rates</structfield> bits.
2380 </para>
2381 </listitem>
2383 <listitem>
2384 <para>
2385 <structfield>channel_min</structfield> and
2386 <structfield>channel_max</structfield>
2387 define, as you might already expected, the minimum and maximum
2388 number of channels.
2389 </para>
2390 </listitem>
2392 <listitem>
2393 <para>
2394 <structfield>buffer_bytes_max</structfield> defines the
2395 maximum buffer size in bytes. There is no
2396 <structfield>buffer_bytes_min</structfield> field, since
2397 it can be calculated from the minimum period size and the
2398 minimum number of periods.
2399 Meanwhile, <structfield>period_bytes_min</structfield> and
2400 define the minimum and maximum size of the period in bytes.
2401 <structfield>periods_max</structfield> and
2402 <structfield>periods_min</structfield> define the maximum and
2403 minimum number of periods in the buffer.
2404 </para>
2406 <para>
2407 The <quote>period</quote> is a term that corresponds to
2408 a fragment in the OSS world. The period defines the size at
2409 which a PCM interrupt is generated. This size strongly
2410 depends on the hardware.
2411 Generally, the smaller period size will give you more
2412 interrupts, that is, more controls.
2413 In the case of capture, this size defines the input latency.
2414 On the other hand, the whole buffer size defines the
2415 output latency for the playback direction.
2416 </para>
2417 </listitem>
2419 <listitem>
2420 <para>
2421 There is also a field <structfield>fifo_size</structfield>.
2422 This specifies the size of the hardware FIFO, but currently it
2423 is neither used in the driver nor in the alsa-lib. So, you
2424 can ignore this field.
2425 </para>
2426 </listitem>
2427 </itemizedlist>
2428 </para>
2429 </section>
2431 <section id="pcm-interface-runtime-config">
2432 <title>PCM Configurations</title>
2433 <para>
2434 Ok, let's go back again to the PCM runtime records.
2435 The most frequently referred records in the runtime instance are
2436 the PCM configurations.
2437 The PCM configurations are stored in the runtime instance
2438 after the application sends <type>hw_params</type> data via
2439 alsa-lib. There are many fields copied from hw_params and
2440 sw_params structs. For example,
2441 <structfield>format</structfield> holds the format type
2442 chosen by the application. This field contains the enum value
2443 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2444 </para>
2446 <para>
2447 One thing to be noted is that the configured buffer and period
2448 sizes are stored in <quote>frames</quote> in the runtime.
2449 In the ALSA world, 1 frame = channels * samples-size.
2450 For conversion between frames and bytes, you can use the
2451 <function>frames_to_bytes()</function> and
2452 <function>bytes_to_frames()</function> helper functions.
2453 <informalexample>
2454 <programlisting>
2455 <![CDATA[
2456 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2457 ]]>
2458 </programlisting>
2459 </informalexample>
2460 </para>
2462 <para>
2463 Also, many software parameters (sw_params) are
2464 stored in frames, too. Please check the type of the field.
2465 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2466 integer while <type>snd_pcm_sframes_t</type> is for the frames
2467 as signed integer.
2468 </para>
2469 </section>
2471 <section id="pcm-interface-runtime-dma">
2472 <title>DMA Buffer Information</title>
2473 <para>
2474 The DMA buffer is defined by the following four fields,
2475 <structfield>dma_area</structfield>,
2476 <structfield>dma_addr</structfield>,
2477 <structfield>dma_bytes</structfield> and
2478 <structfield>dma_private</structfield>.
2479 The <structfield>dma_area</structfield> holds the buffer
2480 pointer (the logical address). You can call
2481 <function>memcpy</function> from/to
2482 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2483 holds the physical address of the buffer. This field is
2484 specified only when the buffer is a linear buffer.
2485 <structfield>dma_bytes</structfield> holds the size of buffer
2486 in bytes. <structfield>dma_private</structfield> is used for
2487 the ALSA DMA allocator.
2488 </para>
2490 <para>
2491 If you use a standard ALSA function,
2492 <function>snd_pcm_lib_malloc_pages()</function>, for
2493 allocating the buffer, these fields are set by the ALSA middle
2494 layer, and you should <emphasis>not</emphasis> change them by
2495 yourself. You can read them but not write them.
2496 On the other hand, if you want to allocate the buffer by
2497 yourself, you'll need to manage it in hw_params callback.
2498 At least, <structfield>dma_bytes</structfield> is mandatory.
2499 <structfield>dma_area</structfield> is necessary when the
2500 buffer is mmapped. If your driver doesn't support mmap, this
2501 field is not necessary. <structfield>dma_addr</structfield>
2502 is also optional. You can use
2503 <structfield>dma_private</structfield> as you like, too.
2504 </para>
2505 </section>
2507 <section id="pcm-interface-runtime-status">
2508 <title>Running Status</title>
2509 <para>
2510 The running status can be referred via <constant>runtime->status</constant>.
2511 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
2512 record. For example, you can get the current DMA hardware
2513 pointer via <constant>runtime->status->hw_ptr</constant>.
2514 </para>
2516 <para>
2517 The DMA application pointer can be referred via
2518 <constant>runtime->control</constant>, which points to the
2519 struct <structname>snd_pcm_mmap_control</structname> record.
2520 However, accessing directly to this value is not recommended.
2521 </para>
2522 </section>
2524 <section id="pcm-interface-runtime-private">
2525 <title>Private Data</title>
2526 <para>
2527 You can allocate a record for the substream and store it in
2528 <constant>runtime->private_data</constant>. Usually, this
2529 is done in
2530 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2531 the open callback</citetitle></link>.
2532 Don't mix this with <constant>pcm->private_data</constant>.
2533 The <constant>pcm->private_data</constant> usually points to the
2534 chip instance assigned statically at the creation of PCM, while the
2535 <constant>runtime->private_data</constant> points to a dynamic
2536 data structure created at the PCM open callback.
2538 <informalexample>
2539 <programlisting>
2540 <![CDATA[
2541 static int snd_xxx_open(struct snd_pcm_substream *substream)
2542 {
2543 struct my_pcm_data *data;
2544 ....
2545 data = kmalloc(sizeof(*data), GFP_KERNEL);
2546 substream->runtime->private_data = data;
2547 ....
2548 }
2549 ]]>
2550 </programlisting>
2551 </informalexample>
2552 </para>
2554 <para>
2555 The allocated object must be released in
2556 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2557 the close callback</citetitle></link>.
2558 </para>
2559 </section>
2561 <section id="pcm-interface-runtime-intr">
2562 <title>Interrupt Callbacks</title>
2563 <para>
2564 The field <structfield>transfer_ack_begin</structfield> and
2565 <structfield>transfer_ack_end</structfield> are called at
2566 the beginning and at the end of
2567 <function>snd_pcm_period_elapsed()</function>, respectively.
2568 </para>
2569 </section>
2571 </section>
2573 <section id="pcm-interface-operators">
2574 <title>Operators</title>
2575 <para>
2576 OK, now let me give details about each pcm callback
2577 (<parameter>ops</parameter>). In general, every callback must
2578 return 0 if successful, or a negative error number
2579 such as <constant>-EINVAL</constant>. To choose an appropriate
2580 error number, it is advised to check what value other parts of
2581 the kernel return when the same kind of request fails.
2582 </para>
2584 <para>
2585 The callback function takes at least the argument with
2586 <structname>snd_pcm_substream</structname> pointer. To retrieve
2587 the chip record from the given substream instance, you can use the
2588 following macro.
2590 <informalexample>
2591 <programlisting>
2592 <![CDATA[
2593 int xxx() {
2594 struct mychip *chip = snd_pcm_substream_chip(substream);
2595 ....
2596 }
2597 ]]>
2598 </programlisting>
2599 </informalexample>
2601 The macro reads <constant>substream->private_data</constant>,
2602 which is a copy of <constant>pcm->private_data</constant>.
2603 You can override the former if you need to assign different data
2604 records per PCM substream. For example, the cmi8330 driver assigns
2605 different private_data for playback and capture directions,
2606 because it uses two different codecs (SB- and AD-compatible) for
2607 different directions.
2608 </para>
2610 <section id="pcm-interface-operators-open-callback">
2611 <title>open callback</title>
2612 <para>
2613 <informalexample>
2614 <programlisting>
2615 <![CDATA[
2616 static int snd_xxx_open(struct snd_pcm_substream *substream);
2617 ]]>
2618 </programlisting>
2619 </informalexample>
2621 This is called when a pcm substream is opened.
2622 </para>
2624 <para>
2625 At least, here you have to initialize the runtime->hw
2626 record. Typically, this is done by like this:
2628 <informalexample>
2629 <programlisting>
2630 <![CDATA[
2631 static int snd_xxx_open(struct snd_pcm_substream *substream)
2632 {
2633 struct mychip *chip = snd_pcm_substream_chip(substream);
2634 struct snd_pcm_runtime *runtime = substream->runtime;
2636 runtime->hw = snd_mychip_playback_hw;
2637 return 0;
2638 }
2639 ]]>
2640 </programlisting>
2641 </informalexample>
2643 where <parameter>snd_mychip_playback_hw</parameter> is the
2644 pre-defined hardware description.
2645 </para>
2647 <para>
2648 You can allocate a private data in this callback, as described
2649 in <link linkend="pcm-interface-runtime-private"><citetitle>
2650 Private Data</citetitle></link> section.
2651 </para>
2653 <para>
2654 If the hardware configuration needs more constraints, set the
2655 hardware constraints here, too.
2656 See <link linkend="pcm-interface-constraints"><citetitle>
2657 Constraints</citetitle></link> for more details.
2658 </para>
2659 </section>
2661 <section id="pcm-interface-operators-close-callback">
2662 <title>close callback</title>
2663 <para>
2664 <informalexample>
2665 <programlisting>
2666 <![CDATA[
2667 static int snd_xxx_close(struct snd_pcm_substream *substream);
2668 ]]>
2669 </programlisting>
2670 </informalexample>
2672 Obviously, this is called when a pcm substream is closed.
2673 </para>
2675 <para>
2676 Any private instance for a pcm substream allocated in the
2677 open callback will be released here.
2679 <informalexample>
2680 <programlisting>
2681 <![CDATA[
2682 static int snd_xxx_close(struct snd_pcm_substream *substream)
2683 {
2684 ....
2685 kfree(substream->runtime->private_data);
2686 ....
2687 }
2688 ]]>
2689 </programlisting>
2690 </informalexample>
2691 </para>
2692 </section>
2694 <section id="pcm-interface-operators-ioctl-callback">
2695 <title>ioctl callback</title>
2696 <para>
2697 This is used for any special call to pcm ioctls. But
2698 usually you can pass a generic ioctl callback,
2699 <function>snd_pcm_lib_ioctl</function>.
2700 </para>
2701 </section>
2703 <section id="pcm-interface-operators-hw-params-callback">
2704 <title>hw_params callback</title>
2705 <para>
2706 <informalexample>
2707 <programlisting>
2708 <![CDATA[
2709 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2710 struct snd_pcm_hw_params *hw_params);
2711 ]]>
2712 </programlisting>
2713 </informalexample>
2714 </para>
2716 <para>
2717 This is called when the hardware parameter
2718 (<structfield>hw_params</structfield>) is set
2719 up by the application,
2720 that is, once when the buffer size, the period size, the
2721 format, etc. are defined for the pcm substream.
2722 </para>
2724 <para>
2725 Many hardware setups should be done in this callback,
2726 including the allocation of buffers.
2727 </para>
2729 <para>
2730 Parameters to be initialized are retrieved by
2731 <function>params_xxx()</function> macros. To allocate
2732 buffer, you can call a helper function,
2734 <informalexample>
2735 <programlisting>
2736 <![CDATA[
2737 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2738 ]]>
2739 </programlisting>
2740 </informalexample>
2742 <function>snd_pcm_lib_malloc_pages()</function> is available
2743 only when the DMA buffers have been pre-allocated.
2744 See the section <link
2745 linkend="buffer-and-memory-buffer-types"><citetitle>
2746 Buffer Types</citetitle></link> for more details.
2747 </para>
2749 <para>
2750 Note that this and <structfield>prepare</structfield> callbacks
2751 may be called multiple times per initialization.
2752 For example, the OSS emulation may
2753 call these callbacks at each change via its ioctl.
2754 </para>
2756 <para>
2757 Thus, you need to be careful not to allocate the same buffers
2758 many times, which will lead to memory leaks! Calling the
2759 helper function above many times is OK. It will release the
2760 previous buffer automatically when it was already allocated.
2761 </para>
2763 <para>
2764 Another note is that this callback is non-atomic
2765 (schedulable). This is important, because the
2766 <structfield>trigger</structfield> callback
2767 is atomic (non-schedulable). That is, mutexes or any
2768 schedule-related functions are not available in
2769 <structfield>trigger</structfield> callback.
2770 Please see the subsection
2771 <link linkend="pcm-interface-atomicity"><citetitle>
2772 Atomicity</citetitle></link> for details.
2773 </para>
2774 </section>
2776 <section id="pcm-interface-operators-hw-free-callback">
2777 <title>hw_free callback</title>
2778 <para>
2779 <informalexample>
2780 <programlisting>
2781 <![CDATA[
2782 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2783 ]]>
2784 </programlisting>
2785 </informalexample>
2786 </para>
2788 <para>
2789 This is called to release the resources allocated via
2790 <structfield>hw_params</structfield>. For example, releasing the
2791 buffer via
2792 <function>snd_pcm_lib_malloc_pages()</function> is done by
2793 calling the following:
2795 <informalexample>
2796 <programlisting>
2797 <![CDATA[
2798 snd_pcm_lib_free_pages(substream);
2799 ]]>
2800 </programlisting>
2801 </informalexample>
2802 </para>
2804 <para>
2805 This function is always called before the close callback is called.
2806 Also, the callback may be called multiple times, too.
2807 Keep track whether the resource was already released.
2808 </para>
2809 </section>
2811 <section id="pcm-interface-operators-prepare-callback">
2812 <title>prepare callback</title>
2813 <para>
2814 <informalexample>
2815 <programlisting>
2816 <![CDATA[
2817 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2818 ]]>
2819 </programlisting>
2820 </informalexample>
2821 </para>
2823 <para>
2824 This callback is called when the pcm is
2825 <quote>prepared</quote>. You can set the format type, sample
2826 rate, etc. here. The difference from
2827 <structfield>hw_params</structfield> is that the
2828 <structfield>prepare</structfield> callback will be called each
2829 time
2830 <function>snd_pcm_prepare()</function> is called, i.e. when
2831 recovering after underruns, etc.
2832 </para>
2834 <para>
2835 Note that this callback is now non-atomic.
2836 You can use schedule-related functions safely in this callback.
2837 </para>
2839 <para>
2840 In this and the following callbacks, you can refer to the
2841 values via the runtime record,
2842 substream->runtime.
2843 For example, to get the current
2844 rate, format or channels, access to
2845 runtime->rate,
2846 runtime->format or
2847 runtime->channels, respectively.
2848 The physical address of the allocated buffer is set to
2849 runtime->dma_area. The buffer and period sizes are
2850 in runtime->buffer_size and runtime->period_size,
2851 respectively.
2852 </para>
2854 <para>
2855 Be careful that this callback will be called many times at
2856 each setup, too.
2857 </para>
2858 </section>
2860 <section id="pcm-interface-operators-trigger-callback">
2861 <title>trigger callback</title>
2862 <para>
2863 <informalexample>
2864 <programlisting>
2865 <![CDATA[
2866 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2867 ]]>
2868 </programlisting>
2869 </informalexample>
2871 This is called when the pcm is started, stopped or paused.
2872 </para>
2874 <para>
2875 Which action is specified in the second argument,
2876 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2877 <filename><sound/pcm.h></filename>. At least,
2878 the <constant>START</constant> and <constant>STOP</constant>
2879 commands must be defined in this callback.
2881 <informalexample>
2882 <programlisting>
2883 <![CDATA[
2884 switch (cmd) {
2885 case SNDRV_PCM_TRIGGER_START:
2886 /* do something to start the PCM engine */
2887 break;
2888 case SNDRV_PCM_TRIGGER_STOP:
2889 /* do something to stop the PCM engine */
2890 break;
2891 default:
2892 return -EINVAL;
2893 }
2894 ]]>
2895 </programlisting>
2896 </informalexample>
2897 </para>
2899 <para>
2900 When the pcm supports the pause operation (given in the info
2901 field of the hardware table), the <constant>PAUSE_PUSE</constant>
2902 and <constant>PAUSE_RELEASE</constant> commands must be
2903 handled here, too. The former is the command to pause the pcm,
2904 and the latter to restart the pcm again.
2905 </para>
2907 <para>
2908 When the pcm supports the suspend/resume operation,
2909 regardless of full or partial suspend/resume support,
2910 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2911 commands must be handled, too.
2912 These commands are issued when the power-management status is
2913 changed. Obviously, the <constant>SUSPEND</constant> and
2914 <constant>RESUME</constant> commands
2915 suspend and resume the pcm substream, and usually, they
2916 are identical to the <constant>STOP</constant> and
2917 <constant>START</constant> commands, respectively.
2918 See the <link linkend="power-management"><citetitle>
2919 Power Management</citetitle></link> section for details.
2920 </para>
2922 <para>
2923 As mentioned, this callback is atomic. You cannot call
2924 functions which may sleep.
2925 The trigger callback should be as minimal as possible,
2926 just really triggering the DMA. The other stuff should be
2927 initialized hw_params and prepare callbacks properly
2928 beforehand.
2929 </para>
2930 </section>
2932 <section id="pcm-interface-operators-pointer-callback">
2933 <title>pointer callback</title>
2934 <para>
2935 <informalexample>
2936 <programlisting>
2937 <![CDATA[
2938 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2939 ]]>
2940 </programlisting>
2941 </informalexample>
2943 This callback is called when the PCM middle layer inquires
2944 the current hardware position on the buffer. The position must
2945 be returned in frames,
2946 ranging from 0 to buffer_size - 1.
2947 </para>
2949 <para>
2950 This is called usually from the buffer-update routine in the
2951 pcm middle layer, which is invoked when
2952 <function>snd_pcm_period_elapsed()</function> is called in the
2953 interrupt routine. Then the pcm middle layer updates the
2954 position and calculates the available space, and wakes up the
2955 sleeping poll threads, etc.
2956 </para>
2958 <para>
2959 This callback is also atomic.
2960 </para>
2961 </section>
2963 <section id="pcm-interface-operators-copy-silence">
2964 <title>copy and silence callbacks</title>
2965 <para>
2966 These callbacks are not mandatory, and can be omitted in
2967 most cases. These callbacks are used when the hardware buffer
2968 cannot be in the normal memory space. Some chips have their
2969 own buffer on the hardware which is not mappable. In such a
2970 case, you have to transfer the data manually from the memory
2971 buffer to the hardware buffer. Or, if the buffer is
2972 non-contiguous on both physical and virtual memory spaces,
2973 these callbacks must be defined, too.
2974 </para>
2976 <para>
2977 If these two callbacks are defined, copy and set-silence
2978 operations are done by them. The detailed will be described in
2979 the later section <link
2980 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2981 Management</citetitle></link>.
2982 </para>
2983 </section>
2985 <section id="pcm-interface-operators-ack">
2986 <title>ack callback</title>
2987 <para>
2988 This callback is also not mandatory. This callback is called
2989 when the appl_ptr is updated in read or write operations.
2990 Some drivers like emu10k1-fx and cs46xx need to track the
2991 current appl_ptr for the internal buffer, and this callback
2992 is useful only for such a purpose.
2993 </para>
2994 <para>
2995 This callback is atomic.
2996 </para>
2997 </section>
2999 <section id="pcm-interface-operators-page-callback">
3000 <title>page callback</title>
3002 <para>
3003 This callback is optional too. This callback is used
3004 mainly for non-contiguous buffers. The mmap calls this
3005 callback to get the page address. Some examples will be
3006 explained in the later section <link
3007 linkend="buffer-and-memory"><citetitle>Buffer and Memory
3008 Management</citetitle></link>, too.
3009 </para>
3010 </section>
3011 </section>
3013 <section id="pcm-interface-interrupt-handler">
3014 <title>Interrupt Handler</title>
3015 <para>
3016 The rest of pcm stuff is the PCM interrupt handler. The
3017 role of PCM interrupt handler in the sound driver is to update
3018 the buffer position and to tell the PCM middle layer when the
3019 buffer position goes across the prescribed period size. To
3020 inform this, call the <function>snd_pcm_period_elapsed()</function>
3021 function.
3022 </para>
3024 <para>
3025 There are several types of sound chips to generate the interrupts.
3026 </para>
3028 <section id="pcm-interface-interrupt-handler-boundary">
3029 <title>Interrupts at the period (fragment) boundary</title>
3030 <para>
3031 This is the most frequently found type: the hardware
3032 generates an interrupt at each period boundary.
3033 In this case, you can call
3034 <function>snd_pcm_period_elapsed()</function> at each
3035 interrupt.
3036 </para>
3038 <para>
3039 <function>snd_pcm_period_elapsed()</function> takes the
3040 substream pointer as its argument. Thus, you need to keep the
3041 substream pointer accessible from the chip instance. For
3042 example, define substream field in the chip record to hold the
3043 current running substream pointer, and set the pointer value
3044 at open callback (and reset at close callback).
3045 </para>
3047 <para>
3048 If you acquire a spinlock in the interrupt handler, and the
3049 lock is used in other pcm callbacks, too, then you have to
3050 release the lock before calling
3051 <function>snd_pcm_period_elapsed()</function>, because
3052 <function>snd_pcm_period_elapsed()</function> calls other pcm
3053 callbacks inside.
3054 </para>
3056 <para>
3057 Typical code would be like:
3059 <example>
3060 <title>Interrupt Handler Case #1</title>
3061 <programlisting>
3062 <![CDATA[
3063 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3064 {
3065 struct mychip *chip = dev_id;
3066 spin_lock(&chip->lock);
3067 ....
3068 if (pcm_irq_invoked(chip)) {
3069 /* call updater, unlock before it */
3070 spin_unlock(&chip->lock);
3071 snd_pcm_period_elapsed(chip->substream);
3072 spin_lock(&chip->lock);
3073 /* acknowledge the interrupt if necessary */
3074 }
3075 ....
3076 spin_unlock(&chip->lock);
3077 return IRQ_HANDLED;
3078 }
3079 ]]>
3080 </programlisting>
3081 </example>
3082 </para>
3083 </section>
3085 <section id="pcm-interface-interrupt-handler-timer">
3086 <title>High frequency timer interrupts</title>
3087 <para>
3088 This happense when the hardware doesn't generate interrupts
3089 at the period boundary but issues timer interrupts at a fixed
3090 timer rate (e.g. es1968 or ymfpci drivers).
3091 In this case, you need to check the current hardware
3092 position and accumulate the processed sample length at each
3093 interrupt. When the accumulated size exceeds the period
3094 size, call
3095 <function>snd_pcm_period_elapsed()</function> and reset the
3096 accumulator.
3097 </para>
3099 <para>
3100 Typical code would be like the following.
3102 <example>
3103 <title>Interrupt Handler Case #2</title>
3104 <programlisting>
3105 <![CDATA[
3106 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3107 {
3108 struct mychip *chip = dev_id;
3109 spin_lock(&chip->lock);
3110 ....
3111 if (pcm_irq_invoked(chip)) {
3112 unsigned int last_ptr, size;
3113 /* get the current hardware pointer (in frames) */
3114 last_ptr = get_hw_ptr(chip);
3115 /* calculate the processed frames since the
3116 * last update
3117 */
3118 if (last_ptr < chip->last_ptr)
3119 size = runtime->buffer_size + last_ptr
3120 - chip->last_ptr;
3121 else
3122 size = last_ptr - chip->last_ptr;
3123 /* remember the last updated point */
3124 chip->last_ptr = last_ptr;
3125 /* accumulate the size */
3126 chip->size += size;
3127 /* over the period boundary? */
3128 if (chip->size >= runtime->period_size) {
3129 /* reset the accumulator */
3130 chip->size %= runtime->period_size;
3131 /* call updater */
3132 spin_unlock(&chip->lock);
3133 snd_pcm_period_elapsed(substream);
3134 spin_lock(&chip->lock);
3135 }
3136 /* acknowledge the interrupt if necessary */
3137 }
3138 ....
3139 spin_unlock(&chip->lock);
3140 return IRQ_HANDLED;
3141 }
3142 ]]>
3143 </programlisting>
3144 </example>
3145 </para>
3146 </section>
3148 <section id="pcm-interface-interrupt-handler-both">
3149 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3150 <para>
3151 In both cases, even if more than one period are elapsed, you
3152 don't have to call
3153 <function>snd_pcm_period_elapsed()</function> many times. Call
3154 only once. And the pcm layer will check the current hardware
3155 pointer and update to the latest status.
3156 </para>
3157 </section>
3158 </section>
3160 <section id="pcm-interface-atomicity">
3161 <title>Atomicity</title>
3162 <para>
3163 One of the most important (and thus difficult to debug) problems
3164 in kernel programming are race conditions.
3165 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3166 or semaphores. In general, if a race condition can happen
3167 in an interrupt handler, it has to be managed atomically, and you
3168 have to use a spinlock to protect the critical session. If the
3169 critical section is not in interrupt handler code and
3170 if taking a relatively long time to execute is acceptable, you
3171 should use mutexes or semaphores instead.
3172 </para>
3174 <para>
3175 As already seen, some pcm callbacks are atomic and some are
3176 not. For example, the <parameter>hw_params</parameter> callback is
3177 non-atomic, while <parameter>trigger</parameter> callback is
3178 atomic. This means, the latter is called already in a spinlock
3179 held by the PCM middle layer. Please take this atomicity into
3180 account when you choose a locking scheme in the callbacks.
3181 </para>
3183 <para>
3184 In the atomic callbacks, you cannot use functions which may call
3185 <function>schedule</function> or go to
3186 <function>sleep</function>. Semaphores and mutexes can sleep,
3187 and hence they cannot be used inside the atomic callbacks
3188 (e.g. <parameter>trigger</parameter> callback).
3189 To implement some delay in such a callback, please use
3190 <function>udelay()</function> or <function>mdelay()</function>.
3191 </para>
3193 <para>
3194 All three atomic callbacks (trigger, pointer, and ack) are
3195 called with local interrupts disabled.
3196 </para>
3198 </section>
3199 <section id="pcm-interface-constraints">
3200 <title>Constraints</title>
3201 <para>
3202 If your chip supports unconventional sample rates, or only the
3203 limited samples, you need to set a constraint for the
3204 condition.
3205 </para>
3207 <para>
3208 For example, in order to restrict the sample rates in the some
3209 supported values, use
3210 <function>snd_pcm_hw_constraint_list()</function>.
3211 You need to call this function in the open callback.
3213 <example>
3214 <title>Example of Hardware Constraints</title>
3215 <programlisting>
3216 <![CDATA[
3217 static unsigned int rates[] =
3218 {4000, 10000, 22050, 44100};
3219 static struct snd_pcm_hw_constraint_list constraints_rates = {
3220 .count = ARRAY_SIZE(rates),
3221 .list = rates,
3222 .mask = 0,
3223 };
3225 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3226 {
3227 int err;
3228 ....
3229 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3230 SNDRV_PCM_HW_PARAM_RATE,
3231 &constraints_rates);
3232 if (err < 0)
3233 return err;
3234 ....
3235 }
3236 ]]>
3237 </programlisting>
3238 </example>
3239 </para>
3241 <para>
3242 There are many different constraints.
3243 Look at <filename>sound/pcm.h</filename> for a complete list.
3244 You can even define your own constraint rules.
3245 For example, let's suppose my_chip can manage a substream of 1 channel
3246 if and only if the format is S16_LE, otherwise it supports any format
3247 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3248 other constraint_list). You can build a rule like this:
3250 <example>
3251 <title>Example of Hardware Constraints for Channels</title>
3252 <programlisting>
3253 <![CDATA[
3254 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3255 struct snd_pcm_hw_rule *rule)
3256 {
3257 struct snd_interval *c = hw_param_interval(params,
3258 SNDRV_PCM_HW_PARAM_CHANNELS);
3259 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3260 struct snd_mask fmt;
3262 snd_mask_any(&fmt); /* Init the struct */
3263 if (c->min < 2) {
3264 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3265 return snd_mask_refine(f, &fmt);
3266 }
3267 return 0;
3268 }
3269 ]]>
3270 </programlisting>
3271 </example>
3272 </para>
3274 <para>
3275 Then you need to call this function to add your rule:
3277 <informalexample>
3278 <programlisting>
3279 <![CDATA[
3280 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3281 hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3282 -1);
3283 ]]>
3284 </programlisting>
3285 </informalexample>
3286 </para>
3288 <para>
3289 The rule function is called when an application sets the number of
3290 channels. But an application can set the format before the number of
3291 channels. Thus you also need to define the inverse rule:
3293 <example>
3294 <title>Example of Hardware Constraints for Channels</title>
3295 <programlisting>
3296 <![CDATA[
3297 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3298 struct snd_pcm_hw_rule *rule)
3299 {
3300 struct snd_interval *c = hw_param_interval(params,
3301 SNDRV_PCM_HW_PARAM_CHANNELS);
3302 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3303 struct snd_interval ch;
3305 snd_interval_any(&ch);
3306 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3307 ch.min = ch.max = 1;
3308 ch.integer = 1;
3309 return snd_interval_refine(c, &ch);
3310 }
3311 return 0;
3312 }
3313 ]]>
3314 </programlisting>
3315 </example>
3316 </para>
3318 <para>
3319 ...and in the open callback:
3320 <informalexample>
3321 <programlisting>
3322 <![CDATA[
3323 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3324 hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3325 -1);
3326 ]]>
3327 </programlisting>
3328 </informalexample>
3329 </para>
3331 <para>
3332 I won't give more details here, rather I
3333 would like to say, <quote>Luke, use the source.</quote>
3334 </para>
3335 </section>
3337 </chapter>
3340 <!-- ****************************************************** -->
3341 <!-- Control Interface -->
3342 <!-- ****************************************************** -->
3343 <chapter id="control-interface">
3344 <title>Control Interface</title>
3346 <section id="control-interface-general">
3347 <title>General</title>
3348 <para>
3349 The control interface is used widely for many switches,
3350 sliders, etc. which are accessed from user-space. Its most
3351 important use is the mixer interface. In other words, since ALSA
3352 0.9.x, all the mixer stuff is implemented on the control kernel API.
3353 </para>
3355 <para>
3356 ALSA has a well-defined AC97 control module. If your chip
3357 supports only the AC97 and nothing else, you can skip this
3358 section.
3359 </para>
3361 <para>
3362 The control API is defined in
3363 <filename><sound/control.h></filename>.
3364 Include this file if you want to add your own controls.
3365 </para>
3366 </section>
3368 <section id="control-interface-definition">
3369 <title>Definition of Controls</title>
3370 <para>
3371 To create a new control, you need to define the
3372 following three
3373 callbacks: <structfield>info</structfield>,
3374 <structfield>get</structfield> and
3375 <structfield>put</structfield>. Then, define a
3376 struct <structname>snd_kcontrol_new</structname> record, such as:
3378 <example>
3379 <title>Definition of a Control</title>
3380 <programlisting>
3381 <![CDATA[
3382 static struct snd_kcontrol_new my_control = {
3383 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3384 .name = "PCM Playback Switch",
3385 .index = 0,
3386 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3387 .private_value = 0xffff,
3388 .info = my_control_info,
3389 .get = my_control_get,
3390 .put = my_control_put
3391 };
3392 ]]>
3393 </programlisting>
3394 </example>
3395 </para>
3397 <para>
3398 The <structfield>iface</structfield> field specifies the control
3399 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3400 is usually <constant>MIXER</constant>.
3401 Use <constant>CARD</constant> for global controls that are not
3402 logically part of the mixer.
3403 If the control is closely associated with some specific device on
3404 the sound card, use <constant>HWDEP</constant>,
3405 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3406 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3407 specify the device number with the
3408 <structfield>device</structfield> and
3409 <structfield>subdevice</structfield> fields.
3410 </para>
3412 <para>
3413 The <structfield>name</structfield> is the name identifier
3414 string. Since ALSA 0.9.x, the control name is very important,
3415 because its role is classified from its name. There are
3416 pre-defined standard control names. The details are described in
3417 the <link linkend="control-interface-control-names"><citetitle>
3418 Control Names</citetitle></link> subsection.
3419 </para>
3421 <para>
3422 The <structfield>index</structfield> field holds the index number
3423 of this control. If there are several different controls with
3424 the same name, they can be distinguished by the index
3425 number. This is the case when
3426 several codecs exist on the card. If the index is zero, you can
3427 omit the definition above.
3428 </para>
3430 <para>
3431 The <structfield>access</structfield> field contains the access
3432 type of this control. Give the combination of bit masks,
3433 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3434 The details will be explained in
3435 the <link linkend="control-interface-access-flags"><citetitle>
3436 Access Flags</citetitle></link> subsection.
3437 </para>
3439 <para>
3440 The <structfield>private_value</structfield> field contains
3441 an arbitrary long integer value for this record. When using
3442 the generic <structfield>info</structfield>,
3443 <structfield>get</structfield> and
3444 <structfield>put</structfield> callbacks, you can pass a value
3445 through this field. If several small numbers are necessary, you can
3446 combine them in bitwise. Or, it's possible to give a pointer
3447 (casted to unsigned long) of some record to this field, too.
3448 </para>
3450 <para>
3451 The <structfield>tlv</structfield> field can be used to provide
3452 metadata about the control; see the
3453 <link linkend="control-interface-tlv">
3454 <citetitle>Metadata</citetitle></link> subsection.
3455 </para>
3457 <para>
3458 The other three are
3459 <link linkend="control-interface-callbacks"><citetitle>
3460 callback functions</citetitle></link>.
3461 </para>
3462 </section>
3464 <section id="control-interface-control-names">
3465 <title>Control Names</title>
3466 <para>
3467 There are some standards to define the control names. A
3468 control is usually defined from the three parts as
3469 <quote>SOURCE DIRECTION FUNCTION</quote>.
3470 </para>
3472 <para>
3473 The first, <constant>SOURCE</constant>, specifies the source
3474 of the control, and is a string such as <quote>Master</quote>,
3475 <quote>PCM</quote>, <quote>CD</quote> and
3476 <quote>Line</quote>. There are many pre-defined sources.
3477 </para>
3479 <para>
3480 The second, <constant>DIRECTION</constant>, is one of the
3481 following strings according to the direction of the control:
3482 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3483 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3484 be omitted, meaning both playback and capture directions.
3485 </para>
3487 <para>
3488 The third, <constant>FUNCTION</constant>, is one of the
3489 following strings according to the function of the control:
3490 <quote>Switch</quote>, <quote>Volume</quote> and
3491 <quote>Route</quote>.
3492 </para>
3494 <para>
3495 The example of control names are, thus, <quote>Master Capture
3496 Switch</quote> or <quote>PCM Playback Volume</quote>.
3497 </para>
3499 <para>
3500 There are some exceptions:
3501 </para>
3503 <section id="control-interface-control-names-global">
3504 <title>Global capture and playback</title>
3505 <para>
3506 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3507 and <quote>Capture Volume</quote> are used for the global
3508 capture (input) source, switch and volume. Similarly,
3509 <quote>Playback Switch</quote> and <quote>Playback
3510 Volume</quote> are used for the global output gain switch and
3511 volume.
3512 </para>
3513 </section>
3515 <section id="control-interface-control-names-tone">
3516 <title>Tone-controls</title>
3517 <para>
3518 tone-control switch and volumes are specified like
3519 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3520 Switch</quote>, <quote>Tone Control - Bass</quote>,
3521 <quote>Tone Control - Center</quote>.
3522 </para>
3523 </section>
3525 <section id="control-interface-control-names-3d">
3526 <title>3D controls</title>
3527 <para>
3528 3D-control switches and volumes are specified like <quote>3D
3529 Control - XXX</quote>, e.g. <quote>3D Control -
3530 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3531 Control - Space</quote>.
3532 </para>
3533 </section>
3535 <section id="control-interface-control-names-mic">
3536 <title>Mic boost</title>
3537 <para>
3538 Mic-boost switch is set as <quote>Mic Boost</quote> or
3539 <quote>Mic Boost (6dB)</quote>.
3540 </para>
3542 <para>
3543 More precise information can be found in
3544 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3545 </para>
3546 </section>
3547 </section>
3549 <section id="control-interface-access-flags">
3550 <title>Access Flags</title>
3552 <para>
3553 The access flag is the bitmask which specifies the access type
3554 of the given control. The default access type is
3555 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3556 which means both read and write are allowed to this control.
3557 When the access flag is omitted (i.e. = 0), it is
3558 considered as <constant>READWRITE</constant> access as default.
3559 </para>
3561 <para>
3562 When the control is read-only, pass
3563 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3564 In this case, you don't have to define
3565 the <structfield>put</structfield> callback.
3566 Similarly, when the control is write-only (although it's a rare
3567 case), you can use the <constant>WRITE</constant> flag instead, and
3568 you don't need the <structfield>get</structfield> callback.
3569 </para>
3571 <para>
3572 If the control value changes frequently (e.g. the VU meter),
3573 <constant>VOLATILE</constant> flag should be given. This means
3574 that the control may be changed without
3575 <link linkend="control-interface-change-notification"><citetitle>
3576 notification</citetitle></link>. Applications should poll such
3577 a control constantly.
3578 </para>
3580 <para>
3581 When the control is inactive, set
3582 the <constant>INACTIVE</constant> flag, too.
3583 There are <constant>LOCK</constant> and
3584 <constant>OWNER</constant> flags to change the write
3585 permissions.
3586 </para>
3588 </section>
3590 <section id="control-interface-callbacks">
3591 <title>Callbacks</title>
3593 <section id="control-interface-callbacks-info">
3594 <title>info callback</title>
3595 <para>
3596 The <structfield>info</structfield> callback is used to get
3597 detailed information on this control. This must store the
3598 values of the given struct <structname>snd_ctl_elem_info</structname>
3599 object. For example, for a boolean control with a single
3600 element:
3602 <example>
3603 <title>Example of info callback</title>
3604 <programlisting>
3605 <![CDATA[
3606 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3607 struct snd_ctl_elem_info *uinfo)
3608 {
3609 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3610 uinfo->count = 1;
3611 uinfo->value.integer.min = 0;
3612 uinfo->value.integer.max = 1;
3613 return 0;
3614 }
3615 ]]>
3616 </programlisting>
3617 </example>
3618 </para>
3620 <para>
3621 The <structfield>type</structfield> field specifies the type
3622 of the control. There are <constant>BOOLEAN</constant>,
3623 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3624 <constant>BYTES</constant>, <constant>IEC958</constant> and
3625 <constant>INTEGER64</constant>. The
3626 <structfield>count</structfield> field specifies the
3627 number of elements in this control. For example, a stereo
3628 volume would have count = 2. The
3629 <structfield>value</structfield> field is a union, and
3630 the values stored are depending on the type. The boolean and
3631 integer types are identical.
3632 </para>
3634 <para>
3635 The enumerated type is a bit different from others. You'll
3636 need to set the string for the currently given item index.
3638 <informalexample>
3639 <programlisting>
3640 <![CDATA[
3641 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3642 struct snd_ctl_elem_info *uinfo)
3643 {
3644 static char *texts[4] = {
3645 "First", "Second", "Third", "Fourth"
3646 };
3647 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3648 uinfo->count = 1;
3649 uinfo->value.enumerated.items = 4;
3650 if (uinfo->value.enumerated.item > 3)
3651 uinfo->value.enumerated.item = 3;
3652 strcpy(uinfo->value.enumerated.name,
3653 texts[uinfo->value.enumerated.item]);
3654 return 0;
3655 }
3656 ]]>
3657 </programlisting>
3658 </informalexample>
3659 </para>
3661 <para>
3662 Some common info callbacks are available for your convenience:
3663 <function>snd_ctl_boolean_mono_info()</function> and
3664 <function>snd_ctl_boolean_stereo_info()</function>.
3665 Obviously, the former is an info callback for a mono channel
3666 boolean item, just like <function>snd_myctl_mono_info</function>
3667 above, and the latter is for a stereo channel boolean item.
3668 </para>
3670 </section>
3672 <section id="control-interface-callbacks-get">
3673 <title>get callback</title>
3675 <para>
3676 This callback is used to read the current value of the
3677 control and to return to user-space.
3678 </para>
3680 <para>
3681 For example,
3683 <example>
3684 <title>Example of get callback</title>
3685 <programlisting>
3686 <![CDATA[
3687 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3688 struct snd_ctl_elem_value *ucontrol)
3689 {
3690 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3691 ucontrol->value.integer.value[0] = get_some_value(chip);
3692 return 0;
3693 }
3694 ]]>
3695 </programlisting>
3696 </example>
3697 </para>
3699 <para>
3700 The <structfield>value</structfield> field depends on
3701 the type of control as well as on the info callback. For example,
3702 the sb driver uses this field to store the register offset,
3703 the bit-shift and the bit-mask. The
3704 <structfield>private_value</structfield> field is set as follows:
3705 <informalexample>
3706 <programlisting>
3707 <![CDATA[
3708 .private_value = reg | (shift << 16) | (mask << 24)
3709 ]]>
3710 </programlisting>
3711 </informalexample>
3712 and is retrieved in callbacks like
3713 <informalexample>
3714 <programlisting>
3715 <![CDATA[
3716 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3717 struct snd_ctl_elem_value *ucontrol)
3718 {
3719 int reg = kcontrol->private_value & 0xff;
3720 int shift = (kcontrol->private_value >> 16) & 0xff;
3721 int mask = (kcontrol->private_value >> 24) & 0xff;
3722 ....
3723 }
3724 ]]>
3725 </programlisting>
3726 </informalexample>
3727 </para>
3729 <para>
3730 In the <structfield>get</structfield> callback,
3731 you have to fill all the elements if the
3732 control has more than one elements,
3733 i.e. <structfield>count</structfield> > 1.
3734 In the example above, we filled only one element
3735 (<structfield>value.integer.value[0]</structfield>) since it's
3736 assumed as <structfield>count</structfield> = 1.
3737 </para>
3738 </section>
3740 <section id="control-interface-callbacks-put">
3741 <title>put callback</title>
3743 <para>
3744 This callback is used to write a value from user-space.
3745 </para>
3747 <para>
3748 For example,
3750 <example>
3751 <title>Example of put callback</title>
3752 <programlisting>
3753 <![CDATA[
3754 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3755 struct snd_ctl_elem_value *ucontrol)
3756 {
3757 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3758 int changed = 0;
3759 if (chip->current_value !=
3760 ucontrol->value.integer.value[0]) {
3761 change_current_value(chip,
3762 ucontrol->value.integer.value[0]);
3763 changed = 1;
3764 }
3765 return changed;
3766 }
3767 ]]>
3768 </programlisting>
3769 </example>
3771 As seen above, you have to return 1 if the value is
3772 changed. If the value is not changed, return 0 instead.
3773 If any fatal error happens, return a negative error code as
3774 usual.
3775 </para>
3777 <para>
3778 As in the <structfield>get</structfield> callback,
3779 when the control has more than one elements,
3780 all elements must be evaluated in this callback, too.
3781 </para>
3782 </section>
3784 <section id="control-interface-callbacks-all">
3785 <title>Callbacks are not atomic</title>
3786 <para>
3787 All these three callbacks are basically not atomic.
3788 </para>
3789 </section>
3790 </section>
3792 <section id="control-interface-constructor">
3793 <title>Constructor</title>
3794 <para>
3795 When everything is ready, finally we can create a new
3796 control. To create a control, there are two functions to be
3797 called, <function>snd_ctl_new1()</function> and
3798 <function>snd_ctl_add()</function>.
3799 </para>
3801 <para>
3802 In the simplest way, you can do like this:
3804 <informalexample>
3805 <programlisting>
3806 <![CDATA[
3807 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3808 if (err < 0)
3809 return err;
3810 ]]>
3811 </programlisting>
3812 </informalexample>
3814 where <parameter>my_control</parameter> is the
3815 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3816 is the object pointer to be passed to
3817 kcontrol->private_data
3818 which can be referred to in callbacks.
3819 </para>
3821 <para>
3822 <function>snd_ctl_new1()</function> allocates a new
3823 <structname>snd_kcontrol</structname> instance,
3824 and <function>snd_ctl_add</function> assigns the given
3825 control component to the card.
3826 </para>
3827 </section>
3829 <section id="control-interface-change-notification">
3830 <title>Change Notification</title>
3831 <para>
3832 If you need to change and update a control in the interrupt
3833 routine, you can call <function>snd_ctl_notify()</function>. For
3834 example,
3836 <informalexample>
3837 <programlisting>
3838 <![CDATA[
3839 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3840 ]]>
3841 </programlisting>
3842 </informalexample>
3844 This function takes the card pointer, the event-mask, and the
3845 control id pointer for the notification. The event-mask
3846 specifies the types of notification, for example, in the above
3847 example, the change of control values is notified.
3848 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3849 to be notified.
3850 You can find some examples in <filename>es1938.c</filename> or
3851 <filename>es1968.c</filename> for hardware volume interrupts.
3852 </para>
3853 </section>
3855 <section id="control-interface-tlv">
3856 <title>Metadata</title>
3857 <para>
3858 To provide information about the dB values of a mixer control, use
3859 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3860 <filename><sound/tlv.h></filename> to define a variable
3861 containing this information, set the<structfield>tlv.p
3862 </structfield> field to point to this variable, and include the
3863 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3864 <structfield>access</structfield> field; like this:
3865 <informalexample>
3866 <programlisting>
3867 <![CDATA[
3868 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3870 static struct snd_kcontrol_new my_control = {
3871 ...
3872 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3873 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3874 ...
3875 .tlv.p = db_scale_my_control,
3876 };
3877 ]]>
3878 </programlisting>
3879 </informalexample>
3880 </para>
3882 <para>
3883 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3884 information about a mixer control where each step in the control's
3885 value changes the dB value by a constant dB amount.
3886 The first parameter is the name of the variable to be defined.
3887 The second parameter is the minimum value, in units of 0.01 dB.
3888 The third parameter is the step size, in units of 0.01 dB.
3889 Set the fourth parameter to 1 if the minimum value actually mutes
3890 the control.
3891 </para>
3893 <para>
3894 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3895 information about a mixer control where the control's value affects
3896 the output linearly.
3897 The first parameter is the name of the variable to be defined.
3898 The second parameter is the minimum value, in units of 0.01 dB.
3899 The third parameter is the maximum value, in units of 0.01 dB.
3900 If the minimum value mutes the control, set the second parameter to
3901 <constant>TLV_DB_GAIN_MUTE</constant>.
3902 </para>
3903 </section>
3905 </chapter>
3908 <!-- ****************************************************** -->
3909 <!-- API for AC97 Codec -->
3910 <!-- ****************************************************** -->
3911 <chapter id="api-ac97">
3912 <title>API for AC97 Codec</title>
3914 <section>
3915 <title>General</title>
3916 <para>
3917 The ALSA AC97 codec layer is a well-defined one, and you don't
3918 have to write much code to control it. Only low-level control
3919 routines are necessary. The AC97 codec API is defined in
3920 <filename><sound/ac97_codec.h></filename>.
3921 </para>
3922 </section>
3924 <section id="api-ac97-example">
3925 <title>Full Code Example</title>
3926 <para>
3927 <example>
3928 <title>Example of AC97 Interface</title>
3929 <programlisting>
3930 <![CDATA[
3931 struct mychip {
3932 ....
3933 struct snd_ac97 *ac97;
3934 ....
3935 };
3937 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3938 unsigned short reg)
3939 {
3940 struct mychip *chip = ac97->private_data;
3941 ....
3942 /* read a register value here from the codec */
3943 return the_register_value;
3944 }
3946 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3947 unsigned short reg, unsigned short val)
3948 {
3949 struct mychip *chip = ac97->private_data;
3950 ....
3951 /* write the given register value to the codec */
3952 }
3954 static int snd_mychip_ac97(struct mychip *chip)
3955 {
3956 struct snd_ac97_bus *bus;
3957 struct snd_ac97_template ac97;
3958 int err;
3959 static struct snd_ac97_bus_ops ops = {
3960 .write = snd_mychip_ac97_write,
3961 .read = snd_mychip_ac97_read,
3962 };
3964 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3965 if (err < 0)
3966 return err;
3967 memset(&ac97, 0, sizeof(ac97));
3968 ac97.private_data = chip;
3969 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3970 }
3972 ]]>
3973 </programlisting>
3974 </example>
3975 </para>
3976 </section>
3978 <section id="api-ac97-constructor">
3979 <title>Constructor</title>
3980 <para>
3981 To create an ac97 instance, first call <function>snd_ac97_bus</function>
3982 with an <type>ac97_bus_ops_t</type> record with callback functions.
3984 <informalexample>
3985 <programlisting>
3986 <![CDATA[
3987 struct snd_ac97_bus *bus;
3988 static struct snd_ac97_bus_ops ops = {
3989 .write = snd_mychip_ac97_write,
3990 .read = snd_mychip_ac97_read,
3991 };
3993 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
3994 ]]>
3995 </programlisting>
3996 </informalexample>
3998 The bus record is shared among all belonging ac97 instances.
3999 </para>
4001 <para>
4002 And then call <function>snd_ac97_mixer()</function> with an
4003 struct <structname>snd_ac97_template</structname>
4004 record together with the bus pointer created above.
4006 <informalexample>
4007 <programlisting>
4008 <![CDATA[
4009 struct snd_ac97_template ac97;
4010 int err;
4012 memset(&ac97, 0, sizeof(ac97));
4013 ac97.private_data = chip;
4014 snd_ac97_mixer(bus, &ac97, &chip->ac97);
4015 ]]>
4016 </programlisting>
4017 </informalexample>
4019 where chip->ac97 is a pointer to a newly created
4020 <type>ac97_t</type> instance.
4021 In this case, the chip pointer is set as the private data, so that
4022 the read/write callback functions can refer to this chip instance.
4023 This instance is not necessarily stored in the chip
4024 record. If you need to change the register values from the
4025 driver, or need the suspend/resume of ac97 codecs, keep this
4026 pointer to pass to the corresponding functions.
4027 </para>
4028 </section>
4030 <section id="api-ac97-callbacks">
4031 <title>Callbacks</title>
4032 <para>
4033 The standard callbacks are <structfield>read</structfield> and
4034 <structfield>write</structfield>. Obviously they
4035 correspond to the functions for read and write accesses to the
4036 hardware low-level codes.
4037 </para>
4039 <para>
4040 The <structfield>read</structfield> callback returns the
4041 register value specified in the argument.
4043 <informalexample>
4044 <programlisting>
4045 <![CDATA[
4046 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4047 unsigned short reg)
4048 {
4049 struct mychip *chip = ac97->private_data;
4050 ....
4051 return the_register_value;
4052 }
4053 ]]>
4054 </programlisting>
4055 </informalexample>
4057 Here, the chip can be cast from ac97->private_data.
4058 </para>
4060 <para>
4061 Meanwhile, the <structfield>write</structfield> callback is
4062 used to set the register value.
4064 <informalexample>
4065 <programlisting>
4066 <![CDATA[
4067 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4068 unsigned short reg, unsigned short val)
4069 ]]>
4070 </programlisting>
4071 </informalexample>
4072 </para>
4074 <para>
4075 These callbacks are non-atomic like the control API callbacks.
4076 </para>
4078 <para>
4079 There are also other callbacks:
4080 <structfield>reset</structfield>,
4081 <structfield>wait</structfield> and
4082 <structfield>init</structfield>.
4083 </para>
4085 <para>
4086 The <structfield>reset</structfield> callback is used to reset
4087 the codec. If the chip requires a special kind of reset, you can
4088 define this callback.
4089 </para>
4091 <para>
4092 The <structfield>wait</structfield> callback is used to
4093 add some waiting time in the standard initialization of the codec. If the
4094 chip requires the extra waiting time, define this callback.
4095 </para>
4097 <para>
4098 The <structfield>init</structfield> callback is used for
4099 additional initialization of the codec.
4100 </para>
4101 </section>
4103 <section id="api-ac97-updating-registers">
4104 <title>Updating Registers in The Driver</title>
4105 <para>
4106 If you need to access to the codec from the driver, you can
4107 call the following functions:
4108 <function>snd_ac97_write()</function>,
4109 <function>snd_ac97_read()</function>,
4110 <function>snd_ac97_update()</function> and
4111 <function>snd_ac97_update_bits()</function>.
4112 </para>
4114 <para>
4115 Both <function>snd_ac97_write()</function> and
4116 <function>snd_ac97_update()</function> functions are used to
4117 set a value to the given register
4118 (<constant>AC97_XXX</constant>). The difference between them is
4119 that <function>snd_ac97_update()</function> doesn't write a
4120 value if the given value has been already set, while
4121 <function>snd_ac97_write()</function> always rewrites the
4122 value.
4124 <informalexample>
4125 <programlisting>
4126 <![CDATA[
4127 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4128 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4129 ]]>
4130 </programlisting>
4131 </informalexample>
4132 </para>
4134 <para>
4135 <function>snd_ac97_read()</function> is used to read the value
4136 of the given register. For example,
4138 <informalexample>
4139 <programlisting>
4140 <![CDATA[
4141 value = snd_ac97_read(ac97, AC97_MASTER);
4142 ]]>
4143 </programlisting>
4144 </informalexample>
4145 </para>
4147 <para>
4148 <function>snd_ac97_update_bits()</function> is used to update
4149 some bits in the given register.
4151 <informalexample>
4152 <programlisting>
4153 <![CDATA[
4154 snd_ac97_update_bits(ac97, reg, mask, value);
4155 ]]>
4156 </programlisting>
4157 </informalexample>
4158 </para>
4160 <para>
4161 Also, there is a function to change the sample rate (of a
4162 given register such as
4163 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4164 DRA is supported by the codec:
4165 <function>snd_ac97_set_rate()</function>.
4167 <informalexample>
4168 <programlisting>
4169 <![CDATA[
4170 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4171 ]]>
4172 </programlisting>
4173 </informalexample>
4174 </para>
4176 <para>
4177 The following registers are available to set the rate:
4178 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4179 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4180 <constant>AC97_PCM_LR_ADC_RATE</constant>,
4181 <constant>AC97_SPDIF</constant>. When
4182 <constant>AC97_SPDIF</constant> is specified, the register is
4183 not really changed but the corresponding IEC958 status bits will
4184 be updated.
4185 </para>
4186 </section>
4188 <section id="api-ac97-clock-adjustment">
4189 <title>Clock Adjustment</title>
4190 <para>
4191 In some chips, the clock of the codec isn't 48000 but using a
4192 PCI clock (to save a quartz!). In this case, change the field
4193 bus->clock to the corresponding
4194 value. For example, intel8x0
4195 and es1968 drivers have their own function to read from the clock.
4196 </para>
4197 </section>
4199 <section id="api-ac97-proc-files">
4200 <title>Proc Files</title>
4201 <para>
4202 The ALSA AC97 interface will create a proc file such as
4203 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4204 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4205 see the current status and registers of the codec.
4206 </para>
4207 </section>
4209 <section id="api-ac97-multiple-codecs">
4210 <title>Multiple Codecs</title>
4211 <para>
4212 When there are several codecs on the same card, you need to
4213 call <function>snd_ac97_mixer()</function> multiple times with
4214 ac97.num=1 or greater. The <structfield>num</structfield> field
4215 specifies the codec number.
4216 </para>
4218 <para>
4219 If you set up multiple codecs, you either need to write
4220 different callbacks for each codec or check
4221 ac97->num in the callback routines.
4222 </para>
4223 </section>
4225 </chapter>
4228 <!-- ****************************************************** -->
4229 <!-- MIDI (MPU401-UART) Interface -->
4230 <!-- ****************************************************** -->
4231 <chapter id="midi-interface">
4232 <title>MIDI (MPU401-UART) Interface</title>
4234 <section id="midi-interface-general">
4235 <title>General</title>
4236 <para>
4237 Many soundcards have built-in MIDI (MPU401-UART)
4238 interfaces. When the soundcard supports the standard MPU401-UART
4239 interface, most likely you can use the ALSA MPU401-UART API. The
4240 MPU401-UART API is defined in
4241 <filename><sound/mpu401.h></filename>.
4242 </para>
4244 <para>
4245 Some soundchips have a similar but slightly different
4246 implementation of mpu401 stuff. For example, emu10k1 has its own
4247 mpu401 routines.
4248 </para>
4249 </section>
4251 <section id="midi-interface-constructor">
4252 <title>Constructor</title>
4253 <para>
4254 To create a rawmidi object, call
4255 <function>snd_mpu401_uart_new()</function>.
4257 <informalexample>
4258 <programlisting>
4259 <![CDATA[
4260 struct snd_rawmidi *rmidi;
4261 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4262 irq, &rmidi);
4263 ]]>
4264 </programlisting>
4265 </informalexample>
4266 </para>
4268 <para>
4269 The first argument is the card pointer, and the second is the
4270 index of this component. You can create up to 8 rawmidi
4271 devices.
4272 </para>
4274 <para>
4275 The third argument is the type of the hardware,
4276 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4277 you can use <constant>MPU401_HW_MPU401</constant>.
4278 </para>
4280 <para>
4281 The 4th argument is the I/O port address. Many
4282 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4283 might be a part of its own PCI I/O region. It depends on the
4284 chip design.
4285 </para>
4287 <para>
4288 The 5th argument is a bitflag for additional information.
4289 When the I/O port address above is part of the PCI I/O
4290 region, the MPU401 I/O port might have been already allocated
4291 (reserved) by the driver itself. In such a case, pass a bit flag
4292 <constant>MPU401_INFO_INTEGRATED</constant>,
4293 and the mpu401-uart layer will allocate the I/O ports by itself.
4294 </para>
4296 <para>
4297 When the controller supports only the input or output MIDI stream,
4298 pass the <constant>MPU401_INFO_INPUT</constant> or
4299 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4300 Then the rawmidi instance is created as a single stream.
4301 </para>
4303 <para>
4304 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4305 the access method to MMIO (via readb and writeb) instead of
4306 iob and outb. In this case, you have to pass the iomapped address
4307 to <function>snd_mpu401_uart_new()</function>.
4308 </para>
4310 <para>
4311 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4312 stream isn't checked in the default interrupt handler. The driver
4313 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4314 by itself to start processing the output stream in the irq handler.
4315 </para>
4317 <para>
4318 If the MPU-401 interface shares its interrupt with the other logical
4319 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4320 (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4321 below</citetitle></link>).
4322 </para>
4324 <para>
4325 Usually, the port address corresponds to the command port and
4326 port + 1 corresponds to the data port. If not, you may change
4327 the <structfield>cport</structfield> field of
4328 struct <structname>snd_mpu401</structname> manually
4329 afterward. However, <structname>snd_mpu401</structname> pointer is not
4330 returned explicitly by
4331 <function>snd_mpu401_uart_new()</function>. You need to cast
4332 rmidi->private_data to
4333 <structname>snd_mpu401</structname> explicitly,
4335 <informalexample>
4336 <programlisting>
4337 <![CDATA[
4338 struct snd_mpu401 *mpu;
4339 mpu = rmidi->private_data;
4340 ]]>
4341 </programlisting>
4342 </informalexample>
4344 and reset the cport as you like:
4346 <informalexample>
4347 <programlisting>
4348 <![CDATA[
4349 mpu->cport = my_own_control_port;
4350 ]]>
4351 </programlisting>
4352 </informalexample>
4353 </para>
4355 <para>
4356 The 6th argument specifies the ISA irq number that will be
4357 allocated. If no interrupt is to be allocated (because your
4358 code is already allocating a shared interrupt, or because the
4359 device does not use interrupts), pass -1 instead.
4360 For a MPU-401 device without an interrupt, a polling timer
4361 will be used instead.
4362 </para>
4363 </section>
4365 <section id="midi-interface-interrupt-handler">
4366 <title>Interrupt Handler</title>
4367 <para>
4368 When the interrupt is allocated in
4369 <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4370 interrupt handler is automatically used, hence you don't have
4371 anything else to do than creating the mpu401 stuff. Otherwise, you
4372 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4373 <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4374 own interrupt handler when it has determined that a UART interrupt
4375 has occurred.
4376 </para>
4378 <para>
4379 In this case, you need to pass the private_data of the
4380 returned rawmidi object from
4381 <function>snd_mpu401_uart_new()</function> as the second
4382 argument of <function>snd_mpu401_uart_interrupt()</function>.
4384 <informalexample>
4385 <programlisting>
4386 <![CDATA[
4387 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4388 ]]>
4389 </programlisting>
4390 </informalexample>
4391 </para>
4392 </section>
4394 </chapter>
4397 <!-- ****************************************************** -->
4398 <!-- RawMIDI Interface -->
4399 <!-- ****************************************************** -->
4400 <chapter id="rawmidi-interface">
4401 <title>RawMIDI Interface</title>
4403 <section id="rawmidi-interface-overview">
4404 <title>Overview</title>
4406 <para>
4407 The raw MIDI interface is used for hardware MIDI ports that can
4408 be accessed as a byte stream. It is not used for synthesizer
4409 chips that do not directly understand MIDI.
4410 </para>
4412 <para>
4413 ALSA handles file and buffer management. All you have to do is
4414 to write some code to move data between the buffer and the
4415 hardware.
4416 </para>
4418 <para>
4419 The rawmidi API is defined in
4420 <filename><sound/rawmidi.h></filename>.
4421 </para>
4422 </section>
4424 <section id="rawmidi-interface-constructor">
4425 <title>Constructor</title>
4427 <para>
4428 To create a rawmidi device, call the
4429 <function>snd_rawmidi_new</function> function:
4430 <informalexample>
4431 <programlisting>
4432 <![CDATA[
4433 struct snd_rawmidi *rmidi;
4434 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4435 if (err < 0)
4436 return err;
4437 rmidi->private_data = chip;
4438 strcpy(rmidi->name, "My MIDI");
4439 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4440 SNDRV_RAWMIDI_INFO_INPUT |
4441 SNDRV_RAWMIDI_INFO_DUPLEX;
4442 ]]>
4443 </programlisting>
4444 </informalexample>
4445 </para>
4447 <para>
4448 The first argument is the card pointer, the second argument is
4449 the ID string.
4450 </para>
4452 <para>
4453 The third argument is the index of this component. You can
4454 create up to 8 rawmidi devices.
4455 </para>
4457 <para>
4458 The fourth and fifth arguments are the number of output and
4459 input substreams, respectively, of this device (a substream is
4460 the equivalent of a MIDI port).
4461 </para>
4463 <para>
4464 Set the <structfield>info_flags</structfield> field to specify
4465 the capabilities of the device.
4466 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4467 at least one output port,
4468 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4469 least one input port,
4470 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4471 can handle output and input at the same time.
4472 </para>
4474 <para>
4475 After the rawmidi device is created, you need to set the
4476 operators (callbacks) for each substream. There are helper
4477 functions to set the operators for all the substreams of a device:
4478 <informalexample>
4479 <programlisting>
4480 <![CDATA[
4481 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4482 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4483 ]]>
4484 </programlisting>
4485 </informalexample>
4486 </para>
4488 <para>
4489 The operators are usually defined like this:
4490 <informalexample>
4491 <programlisting>
4492 <![CDATA[
4493 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4494 .open = snd_mymidi_output_open,
4495 .close = snd_mymidi_output_close,
4496 .trigger = snd_mymidi_output_trigger,
4497 };
4498 ]]>
4499 </programlisting>
4500 </informalexample>
4501 These callbacks are explained in the <link
4502 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4503 section.
4504 </para>
4506 <para>
4507 If there are more than one substream, you should give a
4508 unique name to each of them:
4509 <informalexample>
4510 <programlisting>
4511 <![CDATA[
4512 struct snd_rawmidi_substream *substream;
4513 list_for_each_entry(substream,
4514 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4515 list {
4516 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4517 }
4518 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4519 ]]>
4520 </programlisting>
4521 </informalexample>
4522 </para>
4523 </section>
4525 <section id="rawmidi-interface-callbacks">
4526 <title>Callbacks</title>
4528 <para>
4529 In all the callbacks, the private data that you've set for the
4530 rawmidi device can be accessed as
4531 substream->rmidi->private_data.
4532 <!-- <code> isn't available before DocBook 4.3 -->
4533 </para>
4535 <para>
4536 If there is more than one port, your callbacks can determine the
4537 port index from the struct snd_rawmidi_substream data passed to each
4538 callback:
4539 <informalexample>
4540 <programlisting>
4541 <![CDATA[
4542 struct snd_rawmidi_substream *substream;
4543 int index = substream->number;
4544 ]]>
4545 </programlisting>
4546 </informalexample>
4547 </para>
4549 <section id="rawmidi-interface-op-open">
4550 <title><function>open</function> callback</title>
4552 <informalexample>
4553 <programlisting>
4554 <![CDATA[
4555 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4556 ]]>
4557 </programlisting>
4558 </informalexample>
4560 <para>
4561 This is called when a substream is opened.
4562 You can initialize the hardware here, but you shouldn't
4563 start transmitting/receiving data yet.
4564 </para>
4565 </section>
4567 <section id="rawmidi-interface-op-close">
4568 <title><function>close</function> callback</title>
4570 <informalexample>
4571 <programlisting>
4572 <![CDATA[
4573 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4574 ]]>
4575 </programlisting>
4576 </informalexample>
4578 <para>
4579 Guess what.
4580 </para>
4582 <para>
4583 The <function>open</function> and <function>close</function>
4584 callbacks of a rawmidi device are serialized with a mutex,
4585 and can sleep.
4586 </para>
4587 </section>
4589 <section id="rawmidi-interface-op-trigger-out">
4590 <title><function>trigger</function> callback for output
4591 substreams</title>
4593 <informalexample>
4594 <programlisting>
4595 <![CDATA[
4596 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4597 ]]>
4598 </programlisting>
4599 </informalexample>
4601 <para>
4602 This is called with a nonzero <parameter>up</parameter>
4603 parameter when there is some data in the substream buffer that
4604 must be transmitted.
4605 </para>
4607 <para>
4608 To read data from the buffer, call
4609 <function>snd_rawmidi_transmit_peek</function>. It will
4610 return the number of bytes that have been read; this will be
4611 less than the number of bytes requested when there are no more
4612 data in the buffer.
4613 After the data have been transmitted successfully, call
4614 <function>snd_rawmidi_transmit_ack</function> to remove the
4615 data from the substream buffer:
4616 <informalexample>
4617 <programlisting>
4618 <![CDATA[
4619 unsigned char data;
4620 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4621 if (snd_mychip_try_to_transmit(data))
4622 snd_rawmidi_transmit_ack(substream, 1);
4623 else
4624 break; /* hardware FIFO full */
4625 }
4626 ]]>
4627 </programlisting>
4628 </informalexample>
4629 </para>
4631 <para>
4632 If you know beforehand that the hardware will accept data, you
4633 can use the <function>snd_rawmidi_transmit</function> function
4634 which reads some data and removes them from the buffer at once:
4635 <informalexample>
4636 <programlisting>
4637 <![CDATA[
4638 while (snd_mychip_transmit_possible()) {
4639 unsigned char data;
4640 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4641 break; /* no more data */
4642 snd_mychip_transmit(data);
4643 }
4644 ]]>
4645 </programlisting>
4646 </informalexample>
4647 </para>
4649 <para>
4650 If you know beforehand how many bytes you can accept, you can
4651 use a buffer size greater than one with the
4652 <function>snd_rawmidi_transmit*</function> functions.
4653 </para>
4655 <para>
4656 The <function>trigger</function> callback must not sleep. If
4657 the hardware FIFO is full before the substream buffer has been
4658 emptied, you have to continue transmitting data later, either
4659 in an interrupt handler, or with a timer if the hardware
4660 doesn't have a MIDI transmit interrupt.
4661 </para>
4663 <para>
4664 The <function>trigger</function> callback is called with a
4665 zero <parameter>up</parameter> parameter when the transmission
4666 of data should be aborted.
4667 </para>
4668 </section>
4670 <section id="rawmidi-interface-op-trigger-in">
4671 <title><function>trigger</function> callback for input
4672 substreams</title>
4674 <informalexample>
4675 <programlisting>
4676 <![CDATA[
4677 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4678 ]]>
4679 </programlisting>
4680 </informalexample>
4682 <para>
4683 This is called with a nonzero <parameter>up</parameter>
4684 parameter to enable receiving data, or with a zero
4685 <parameter>up</parameter> parameter do disable receiving data.
4686 </para>
4688 <para>
4689 The <function>trigger</function> callback must not sleep; the
4690 actual reading of data from the device is usually done in an
4691 interrupt handler.
4692 </para>
4694 <para>
4695 When data reception is enabled, your interrupt handler should
4696 call <function>snd_rawmidi_receive</function> for all received
4697 data:
4698 <informalexample>
4699 <programlisting>
4700 <![CDATA[
4701 void snd_mychip_midi_interrupt(...)
4702 {
4703 while (mychip_midi_available()) {
4704 unsigned char data;
4705 data = mychip_midi_read();
4706 snd_rawmidi_receive(substream, &data, 1);
4707 }
4708 }
4709 ]]>
4710 </programlisting>
4711 </informalexample>
4712 </para>
4713 </section>
4715 <section id="rawmidi-interface-op-drain">
4716 <title><function>drain</function> callback</title>
4718 <informalexample>
4719 <programlisting>
4720 <![CDATA[
4721 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4722 ]]>
4723 </programlisting>
4724 </informalexample>
4726 <para>
4727 This is only used with output substreams. This function should wait
4728 until all data read from the substream buffer have been transmitted.
4729 This ensures that the device can be closed and the driver unloaded
4730 without losing data.
4731 </para>
4733 <para>
4734 This callback is optional. If you do not set
4735 <structfield>drain</structfield> in the struct snd_rawmidi_ops
4736 structure, ALSA will simply wait for 50 milliseconds
4737 instead.
4738 </para>
4739 </section>
4740 </section>
4742 </chapter>
4745 <!-- ****************************************************** -->
4746 <!-- Miscellaneous Devices -->
4747 <!-- ****************************************************** -->
4748 <chapter id="misc-devices">
4749 <title>Miscellaneous Devices</title>
4751 <section id="misc-devices-opl3">
4752 <title>FM OPL3</title>
4753 <para>
4754 The FM OPL3 is still used in many chips (mainly for backward
4755 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4756 OPL3 API is defined in
4757 <filename><sound/opl3.h></filename>.
4758 </para>
4760 <para>
4761 FM registers can be directly accessed through the direct-FM API,
4762 defined in <filename><sound/asound_fm.h></filename>. In
4763 ALSA native mode, FM registers are accessed through
4764 the Hardware-Dependent Device direct-FM extension API, whereas in
4765 OSS compatible mode, FM registers can be accessed with the OSS
4766 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
4767 </para>
4769 <para>
4770 To create the OPL3 component, you have two functions to
4771 call. The first one is a constructor for the <type>opl3_t</type>
4772 instance.
4774 <informalexample>
4775 <programlisting>
4776 <![CDATA[
4777 struct snd_opl3 *opl3;
4778 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4779 integrated, &opl3);
4780 ]]>
4781 </programlisting>
4782 </informalexample>
4783 </para>
4785 <para>
4786 The first argument is the card pointer, the second one is the
4787 left port address, and the third is the right port address. In
4788 most cases, the right port is placed at the left port + 2.
4789 </para>
4791 <para>
4792 The fourth argument is the hardware type.
4793 </para>
4795 <para>
4796 When the left and right ports have been already allocated by
4797 the card driver, pass non-zero to the fifth argument
4798 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4799 allocate the specified ports by itself.
4800 </para>
4802 <para>
4803 When the accessing the hardware requires special method
4804 instead of the standard I/O access, you can create opl3 instance
4805 separately with <function>snd_opl3_new()</function>.
4807 <informalexample>
4808 <programlisting>
4809 <![CDATA[
4810 struct snd_opl3 *opl3;
4811 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4812 ]]>
4813 </programlisting>
4814 </informalexample>
4815 </para>
4817 <para>
4818 Then set <structfield>command</structfield>,
4819 <structfield>private_data</structfield> and
4820 <structfield>private_free</structfield> for the private
4821 access function, the private data and the destructor.
4822 The l_port and r_port are not necessarily set. Only the
4823 command must be set properly. You can retrieve the data
4824 from the opl3->private_data field.
4825 </para>
4827 <para>
4828 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4829 call <function>snd_opl3_init()</function> to initialize the chip to the
4830 proper state. Note that <function>snd_opl3_create()</function> always
4831 calls it internally.
4832 </para>
4834 <para>
4835 If the opl3 instance is created successfully, then create a
4836 hwdep device for this opl3.
4838 <informalexample>
4839 <programlisting>
4840 <![CDATA[
4841 struct snd_hwdep *opl3hwdep;
4842 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4843 ]]>
4844 </programlisting>
4845 </informalexample>
4846 </para>
4848 <para>
4849 The first argument is the <type>opl3_t</type> instance you
4850 created, and the second is the index number, usually 0.
4851 </para>
4853 <para>
4854 The third argument is the index-offset for the sequencer
4855 client assigned to the OPL3 port. When there is an MPU401-UART,
4856 give 1 for here (UART always takes 0).
4857 </para>
4858 </section>
4860 <section id="misc-devices-hardware-dependent">
4861 <title>Hardware-Dependent Devices</title>
4862 <para>
4863 Some chips need user-space access for special
4864 controls or for loading the micro code. In such a case, you can
4865 create a hwdep (hardware-dependent) device. The hwdep API is
4866 defined in <filename><sound/hwdep.h></filename>. You can
4867 find examples in opl3 driver or
4868 <filename>isa/sb/sb16_csp.c</filename>.
4869 </para>
4871 <para>
4872 The creation of the <type>hwdep</type> instance is done via
4873 <function>snd_hwdep_new()</function>.
4875 <informalexample>
4876 <programlisting>
4877 <![CDATA[
4878 struct snd_hwdep *hw;
4879 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4880 ]]>
4881 </programlisting>
4882 </informalexample>
4884 where the third argument is the index number.
4885 </para>
4887 <para>
4888 You can then pass any pointer value to the
4889 <parameter>private_data</parameter>.
4890 If you assign a private data, you should define the
4891 destructor, too. The destructor function is set in
4892 the <structfield>private_free</structfield> field.
4894 <informalexample>
4895 <programlisting>
4896 <![CDATA[
4897 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4898 hw->private_data = p;
4899 hw->private_free = mydata_free;
4900 ]]>
4901 </programlisting>
4902 </informalexample>
4904 and the implementation of the destructor would be:
4906 <informalexample>
4907 <programlisting>
4908 <![CDATA[
4909 static void mydata_free(struct snd_hwdep *hw)
4910 {
4911 struct mydata *p = hw->private_data;
4912 kfree(p);
4913 }
4914 ]]>
4915 </programlisting>
4916 </informalexample>
4917 </para>
4919 <para>
4920 The arbitrary file operations can be defined for this
4921 instance. The file operators are defined in
4922 the <parameter>ops</parameter> table. For example, assume that
4923 this chip needs an ioctl.
4925 <informalexample>
4926 <programlisting>
4927 <![CDATA[
4928 hw->ops.open = mydata_open;
4929 hw->ops.ioctl = mydata_ioctl;
4930 hw->ops.release = mydata_release;
4931 ]]>
4932 </programlisting>
4933 </informalexample>
4935 And implement the callback functions as you like.
4936 </para>
4937 </section>
4939 <section id="misc-devices-IEC958">
4940 <title>IEC958 (S/PDIF)</title>
4941 <para>
4942 Usually the controls for IEC958 devices are implemented via
4943 the control interface. There is a macro to compose a name string for
4944 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4945 defined in <filename><include/asound.h></filename>.
4946 </para>
4948 <para>
4949 There are some standard controls for IEC958 status bits. These
4950 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4951 and the size of element is fixed as 4 bytes array
4952 (value.iec958.status[x]). For the <structfield>info</structfield>
4953 callback, you don't specify
4954 the value field for this type (the count field must be set,
4955 though).
4956 </para>
4958 <para>
4959 <quote>IEC958 Playback Con Mask</quote> is used to return the
4960 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4961 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4962 professional mode. They are read-only controls, and are defined
4963 as MIXER controls (iface =
4964 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4965 </para>
4967 <para>
4968 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4969 defined for getting and setting the current default IEC958
4970 bits. Note that this one is usually defined as a PCM control
4971 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4972 although in some places it's defined as a MIXER control.
4973 </para>
4975 <para>
4976 In addition, you can define the control switches to
4977 enable/disable or to set the raw bit mode. The implementation
4978 will depend on the chip, but the control should be named as
4979 <quote>IEC958 xxx</quote>, preferably using
4980 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
4981 </para>
4983 <para>
4984 You can find several cases, for example,
4985 <filename>pci/emu10k1</filename>,
4986 <filename>pci/ice1712</filename>, or
4987 <filename>pci/cmipci.c</filename>.
4988 </para>
4989 </section>
4991 </chapter>
4994 <!-- ****************************************************** -->
4995 <!-- Buffer and Memory Management -->
4996 <!-- ****************************************************** -->
4997 <chapter id="buffer-and-memory">
4998 <title>Buffer and Memory Management</title>
5000 <section id="buffer-and-memory-buffer-types">
5001 <title>Buffer Types</title>
5002 <para>
5003 ALSA provides several different buffer allocation functions
5004 depending on the bus and the architecture. All these have a
5005 consistent API. The allocation of physically-contiguous pages is
5006 done via
5007 <function>snd_malloc_xxx_pages()</function> function, where xxx
5008 is the bus type.
5009 </para>
5011 <para>
5012 The allocation of pages with fallback is
5013 <function>snd_malloc_xxx_pages_fallback()</function>. This
5014 function tries to allocate the specified pages but if the pages
5015 are not available, it tries to reduce the page sizes until
5016 enough space is found.
5017 </para>
5019 <para>
5020 The release the pages, call
5021 <function>snd_free_xxx_pages()</function> function.
5022 </para>
5024 <para>
5025 Usually, ALSA drivers try to allocate and reserve
5026 a large contiguous physical space
5027 at the time the module is loaded for the later use.
5028 This is called <quote>pre-allocation</quote>.
5029 As already written, you can call the following function at
5030 pcm instance construction time (in the case of PCI bus).
5032 <informalexample>
5033 <programlisting>
5034 <![CDATA[
5035 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5036 snd_dma_pci_data(pci), size, max);
5037 ]]>
5038 </programlisting>
5039 </informalexample>
5041 where <parameter>size</parameter> is the byte size to be
5042 pre-allocated and the <parameter>max</parameter> is the maximum
5043 size to be changed via the <filename>prealloc</filename> proc file.
5044 The allocator will try to get an area as large as possible
5045 within the given size.
5046 </para>
5048 <para>
5049 The second argument (type) and the third argument (device pointer)
5050 are dependent on the bus.
5051 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5052 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5053 For the continuous buffer unrelated to the bus can be pre-allocated
5054 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5055 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5056 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5057 use.
5058 For the PCI scatter-gather buffers, use
5059 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5060 <function>snd_dma_pci_data(pci)</function>
5061 (see the
5062 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5063 </citetitle></link> section).
5064 </para>
5066 <para>
5067 Once the buffer is pre-allocated, you can use the
5068 allocator in the <structfield>hw_params</structfield> callback:
5070 <informalexample>
5071 <programlisting>
5072 <![CDATA[
5073 snd_pcm_lib_malloc_pages(substream, size);
5074 ]]>
5075 </programlisting>
5076 </informalexample>
5078 Note that you have to pre-allocate to use this function.
5079 </para>
5080 </section>
5082 <section id="buffer-and-memory-external-hardware">
5083 <title>External Hardware Buffers</title>
5084 <para>
5085 Some chips have their own hardware buffers and the DMA
5086 transfer from the host memory is not available. In such a case,
5087 you need to either 1) copy/set the audio data directly to the
5088 external hardware buffer, or 2) make an intermediate buffer and
5089 copy/set the data from it to the external hardware buffer in
5090 interrupts (or in tasklets, preferably).
5091 </para>
5093 <para>
5094 The first case works fine if the external hardware buffer is large
5095 enough. This method doesn't need any extra buffers and thus is
5096 more effective. You need to define the
5097 <structfield>copy</structfield> and
5098 <structfield>silence</structfield> callbacks for
5099 the data transfer. However, there is a drawback: it cannot
5100 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5101 wavetable PCM.
5102 </para>
5104 <para>
5105 The second case allows for mmap on the buffer, although you have
5106 to handle an interrupt or a tasklet to transfer the data
5107 from the intermediate buffer to the hardware buffer. You can find an
5108 example in the vxpocket driver.
5109 </para>
5111 <para>
5112 Another case is when the chip uses a PCI memory-map
5113 region for the buffer instead of the host memory. In this case,
5114 mmap is available only on certain architectures like the Intel one.
5115 In non-mmap mode, the data cannot be transferred as in the normal
5116 way. Thus you need to define the <structfield>copy</structfield> and
5117 <structfield>silence</structfield> callbacks as well,
5118 as in the cases above. The examples are found in
5119 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5120 </para>
5122 <para>
5123 The implementation of the <structfield>copy</structfield> and
5124 <structfield>silence</structfield> callbacks depends upon
5125 whether the hardware supports interleaved or non-interleaved
5126 samples. The <structfield>copy</structfield> callback is
5127 defined like below, a bit
5128 differently depending whether the direction is playback or
5129 capture:
5131 <informalexample>
5132 <programlisting>
5133 <![CDATA[
5134 static int playback_copy(struct snd_pcm_substream *substream, int channel,
5135 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5136 static int capture_copy(struct snd_pcm_substream *substream, int channel,
5137 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5138 ]]>
5139 </programlisting>
5140 </informalexample>
5141 </para>
5143 <para>
5144 In the case of interleaved samples, the second argument
5145 (<parameter>channel</parameter>) is not used. The third argument
5146 (<parameter>pos</parameter>) points the
5147 current position offset in frames.
5148 </para>
5150 <para>
5151 The meaning of the fourth argument is different between
5152 playback and capture. For playback, it holds the source data
5153 pointer, and for capture, it's the destination data pointer.
5154 </para>
5156 <para>
5157 The last argument is the number of frames to be copied.
5158 </para>
5160 <para>
5161 What you have to do in this callback is again different
5162 between playback and capture directions. In the
5163 playback case, you copy the given amount of data
5164 (<parameter>count</parameter>) at the specified pointer
5165 (<parameter>src</parameter>) to the specified offset
5166 (<parameter>pos</parameter>) on the hardware buffer. When
5167 coded like memcpy-like way, the copy would be like:
5169 <informalexample>
5170 <programlisting>
5171 <![CDATA[
5172 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5173 frames_to_bytes(runtime, count));
5174 ]]>
5175 </programlisting>
5176 </informalexample>
5177 </para>
5179 <para>
5180 For the capture direction, you copy the given amount of
5181 data (<parameter>count</parameter>) at the specified offset
5182 (<parameter>pos</parameter>) on the hardware buffer to the
5183 specified pointer (<parameter>dst</parameter>).
5185 <informalexample>
5186 <programlisting>
5187 <![CDATA[
5188 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5189 frames_to_bytes(runtime, count));
5190 ]]>
5191 </programlisting>
5192 </informalexample>
5194 Note that both the position and the amount of data are given
5195 in frames.
5196 </para>
5198 <para>
5199 In the case of non-interleaved samples, the implementation
5200 will be a bit more complicated.
5201 </para>
5203 <para>
5204 You need to check the channel argument, and if it's -1, copy
5205 the whole channels. Otherwise, you have to copy only the
5206 specified channel. Please check
5207 <filename>isa/gus/gus_pcm.c</filename> as an example.
5208 </para>
5210 <para>
5211 The <structfield>silence</structfield> callback is also
5212 implemented in a similar way.
5214 <informalexample>
5215 <programlisting>
5216 <![CDATA[
5217 static int silence(struct snd_pcm_substream *substream, int channel,
5218 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5219 ]]>
5220 </programlisting>
5221 </informalexample>
5222 </para>
5224 <para>
5225 The meanings of arguments are the same as in the
5226 <structfield>copy</structfield>
5227 callback, although there is no <parameter>src/dst</parameter>
5228 argument. In the case of interleaved samples, the channel
5229 argument has no meaning, as well as on
5230 <structfield>copy</structfield> callback.
5231 </para>
5233 <para>
5234 The role of <structfield>silence</structfield> callback is to
5235 set the given amount
5236 (<parameter>count</parameter>) of silence data at the
5237 specified offset (<parameter>pos</parameter>) on the hardware
5238 buffer. Suppose that the data format is signed (that is, the
5239 silent-data is 0), and the implementation using a memset-like
5240 function would be like:
5242 <informalexample>
5243 <programlisting>
5244 <![CDATA[
5245 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5246 frames_to_bytes(runtime, count));
5247 ]]>
5248 </programlisting>
5249 </informalexample>
5250 </para>
5252 <para>
5253 In the case of non-interleaved samples, again, the
5254 implementation becomes a bit more complicated. See, for example,
5255 <filename>isa/gus/gus_pcm.c</filename>.
5256 </para>
5257 </section>
5259 <section id="buffer-and-memory-non-contiguous">
5260 <title>Non-Contiguous Buffers</title>
5261 <para>
5262 If your hardware supports the page table as in emu10k1 or the
5263 buffer descriptors as in via82xx, you can use the scatter-gather
5264 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5265 The API is provided in <filename><sound/pcm.h></filename>.
5266 </para>
5268 <para>
5269 For creating the SG-buffer handler, call
5270 <function>snd_pcm_lib_preallocate_pages()</function> or
5271 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5272 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5273 in the PCM constructor like other PCI pre-allocator.
5274 You need to pass <function>snd_dma_pci_data(pci)</function>,
5275 where pci is the struct <structname>pci_dev</structname> pointer
5276 of the chip as well.
5277 The <type>struct snd_sg_buf</type> instance is created as
5278 substream->dma_private. You can cast
5279 the pointer like:
5281 <informalexample>
5282 <programlisting>
5283 <![CDATA[
5284 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5285 ]]>
5286 </programlisting>
5287 </informalexample>
5288 </para>
5290 <para>
5291 Then call <function>snd_pcm_lib_malloc_pages()</function>
5292 in the <structfield>hw_params</structfield> callback
5293 as well as in the case of normal PCI buffer.
5294 The SG-buffer handler will allocate the non-contiguous kernel
5295 pages of the given size and map them onto the virtually contiguous
5296 memory. The virtual pointer is addressed in runtime->dma_area.
5297 The physical address (runtime->dma_addr) is set to zero,
5298 because the buffer is physically non-contiguous.
5299 The physical address table is set up in sgbuf->table.
5300 You can get the physical address at a certain offset via
5301 <function>snd_pcm_sgbuf_get_addr()</function>.
5302 </para>
5304 <para>
5305 When a SG-handler is used, you need to set
5306 <function>snd_pcm_sgbuf_ops_page</function> as
5307 the <structfield>page</structfield> callback.
5308 (See <link linkend="pcm-interface-operators-page-callback">
5309 <citetitle>page callback section</citetitle></link>.)
5310 </para>
5312 <para>
5313 To release the data, call
5314 <function>snd_pcm_lib_free_pages()</function> in the
5315 <structfield>hw_free</structfield> callback as usual.
5316 </para>
5317 </section>
5319 <section id="buffer-and-memory-vmalloced">
5320 <title>Vmalloc'ed Buffers</title>
5321 <para>
5322 It's possible to use a buffer allocated via
5323 <function>vmalloc</function>, for example, for an intermediate
5324 buffer. Since the allocated pages are not contiguous, you need
5325 to set the <structfield>page</structfield> callback to obtain
5326 the physical address at every offset.
5327 </para>
5329 <para>
5330 The implementation of <structfield>page</structfield> callback
5331 would be like this:
5333 <informalexample>
5334 <programlisting>
5335 <![CDATA[
5336 #include <linux/vmalloc.h>
5338 /* get the physical page pointer on the given offset */
5339 static struct page *mychip_page(struct snd_pcm_substream *substream,
5340 unsigned long offset)
5341 {
5342 void *pageptr = substream->runtime->dma_area + offset;
5343 return vmalloc_to_page(pageptr);
5344 }
5345 ]]>
5346 </programlisting>
5347 </informalexample>
5348 </para>
5349 </section>
5351 </chapter>
5354 <!-- ****************************************************** -->
5355 <!-- Proc Interface -->
5356 <!-- ****************************************************** -->
5357 <chapter id="proc-interface">
5358 <title>Proc Interface</title>
5359 <para>
5360 ALSA provides an easy interface for procfs. The proc files are
5361 very useful for debugging. I recommend you set up proc files if
5362 you write a driver and want to get a running status or register
5363 dumps. The API is found in
5364 <filename><sound/info.h></filename>.
5365 </para>
5367 <para>
5368 To create a proc file, call
5369 <function>snd_card_proc_new()</function>.
5371 <informalexample>
5372 <programlisting>
5373 <![CDATA[
5374 struct snd_info_entry *entry;
5375 int err = snd_card_proc_new(card, "my-file", &entry);
5376 ]]>
5377 </programlisting>
5378 </informalexample>
5380 where the second argument specifies the name of the proc file to be
5381 created. The above example will create a file
5382 <filename>my-file</filename> under the card directory,
5383 e.g. <filename>/proc/asound/card0/my-file</filename>.
5384 </para>
5386 <para>
5387 Like other components, the proc entry created via
5388 <function>snd_card_proc_new()</function> will be registered and
5389 released automatically in the card registration and release
5390 functions.
5391 </para>
5393 <para>
5394 When the creation is successful, the function stores a new
5395 instance in the pointer given in the third argument.
5396 It is initialized as a text proc file for read only. To use
5397 this proc file as a read-only text file as it is, set the read
5398 callback with a private data via
5399 <function>snd_info_set_text_ops()</function>.
5401 <informalexample>
5402 <programlisting>
5403 <![CDATA[
5404 snd_info_set_text_ops(entry, chip, my_proc_read);
5405 ]]>
5406 </programlisting>
5407 </informalexample>
5409 where the second argument (<parameter>chip</parameter>) is the
5410 private data to be used in the callbacks. The third parameter
5411 specifies the read buffer size and the fourth
5412 (<parameter>my_proc_read</parameter>) is the callback function, which
5413 is defined like
5415 <informalexample>
5416 <programlisting>
5417 <![CDATA[
5418 static void my_proc_read(struct snd_info_entry *entry,
5419 struct snd_info_buffer *buffer);
5420 ]]>
5421 </programlisting>
5422 </informalexample>
5424 </para>
5426 <para>
5427 In the read callback, use <function>snd_iprintf()</function> for
5428 output strings, which works just like normal
5429 <function>printf()</function>. For example,
5431 <informalexample>
5432 <programlisting>
5433 <![CDATA[
5434 static void my_proc_read(struct snd_info_entry *entry,
5435 struct snd_info_buffer *buffer)
5436 {
5437 struct my_chip *chip = entry->private_data;
5439 snd_iprintf(buffer, "This is my chip!\n");
5440 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5441 }
5442 ]]>
5443 </programlisting>
5444 </informalexample>
5445 </para>
5447 <para>
5448 The file permissions can be changed afterwards. As default, it's
5449 set as read only for all users. If you want to add write
5450 permission for the user (root as default), do as follows:
5452 <informalexample>
5453 <programlisting>
5454 <![CDATA[
5455 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5456 ]]>
5457 </programlisting>
5458 </informalexample>
5460 and set the write buffer size and the callback
5462 <informalexample>
5463 <programlisting>
5464 <![CDATA[
5465 entry->c.text.write = my_proc_write;
5466 ]]>
5467 </programlisting>
5468 </informalexample>
5469 </para>
5471 <para>
5472 For the write callback, you can use
5473 <function>snd_info_get_line()</function> to get a text line, and
5474 <function>snd_info_get_str()</function> to retrieve a string from
5475 the line. Some examples are found in
5476 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5477 <filename>pcm_oss.c</filename>.
5478 </para>
5480 <para>
5481 For a raw-data proc-file, set the attributes as follows:
5483 <informalexample>
5484 <programlisting>
5485 <![CDATA[
5486 static struct snd_info_entry_ops my_file_io_ops = {
5487 .read = my_file_io_read,
5488 };
5490 entry->content = SNDRV_INFO_CONTENT_DATA;
5491 entry->private_data = chip;
5492 entry->c.ops = &my_file_io_ops;
5493 entry->size = 4096;
5494 entry->mode = S_IFREG | S_IRUGO;
5495 ]]>
5496 </programlisting>
5497 </informalexample>
5499 For the raw data, <structfield>size</structfield> field must be
5500 set properly. This specifies the maximum size of the proc file access.
5501 </para>
5503 <para>
5504 The read/write callbacks of raw mode are more direct than the text mode.
5505 You need to use a low-level I/O functions such as
5506 <function>copy_from/to_user()</function> to transfer the
5507 data.
5509 <informalexample>
5510 <programlisting>
5511 <![CDATA[
5512 static ssize_t my_file_io_read(struct snd_info_entry *entry,
5513 void *file_private_data,
5514 struct file *file,
5515 char *buf,
5516 size_t count,
5517 loff_t pos)
5518 {
5519 if (copy_to_user(buf, local_data + pos, count))
5520 return -EFAULT;
5521 return count;
5522 }
5523 ]]>
5524 </programlisting>
5525 </informalexample>
5527 If the size of the info entry has been set up properly,
5528 <structfield>count</structfield> and <structfield>pos</structfield> are
5529 guaranteed to fit within 0 and the given size.
5530 You don't have to check the range in the callbacks unless any
5531 other condition is required.
5533 </para>
5535 </chapter>
5538 <!-- ****************************************************** -->
5539 <!-- Power Management -->
5540 <!-- ****************************************************** -->
5541 <chapter id="power-management">
5542 <title>Power Management</title>
5543 <para>
5544 If the chip is supposed to work with suspend/resume
5545 functions, you need to add power-management code to the
5546 driver. The additional code for power-management should be
5547 <function>ifdef</function>'ed with
5548 <constant>CONFIG_PM</constant>.
5549 </para>
5551 <para>
5552 If the driver <emphasis>fully</emphasis> supports suspend/resume
5553 that is, the device can be
5554 properly resumed to its state when suspend was called,
5555 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5556 in the pcm info field. Usually, this is possible when the
5557 registers of the chip can be safely saved and restored to
5558 RAM. If this is set, the trigger callback is called with
5559 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5560 callback completes.
5561 </para>
5563 <para>
5564 Even if the driver doesn't support PM fully but
5565 partial suspend/resume is still possible, it's still worthy to
5566 implement suspend/resume callbacks. In such a case, applications
5567 would reset the status by calling
5568 <function>snd_pcm_prepare()</function> and restart the stream
5569 appropriately. Hence, you can define suspend/resume callbacks
5570 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5571 info flag to the PCM.
5572 </para>
5574 <para>
5575 Note that the trigger with SUSPEND can always be called when
5576 <function>snd_pcm_suspend_all</function> is called,
5577 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5578 The <constant>RESUME</constant> flag affects only the behavior
5579 of <function>snd_pcm_resume()</function>.
5580 (Thus, in theory,
5581 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5582 to be handled in the trigger callback when no
5583 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
5584 it's better to keep it for compatibility reasons.)
5585 </para>
5586 <para>
5587 In the earlier version of ALSA drivers, a common
5588 power-management layer was provided, but it has been removed.
5589 The driver needs to define the suspend/resume hooks according to
5590 the bus the device is connected to. In the case of PCI drivers, the
5591 callbacks look like below:
5593 <informalexample>
5594 <programlisting>
5595 <![CDATA[
5596 #ifdef CONFIG_PM
5597 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5598 {
5599 .... /* do things for suspend */
5600 return 0;
5601 }
5602 static int snd_my_resume(struct pci_dev *pci)
5603 {
5604 .... /* do things for suspend */
5605 return 0;
5606 }
5607 #endif
5608 ]]>
5609 </programlisting>
5610 </informalexample>
5611 </para>
5613 <para>
5614 The scheme of the real suspend job is as follows.
5616 <orderedlist>
5617 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5618 <listitem><para>Call <function>snd_power_change_state()</function> with
5619 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5620 power status.</para></listitem>
5621 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5622 <listitem><para>If AC97 codecs are used, call
5623 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5624 <listitem><para>Save the register values if necessary.</para></listitem>
5625 <listitem><para>Stop the hardware if necessary.</para></listitem>
5626 <listitem><para>Disable the PCI device by calling
5627 <function>pci_disable_device()</function>. Then, call
5628 <function>pci_save_state()</function> at last.</para></listitem>
5629 </orderedlist>
5630 </para>
5632 <para>
5633 A typical code would be like:
5635 <informalexample>
5636 <programlisting>
5637 <![CDATA[
5638 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5639 {
5640 /* (1) */
5641 struct snd_card *card = pci_get_drvdata(pci);
5642 struct mychip *chip = card->private_data;
5643 /* (2) */
5644 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5645 /* (3) */
5646 snd_pcm_suspend_all(chip->pcm);
5647 /* (4) */
5648 snd_ac97_suspend(chip->ac97);
5649 /* (5) */
5650 snd_mychip_save_registers(chip);
5651 /* (6) */
5652 snd_mychip_stop_hardware(chip);
5653 /* (7) */
5654 pci_disable_device(pci);
5655 pci_save_state(pci);
5656 return 0;
5657 }
5658 ]]>
5659 </programlisting>
5660 </informalexample>
5661 </para>
5663 <para>
5664 The scheme of the real resume job is as follows.
5666 <orderedlist>
5667 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5668 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5669 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5670 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5671 <listitem><para>Re-initialize the chip.</para></listitem>
5672 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5673 <listitem><para>Resume the mixer, e.g. calling
5674 <function>snd_ac97_resume()</function>.</para></listitem>
5675 <listitem><para>Restart the hardware (if any).</para></listitem>
5676 <listitem><para>Call <function>snd_power_change_state()</function> with
5677 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5678 </orderedlist>
5679 </para>
5681 <para>
5682 A typical code would be like:
5684 <informalexample>
5685 <programlisting>
5686 <![CDATA[
5687 static int mychip_resume(struct pci_dev *pci)
5688 {
5689 /* (1) */
5690 struct snd_card *card = pci_get_drvdata(pci);
5691 struct mychip *chip = card->private_data;
5692 /* (2) */
5693 pci_restore_state(pci);
5694 pci_enable_device(pci);
5695 pci_set_master(pci);
5696 /* (3) */
5697 snd_mychip_reinit_chip(chip);
5698 /* (4) */
5699 snd_mychip_restore_registers(chip);
5700 /* (5) */
5701 snd_ac97_resume(chip->ac97);
5702 /* (6) */
5703 snd_mychip_restart_chip(chip);
5704 /* (7) */
5705 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5706 return 0;
5707 }
5708 ]]>
5709 </programlisting>
5710 </informalexample>
5711 </para>
5713 <para>
5714 As shown in the above, it's better to save registers after
5715 suspending the PCM operations via
5716 <function>snd_pcm_suspend_all()</function> or
5717 <function>snd_pcm_suspend()</function>. It means that the PCM
5718 streams are already stoppped when the register snapshot is
5719 taken. But, remember that you don't have to restart the PCM
5720 stream in the resume callback. It'll be restarted via
5721 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5722 when necessary.
5723 </para>
5725 <para>
5726 OK, we have all callbacks now. Let's set them up. In the
5727 initialization of the card, make sure that you can get the chip
5728 data from the card instance, typically via
5729 <structfield>private_data</structfield> field, in case you
5730 created the chip data individually.
5732 <informalexample>
5733 <programlisting>
5734 <![CDATA[
5735 static int snd_mychip_probe(struct pci_dev *pci,
5736 const struct pci_device_id *pci_id)
5737 {
5738 ....
5739 struct snd_card *card;
5740 struct mychip *chip;
5741 int err;
5742 ....
5743 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
5744 ....
5745 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5746 ....
5747 card->private_data = chip;
5748 ....
5749 }
5750 ]]>
5751 </programlisting>
5752 </informalexample>
5754 When you created the chip data with
5755 <function>snd_card_create()</function>, it's anyway accessible
5756 via <structfield>private_data</structfield> field.
5758 <informalexample>
5759 <programlisting>
5760 <![CDATA[
5761 static int snd_mychip_probe(struct pci_dev *pci,
5762 const struct pci_device_id *pci_id)
5763 {
5764 ....
5765 struct snd_card *card;
5766 struct mychip *chip;
5767 int err;
5768 ....
5769 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
5770 sizeof(struct mychip), &card);
5771 ....
5772 chip = card->private_data;
5773 ....
5774 }
5775 ]]>
5776 </programlisting>
5777 </informalexample>
5779 </para>
5781 <para>
5782 If you need a space to save the registers, allocate the
5783 buffer for it here, too, since it would be fatal
5784 if you cannot allocate a memory in the suspend phase.
5785 The allocated buffer should be released in the corresponding
5786 destructor.
5787 </para>
5789 <para>
5790 And next, set suspend/resume callbacks to the pci_driver.
5792 <informalexample>
5793 <programlisting>
5794 <![CDATA[
5795 static struct pci_driver driver = {
5796 .name = KBUILD_MODNAME,
5797 .id_table = snd_my_ids,
5798 .probe = snd_my_probe,
5799 .remove = snd_my_remove,
5800 #ifdef CONFIG_PM
5801 .suspend = snd_my_suspend,
5802 .resume = snd_my_resume,
5803 #endif
5804 };
5805 ]]>
5806 </programlisting>
5807 </informalexample>
5808 </para>
5810 </chapter>
5813 <!-- ****************************************************** -->
5814 <!-- Module Parameters -->
5815 <!-- ****************************************************** -->
5816 <chapter id="module-parameters">
5817 <title>Module Parameters</title>
5818 <para>
5819 There are standard module options for ALSA. At least, each
5820 module should have the <parameter>index</parameter>,
5821 <parameter>id</parameter> and <parameter>enable</parameter>
5822 options.
5823 </para>
5825 <para>
5826 If the module supports multiple cards (usually up to
5827 8 = <constant>SNDRV_CARDS</constant> cards), they should be
5828 arrays. The default initial values are defined already as
5829 constants for easier programming:
5831 <informalexample>
5832 <programlisting>
5833 <![CDATA[
5834 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5835 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5836 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5837 ]]>
5838 </programlisting>
5839 </informalexample>
5840 </para>
5842 <para>
5843 If the module supports only a single card, they could be single
5844 variables, instead. <parameter>enable</parameter> option is not
5845 always necessary in this case, but it would be better to have a
5846 dummy option for compatibility.
5847 </para>
5849 <para>
5850 The module parameters must be declared with the standard
5851 <function>module_param()()</function>,
5852 <function>module_param_array()()</function> and
5853 <function>MODULE_PARM_DESC()</function> macros.
5854 </para>
5856 <para>
5857 The typical coding would be like below:
5859 <informalexample>
5860 <programlisting>
5861 <![CDATA[
5862 #define CARD_NAME "My Chip"
5864 module_param_array(index, int, NULL, 0444);
5865 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5866 module_param_array(id, charp, NULL, 0444);
5867 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5868 module_param_array(enable, bool, NULL, 0444);
5869 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5870 ]]>
5871 </programlisting>
5872 </informalexample>
5873 </para>
5875 <para>
5876 Also, don't forget to define the module description, classes,
5877 license and devices. Especially, the recent modprobe requires to
5878 define the module license as GPL, etc., otherwise the system is
5879 shown as <quote>tainted</quote>.
5881 <informalexample>
5882 <programlisting>
5883 <![CDATA[
5884 MODULE_DESCRIPTION("My Chip");
5885 MODULE_LICENSE("GPL");
5886 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5887 ]]>
5888 </programlisting>
5889 </informalexample>
5890 </para>
5892 </chapter>
5895 <!-- ****************************************************** -->
5896 <!-- How To Put Your Driver -->
5897 <!-- ****************************************************** -->
5898 <chapter id="how-to-put-your-driver">
5899 <title>How To Put Your Driver Into ALSA Tree</title>
5900 <section>
5901 <title>General</title>
5902 <para>
5903 So far, you've learned how to write the driver codes.
5904 And you might have a question now: how to put my own
5905 driver into the ALSA driver tree?
5906 Here (finally :) the standard procedure is described briefly.
5907 </para>
5909 <para>
5910 Suppose that you create a new PCI driver for the card
5911 <quote>xyz</quote>. The card module name would be
5912 snd-xyz. The new driver is usually put into the alsa-driver
5913 tree, <filename>alsa-driver/pci</filename> directory in
5914 the case of PCI cards.
5915 Then the driver is evaluated, audited and tested
5916 by developers and users. After a certain time, the driver
5917 will go to the alsa-kernel tree (to the corresponding directory,
5918 such as <filename>alsa-kernel/pci</filename>) and eventually
5919 will be integrated into the Linux 2.6 tree (the directory would be
5920 <filename>linux/sound/pci</filename>).
5921 </para>
5923 <para>
5924 In the following sections, the driver code is supposed
5925 to be put into alsa-driver tree. The two cases are covered:
5926 a driver consisting of a single source file and one consisting
5927 of several source files.
5928 </para>
5929 </section>
5931 <section>
5932 <title>Driver with A Single Source File</title>
5933 <para>
5934 <orderedlist>
5935 <listitem>
5936 <para>
5937 Modify alsa-driver/pci/Makefile
5938 </para>
5940 <para>
5941 Suppose you have a file xyz.c. Add the following
5942 two lines
5943 <informalexample>
5944 <programlisting>
5945 <![CDATA[
5946 snd-xyz-objs := xyz.o
5947 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5948 ]]>
5949 </programlisting>
5950 </informalexample>
5951 </para>
5952 </listitem>
5954 <listitem>
5955 <para>
5956 Create the Kconfig entry
5957 </para>
5959 <para>
5960 Add the new entry of Kconfig for your xyz driver.
5961 <informalexample>
5962 <programlisting>
5963 <![CDATA[
5964 config SND_XYZ
5965 tristate "Foobar XYZ"
5966 depends on SND
5967 select SND_PCM
5968 help
5969 Say Y here to include support for Foobar XYZ soundcard.
5971 To compile this driver as a module, choose M here: the module
5972 will be called snd-xyz.
5973 ]]>
5974 </programlisting>
5975 </informalexample>
5977 the line, select SND_PCM, specifies that the driver xyz supports
5978 PCM. In addition to SND_PCM, the following components are
5979 supported for select command:
5980 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5981 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5982 Add the select command for each supported component.
5983 </para>
5985 <para>
5986 Note that some selections imply the lowlevel selections.
5987 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5988 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5989 You don't need to give the lowlevel selections again.
5990 </para>
5992 <para>
5993 For the details of Kconfig script, refer to the kbuild
5994 documentation.
5995 </para>
5997 </listitem>
5999 <listitem>
6000 <para>
6001 Run cvscompile script to re-generate the configure script and
6002 build the whole stuff again.
6003 </para>
6004 </listitem>
6005 </orderedlist>
6006 </para>
6007 </section>
6009 <section>
6010 <title>Drivers with Several Source Files</title>
6011 <para>
6012 Suppose that the driver snd-xyz have several source files.
6013 They are located in the new subdirectory,
6014 pci/xyz.
6016 <orderedlist>
6017 <listitem>
6018 <para>
6019 Add a new directory (<filename>xyz</filename>) in
6020 <filename>alsa-driver/pci/Makefile</filename> as below
6022 <informalexample>
6023 <programlisting>
6024 <![CDATA[
6025 obj-$(CONFIG_SND) += xyz/
6026 ]]>
6027 </programlisting>
6028 </informalexample>
6029 </para>
6030 </listitem>
6032 <listitem>
6033 <para>
6034 Under the directory <filename>xyz</filename>, create a Makefile
6036 <example>
6037 <title>Sample Makefile for a driver xyz</title>
6038 <programlisting>
6039 <![CDATA[
6040 ifndef SND_TOPDIR
6041 SND_TOPDIR=../..
6042 endif
6044 include $(SND_TOPDIR)/toplevel.config
6045 include $(SND_TOPDIR)/Makefile.conf
6047 snd-xyz-objs := xyz.o abc.o def.o
6049 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6051 include $(SND_TOPDIR)/Rules.make
6052 ]]>
6053 </programlisting>
6054 </example>
6055 </para>
6056 </listitem>
6058 <listitem>
6059 <para>
6060 Create the Kconfig entry
6061 </para>
6063 <para>
6064 This procedure is as same as in the last section.
6065 </para>
6066 </listitem>
6068 <listitem>
6069 <para>
6070 Run cvscompile script to re-generate the configure script and
6071 build the whole stuff again.
6072 </para>
6073 </listitem>
6074 </orderedlist>
6075 </para>
6076 </section>
6078 </chapter>
6080 <!-- ****************************************************** -->
6081 <!-- Useful Functions -->
6082 <!-- ****************************************************** -->
6083 <chapter id="useful-functions">
6084 <title>Useful Functions</title>
6086 <section id="useful-functions-snd-printk">
6087 <title><function>snd_printk()</function> and friends</title>
6088 <para>
6089 ALSA provides a verbose version of the
6090 <function>printk()</function> function. If a kernel config
6091 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6092 function prints the given message together with the file name
6093 and the line of the caller. The <constant>KERN_XXX</constant>
6094 prefix is processed as
6095 well as the original <function>printk()</function> does, so it's
6096 recommended to add this prefix, e.g.
6098 <informalexample>
6099 <programlisting>
6100 <![CDATA[
6101 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6102 ]]>
6103 </programlisting>
6104 </informalexample>
6105 </para>
6107 <para>
6108 There are also <function>printk()</function>'s for
6109 debugging. <function>snd_printd()</function> can be used for
6110 general debugging purposes. If
6111 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6112 compiled, and works just like
6113 <function>snd_printk()</function>. If the ALSA is compiled
6114 without the debugging flag, it's ignored.
6115 </para>
6117 <para>
6118 <function>snd_printdd()</function> is compiled in only when
6119 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6120 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6121 even if you configure the alsa-driver with
6122 <option>--with-debug=full</option> option. You need to give
6123 explicitly <option>--with-debug=detect</option> option instead.
6124 </para>
6125 </section>
6127 <section id="useful-functions-snd-bug">
6128 <title><function>snd_BUG()</function></title>
6129 <para>
6130 It shows the <computeroutput>BUG?</computeroutput> message and
6131 stack trace as well as <function>snd_BUG_ON</function> at the point.
6132 It's useful to show that a fatal error happens there.
6133 </para>
6134 <para>
6135 When no debug flag is set, this macro is ignored.
6136 </para>
6137 </section>
6139 <section id="useful-functions-snd-bug-on">
6140 <title><function>snd_BUG_ON()</function></title>
6141 <para>
6142 <function>snd_BUG_ON()</function> macro is similar with
6143 <function>WARN_ON()</function> macro. For example,
6145 <informalexample>
6146 <programlisting>
6147 <![CDATA[
6148 snd_BUG_ON(!pointer);
6149 ]]>
6150 </programlisting>
6151 </informalexample>
6153 or it can be used as the condition,
6154 <informalexample>
6155 <programlisting>
6156 <![CDATA[
6157 if (snd_BUG_ON(non_zero_is_bug))
6158 return -EINVAL;
6159 ]]>
6160 </programlisting>
6161 </informalexample>
6163 </para>
6165 <para>
6166 The macro takes an conditional expression to evaluate.
6167 When <constant>CONFIG_SND_DEBUG</constant>, is set, the
6168 expression is actually evaluated. If it's non-zero, it shows
6169 the warning message such as
6170 <computeroutput>BUG? (xxx)</computeroutput>
6171 normally followed by stack trace. It returns the evaluated
6172 value.
6173 When no <constant>CONFIG_SND_DEBUG</constant> is set, this
6174 macro always returns zero.
6175 </para>
6177 </section>
6179 </chapter>
6182 <!-- ****************************************************** -->
6183 <!-- Acknowledgments -->
6184 <!-- ****************************************************** -->
6185 <chapter id="acknowledgments">
6186 <title>Acknowledgments</title>
6187 <para>
6188 I would like to thank Phil Kerr for his help for improvement and
6189 corrections of this document.
6190 </para>
6191 <para>
6192 Kevin Conder reformatted the original plain-text to the
6193 DocBook format.
6194 </para>
6195 <para>
6196 Giuliano Pochini corrected typos and contributed the example codes
6197 in the hardware constraints section.
6198 </para>
6199 </chapter>
6200 </book>