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