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