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