bb18115d51700abc3f3a02b1a54fffb70c23045e
[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, DMA_28BIT_MASK) < 0 ||
1127               pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 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[] __devinitdata = {
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, DMA_28BIT_MASK) < 0 ||
1240       pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 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[] __devinitdata = {
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_addr,
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 functions 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 acquire 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_value = 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_value</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, info_flags,
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         The 5th argument is bitflags for additional information.
4246         When the i/o port address above is a part of the PCI i/o
4247       region, the MPU401 i/o port might have been already allocated
4248       (reserved) by the driver itself. In such a case, pass a bit flag
4249       <constant>MPU401_INFO_INTEGRATED</constant>,
4250       and 
4251       the mpu401-uart layer will allocate the i/o ports by itself. 
4252       </para>
4253
4254         <para>
4255         When the controller supports only the input or output MIDI stream,
4256         pass <constant>MPU401_INFO_INPUT</constant> or
4257         <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4258         Then the rawmidi instance is created as a single stream.
4259         </para>
4260
4261         <para>
4262         <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4263         the access method to MMIO (via readb and writeb) instead of
4264         iob and outb.  In this case, you have to pass the iomapped address
4265         to <function>snd_mpu401_uart_new()</function>.
4266         </para>
4267
4268         <para>
4269         When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4270         stream isn't checked in the default interrupt handler.  The driver
4271         needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4272         by itself to start processing the output stream in irq handler.
4273         </para>
4274
4275       <para>
4276         Usually, the port address corresponds to the command port and
4277         port + 1 corresponds to the data port. If not, you may change
4278         the <structfield>cport</structfield> field of
4279         struct <structname>snd_mpu401</structname> manually 
4280         afterward. However, <structname>snd_mpu401</structname> pointer is not
4281         returned explicitly by
4282         <function>snd_mpu401_uart_new()</function>. You need to cast
4283         rmidi-&gt;private_data to
4284         <structname>snd_mpu401</structname> explicitly, 
4285
4286         <informalexample>
4287           <programlisting>
4288 <![CDATA[
4289   struct snd_mpu401 *mpu;
4290   mpu = rmidi->private_data;
4291 ]]>
4292           </programlisting>
4293         </informalexample>
4294
4295         and reset the cport as you like:
4296
4297         <informalexample>
4298           <programlisting>
4299 <![CDATA[
4300   mpu->cport = my_own_control_port;
4301 ]]>
4302           </programlisting>
4303         </informalexample>
4304       </para>
4305
4306       <para>
4307         The 6th argument specifies the irq number for UART. If the irq
4308       is already allocated, pass 0 to the 7th argument
4309       (<parameter>irq_flags</parameter>). Otherwise, pass the flags
4310       for irq allocation 
4311       (<constant>SA_XXX</constant> bits) to it, and the irq will be
4312       reserved by the mpu401-uart layer. If the card doesn't generates
4313       UART interrupts, pass -1 as the irq number. Then a timer
4314       interrupt will be invoked for polling. 
4315       </para>
4316     </section>
4317
4318     <section id="midi-interface-interrupt-handler">
4319       <title>Interrupt Handler</title>
4320       <para>
4321         When the interrupt is allocated in
4322       <function>snd_mpu401_uart_new()</function>, the private
4323       interrupt handler is used, hence you don't have to do nothing
4324       else than creating the mpu401 stuff. Otherwise, you have to call
4325       <function>snd_mpu401_uart_interrupt()</function> explicitly when
4326       a UART interrupt is invoked and checked in your own interrupt
4327       handler.  
4328       </para>
4329
4330       <para>
4331         In this case, you need to pass the private_data of the
4332         returned rawmidi object from
4333         <function>snd_mpu401_uart_new()</function> as the second
4334         argument of <function>snd_mpu401_uart_interrupt()</function>. 
4335
4336         <informalexample>
4337           <programlisting>
4338 <![CDATA[
4339   snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4340 ]]>
4341           </programlisting>
4342         </informalexample>
4343       </para>
4344     </section>
4345
4346   </chapter>
4347
4348
4349 <!-- ****************************************************** -->
4350 <!-- RawMIDI Interface  -->
4351 <!-- ****************************************************** -->
4352   <chapter id="rawmidi-interface">
4353     <title>RawMIDI Interface</title>
4354
4355     <section id="rawmidi-interface-overview">
4356       <title>Overview</title>
4357
4358       <para>
4359       The raw MIDI interface is used for hardware MIDI ports that can
4360       be accessed as a byte stream.  It is not used for synthesizer
4361       chips that do not directly understand MIDI.
4362       </para>
4363
4364       <para>
4365       ALSA handles file and buffer management.  All you have to do is
4366       to write some code to move data between the buffer and the
4367       hardware.
4368       </para>
4369
4370       <para>
4371       The rawmidi API is defined in
4372       <filename>&lt;sound/rawmidi.h&gt;</filename>.
4373       </para>
4374     </section>
4375
4376     <section id="rawmidi-interface-constructor">
4377       <title>Constructor</title>
4378
4379       <para>
4380       To create a rawmidi device, call the
4381       <function>snd_rawmidi_new</function> function:
4382         <informalexample>
4383           <programlisting>
4384 <![CDATA[
4385   struct snd_rawmidi *rmidi;
4386   err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4387   if (err < 0)
4388           return err;
4389   rmidi->private_data = chip;
4390   strcpy(rmidi->name, "My MIDI");
4391   rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4392                       SNDRV_RAWMIDI_INFO_INPUT |
4393                       SNDRV_RAWMIDI_INFO_DUPLEX;
4394 ]]>
4395           </programlisting>
4396         </informalexample>
4397       </para>
4398
4399       <para>
4400       The first argument is the card pointer, the second argument is
4401       the ID string.
4402       </para>
4403
4404       <para>
4405       The third argument is the index of this component.  You can
4406       create up to 8 rawmidi devices.
4407       </para>
4408
4409       <para>
4410       The fourth and fifth arguments are the number of output and
4411       input substreams, respectively, of this device.  (A substream is
4412       the equivalent of a MIDI port.)
4413       </para>
4414
4415       <para>
4416       Set the <structfield>info_flags</structfield> field to specify
4417       the capabilities of the device.
4418       Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4419       at least one output port,
4420       <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4421       least one input port,
4422       and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4423       can handle output and input at the same time.
4424       </para>
4425
4426       <para>
4427       After the rawmidi device is created, you need to set the
4428       operators (callbacks) for each substream.  There are helper
4429       functions to set the operators for all substream of a device:
4430         <informalexample>
4431           <programlisting>
4432 <![CDATA[
4433   snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4434   snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4435 ]]>
4436           </programlisting>
4437         </informalexample>
4438       </para>
4439
4440       <para>
4441       The operators are usually defined like this:
4442         <informalexample>
4443           <programlisting>
4444 <![CDATA[
4445   static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4446           .open =    snd_mymidi_output_open,
4447           .close =   snd_mymidi_output_close,
4448           .trigger = snd_mymidi_output_trigger,
4449   };
4450 ]]>
4451           </programlisting>
4452         </informalexample>
4453       These callbacks are explained in the <link
4454       linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4455       section.
4456       </para>
4457
4458       <para>
4459       If there is more than one substream, you should give each one a
4460       unique name:
4461         <informalexample>
4462           <programlisting>
4463 <![CDATA[
4464   struct list_head *list;
4465   struct snd_rawmidi_substream *substream;
4466   list_for_each(list, &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams) {
4467           substream = list_entry(list, struct snd_rawmidi_substream, list);
4468           sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4469   }
4470   /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4471 ]]>
4472           </programlisting>
4473         </informalexample>
4474       </para>
4475     </section>
4476
4477     <section id="rawmidi-interface-callbacks">
4478       <title>Callbacks</title>
4479
4480       <para>
4481       In all callbacks, the private data that you've set for the
4482       rawmidi device can be accessed as
4483       substream-&gt;rmidi-&gt;private_data.
4484       <!-- <code> isn't available before DocBook 4.3 -->
4485       </para>
4486
4487       <para>
4488       If there is more than one port, your callbacks can determine the
4489       port index from the struct snd_rawmidi_substream data passed to each
4490       callback:
4491         <informalexample>
4492           <programlisting>
4493 <![CDATA[
4494   struct snd_rawmidi_substream *substream;
4495   int index = substream->number;
4496 ]]>
4497           </programlisting>
4498         </informalexample>
4499       </para>
4500
4501       <section id="rawmidi-interface-op-open">
4502       <title><function>open</function> callback</title>
4503
4504         <informalexample>
4505           <programlisting>
4506 <![CDATA[
4507   static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4508 ]]>
4509           </programlisting>
4510         </informalexample>
4511
4512         <para>
4513         This is called when a substream is opened.
4514         You can initialize the hardware here, but you should not yet
4515         start transmitting/receiving data.
4516         </para>
4517       </section>
4518
4519       <section id="rawmidi-interface-op-close">
4520       <title><function>close</function> callback</title>
4521
4522         <informalexample>
4523           <programlisting>
4524 <![CDATA[
4525   static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4526 ]]>
4527           </programlisting>
4528         </informalexample>
4529
4530         <para>
4531         Guess what.
4532         </para>
4533
4534         <para>
4535         The <function>open</function> and <function>close</function>
4536         callbacks of a rawmidi device are serialized with a mutex,
4537         and can sleep.
4538         </para>
4539       </section>
4540
4541       <section id="rawmidi-interface-op-trigger-out">
4542       <title><function>trigger</function> callback for output
4543       substreams</title>
4544
4545         <informalexample>
4546           <programlisting>
4547 <![CDATA[
4548   static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4549 ]]>
4550           </programlisting>
4551         </informalexample>
4552
4553         <para>
4554         This is called with a nonzero <parameter>up</parameter>
4555         parameter when there is some data in the substream buffer that
4556         must be transmitted.
4557         </para>
4558
4559         <para>
4560         To read data from the buffer, call
4561         <function>snd_rawmidi_transmit_peek</function>.  It will
4562         return the number of bytes that have been read; this will be
4563         less than the number of bytes requested when there is no more
4564         data in the buffer.
4565         After the data has been transmitted successfully, call
4566         <function>snd_rawmidi_transmit_ack</function> to remove the
4567         data from the substream buffer:
4568           <informalexample>
4569             <programlisting>
4570 <![CDATA[
4571   unsigned char data;
4572   while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4573           if (snd_mychip_try_to_transmit(data))
4574                   snd_rawmidi_transmit_ack(substream, 1);
4575           else
4576                   break; /* hardware FIFO full */
4577   }
4578 ]]>
4579             </programlisting>
4580           </informalexample>
4581         </para>
4582
4583         <para>
4584         If you know beforehand that the hardware will accept data, you
4585         can use the <function>snd_rawmidi_transmit</function> function
4586         which reads some data and removes it from the buffer at once:
4587           <informalexample>
4588             <programlisting>
4589 <![CDATA[
4590   while (snd_mychip_transmit_possible()) {
4591           unsigned char data;
4592           if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4593                   break; /* no more data */
4594           snd_mychip_transmit(data);
4595   }
4596 ]]>
4597             </programlisting>
4598           </informalexample>
4599         </para>
4600
4601         <para>
4602         If you know beforehand how many bytes you can accept, you can
4603         use a buffer size greater than one with the
4604         <function>snd_rawmidi_transmit*</function> functions.
4605         </para>
4606
4607         <para>
4608         The <function>trigger</function> callback must not sleep.  If
4609         the hardware FIFO is full before the substream buffer has been
4610         emptied, you have to continue transmitting data later, either
4611         in an interrupt handler, or with a timer if the hardware
4612         doesn't have a MIDI transmit interrupt.
4613         </para>
4614
4615         <para>
4616         The <function>trigger</function> callback is called with a
4617         zero <parameter>up</parameter> parameter when the transmission
4618         of data should be aborted.
4619         </para>
4620       </section>
4621
4622       <section id="rawmidi-interface-op-trigger-in">
4623       <title><function>trigger</function> callback for input
4624       substreams</title>
4625
4626         <informalexample>
4627           <programlisting>
4628 <![CDATA[
4629   static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4630 ]]>
4631           </programlisting>
4632         </informalexample>
4633
4634         <para>
4635         This is called with a nonzero <parameter>up</parameter>
4636         parameter to enable receiving data, or with a zero
4637         <parameter>up</parameter> parameter do disable receiving data.
4638         </para>
4639
4640         <para>
4641         The <function>trigger</function> callback must not sleep; the
4642         actual reading of data from the device is usually done in an
4643         interrupt handler.
4644         </para>
4645
4646         <para>
4647         When data reception is enabled, your interrupt handler should
4648         call <function>snd_rawmidi_receive</function> for all received
4649         data:
4650           <informalexample>
4651             <programlisting>
4652 <![CDATA[
4653   void snd_mychip_midi_interrupt(...)
4654   {
4655           while (mychip_midi_available()) {
4656                   unsigned char data;
4657                   data = mychip_midi_read();
4658                   snd_rawmidi_receive(substream, &data, 1);
4659           }
4660   }
4661 ]]>
4662             </programlisting>
4663           </informalexample>
4664         </para>
4665       </section>
4666
4667       <section id="rawmidi-interface-op-drain">
4668       <title><function>drain</function> callback</title>
4669
4670         <informalexample>
4671           <programlisting>
4672 <![CDATA[
4673   static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4674 ]]>
4675           </programlisting>
4676         </informalexample>
4677
4678         <para>
4679         This is only used with output substreams.  This function should wait
4680         until all data read from the substream buffer has been transmitted.
4681         This ensures that the device can be closed and the driver unloaded
4682         without losing data.
4683         </para>
4684
4685         <para>
4686         This callback is optional.  If you do not set
4687         <structfield>drain</structfield> in the struct snd_rawmidi_ops
4688         structure, ALSA will simply wait for 50&nbsp;milliseconds
4689         instead.
4690         </para>
4691       </section>
4692     </section>
4693
4694   </chapter>
4695
4696
4697 <!-- ****************************************************** -->
4698 <!-- Miscellaneous Devices  -->
4699 <!-- ****************************************************** -->
4700   <chapter id="misc-devices">
4701     <title>Miscellaneous Devices</title>
4702
4703     <section id="misc-devices-opl3">
4704       <title>FM OPL3</title>
4705       <para>
4706         The FM OPL3 is still used on many chips (mainly for backward
4707       compatibility). ALSA has a nice OPL3 FM control layer, too. The
4708       OPL3 API is defined in
4709       <filename>&lt;sound/opl3.h&gt;</filename>. 
4710       </para>
4711
4712       <para>
4713         FM registers can be directly accessed through direct-FM API,
4714       defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4715       ALSA native mode, FM registers are accessed through
4716       Hardware-Dependant Device direct-FM extension API, whereas in
4717       OSS compatible mode, FM registers can be accessed with OSS
4718       direct-FM compatible API on <filename>/dev/dmfmX</filename> device. 
4719       </para>
4720
4721       <para>
4722         For creating the OPL3 component, you have two functions to
4723         call. The first one is a constructor for <type>opl3_t</type>
4724         instance. 
4725
4726         <informalexample>
4727           <programlisting>
4728 <![CDATA[
4729   struct snd_opl3 *opl3;
4730   snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4731                   integrated, &opl3);
4732 ]]>
4733           </programlisting>
4734         </informalexample>
4735       </para>
4736
4737       <para>
4738         The first argument is the card pointer, the second one is the
4739       left port address, and the third is the right port address. In
4740       most cases, the right port is placed at the left port + 2. 
4741       </para>
4742
4743       <para>
4744         The fourth argument is the hardware type.
4745       </para>
4746
4747       <para>
4748         When the left and right ports have been already allocated by
4749       the card driver, pass non-zero to the fifth argument
4750       (<parameter>integrated</parameter>). Otherwise, opl3 module will
4751       allocate the specified ports by itself. 
4752       </para>
4753
4754       <para>
4755         When the accessing to the hardware requires special method
4756         instead of the standard I/O access, you can create opl3 instance
4757         separately with <function>snd_opl3_new()</function>.
4758
4759         <informalexample>
4760           <programlisting>
4761 <![CDATA[
4762   struct snd_opl3 *opl3;
4763   snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4764 ]]>
4765           </programlisting>
4766         </informalexample>
4767       </para>
4768
4769       <para>
4770         Then set <structfield>command</structfield>,
4771         <structfield>private_data</structfield> and
4772         <structfield>private_free</structfield> for the private
4773         access function, the private data and the destructor.
4774         The l_port and r_port are not necessarily set.  Only the
4775         command must be set properly.  You can retrieve the data
4776         from opl3-&gt;private_data field.
4777       </para>
4778
4779       <para>
4780         After creating the opl3 instance via <function>snd_opl3_new()</function>,
4781         call <function>snd_opl3_init()</function> to initialize the chip to the
4782         proper state.  Note that <function>snd_opl3_create()</function> always
4783         calls it internally.
4784       </para>
4785
4786       <para>
4787         If the opl3 instance is created successfully, then create a
4788         hwdep device for this opl3. 
4789
4790         <informalexample>
4791           <programlisting>
4792 <![CDATA[
4793   struct snd_hwdep *opl3hwdep;
4794   snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4795 ]]>
4796           </programlisting>
4797         </informalexample>
4798       </para>
4799
4800       <para>
4801         The first argument is the <type>opl3_t</type> instance you
4802       created, and the second is the index number, usually 0. 
4803       </para>
4804
4805       <para>
4806         The third argument is the index-offset for the sequencer
4807       client assigned to the OPL3 port. When there is an MPU401-UART,
4808       give 1 for here (UART always takes 0). 
4809       </para>
4810     </section>
4811
4812     <section id="misc-devices-hardware-dependent">
4813       <title>Hardware-Dependent Devices</title>
4814       <para>
4815         Some chips need the access from the user-space for special
4816       controls or for loading the micro code. In such a case, you can
4817       create a hwdep (hardware-dependent) device. The hwdep API is
4818       defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4819       find examples in opl3 driver or
4820       <filename>isa/sb/sb16_csp.c</filename>. 
4821       </para>
4822
4823       <para>
4824         Creation of the <type>hwdep</type> instance is done via
4825         <function>snd_hwdep_new()</function>. 
4826
4827         <informalexample>
4828           <programlisting>
4829 <![CDATA[
4830   struct snd_hwdep *hw;
4831   snd_hwdep_new(card, "My HWDEP", 0, &hw);
4832 ]]>
4833           </programlisting>
4834         </informalexample>
4835
4836         where the third argument is the index number.
4837       </para>
4838
4839       <para>
4840         You can then pass any pointer value to the
4841         <parameter>private_data</parameter>.
4842         If you assign a private data, you should define the
4843         destructor, too. The destructor function is set to
4844         <structfield>private_free</structfield> field.  
4845
4846         <informalexample>
4847           <programlisting>
4848 <![CDATA[
4849   struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4850   hw->private_data = p;
4851   hw->private_free = mydata_free;
4852 ]]>
4853           </programlisting>
4854         </informalexample>
4855
4856         and the implementation of destructor would be:
4857
4858         <informalexample>
4859           <programlisting>
4860 <![CDATA[
4861   static void mydata_free(struct snd_hwdep *hw)
4862   {
4863           struct mydata *p = hw->private_data;
4864           kfree(p);
4865   }
4866 ]]>
4867           </programlisting>
4868         </informalexample>
4869       </para>
4870
4871       <para>
4872         The arbitrary file operations can be defined for this
4873         instance. The file operators are defined in
4874         <parameter>ops</parameter> table. For example, assume that
4875         this chip needs an ioctl. 
4876
4877         <informalexample>
4878           <programlisting>
4879 <![CDATA[
4880   hw->ops.open = mydata_open;
4881   hw->ops.ioctl = mydata_ioctl;
4882   hw->ops.release = mydata_release;
4883 ]]>
4884           </programlisting>
4885         </informalexample>
4886
4887         And implement the callback functions as you like.
4888       </para>
4889     </section>
4890
4891     <section id="misc-devices-IEC958">
4892       <title>IEC958 (S/PDIF)</title>
4893       <para>
4894         Usually the controls for IEC958 devices are implemented via
4895       control interface. There is a macro to compose a name string for
4896       IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4897       defined in <filename>&lt;include/asound.h&gt;</filename>.  
4898       </para>
4899
4900       <para>
4901         There are some standard controls for IEC958 status bits. These
4902       controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4903       and the size of element is fixed as 4 bytes array
4904       (value.iec958.status[x]). For <structfield>info</structfield>
4905       callback, you don't specify 
4906       the value field for this type (the count field must be set,
4907       though). 
4908       </para>
4909
4910       <para>
4911         <quote>IEC958 Playback Con Mask</quote> is used to return the
4912       bit-mask for the IEC958 status bits of consumer mode. Similarly,
4913       <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4914       professional mode. They are read-only controls, and are defined
4915       as MIXER controls (iface =
4916       <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).  
4917       </para>
4918
4919       <para>
4920         Meanwhile, <quote>IEC958 Playback Default</quote> control is
4921       defined for getting and setting the current default IEC958
4922       bits. Note that this one is usually defined as a PCM control
4923       (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4924       although in some places it's defined as a MIXER control. 
4925       </para>
4926
4927       <para>
4928         In addition, you can define the control switches to
4929       enable/disable or to set the raw bit mode. The implementation
4930       will depend on the chip, but the control should be named as
4931       <quote>IEC958 xxx</quote>, preferably using
4932       <function>SNDRV_CTL_NAME_IEC958()</function> macro. 
4933       </para>
4934
4935       <para>
4936         You can find several cases, for example,
4937       <filename>pci/emu10k1</filename>,
4938       <filename>pci/ice1712</filename>, or
4939       <filename>pci/cmipci.c</filename>.  
4940       </para>
4941     </section>
4942
4943   </chapter>
4944
4945
4946 <!-- ****************************************************** -->
4947 <!-- Buffer and Memory Management  -->
4948 <!-- ****************************************************** -->
4949   <chapter id="buffer-and-memory">
4950     <title>Buffer and Memory Management</title>
4951
4952     <section id="buffer-and-memory-buffer-types">
4953       <title>Buffer Types</title>
4954       <para>
4955         ALSA provides several different buffer allocation functions
4956       depending on the bus and the architecture. All these have a
4957       consistent API. The allocation of physically-contiguous pages is
4958       done via 
4959       <function>snd_malloc_xxx_pages()</function> function, where xxx
4960       is the bus type. 
4961       </para>
4962
4963       <para>
4964         The allocation of pages with fallback is
4965       <function>snd_malloc_xxx_pages_fallback()</function>. This
4966       function tries to allocate the specified pages but if the pages
4967       are not available, it tries to reduce the page sizes until the
4968       enough space is found.
4969       </para>
4970
4971       <para>
4972       For releasing the space, call
4973       <function>snd_free_xxx_pages()</function> function. 
4974       </para>
4975
4976       <para>
4977       Usually, ALSA drivers try to allocate and reserve
4978        a large contiguous physical space
4979        at the time the module is loaded for the later use.
4980        This is called <quote>pre-allocation</quote>.
4981        As already written, you can call the following function at the
4982        construction of pcm instance (in the case of PCI bus). 
4983
4984         <informalexample>
4985           <programlisting>
4986 <![CDATA[
4987   snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
4988                                         snd_dma_pci_data(pci), size, max);
4989 ]]>
4990           </programlisting>
4991         </informalexample>
4992
4993         where <parameter>size</parameter> is the byte size to be
4994       pre-allocated and the <parameter>max</parameter> is the maximal
4995       size to be changed via <filename>prealloc</filename> proc file.
4996       The allocator will try to get as large area as possible
4997       within the given size. 
4998       </para>
4999
5000       <para>
5001       The second argument (type) and the third argument (device pointer)
5002       are dependent on the bus.
5003       In the case of ISA bus, pass <function>snd_dma_isa_data()</function>
5004       as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5005       For the continuous buffer unrelated to the bus can be pre-allocated
5006       with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5007       <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5008       whereh <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5009       use.  For the SBUS, <constant>SNDRV_DMA_TYPE_SBUS</constant> and
5010       <function>snd_dma_sbus_data(sbus_dev)</function> are used instead.
5011       For the PCI scatter-gather buffers, use
5012       <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5013       <function>snd_dma_pci_data(pci)</function>
5014       (see the section
5015           <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5016           </citetitle></link>).
5017       </para>
5018
5019       <para>
5020         Once when the buffer is pre-allocated, you can use the
5021         allocator in the <structfield>hw_params</structfield> callback 
5022
5023         <informalexample>
5024           <programlisting>
5025 <![CDATA[
5026   snd_pcm_lib_malloc_pages(substream, size);
5027 ]]>
5028           </programlisting>
5029         </informalexample>
5030
5031         Note that you have to pre-allocate to use this function.
5032       </para>
5033     </section>
5034
5035     <section id="buffer-and-memory-external-hardware">
5036       <title>External Hardware Buffers</title>
5037       <para>
5038         Some chips have their own hardware buffers and the DMA
5039       transfer from the host memory is not available. In such a case,
5040       you need to either 1) copy/set the audio data directly to the
5041       external hardware buffer, or 2) make an intermediate buffer and
5042       copy/set the data from it to the external hardware buffer in
5043       interrupts (or in tasklets, preferably).
5044       </para>
5045
5046       <para>
5047         The first case works fine if the external hardware buffer is enough
5048       large.  This method doesn't need any extra buffers and thus is
5049       more effective. You need to define the
5050       <structfield>copy</structfield> and
5051       <structfield>silence</structfield> callbacks for 
5052       the data transfer. However, there is a drawback: it cannot
5053       be mmapped. The examples are GUS's GF1 PCM or emu8000's
5054       wavetable PCM. 
5055       </para>
5056
5057       <para>
5058         The second case allows the mmap of the buffer, although you have
5059       to handle an interrupt or a tasklet for transferring the data
5060       from the intermediate buffer to the hardware buffer. You can find an
5061       example in vxpocket driver. 
5062       </para>
5063
5064       <para>
5065         Another case is that the chip uses a PCI memory-map
5066       region for the buffer instead of the host memory. In this case,
5067       mmap is available only on certain architectures like intel. In
5068       non-mmap mode, the data cannot be transferred as the normal
5069       way. Thus you need to define <structfield>copy</structfield> and
5070       <structfield>silence</structfield> callbacks as well 
5071       as in the cases above. The examples are found in
5072       <filename>rme32.c</filename> and <filename>rme96.c</filename>. 
5073       </para>
5074
5075       <para>
5076         The implementation of <structfield>copy</structfield> and
5077         <structfield>silence</structfield> callbacks depends upon 
5078         whether the hardware supports interleaved or non-interleaved
5079         samples. The <structfield>copy</structfield> callback is
5080         defined like below, a bit 
5081         differently depending whether the direction is playback or
5082         capture: 
5083
5084         <informalexample>
5085           <programlisting>
5086 <![CDATA[
5087   static int playback_copy(struct snd_pcm_substream *substream, int channel,
5088                snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5089   static int capture_copy(struct snd_pcm_substream *substream, int channel,
5090                snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5091 ]]>
5092           </programlisting>
5093         </informalexample>
5094       </para>
5095
5096       <para>
5097         In the case of interleaved samples, the second argument
5098       (<parameter>channel</parameter>) is not used. The third argument
5099       (<parameter>pos</parameter>) points the 
5100       current position offset in frames. 
5101       </para>
5102
5103       <para>
5104         The meaning of the fourth argument is different between
5105       playback and capture. For playback, it holds the source data
5106       pointer, and for capture, it's the destination data pointer. 
5107       </para>
5108
5109       <para>
5110         The last argument is the number of frames to be copied.
5111       </para>
5112
5113       <para>
5114         What you have to do in this callback is again different
5115         between playback and capture directions. In the case of
5116         playback, you do: copy the given amount of data
5117         (<parameter>count</parameter>) at the specified pointer
5118         (<parameter>src</parameter>) to the specified offset
5119         (<parameter>pos</parameter>) on the hardware buffer. When
5120         coded like memcpy-like way, the copy would be like: 
5121
5122         <informalexample>
5123           <programlisting>
5124 <![CDATA[
5125   my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5126             frames_to_bytes(runtime, count));
5127 ]]>
5128           </programlisting>
5129         </informalexample>
5130       </para>
5131
5132       <para>
5133         For the capture direction, you do: copy the given amount of
5134         data (<parameter>count</parameter>) at the specified offset
5135         (<parameter>pos</parameter>) on the hardware buffer to the
5136         specified pointer (<parameter>dst</parameter>). 
5137
5138         <informalexample>
5139           <programlisting>
5140 <![CDATA[
5141   my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5142             frames_to_bytes(runtime, count));
5143 ]]>
5144           </programlisting>
5145         </informalexample>
5146
5147         Note that both of the position and the data amount are given
5148       in frames. 
5149       </para>
5150
5151       <para>
5152         In the case of non-interleaved samples, the implementation
5153       will be a bit more complicated. 
5154       </para>
5155
5156       <para>
5157         You need to check the channel argument, and if it's -1, copy
5158       the whole channels. Otherwise, you have to copy only the
5159       specified channel. Please check
5160       <filename>isa/gus/gus_pcm.c</filename> as an example. 
5161       </para>
5162
5163       <para>
5164         The <structfield>silence</structfield> callback is also
5165         implemented in a similar way. 
5166
5167         <informalexample>
5168           <programlisting>
5169 <![CDATA[
5170   static int silence(struct snd_pcm_substream *substream, int channel,
5171                      snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5172 ]]>
5173           </programlisting>
5174         </informalexample>
5175       </para>
5176
5177       <para>
5178         The meanings of arguments are identical with the
5179       <structfield>copy</structfield> 
5180       callback, although there is no <parameter>src/dst</parameter>
5181       argument. In the case of interleaved samples, the channel
5182       argument has no meaning, as well as on
5183       <structfield>copy</structfield> callback.  
5184       </para>
5185
5186       <para>
5187         The role of <structfield>silence</structfield> callback is to
5188         set the given amount 
5189         (<parameter>count</parameter>) of silence data at the
5190         specified offset (<parameter>pos</parameter>) on the hardware
5191         buffer. Suppose that the data format is signed (that is, the
5192         silent-data is 0), and the implementation using a memset-like
5193         function would be like: 
5194
5195         <informalexample>
5196           <programlisting>
5197 <![CDATA[
5198   my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5199             frames_to_bytes(runtime, count));
5200 ]]>
5201           </programlisting>
5202         </informalexample>
5203       </para>
5204
5205       <para>
5206         In the case of non-interleaved samples, again, the
5207       implementation becomes a bit more complicated. See, for example,
5208       <filename>isa/gus/gus_pcm.c</filename>. 
5209       </para>
5210     </section>
5211
5212     <section id="buffer-and-memory-non-contiguous">
5213       <title>Non-Contiguous Buffers</title>
5214       <para>
5215         If your hardware supports the page table like emu10k1 or the
5216       buffer descriptors like via82xx, you can use the scatter-gather
5217       (SG) DMA. ALSA provides an interface for handling SG-buffers.
5218       The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>. 
5219       </para>
5220
5221       <para>
5222         For creating the SG-buffer handler, call
5223         <function>snd_pcm_lib_preallocate_pages()</function> or
5224         <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5225         with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5226         in the PCM constructor like other PCI pre-allocator.
5227         You need to pass the <function>snd_dma_pci_data(pci)</function>,
5228         where pci is the struct <structname>pci_dev</structname> pointer
5229         of the chip as well.
5230         The <type>struct snd_sg_buf</type> instance is created as
5231         substream-&gt;dma_private. You can cast
5232         the pointer like: 
5233
5234         <informalexample>
5235           <programlisting>
5236 <![CDATA[
5237   struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5238 ]]>
5239           </programlisting>
5240         </informalexample>
5241       </para>
5242
5243       <para>
5244         Then call <function>snd_pcm_lib_malloc_pages()</function>
5245       in <structfield>hw_params</structfield> callback
5246       as well as in the case of normal PCI buffer.
5247       The SG-buffer handler will allocate the non-contiguous kernel
5248       pages of the given size and map them onto the virtually contiguous
5249       memory.  The virtual pointer is addressed in runtime-&gt;dma_area.
5250       The physical address (runtime-&gt;dma_addr) is set to zero,
5251       because the buffer is physically non-contigous.
5252       The physical address table is set up in sgbuf-&gt;table.
5253       You can get the physical address at a certain offset via
5254       <function>snd_pcm_sgbuf_get_addr()</function>. 
5255       </para>
5256
5257       <para>
5258         When a SG-handler is used, you need to set
5259       <function>snd_pcm_sgbuf_ops_page</function> as
5260       the <structfield>page</structfield> callback.
5261       (See <link linkend="pcm-interface-operators-page-callback">
5262       <citetitle>page callback section</citetitle></link>.)
5263       </para>
5264
5265       <para>
5266         For releasing the data, call
5267       <function>snd_pcm_lib_free_pages()</function> in the
5268       <structfield>hw_free</structfield> callback as usual.
5269       </para>
5270     </section>
5271
5272     <section id="buffer-and-memory-vmalloced">
5273       <title>Vmalloc'ed Buffers</title>
5274       <para>
5275         It's possible to use a buffer allocated via
5276       <function>vmalloc</function>, for example, for an intermediate
5277       buffer. Since the allocated pages are not contiguous, you need
5278       to set the <structfield>page</structfield> callback to obtain
5279       the physical address at every offset. 
5280       </para>
5281
5282       <para>
5283         The implementation of <structfield>page</structfield> callback
5284         would be like this: 
5285
5286         <informalexample>
5287           <programlisting>
5288 <![CDATA[
5289   #include <linux/vmalloc.h>
5290
5291   /* get the physical page pointer on the given offset */
5292   static struct page *mychip_page(struct snd_pcm_substream *substream,
5293                                   unsigned long offset)
5294   {
5295           void *pageptr = substream->runtime->dma_area + offset;
5296           return vmalloc_to_page(pageptr);
5297   }
5298 ]]>
5299           </programlisting>
5300         </informalexample>
5301       </para>
5302     </section>
5303
5304   </chapter>
5305
5306
5307 <!-- ****************************************************** -->
5308 <!-- Proc Interface  -->
5309 <!-- ****************************************************** -->
5310   <chapter id="proc-interface">
5311     <title>Proc Interface</title>
5312     <para>
5313       ALSA provides an easy interface for procfs. The proc files are
5314       very useful for debugging. I recommend you set up proc files if
5315       you write a driver and want to get a running status or register
5316       dumps. The API is found in
5317       <filename>&lt;sound/info.h&gt;</filename>. 
5318     </para>
5319
5320     <para>
5321       For creating a proc file, call
5322       <function>snd_card_proc_new()</function>. 
5323
5324       <informalexample>
5325         <programlisting>
5326 <![CDATA[
5327   struct snd_info_entry *entry;
5328   int err = snd_card_proc_new(card, "my-file", &entry);
5329 ]]>
5330         </programlisting>
5331       </informalexample>
5332
5333       where the second argument specifies the proc-file name to be
5334     created. The above example will create a file
5335     <filename>my-file</filename> under the card directory,
5336     e.g. <filename>/proc/asound/card0/my-file</filename>. 
5337     </para>
5338
5339     <para>
5340     Like other components, the proc entry created via
5341     <function>snd_card_proc_new()</function> will be registered and
5342     released automatically in the card registration and release
5343     functions.
5344     </para>
5345
5346     <para>
5347       When the creation is successful, the function stores a new
5348     instance at the pointer given in the third argument.
5349     It is initialized as a text proc file for read only.  For using
5350     this proc file as a read-only text file as it is, set the read
5351     callback with a private data via 
5352      <function>snd_info_set_text_ops()</function>.
5353
5354       <informalexample>
5355         <programlisting>
5356 <![CDATA[
5357   snd_info_set_text_ops(entry, chip, my_proc_read);
5358 ]]>
5359         </programlisting>
5360       </informalexample>
5361     
5362     where the second argument (<parameter>chip</parameter>) is the
5363     private data to be used in the callbacks. The third parameter
5364     specifies the read buffer size and the fourth
5365     (<parameter>my_proc_read</parameter>) is the callback function, which
5366     is defined like
5367
5368       <informalexample>
5369         <programlisting>
5370 <![CDATA[
5371   static void my_proc_read(struct snd_info_entry *entry,
5372                            struct snd_info_buffer *buffer);
5373 ]]>
5374         </programlisting>
5375       </informalexample>
5376     
5377     </para>
5378
5379     <para>
5380     In the read callback, use <function>snd_iprintf()</function> for
5381     output strings, which works just like normal
5382     <function>printf()</function>.  For example,
5383
5384       <informalexample>
5385         <programlisting>
5386 <![CDATA[
5387   static void my_proc_read(struct snd_info_entry *entry,
5388                            struct snd_info_buffer *buffer)
5389   {
5390           struct my_chip *chip = entry->private_data;
5391
5392           snd_iprintf(buffer, "This is my chip!\n");
5393           snd_iprintf(buffer, "Port = %ld\n", chip->port);
5394   }
5395 ]]>
5396         </programlisting>
5397       </informalexample>
5398     </para>
5399
5400     <para>
5401     The file permission can be changed afterwards.  As default, it's
5402     set as read only for all users.  If you want to add the write
5403     permission to the user (root as default), set like below:
5404
5405       <informalexample>
5406         <programlisting>
5407 <![CDATA[
5408  entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5409 ]]>
5410         </programlisting>
5411       </informalexample>
5412
5413     and set the write buffer size and the callback
5414
5415       <informalexample>
5416         <programlisting>
5417 <![CDATA[
5418   entry->c.text.write = my_proc_write;
5419 ]]>
5420         </programlisting>
5421       </informalexample>
5422     </para>
5423
5424     <para>
5425       For the write callback, you can use
5426     <function>snd_info_get_line()</function> to get a text line, and
5427     <function>snd_info_get_str()</function> to retrieve a string from
5428     the line. Some examples are found in
5429     <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5430     <filename>pcm_oss.c</filename>. 
5431     </para>
5432
5433     <para>
5434       For a raw-data proc-file, set the attributes like the following:
5435
5436       <informalexample>
5437         <programlisting>
5438 <![CDATA[
5439   static struct snd_info_entry_ops my_file_io_ops = {
5440           .read = my_file_io_read,
5441   };
5442
5443   entry->content = SNDRV_INFO_CONTENT_DATA;
5444   entry->private_data = chip;
5445   entry->c.ops = &my_file_io_ops;
5446   entry->size = 4096;
5447   entry->mode = S_IFREG | S_IRUGO;
5448 ]]>
5449         </programlisting>
5450       </informalexample>
5451     </para>
5452
5453     <para>
5454       The callback is much more complicated than the text-file
5455       version. You need to use a low-level i/o functions such as
5456       <function>copy_from/to_user()</function> to transfer the
5457       data.
5458
5459       <informalexample>
5460         <programlisting>
5461 <![CDATA[
5462   static long my_file_io_read(struct snd_info_entry *entry,
5463                               void *file_private_data,
5464                               struct file *file,
5465                               char *buf,
5466                               unsigned long count,
5467                               unsigned long pos)
5468   {
5469           long size = count;
5470           if (pos + size > local_max_size)
5471                   size = local_max_size - pos;
5472           if (copy_to_user(buf, local_data + pos, size))
5473                   return -EFAULT;
5474           return size;
5475   }
5476 ]]>
5477         </programlisting>
5478       </informalexample>
5479     </para>
5480
5481   </chapter>
5482
5483
5484 <!-- ****************************************************** -->
5485 <!-- Power Management  -->
5486 <!-- ****************************************************** -->
5487   <chapter id="power-management">
5488     <title>Power Management</title>
5489     <para>
5490       If the chip is supposed to work with with suspend/resume
5491       functions, you need to add the power-management codes to the
5492       driver. The additional codes for the power-management should be
5493       <function>ifdef</function>'ed with
5494       <constant>CONFIG_PM</constant>. 
5495     </para>
5496
5497         <para>
5498         If the driver supports the suspend/resume
5499         <emphasis>fully</emphasis>, that is, the device can be
5500         properly resumed to the status at the suspend is called,
5501         you can set <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5502         to pcm info field.  Usually, this is possible when the
5503         registers of ths chip can be safely saved and restored to the
5504         RAM.  If this is set, the trigger callback is called with
5505         <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after resume
5506         callback is finished. 
5507         </para>
5508
5509         <para>
5510         Even if the driver doesn't support PM fully but only the
5511         partial suspend/resume is possible, it's still worthy to
5512         implement suspend/resume callbacks.  In such a case, applications
5513         would reset the status by calling
5514         <function>snd_pcm_prepare()</function> and restart the stream
5515         appropriately.  Hence, you can define suspend/resume callbacks
5516         below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5517         info flag to the PCM.
5518         </para>
5519         
5520         <para>
5521         Note that the trigger with SUSPEND can be always called when
5522         <function>snd_pcm_suspend_all</function> is called,
5523         regardless of <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5524         The <constant>RESUME</constant> flag affects only the behavior
5525         of <function>snd_pcm_resume()</function>.
5526         (Thus, in theory,
5527         <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5528         to be handled in the trigger callback when no
5529         <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set.  But,
5530         it's better to keep it for compatibility reason.)
5531         </para>
5532     <para>
5533       In the earlier version of ALSA drivers, a common
5534       power-management layer was provided, but it has been removed.
5535       The driver needs to define the suspend/resume hooks according to
5536       the bus the device is assigned.  In the case of PCI driver, the
5537       callbacks look like below:
5538
5539       <informalexample>
5540         <programlisting>
5541 <![CDATA[
5542   #ifdef CONFIG_PM
5543   static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5544   {
5545           .... /* do things for suspsend */
5546           return 0;
5547   }
5548   static int snd_my_resume(struct pci_dev *pci)
5549   {
5550           .... /* do things for suspsend */
5551           return 0;
5552   }
5553   #endif
5554 ]]>
5555         </programlisting>
5556       </informalexample>
5557     </para>
5558
5559     <para>
5560       The scheme of the real suspend job is as following.
5561
5562       <orderedlist>
5563         <listitem><para>Retrieve the card and the chip data.</para></listitem>
5564         <listitem><para>Call <function>snd_power_change_state()</function> with
5565           <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5566           power status.</para></listitem>
5567         <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5568         <listitem><para>If AC97 codecs are used, call
5569         <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5570         <listitem><para>Save the register values if necessary.</para></listitem>
5571         <listitem><para>Stop the hardware if necessary.</para></listitem>
5572         <listitem><para>Disable the PCI device by calling
5573           <function>pci_disable_device()</function>.  Then, call
5574           <function>pci_save_state()</function> at last.</para></listitem>
5575       </orderedlist>
5576     </para>
5577
5578     <para>
5579       A typical code would be like:
5580
5581       <informalexample>
5582         <programlisting>
5583 <![CDATA[
5584   static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5585   {
5586           /* (1) */
5587           struct snd_card *card = pci_get_drvdata(pci);
5588           struct mychip *chip = card->private_data;
5589           /* (2) */
5590           snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5591           /* (3) */
5592           snd_pcm_suspend_all(chip->pcm);
5593           /* (4) */
5594           snd_ac97_suspend(chip->ac97);
5595           /* (5) */
5596           snd_mychip_save_registers(chip);
5597           /* (6) */
5598           snd_mychip_stop_hardware(chip);
5599           /* (7) */
5600           pci_disable_device(pci);
5601           pci_save_state(pci);
5602           return 0;
5603   }
5604 ]]>
5605         </programlisting>
5606       </informalexample>
5607     </para>
5608
5609     <para>
5610     The scheme of the real resume job is as following.
5611
5612     <orderedlist>
5613     <listitem><para>Retrieve the card and the chip data.</para></listitem>
5614     <listitem><para>Set up PCI.  First, call <function>pci_restore_state()</function>.
5615         Then enable the pci device again by calling <function>pci_enable_device()</function>.
5616         Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5617     <listitem><para>Re-initialize the chip.</para></listitem>
5618     <listitem><para>Restore the saved registers if necessary.</para></listitem>
5619     <listitem><para>Resume the mixer, e.g. calling
5620     <function>snd_ac97_resume()</function>.</para></listitem>
5621     <listitem><para>Restart the hardware (if any).</para></listitem>
5622     <listitem><para>Call <function>snd_power_change_state()</function> with
5623         <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5624     </orderedlist>
5625     </para>
5626
5627     <para>
5628     A typical code would be like:
5629
5630       <informalexample>
5631         <programlisting>
5632 <![CDATA[
5633   static int mychip_resume(struct pci_dev *pci)
5634   {
5635           /* (1) */
5636           struct snd_card *card = pci_get_drvdata(pci);
5637           struct mychip *chip = card->private_data;
5638           /* (2) */
5639           pci_restore_state(pci);
5640           pci_enable_device(pci);
5641           pci_set_master(pci);
5642           /* (3) */
5643           snd_mychip_reinit_chip(chip);
5644           /* (4) */
5645           snd_mychip_restore_registers(chip);
5646           /* (5) */
5647           snd_ac97_resume(chip->ac97);
5648           /* (6) */
5649           snd_mychip_restart_chip(chip);
5650           /* (7) */
5651           snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5652           return 0;
5653   }
5654 ]]>
5655         </programlisting>
5656       </informalexample>
5657     </para>
5658
5659     <para>
5660         As shown in the above, it's better to save registers after
5661         suspending the PCM operations via
5662         <function>snd_pcm_suspend_all()</function> or
5663         <function>snd_pcm_suspend()</function>.  It means that the PCM
5664         streams are already stoppped when the register snapshot is
5665         taken.  But, remind that you don't have to restart the PCM
5666         stream in the resume callback. It'll be restarted via 
5667         trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5668         when necessary.
5669     </para>
5670
5671     <para>
5672       OK, we have all callbacks now. Let's set them up. In the
5673       initialization of the card, make sure that you can get the chip
5674       data from the card instance, typically via
5675       <structfield>private_data</structfield> field, in case you
5676       created the chip data individually.
5677
5678       <informalexample>
5679         <programlisting>
5680 <![CDATA[
5681   static int __devinit snd_mychip_probe(struct pci_dev *pci,
5682                                const struct pci_device_id *pci_id)
5683   {
5684           ....
5685           struct snd_card *card;
5686           struct mychip *chip;
5687           ....
5688           card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL);
5689           ....
5690           chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5691           ....
5692           card->private_data = chip;
5693           ....
5694   }
5695 ]]>
5696         </programlisting>
5697       </informalexample>
5698
5699         When you created the chip data with
5700         <function>snd_card_new()</function>, it's anyway accessible
5701         via <structfield>private_data</structfield> field.
5702
5703       <informalexample>
5704         <programlisting>
5705 <![CDATA[
5706   static int __devinit snd_mychip_probe(struct pci_dev *pci,
5707                                const struct pci_device_id *pci_id)
5708   {
5709           ....
5710           struct snd_card *card;
5711           struct mychip *chip;
5712           ....
5713           card = snd_card_new(index[dev], id[dev], THIS_MODULE,
5714                               sizeof(struct mychip));
5715           ....
5716           chip = card->private_data;
5717           ....
5718   }
5719 ]]>
5720         </programlisting>
5721       </informalexample>
5722
5723     </para>
5724
5725     <para>
5726       If you need a space for saving the registers, allocate the
5727         buffer for it here, too, since it would be fatal
5728     if you cannot allocate a memory in the suspend phase.
5729     The allocated buffer should be released in the corresponding
5730     destructor.
5731     </para>
5732
5733     <para>
5734       And next, set suspend/resume callbacks to the pci_driver.
5735
5736       <informalexample>
5737         <programlisting>
5738 <![CDATA[
5739   static struct pci_driver driver = {
5740           .name = "My Chip",
5741           .id_table = snd_my_ids,
5742           .probe = snd_my_probe,
5743           .remove = __devexit_p(snd_my_remove),
5744   #ifdef CONFIG_PM
5745           .suspend = snd_my_suspend,
5746           .resume = snd_my_resume,
5747   #endif
5748   };
5749 ]]>
5750         </programlisting>
5751       </informalexample>
5752     </para>
5753
5754   </chapter>
5755
5756
5757 <!-- ****************************************************** -->
5758 <!-- Module Parameters  -->
5759 <!-- ****************************************************** -->
5760   <chapter id="module-parameters">
5761     <title>Module Parameters</title>
5762     <para>
5763       There are standard module options for ALSA. At least, each
5764       module should have <parameter>index</parameter>,
5765       <parameter>id</parameter> and <parameter>enable</parameter>
5766       options. 
5767     </para>
5768
5769     <para>
5770       If the module supports multiple cards (usually up to
5771       8 = <constant>SNDRV_CARDS</constant> cards), they should be
5772       arrays.  The default initial values are defined already as
5773       constants for ease of programming:
5774
5775       <informalexample>
5776         <programlisting>
5777 <![CDATA[
5778   static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5779   static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5780   static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5781 ]]>
5782         </programlisting>
5783       </informalexample>
5784     </para>
5785
5786     <para>
5787       If the module supports only a single card, they could be single
5788     variables, instead.  <parameter>enable</parameter> option is not
5789     always necessary in this case, but it wouldn't be so bad to have a
5790     dummy option for compatibility.
5791     </para>
5792
5793     <para>
5794       The module parameters must be declared with the standard
5795     <function>module_param()()</function>,
5796     <function>module_param_array()()</function> and
5797     <function>MODULE_PARM_DESC()</function> macros.
5798     </para>
5799
5800     <para>
5801       The typical coding would be like below:
5802
5803       <informalexample>
5804         <programlisting>
5805 <![CDATA[
5806   #define CARD_NAME "My Chip"
5807
5808   module_param_array(index, int, NULL, 0444);
5809   MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5810   module_param_array(id, charp, NULL, 0444);
5811   MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5812   module_param_array(enable, bool, NULL, 0444);
5813   MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5814 ]]>
5815         </programlisting>
5816       </informalexample>
5817     </para>
5818
5819     <para>
5820       Also, don't forget to define the module description, classes,
5821       license and devices. Especially, the recent modprobe requires to
5822       define the module license as GPL, etc., otherwise the system is
5823       shown as <quote>tainted</quote>. 
5824
5825       <informalexample>
5826         <programlisting>
5827 <![CDATA[
5828   MODULE_DESCRIPTION("My Chip");
5829   MODULE_LICENSE("GPL");
5830   MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5831 ]]>
5832         </programlisting>
5833       </informalexample>
5834     </para>
5835
5836   </chapter>
5837
5838
5839 <!-- ****************************************************** -->
5840 <!-- How To Put Your Driver  -->
5841 <!-- ****************************************************** -->
5842   <chapter id="how-to-put-your-driver">
5843     <title>How To Put Your Driver Into ALSA Tree</title>
5844         <section>
5845         <title>General</title>
5846         <para>
5847         So far, you've learned how to write the driver codes.
5848         And you might have a question now: how to put my own
5849         driver into the ALSA driver tree?
5850         Here (finally :) the standard procedure is described briefly.
5851         </para>
5852
5853         <para>
5854         Suppose that you'll create a new PCI driver for the card
5855         <quote>xyz</quote>.  The card module name would be
5856         snd-xyz.  The new driver is usually put into alsa-driver
5857         tree, <filename>alsa-driver/pci</filename> directory in
5858         the case of PCI cards.
5859         Then the driver is evaluated, audited and tested
5860         by developers and users.  After a certain time, the driver
5861         will go to alsa-kernel tree (to the corresponding directory,
5862         such as <filename>alsa-kernel/pci</filename>) and eventually
5863         integrated into Linux 2.6 tree (the directory would be
5864         <filename>linux/sound/pci</filename>).
5865         </para>
5866
5867         <para>
5868         In the following sections, the driver code is supposed
5869         to be put into alsa-driver tree.  The two cases are assumed:
5870         a driver consisting of a single source file and one consisting
5871         of several source files.
5872         </para>
5873         </section>
5874
5875         <section>
5876         <title>Driver with A Single Source File</title>
5877         <para>
5878         <orderedlist>
5879         <listitem>
5880         <para>
5881         Modify alsa-driver/pci/Makefile
5882         </para>
5883
5884         <para>
5885         Suppose you have a file xyz.c.  Add the following
5886         two lines
5887       <informalexample>
5888         <programlisting>
5889 <![CDATA[
5890   snd-xyz-objs := xyz.o
5891   obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5892 ]]>
5893         </programlisting>
5894       </informalexample>
5895         </para>
5896         </listitem>
5897
5898         <listitem>
5899         <para>
5900         Create the Kconfig entry
5901         </para>
5902
5903         <para>
5904         Add the new entry of Kconfig for your xyz driver.
5905       <informalexample>
5906         <programlisting>
5907 <![CDATA[
5908   config SND_XYZ
5909           tristate "Foobar XYZ"
5910           depends on SND
5911           select SND_PCM
5912           help
5913             Say Y here to include support for Foobar XYZ soundcard.
5914
5915             To compile this driver as a module, choose M here: the module
5916             will be called snd-xyz.
5917 ]]>
5918         </programlisting>
5919       </informalexample>
5920
5921         the line, select SND_PCM, specifies that the driver xyz supports
5922         PCM.  In addition to SND_PCM, the following components are
5923         supported for select command:
5924         SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5925         SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5926         Add the select command for each supported component.
5927         </para>
5928
5929         <para>
5930         Note that some selections imply the lowlevel selections.
5931         For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5932         AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5933         You don't need to give the lowlevel selections again.
5934         </para>
5935
5936         <para>
5937         For the details of Kconfig script, refer to the kbuild
5938         documentation.
5939         </para>
5940
5941         </listitem>
5942
5943         <listitem>
5944         <para>
5945         Run cvscompile script to re-generate the configure script and
5946         build the whole stuff again.
5947         </para>
5948         </listitem>
5949         </orderedlist>
5950         </para>
5951         </section>
5952
5953         <section>
5954         <title>Drivers with Several Source Files</title>
5955         <para>
5956         Suppose that the driver snd-xyz have several source files.
5957         They are located in the new subdirectory,
5958         pci/xyz.
5959
5960         <orderedlist>
5961         <listitem>
5962         <para>
5963         Add a new directory (<filename>xyz</filename>) in
5964         <filename>alsa-driver/pci/Makefile</filename> like below
5965
5966       <informalexample>
5967         <programlisting>
5968 <![CDATA[
5969   obj-$(CONFIG_SND) += xyz/
5970 ]]>
5971         </programlisting>
5972       </informalexample>
5973         </para>
5974         </listitem>
5975
5976         <listitem>
5977         <para>
5978         Under the directory <filename>xyz</filename>, create a Makefile
5979
5980       <example>
5981         <title>Sample Makefile for a driver xyz</title>
5982         <programlisting>
5983 <![CDATA[
5984   ifndef SND_TOPDIR
5985   SND_TOPDIR=../..
5986   endif
5987
5988   include $(SND_TOPDIR)/toplevel.config
5989   include $(SND_TOPDIR)/Makefile.conf
5990
5991   snd-xyz-objs := xyz.o abc.o def.o
5992
5993   obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5994
5995   include $(SND_TOPDIR)/Rules.make
5996 ]]>
5997         </programlisting>
5998       </example>
5999         </para>
6000         </listitem>
6001
6002         <listitem>
6003         <para>
6004         Create the Kconfig entry
6005         </para>
6006
6007         <para>
6008         This procedure is as same as in the last section.
6009         </para>
6010         </listitem>
6011
6012         <listitem>
6013         <para>
6014         Run cvscompile script to re-generate the configure script and
6015         build the whole stuff again.
6016         </para>
6017         </listitem>
6018         </orderedlist>
6019         </para>
6020         </section>
6021
6022   </chapter>
6023
6024 <!-- ****************************************************** -->
6025 <!-- Useful Functions  -->
6026 <!-- ****************************************************** -->
6027   <chapter id="useful-functions">
6028     <title>Useful Functions</title>
6029
6030     <section id="useful-functions-snd-printk">
6031       <title><function>snd_printk()</function> and friends</title>
6032       <para>
6033         ALSA provides a verbose version of
6034       <function>printk()</function> function. If a kernel config
6035       <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6036       function prints the given message together with the file name
6037       and the line of the caller. The <constant>KERN_XXX</constant>
6038       prefix is processed as 
6039       well as the original <function>printk()</function> does, so it's
6040       recommended to add this prefix, e.g. 
6041
6042         <informalexample>
6043           <programlisting>
6044 <![CDATA[
6045   snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6046 ]]>
6047           </programlisting>
6048         </informalexample>
6049       </para>
6050
6051       <para>
6052         There are also <function>printk()</function>'s for
6053       debugging. <function>snd_printd()</function> can be used for
6054       general debugging purposes. If
6055       <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6056       compiled, and works just like
6057       <function>snd_printk()</function>. If the ALSA is compiled
6058       without the debugging flag, it's ignored. 
6059       </para>
6060
6061       <para>
6062         <function>snd_printdd()</function> is compiled in only when
6063       <constant>CONFIG_SND_DEBUG_DETECT</constant> is set. Please note
6064       that <constant>DEBUG_DETECT</constant> is not set as default
6065       even if you configure the alsa-driver with
6066       <option>--with-debug=full</option> option. You need to give
6067       explicitly <option>--with-debug=detect</option> option instead. 
6068       </para>
6069     </section>
6070
6071     <section id="useful-functions-snd-assert">
6072       <title><function>snd_assert()</function></title>
6073       <para>
6074         <function>snd_assert()</function> macro is similar with the
6075       normal <function>assert()</function> macro. For example,  
6076
6077         <informalexample>
6078           <programlisting>
6079 <![CDATA[
6080   snd_assert(pointer != NULL, return -EINVAL);
6081 ]]>
6082           </programlisting>
6083         </informalexample>
6084       </para>
6085
6086       <para>
6087         The first argument is the expression to evaluate, and the
6088       second argument is the action if it fails. When
6089       <constant>CONFIG_SND_DEBUG</constant>, is set, it will show an
6090       error message such as <computeroutput>BUG? (xxx)</computeroutput>
6091       together with stack trace.
6092       </para>
6093       <para>
6094          When no debug flag is set, this macro is ignored. 
6095       </para>
6096     </section>
6097
6098     <section id="useful-functions-snd-bug">
6099       <title><function>snd_BUG()</function></title>
6100       <para>
6101         It shows <computeroutput>BUG?</computeroutput> message and
6102       stack trace as well as <function>snd_assert</function> at the point.
6103       It's useful to show that a fatal error happens there. 
6104       </para>
6105       <para>
6106          When no debug flag is set, this macro is ignored. 
6107       </para>
6108     </section>
6109   </chapter>
6110
6111
6112 <!-- ****************************************************** -->
6113 <!-- Acknowledgments  -->
6114 <!-- ****************************************************** -->
6115   <chapter id="acknowledments">
6116     <title>Acknowledgments</title>
6117     <para>
6118       I would like to thank Phil Kerr for his help for improvement and
6119       corrections of this document. 
6120     </para>
6121     <para>
6122     Kevin Conder reformatted the original plain-text to the
6123     DocBook format.
6124     </para>
6125     <para>
6126     Giuliano Pochini corrected typos and contributed the example codes
6127     in the hardware constraints section.
6128     </para>
6129   </chapter>
6130
6131
6132 </book>