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