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