0475478c2484c90c3b14b6c74a4a8efe8fa4941b
[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>March 6, 2005</date>
22      <edition>0.3.4</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-2004  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 = kcalloc(1, 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>kcalloc()</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 = kcalloc(1, 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 = kcalloc(1, 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>kcalloc()</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         int tstamp_timespec;            /* use timeval (0) or timespec (1) */
2194         snd_pcm_tstamp_t tstamp_mode;   /* mmap timestamp is updated */
2195         unsigned int period_step;
2196         unsigned int sleep_min;         /* min ticks to sleep */
2197         snd_pcm_uframes_t xfer_align;   /* xfer size need to be a multiple */
2198         snd_pcm_uframes_t start_threshold;
2199         snd_pcm_uframes_t stop_threshold;
2200         snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2201                                                 noise is nearest than this */
2202         snd_pcm_uframes_t silence_size; /* Silence filling size */
2203         snd_pcm_uframes_t boundary;     /* pointers wrap point */
2204
2205         snd_pcm_uframes_t silenced_start;
2206         snd_pcm_uframes_t silenced_size;
2207
2208         snd_pcm_sync_id_t sync;         /* hardware synchronization ID */
2209
2210         /* -- mmap -- */
2211         volatile snd_pcm_mmap_status_t *status;
2212         volatile snd_pcm_mmap_control_t *control;
2213         atomic_t mmap_count;
2214
2215         /* -- locking / scheduling -- */
2216         spinlock_t lock;
2217         wait_queue_head_t sleep;
2218         struct timer_list tick_timer;
2219         struct fasync_struct *fasync;
2220
2221         /* -- private section -- */
2222         void *private_data;
2223         void (*private_free)(snd_pcm_runtime_t *runtime);
2224
2225         /* -- hardware description -- */
2226         snd_pcm_hardware_t hw;
2227         snd_pcm_hw_constraints_t hw_constraints;
2228
2229         /* -- interrupt callbacks -- */
2230         void (*transfer_ack_begin)(snd_pcm_substream_t *substream);
2231         void (*transfer_ack_end)(snd_pcm_substream_t *substream);
2232
2233         /* -- timer -- */
2234         unsigned int timer_resolution;  /* timer resolution */
2235
2236         /* -- DMA -- */           
2237         unsigned char *dma_area;        /* DMA area */
2238         dma_addr_t dma_addr;            /* physical bus address (not accessible from main CPU) */
2239         size_t dma_bytes;               /* size of DMA area */
2240
2241         struct snd_dma_buffer *dma_buffer_p;    /* allocated buffer */
2242
2243 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2244         /* -- OSS things -- */
2245         snd_pcm_oss_runtime_t oss;
2246 #endif
2247 };
2248 ]]>
2249             </programlisting>
2250           </informalexample>
2251         </para>
2252
2253         <para>
2254           For the operators (callbacks) of each sound driver, most of
2255         these records are supposed to be read-only.  Only the PCM
2256         middle-layer changes / updates these info.  The exceptions are
2257         the hardware description (hw), interrupt callbacks
2258         (transfer_ack_xxx), DMA buffer information, and the private
2259         data.  Besides, if you use the standard buffer allocation
2260         method via <function>snd_pcm_lib_malloc_pages()</function>,
2261         you don't need to set the DMA buffer information by yourself.
2262         </para>
2263
2264         <para>
2265         In the sections below, important records are explained.
2266         </para>
2267
2268         <section id="pcm-interface-runtime-hw">
2269         <title>Hardware Description</title>
2270         <para>
2271           The hardware descriptor (<type>snd_pcm_hardware_t</type>)
2272         contains the definitions of the fundamental hardware
2273         configuration.  Above all, you'll need to define this in
2274         <link linkend="pcm-interface-operators-open-callback"><citetitle>
2275         the open callback</citetitle></link>.
2276         Note that the runtime instance holds the copy of the
2277         descriptor, not the pointer to the existing descriptor.  That
2278         is, in the open callback, you can modify the copied descriptor
2279         (<constant>runtime-&gt;hw</constant>) as you need.  For example, if the maximum
2280         number of channels is 1 only on some chip models, you can
2281         still use the same hardware descriptor and change the
2282         channels_max later:
2283           <informalexample>
2284             <programlisting>
2285 <![CDATA[
2286           snd_pcm_runtime_t *runtime = substream->runtime;
2287           ...
2288           runtime->hw = snd_mychip_playback_hw; /* common definition */
2289           if (chip->model == VERY_OLD_ONE)
2290                   runtime->hw.channels_max = 1;
2291 ]]>
2292             </programlisting>
2293           </informalexample>
2294         </para>
2295
2296         <para>
2297           Typically, you'll have a hardware descriptor like below:
2298           <informalexample>
2299             <programlisting>
2300 <![CDATA[
2301   static snd_pcm_hardware_t snd_mychip_playback_hw = {
2302           .info = (SNDRV_PCM_INFO_MMAP |
2303                    SNDRV_PCM_INFO_INTERLEAVED |
2304                    SNDRV_PCM_INFO_BLOCK_TRANSFER |
2305                    SNDRV_PCM_INFO_MMAP_VALID),
2306           .formats =          SNDRV_PCM_FMTBIT_S16_LE,
2307           .rates =            SNDRV_PCM_RATE_8000_48000,
2308           .rate_min =         8000,
2309           .rate_max =         48000,
2310           .channels_min =     2,
2311           .channels_max =     2,
2312           .buffer_bytes_max = 32768,
2313           .period_bytes_min = 4096,
2314           .period_bytes_max = 32768,
2315           .periods_min =      1,
2316           .periods_max =      1024,
2317   };
2318 ]]>
2319             </programlisting>
2320           </informalexample>
2321         </para>
2322
2323         <para>
2324         <itemizedlist>
2325         <listitem><para>
2326           The <structfield>info</structfield> field contains the type and
2327         capabilities of this pcm. The bit flags are defined in
2328         <filename>&lt;sound/asound.h&gt;</filename> as
2329         <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2330         have to specify whether the mmap is supported and which
2331         interleaved format is supported.
2332         When the mmap is supported, add
2333         <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2334         hardware supports the interleaved or the non-interleaved
2335         format, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2336         <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2337         be set, respectively. If both are supported, you can set both,
2338         too. 
2339         </para>
2340
2341         <para>
2342           In the above example, <constant>MMAP_VALID</constant> and
2343         <constant>BLOCK_TRANSFER</constant> are specified for OSS mmap
2344         mode. Usually both are set. Of course,
2345         <constant>MMAP_VALID</constant> is set only if the mmap is
2346         really supported. 
2347         </para>
2348
2349         <para>
2350           The other possible flags are
2351         <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2352         <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2353         <constant>PAUSE</constant> bit means that the pcm supports the
2354         <quote>pause</quote> operation, while the
2355         <constant>RESUME</constant> bit means that the pcm supports
2356         the <quote>suspend/resume</quote> operation. If these flags
2357         are set, the <structfield>trigger</structfield> callback below
2358         must handle the corresponding commands. 
2359         </para>
2360
2361         <para>
2362           When the PCM substreams can be synchronized (typically,
2363         synchorinized start/stop of a playback and a capture streams),
2364         you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2365         too.  In this case, you'll need to check the linked-list of
2366         PCM substreams in the trigger callback.  This will be
2367         described in the later section.
2368         </para>
2369         </listitem>
2370
2371         <listitem>
2372         <para>
2373           <structfield>formats</structfield> field contains the bit-flags
2374         of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2375         If the hardware supports more than one format, give all or'ed
2376         bits.  In the example above, the signed 16bit little-endian
2377         format is specified.
2378         </para>
2379         </listitem>
2380
2381         <listitem>
2382         <para>
2383         <structfield>rates</structfield> field contains the bit-flags of
2384         supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2385         When the chip supports continuous rates, pass
2386         <constant>CONTINUOUS</constant> bit additionally.
2387         The pre-defined rate bits are provided only for typical
2388         rates. If your chip supports unconventional rates, you need to add
2389         <constant>KNOT</constant> bit and set up the hardware
2390         constraint manually (explained later).
2391         </para>
2392         </listitem>
2393
2394         <listitem>
2395         <para>
2396         <structfield>rate_min</structfield> and
2397         <structfield>rate_max</structfield> define the minimal and
2398         maximal sample rate.  This should correspond somehow to
2399         <structfield>rates</structfield> bits.
2400         </para>
2401         </listitem>
2402
2403         <listitem>
2404         <para>
2405         <structfield>channel_min</structfield> and
2406         <structfield>channel_max</structfield> 
2407         define, as you might already expected, the minimal and maximal
2408         number of channels.
2409         </para>
2410         </listitem>
2411
2412         <listitem>
2413         <para>
2414         <structfield>buffer_bytes_max</structfield> defines the
2415         maximal buffer size in bytes.  There is no
2416         <structfield>buffer_bytes_min</structfield> field, since
2417         it can be calculated from the minimal period size and the
2418         minimal number of periods.
2419         Meanwhile, <structfield>period_bytes_min</structfield> and
2420         define the minimal and maximal size of the period in bytes.
2421         <structfield>periods_max</structfield> and
2422         <structfield>periods_min</structfield> define the maximal and
2423         minimal number of periods in the buffer.
2424         </para>
2425
2426         <para>
2427         The <quote>period</quote> is a term, that corresponds to
2428         fragment in the OSS world.  The period defines the size at
2429         which the PCM interrupt is generated. This size strongly
2430         depends on the hardware. 
2431         Generally, the smaller period size will give you more
2432         interrupts, that is, more controls. 
2433         In the case of capture, this size defines the input latency.
2434         On the other hand, the whole buffer size defines the
2435         output latency for the playback direction.
2436         </para>
2437         </listitem>
2438
2439         <listitem>
2440         <para>
2441         There is also a field <structfield>fifo_size</structfield>.
2442         This specifies the size of the hardware FIFO, but it's not
2443         used currently in the driver nor in the alsa-lib.  So, you
2444         can ignore this field.
2445         </para>
2446         </listitem>
2447         </itemizedlist>
2448         </para>
2449         </section>
2450
2451         <section id="pcm-interface-runtime-config">
2452         <title>PCM Configurations</title>
2453         <para>
2454         Ok, let's go back again to the PCM runtime records.
2455         The most frequently referred records in the runtime instance are
2456         the PCM configurations.
2457         The PCM configurations are stored on runtime instance
2458         after the application sends <type>hw_params</type> data via
2459         alsa-lib.  There are many fields copied from hw_params and
2460         sw_params structs.  For example,
2461         <structfield>format</structfield> holds the format type
2462         chosen by the application.  This field contains the enum value
2463         <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2464         </para>
2465
2466         <para>
2467         One thing to be noted is that the configured buffer and period
2468         sizes are stored in <quote>frames</quote> in the runtime
2469         In the ALSA world, 1 frame = channels * samples-size.
2470         For conversion between frames and bytes, you can use the
2471         helper functions, <function>frames_to_bytes()</function> and
2472           <function>bytes_to_frames()</function>. 
2473           <informalexample>
2474             <programlisting>
2475 <![CDATA[
2476   period_bytes = frames_to_bytes(runtime, runtime->period_size);
2477 ]]>
2478             </programlisting>
2479           </informalexample>
2480         </para>
2481
2482         <para>
2483         Also, many software parameters (sw_params) are
2484         stored in frames, too.  Please check the type of the field.
2485         <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2486         integer while <type>snd_pcm_sframes_t</type> is for the frames
2487         as signed integer.
2488         </para>
2489         </section>
2490
2491         <section id="pcm-interface-runtime-dma">
2492         <title>DMA Buffer Information</title>
2493         <para>
2494         The DMA buffer is defined by the following four fields,
2495         <structfield>dma_area</structfield>,
2496         <structfield>dma_addr</structfield>,
2497         <structfield>dma_bytes</structfield> and
2498         <structfield>dma_private</structfield>.
2499         The <structfield>dma_area</structfield> holds the buffer
2500         pointer (the logical address).  You can call
2501         <function>memcpy</function> from/to 
2502         this pointer.  Meanwhile, <structfield>dma_addr</structfield>
2503         holds the physical address of the buffer.  This field is
2504         specified only when the buffer is a linear buffer.
2505         <structfield>dma_bytes</structfield> holds the size of buffer
2506         in bytes.  <structfield>dma_private</structfield> is used for
2507         the ALSA DMA allocator.
2508         </para>
2509
2510         <para>
2511         If you use a standard ALSA function,
2512         <function>snd_pcm_lib_malloc_pages()</function>, for
2513         allocating the buffer, these fields are set by the ALSA middle
2514         layer, and you should <emphasis>not</emphasis> change them by
2515         yourself.  You can read them but not write them.
2516         On the other hand, if you want to allocate the buffer by
2517         yourself, you'll need to manage it in hw_params callback.
2518         At least, <structfield>dma_bytes</structfield> is mandatory.
2519         <structfield>dma_area</structfield> is necessary when the
2520         buffer is mmapped.  If your driver doesn't support mmap, this
2521         field is not necessary.  <structfield>dma_addr</structfield>
2522         is also not mandatory.  You can use
2523         <structfield>dma_private</structfield> as you like, too.
2524         </para>
2525         </section>
2526
2527         <section id="pcm-interface-runtime-status">
2528         <title>Running Status</title>
2529         <para>
2530         The running status can be referred via <constant>runtime-&gt;status</constant>.
2531         This is the pointer to <type>snd_pcm_mmap_status_t</type>
2532         record.  For example, you can get the current DMA hardware
2533         pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2534         </para>
2535
2536         <para>
2537         The DMA application pointer can be referred via
2538         <constant>runtime-&gt;control</constant>, which points
2539         <type>snd_pcm_mmap_control_t</type> record.
2540         However, accessing directly to this value is not recommended.
2541         </para>
2542         </section>
2543
2544         <section id="pcm-interface-runtime-private">
2545         <title>Private Data</title> 
2546         <para>
2547         You can allocate a record for the substream and store it in
2548         <constant>runtime-&gt;private_data</constant>.  Usually, this
2549         done in
2550         <link linkend="pcm-interface-operators-open-callback"><citetitle>
2551         the open callback</citetitle></link>.
2552         Don't mix this with <constant>pcm-&gt;private_data</constant>.
2553         The <constant>pcm-&gt;private_data</constant> usually points the
2554         chip instance assigned statically at the creation of PCM, while the 
2555         <constant>runtime-&gt;private_data</constant> points a dynamic
2556         data created at the PCM open callback.
2557
2558           <informalexample>
2559             <programlisting>
2560 <![CDATA[
2561   static int snd_xxx_open(snd_pcm_substream_t *substream)
2562   {
2563           my_pcm_data_t *data;
2564           ....
2565           data = kmalloc(sizeof(*data), GFP_KERNEL);
2566           substream->runtime->private_data = data;
2567           ....
2568   }
2569 ]]>
2570             </programlisting>
2571           </informalexample>
2572         </para>
2573
2574         <para>
2575           The allocated object must be released in
2576         <link linkend="pcm-interface-operators-open-callback"><citetitle>
2577         the close callback</citetitle></link>.
2578         </para>
2579         </section>
2580
2581         <section id="pcm-interface-runtime-intr">
2582         <title>Interrupt Callbacks</title>
2583         <para>
2584         The field <structfield>transfer_ack_begin</structfield> and
2585         <structfield>transfer_ack_end</structfield> are called at
2586         the beginning and the end of
2587         <function>snd_pcm_period_elapsed()</function>, respectively. 
2588         </para>
2589         </section>
2590
2591     </section>
2592
2593     <section id="pcm-interface-operators">
2594       <title>Operators</title>
2595       <para>
2596         OK, now let me explain the detail of each pcm callback
2597       (<parameter>ops</parameter>). In general, every callback must
2598       return 0 if successful, or a negative number with the error
2599       number such as <constant>-EINVAL</constant> at any
2600       error. 
2601       </para>
2602
2603       <para>
2604         The callback function takes at least the argument with
2605         <type>snd_pcm_substream_t</type> pointer. For retrieving the
2606         chip record from the given substream instance, you can use the
2607         following macro. 
2608
2609         <informalexample>
2610           <programlisting>
2611 <![CDATA[
2612   int xxx() {
2613           mychip_t *chip = snd_pcm_substream_chip(substream);
2614           ....
2615   }
2616 ]]>
2617           </programlisting>
2618         </informalexample>
2619
2620         The macro reads <constant>substream-&gt;private_data</constant>,
2621         which is a copy of <constant>pcm-&gt;private_data</constant>.
2622         You can override the former if you need to assign different data
2623         records per PCM substream.  For example, cmi8330 driver assigns
2624         different private_data for playback and capture directions,
2625         because it uses two different codecs (SB- and AD-compatible) for
2626         different directions.
2627       </para>
2628
2629       <section id="pcm-interface-operators-open-callback">
2630         <title>open callback</title>
2631         <para>
2632           <informalexample>
2633             <programlisting>
2634 <![CDATA[
2635   static int snd_xxx_open(snd_pcm_substream_t *substream);
2636 ]]>
2637             </programlisting>
2638           </informalexample>
2639
2640           This is called when a pcm substream is opened.
2641         </para>
2642
2643         <para>
2644           At least, here you have to initialize the runtime-&gt;hw
2645           record. Typically, this is done by like this: 
2646
2647           <informalexample>
2648             <programlisting>
2649 <![CDATA[
2650   static int snd_xxx_open(snd_pcm_substream_t *substream)
2651   {
2652           mychip_t *chip = snd_pcm_substream_chip(substream);
2653           snd_pcm_runtime_t *runtime = substream->runtime;
2654
2655           runtime->hw = snd_mychip_playback_hw;
2656           return 0;
2657   }
2658 ]]>
2659             </programlisting>
2660           </informalexample>
2661
2662           where <parameter>snd_mychip_playback_hw</parameter> is the
2663           pre-defined hardware description.
2664         </para>
2665
2666         <para>
2667         You can allocate a private data in this callback, as described
2668         in <link linkend="pcm-interface-runtime-private"><citetitle>
2669         Private Data</citetitle></link> section.
2670         </para>
2671
2672         <para>
2673         If the hardware configuration needs more constraints, set the
2674         hardware constraints here, too.
2675         See <link linkend="pcm-interface-constraints"><citetitle>
2676         Constraints</citetitle></link> for more details.
2677         </para>
2678       </section>
2679
2680       <section id="pcm-interface-operators-close-callback">
2681         <title>close callback</title>
2682         <para>
2683           <informalexample>
2684             <programlisting>
2685 <![CDATA[
2686   static int snd_xxx_close(snd_pcm_substream_t *substream);
2687 ]]>
2688             </programlisting>
2689           </informalexample>
2690
2691           Obviously, this is called when a pcm substream is closed.
2692         </para>
2693
2694         <para>
2695           Any private instance for a pcm substream allocated in the
2696           open callback will be released here. 
2697
2698           <informalexample>
2699             <programlisting>
2700 <![CDATA[
2701   static int snd_xxx_close(snd_pcm_substream_t *substream)
2702   {
2703           ....
2704           kfree(substream->runtime->private_data);
2705           ....
2706   }
2707 ]]>
2708             </programlisting>
2709           </informalexample>
2710         </para>
2711       </section>
2712
2713       <section id="pcm-interface-operators-ioctl-callback">
2714         <title>ioctl callback</title>
2715         <para>
2716           This is used for any special action to pcm ioctls. But
2717         usually you can pass a generic ioctl callback, 
2718         <function>snd_pcm_lib_ioctl</function>.
2719         </para>
2720       </section>
2721
2722       <section id="pcm-interface-operators-hw-params-callback">
2723         <title>hw_params callback</title>
2724         <para>
2725           <informalexample>
2726             <programlisting>
2727 <![CDATA[
2728   static int snd_xxx_hw_params(snd_pcm_substream_t * substream,
2729                                snd_pcm_hw_params_t * hw_params);
2730 ]]>
2731             </programlisting>
2732           </informalexample>
2733
2734           This and <structfield>hw_free</structfield> callbacks exist
2735         only on ALSA 0.9.x. 
2736         </para>
2737
2738         <para>
2739           This is called when the hardware parameter
2740         (<structfield>hw_params</structfield>) is set
2741         up by the application, 
2742         that is, once when the buffer size, the period size, the
2743         format, etc. are defined for the pcm substream. 
2744         </para>
2745
2746         <para>
2747           Many hardware set-up should be done in this callback,
2748         including the allocation of buffers. 
2749         </para>
2750
2751         <para>
2752           Parameters to be initialized are retrieved by
2753           <function>params_xxx()</function> macros. For allocating a
2754           buffer, you can call a helper function, 
2755
2756           <informalexample>
2757             <programlisting>
2758 <![CDATA[
2759   snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2760 ]]>
2761             </programlisting>
2762           </informalexample>
2763
2764           <function>snd_pcm_lib_malloc_pages()</function> is available
2765           only when the DMA buffers have been pre-allocated.
2766           See the section <link
2767           linkend="buffer-and-memory-buffer-types"><citetitle>
2768           Buffer Types</citetitle></link> for more details.
2769         </para>
2770
2771         <para>
2772           Note that this and <structfield>prepare</structfield> callbacks
2773         may be called multiple times per initialization.
2774         For example, the OSS emulation may
2775         call these callbacks at each change via its ioctl. 
2776         </para>
2777
2778         <para>
2779           Thus, you need to take care not to allocate the same buffers
2780         many times, which will lead to memory leak!  Calling the
2781         helper function above many times is OK. It will release the
2782         previous buffer automatically when it was already allocated. 
2783         </para>
2784
2785         <para>
2786           Another note is that this callback is non-atomic
2787         (schedulable). This is important, because the
2788         <structfield>trigger</structfield> callback 
2789         is atomic (non-schedulable). That is, mutex or any
2790         schedule-related functions are not available in
2791         <structfield>trigger</structfield> callback.
2792         Please see the subsection
2793         <link linkend="pcm-interface-atomicity"><citetitle>
2794         Atomicity</citetitle></link> for details.
2795         </para>
2796       </section>
2797
2798       <section id="pcm-interface-operators-hw-free-callback">
2799         <title>hw_free callback</title>
2800         <para>
2801           <informalexample>
2802             <programlisting>
2803 <![CDATA[
2804   static int snd_xxx_hw_free(snd_pcm_substream_t * substream);
2805 ]]>
2806             </programlisting>
2807           </informalexample>
2808         </para>
2809
2810         <para>
2811           This is called to release the resources allocated via
2812           <structfield>hw_params</structfield>. For example, releasing the
2813           buffer via 
2814           <function>snd_pcm_lib_malloc_pages()</function> is done by
2815           calling the following: 
2816
2817           <informalexample>
2818             <programlisting>
2819 <![CDATA[
2820   snd_pcm_lib_free_pages(substream);
2821 ]]>
2822             </programlisting>
2823           </informalexample>
2824         </para>
2825
2826         <para>
2827           This function is always called before the close callback is called.
2828           Also, the callback may be called multiple times, too.
2829           Keep track whether the resource was already released. 
2830         </para>
2831       </section>
2832
2833       <section id="pcm-interface-operators-prepare-callback">
2834        <title>prepare callback</title>
2835         <para>
2836           <informalexample>
2837             <programlisting>
2838 <![CDATA[
2839   static int snd_xxx_prepare(snd_pcm_substream_t * substream);
2840 ]]>
2841             </programlisting>
2842           </informalexample>
2843         </para>
2844
2845         <para>
2846           This callback is called when the pcm is
2847         <quote>prepared</quote>. You can set the format type, sample
2848         rate, etc. here. The difference from
2849         <structfield>hw_params</structfield> is that the 
2850         <structfield>prepare</structfield> callback will be called at each
2851         time 
2852         <function>snd_pcm_prepare()</function> is called, i.e. when
2853         recovered after underruns, etc. 
2854         </para>
2855
2856         <para>
2857         Note that this callback became non-atomic since the recent version.
2858         You can use schedule-related fucntions safely in this callback now.
2859         </para>
2860
2861         <para>
2862           In this and the following callbacks, you can refer to the
2863         values via the runtime record,
2864         substream-&gt;runtime.
2865         For example, to get the current
2866         rate, format or channels, access to
2867         runtime-&gt;rate,
2868         runtime-&gt;format or
2869         runtime-&gt;channels, respectively. 
2870         The physical address of the allocated buffer is set to
2871         runtime-&gt;dma_area.  The buffer and period sizes are
2872         in runtime-&gt;buffer_size and runtime-&gt;period_size,
2873         respectively.
2874         </para>
2875
2876         <para>
2877           Be careful that this callback will be called many times at
2878         each set up, too. 
2879         </para>
2880       </section>
2881
2882       <section id="pcm-interface-operators-trigger-callback">
2883         <title>trigger callback</title>
2884         <para>
2885           <informalexample>
2886             <programlisting>
2887 <![CDATA[
2888   static int snd_xxx_trigger(snd_pcm_substream_t * substream, int cmd);
2889 ]]>
2890             </programlisting>
2891           </informalexample>
2892
2893           This is called when the pcm is started, stopped or paused.
2894         </para>
2895
2896         <para>
2897           Which action is specified in the second argument,
2898           <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2899           <filename>&lt;sound/pcm.h&gt;</filename>. At least,
2900           <constant>START</constant> and <constant>STOP</constant>
2901           commands must be defined in this callback. 
2902
2903           <informalexample>
2904             <programlisting>
2905 <![CDATA[
2906   switch (cmd) {
2907   case SNDRV_PCM_TRIGGER_START:
2908           // do something to start the PCM engine
2909           break;
2910   case SNDRV_PCM_TRIGGER_STOP:
2911           // do something to stop the PCM engine
2912           break;
2913   default:
2914           return -EINVAL;
2915   }
2916 ]]>
2917             </programlisting>
2918           </informalexample>
2919         </para>
2920
2921         <para>
2922           When the pcm supports the pause operation (given in info
2923         field of the hardware table), <constant>PAUSE_PUSE</constant>
2924         and <constant>PAUSE_RELEASE</constant> commands must be
2925         handled here, too. The former is the command to pause the pcm,
2926         and the latter to restart the pcm again. 
2927         </para>
2928
2929         <para>
2930           When the pcm supports the suspend/resume operation
2931         (i.e. <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set),
2932         <constant>SUSPEND</constant> and <constant>RESUME</constant>
2933         commands must be handled, too.
2934         These commands are issued when the power-management status is
2935         changed.  Obviously, the <constant>SUSPEND</constant> and
2936         <constant>RESUME</constant>
2937         do suspend and resume of the pcm substream, and usually, they
2938         are identical with <constant>STOP</constant> and
2939         <constant>START</constant> commands, respectively.
2940         </para>
2941
2942         <para>
2943           As mentioned, this callback is atomic.  You cannot call
2944           the function going to sleep.
2945           The trigger callback should be as minimal as possible,
2946           just really triggering the DMA.  The other stuff should be
2947           initialized hw_params and prepare callbacks properly
2948           beforehand.
2949         </para>
2950       </section>
2951
2952       <section id="pcm-interface-operators-pointer-callback">
2953         <title>pointer callback</title>
2954         <para>
2955           <informalexample>
2956             <programlisting>
2957 <![CDATA[
2958   static snd_pcm_uframes_t snd_xxx_pointer(snd_pcm_substream_t * substream)
2959 ]]>
2960             </programlisting>
2961           </informalexample>
2962
2963           This callback is called when the PCM middle layer inquires
2964         the current hardware position on the buffer. The position must
2965         be returned in frames (which was in bytes on ALSA 0.5.x),
2966         ranged from 0 to buffer_size - 1.
2967         </para>
2968
2969         <para>
2970           This is called usually from the buffer-update routine in the
2971         pcm middle layer, which is invoked when
2972         <function>snd_pcm_period_elapsed()</function> is called in the
2973         interrupt routine. Then the pcm middle layer updates the
2974         position and calculates the available space, and wakes up the
2975         sleeping poll threads, etc. 
2976         </para>
2977
2978         <para>
2979           This callback is also atomic.
2980         </para>
2981       </section>
2982
2983       <section id="pcm-interface-operators-copy-silence">
2984         <title>copy and silence callbacks</title>
2985         <para>
2986           These callbacks are not mandatory, and can be omitted in
2987         most cases. These callbacks are used when the hardware buffer
2988         cannot be on the normal memory space. Some chips have their
2989         own buffer on the hardware which is not mappable. In such a
2990         case, you have to transfer the data manually from the memory
2991         buffer to the hardware buffer. Or, if the buffer is
2992         non-contiguous on both physical and virtual memory spaces,
2993         these callbacks must be defined, too. 
2994         </para>
2995
2996         <para>
2997           If these two callbacks are defined, copy and set-silence
2998         operations are done by them. The detailed will be described in
2999         the later section <link
3000         linkend="buffer-and-memory"><citetitle>Buffer and Memory
3001         Management</citetitle></link>. 
3002         </para>
3003       </section>
3004
3005       <section id="pcm-interface-operators-ack">
3006         <title>ack callback</title>
3007         <para>
3008           This callback is also not mandatory. This callback is called
3009         when the appl_ptr is updated in read or write operations.
3010         Some drivers like emu10k1-fx and cs46xx need to track the
3011         current appl_ptr for the internal buffer, and this callback
3012         is useful only for such a purpose.
3013         </para>
3014         <para>
3015           This callback is atomic.
3016         </para>
3017       </section>
3018
3019       <section id="pcm-interface-operators-page-callback">
3020         <title>page callback</title>
3021
3022         <para>
3023           This callback is also not mandatory. This callback is used
3024         mainly for the non-contiguous buffer. The mmap calls this
3025         callback to get the page address. Some examples will be
3026         explained in the later section <link
3027         linkend="buffer-and-memory"><citetitle>Buffer and Memory
3028         Management</citetitle></link>, too. 
3029         </para>
3030       </section>
3031     </section>
3032
3033     <section id="pcm-interface-interrupt-handler">
3034       <title>Interrupt Handler</title>
3035       <para>
3036         The rest of pcm stuff is the PCM interrupt handler. The
3037       role of PCM interrupt handler in the sound driver is to update
3038       the buffer position and to tell the PCM middle layer when the
3039       buffer position goes across the prescribed period size. To
3040       inform this, call <function>snd_pcm_period_elapsed()</function>
3041       function. 
3042       </para>
3043
3044       <para>
3045         There are several types of sound chips to generate the interrupts.
3046       </para>
3047
3048       <section id="pcm-interface-interrupt-handler-boundary">
3049         <title>Interrupts at the period (fragment) boundary</title>
3050         <para>
3051           This is the most frequently found type:  the hardware
3052         generates an interrupt at each period boundary.
3053         In this case, you can call
3054         <function>snd_pcm_period_elapsed()</function> at each 
3055         interrupt. 
3056         </para>
3057
3058         <para>
3059           <function>snd_pcm_period_elapsed()</function> takes the
3060         substream pointer as its argument. Thus, you need to keep the
3061         substream pointer accessible from the chip instance. For
3062         example, define substream field in the chip record to hold the
3063         current running substream pointer, and set the pointer value
3064         at open callback (and reset at close callback). 
3065         </para>
3066
3067         <para>
3068           If you aquire a spinlock in the interrupt handler, and the
3069         lock is used in other pcm callbacks, too, then you have to
3070         release the lock before calling
3071         <function>snd_pcm_period_elapsed()</function>, because
3072         <function>snd_pcm_period_elapsed()</function> calls other pcm
3073         callbacks inside. 
3074         </para>
3075
3076         <para>
3077           A typical coding would be like:
3078
3079           <example>
3080             <title>Interrupt Handler Case #1</title>
3081             <programlisting>
3082 <![CDATA[
3083   static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id,
3084                                           struct pt_regs *regs)
3085   {
3086           mychip_t *chip = dev_id;
3087           spin_lock(&chip->lock);
3088           ....
3089           if (pcm_irq_invoked(chip)) {
3090                   /* call updater, unlock before it */
3091                   spin_unlock(&chip->lock);
3092                   snd_pcm_period_elapsed(chip->substream);
3093                   spin_lock(&chip->lock);
3094                   // acknowledge the interrupt if necessary
3095           }
3096           ....
3097           spin_unlock(&chip->lock);
3098           return IRQ_HANDLED;
3099   }
3100 ]]>
3101             </programlisting>
3102           </example>
3103         </para>
3104       </section>
3105
3106       <section id="pcm-interface-interrupt-handler-timer">
3107         <title>High-frequent timer interrupts</title>
3108         <para>
3109         This is the case when the hardware doesn't generate interrupts
3110         at the period boundary but do timer-interrupts at the fixed
3111         timer rate (e.g. es1968 or ymfpci drivers). 
3112         In this case, you need to check the current hardware
3113         position and accumulates the processed sample length at each
3114         interrupt.  When the accumulated size overcomes the period
3115         size, call 
3116         <function>snd_pcm_period_elapsed()</function> and reset the
3117         accumulator. 
3118         </para>
3119
3120         <para>
3121           A typical coding would be like the following.
3122
3123           <example>
3124             <title>Interrupt Handler Case #2</title>
3125             <programlisting>
3126 <![CDATA[
3127   static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id,
3128                                           struct pt_regs *regs)
3129   {
3130           mychip_t *chip = dev_id;
3131           spin_lock(&chip->lock);
3132           ....
3133           if (pcm_irq_invoked(chip)) {
3134                   unsigned int last_ptr, size;
3135                   /* get the current hardware pointer (in frames) */
3136                   last_ptr = get_hw_ptr(chip);
3137                   /* calculate the processed frames since the
3138                    * last update
3139                    */
3140                   if (last_ptr < chip->last_ptr)
3141                           size = runtime->buffer_size + last_ptr 
3142                                    - chip->last_ptr; 
3143                   else
3144                           size = last_ptr - chip->last_ptr;
3145                   /* remember the last updated point */
3146                   chip->last_ptr = last_ptr;
3147                   /* accumulate the size */
3148                   chip->size += size;
3149                   /* over the period boundary? */
3150                   if (chip->size >= runtime->period_size) {
3151                           /* reset the accumulator */
3152                           chip->size %= runtime->period_size;
3153                           /* call updater */
3154                           spin_unlock(&chip->lock);
3155                           snd_pcm_period_elapsed(substream);
3156                           spin_lock(&chip->lock);
3157                   }
3158                   // acknowledge the interrupt if necessary
3159           }
3160           ....
3161           spin_unlock(&chip->lock);
3162           return IRQ_HANDLED;
3163   }
3164 ]]>
3165             </programlisting>
3166           </example>
3167         </para>
3168       </section>
3169
3170       <section id="pcm-interface-interrupt-handler-both">
3171         <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3172         <para>
3173           In both cases, even if more than one period are elapsed, you
3174         don't have to call
3175         <function>snd_pcm_period_elapsed()</function> many times. Call
3176         only once. And the pcm layer will check the current hardware
3177         pointer and update to the latest status. 
3178         </para>
3179       </section>
3180     </section>
3181
3182     <section id="pcm-interface-atomicity">
3183       <title>Atomicity</title>
3184       <para>
3185       One of the most important (and thus difficult to debug) problem
3186       on the kernel programming is the race condition.
3187       On linux kernel, usually it's solved via spin-locks or
3188       semaphores.  In general, if the race condition may
3189       happen in the interrupt handler, it's handled as atomic, and you
3190       have to use spinlock for protecting the critical session.  If it
3191       never happens in the interrupt and it may take relatively long
3192       time, you should use semaphore.
3193       </para>
3194
3195       <para>
3196       As already seen, some pcm callbacks are atomic and some are
3197       not.  For example, <parameter>hw_params</parameter> callback is
3198       non-atomic, while <parameter>trigger</parameter> callback is
3199       atomic.  This means, the latter is called already in a spinlock
3200       held by the PCM middle layer. Please take this atomicity into
3201       account when you use a spinlock or a semaphore in the callbacks.
3202       </para>
3203
3204       <para>
3205       In the atomic callbacks, you cannot use functions which may call
3206       <function>schedule</function> or go to
3207       <function>sleep</function>.  The semaphore and mutex do sleep,
3208       and hence they cannot be used inside the atomic callbacks
3209       (e.g. <parameter>trigger</parameter> callback).
3210       For taking a certain delay in such a callback, please use
3211       <function>udelay()</function> or <function>mdelay()</function>.
3212       </para>
3213
3214       <para>
3215       All three atomic callbacks (trigger, pointer, and ack) are
3216       called with local interrupts disabled.
3217       </para>
3218
3219     </section>
3220     <section id="pcm-interface-constraints">
3221       <title>Constraints</title>
3222       <para>
3223         If your chip supports unconventional sample rates, or only the
3224       limited samples, you need to set a constraint for the
3225       condition. 
3226       </para>
3227
3228       <para>
3229         For example, in order to restrict the sample rates in the some
3230         supported values, use
3231         <function>snd_pcm_hw_constraint_list()</function>.
3232         You need to call this function in the open callback.
3233
3234         <example>
3235           <title>Example of Hardware Constraints</title>
3236           <programlisting>
3237 <![CDATA[
3238   static unsigned int rates[] =
3239           {4000, 10000, 22050, 44100};
3240   static snd_pcm_hw_constraint_list_t constraints_rates = {
3241           .count = ARRAY_SIZE(rates),
3242           .list = rates,
3243           .mask = 0,
3244   };
3245
3246   static int snd_mychip_pcm_open(snd_pcm_substream_t *substream)
3247   {
3248           int err;
3249           ....
3250           err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3251                                            SNDRV_PCM_HW_PARAM_RATE,
3252                                            &constraints_rates);
3253           if (err < 0)
3254                   return err;
3255           ....
3256   }
3257 ]]>
3258           </programlisting>
3259         </example>
3260       </para>
3261
3262       <para>
3263         There are many different constraints.
3264         Look in <filename>sound/pcm.h</filename> for a complete list.
3265         You can even define your own constraint rules.
3266         For example, let's suppose my_chip can manage a substream of 1 channel
3267         if and only if the format is S16_LE, otherwise it supports any format
3268         specified in the <type>snd_pcm_hardware_t</type> stucture (or in any
3269         other constraint_list). You can build a rule like this:
3270
3271         <example>
3272           <title>Example of Hardware Constraints for Channels</title>
3273           <programlisting>
3274 <![CDATA[
3275   static int hw_rule_format_by_channels(snd_pcm_hw_params_t *params,
3276                                         snd_pcm_hw_rule_t *rule)
3277   {
3278           snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
3279           snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3280           snd_mask_t fmt;
3281
3282           snd_mask_any(&fmt);    /* Init the struct */
3283           if (c->min < 2) {
3284                   fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3285                   return snd_mask_refine(f, &fmt);
3286           }
3287           return 0;
3288   }
3289 ]]>
3290           </programlisting>
3291         </example>
3292       </para>
3293  
3294       <para>
3295         Then you need to call this function to add your rule:
3296
3297        <informalexample>
3298          <programlisting>
3299 <![CDATA[
3300   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3301                       hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3302                       -1);
3303 ]]>
3304           </programlisting>
3305         </informalexample>
3306       </para>
3307
3308       <para>
3309         The rule function is called when an application sets the number of
3310         channels. But an application can set the format before the number of
3311         channels. Thus you also need to define the inverse rule:
3312
3313        <example>
3314          <title>Example of Hardware Constraints for Channels</title>
3315          <programlisting>
3316 <![CDATA[
3317   static int hw_rule_channels_by_format(snd_pcm_hw_params_t *params,
3318                                         snd_pcm_hw_rule_t *rule)
3319   {
3320           snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
3321           snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3322           snd_interval_t ch;
3323
3324           snd_interval_any(&ch);
3325           if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3326                   ch.min = ch.max = 1;
3327                   ch.integer = 1;
3328                   return snd_interval_refine(c, &ch);
3329           }
3330           return 0;
3331   }
3332 ]]>
3333           </programlisting>
3334         </example>
3335       </para>
3336
3337       <para>
3338       ...and in the open callback:
3339        <informalexample>
3340          <programlisting>
3341 <![CDATA[
3342   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3343                       hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3344                       -1);
3345 ]]>
3346           </programlisting>
3347         </informalexample>
3348       </para>
3349
3350       <para>
3351         I won't explain more details here, rather I
3352         would like to say, <quote>Luke, use the source.</quote>
3353       </para>
3354     </section>
3355
3356   </chapter>
3357
3358
3359 <!-- ****************************************************** -->
3360 <!-- Control Interface  -->
3361 <!-- ****************************************************** -->
3362   <chapter id="control-interface">
3363     <title>Control Interface</title>
3364
3365     <section id="control-interface-general">
3366       <title>General</title>
3367       <para>
3368         The control interface is used widely for many switches,
3369       sliders, etc. which are accessed from the user-space. Its most
3370       important use is the mixer interface. In other words, on ALSA
3371       0.9.x, all the mixer stuff is implemented on the control kernel
3372       API (while there was an independent mixer kernel API on 0.5.x). 
3373       </para>
3374
3375       <para>
3376         ALSA has a well-defined AC97 control module. If your chip
3377       supports only the AC97 and nothing else, you can skip this
3378       section. 
3379       </para>
3380
3381       <para>
3382         The control API is defined in
3383       <filename>&lt;sound/control.h&gt;</filename>.
3384       Include this file if you add your own controls.
3385       </para>
3386     </section>
3387
3388     <section id="control-interface-definition">
3389       <title>Definition of Controls</title>
3390       <para>
3391         For creating a new control, you need to define the three
3392       callbacks: <structfield>info</structfield>,
3393       <structfield>get</structfield> and
3394       <structfield>put</structfield>. Then, define a
3395       <type>snd_kcontrol_new_t</type> record, such as: 
3396
3397         <example>
3398           <title>Definition of a Control</title>
3399           <programlisting>
3400 <![CDATA[
3401   static snd_kcontrol_new_t my_control __devinitdata = {
3402           .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3403           .name = "PCM Playback Switch",
3404           .index = 0,
3405           .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3406           .private_values = 0xffff,
3407           .info = my_control_info,
3408           .get = my_control_get,
3409           .put = my_control_put
3410   };
3411 ]]>
3412           </programlisting>
3413         </example>
3414       </para>
3415
3416       <para>
3417         Most likely the control is created via
3418       <function>snd_ctl_new1()</function>, and in such a case, you can
3419       add <parameter>__devinitdata</parameter> prefix to the
3420       definition like above. 
3421       </para>
3422
3423       <para>
3424         The <structfield>iface</structfield> field specifies the type of
3425       the control, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3426       is usually <constant>MIXER</constant>.
3427       Use <constant>CARD</constant> for global controls that are not
3428       logically part of the mixer.
3429       If the control is closely associated with some specific device on
3430       the sound card, use <constant>HWDEP</constant>,
3431       <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3432       <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3433       specify the device number with the
3434       <structfield>device</structfield> and
3435       <structfield>subdevice</structfield> fields.
3436       </para>
3437
3438       <para>
3439         The <structfield>name</structfield> is the name identifier
3440       string. On ALSA 0.9.x, the control name is very important,
3441       because its role is classified from its name. There are
3442       pre-defined standard control names. The details are described in
3443       the subsection
3444       <link linkend="control-interface-control-names"><citetitle>
3445       Control Names</citetitle></link>.
3446       </para>
3447
3448       <para>
3449         The <structfield>index</structfield> field holds the index number
3450       of this control. If there are several different controls with
3451       the same name, they can be distinguished by the index
3452       number. This is the case when 
3453       several codecs exist on the card. If the index is zero, you can
3454       omit the definition above. 
3455       </para>
3456
3457       <para>
3458         The <structfield>access</structfield> field contains the access
3459       type of this control. Give the combination of bit masks,
3460       <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3461       The detailed will be explained in the subsection
3462       <link linkend="control-interface-access-flags"><citetitle>
3463       Access Flags</citetitle></link>.
3464       </para>
3465
3466       <para>
3467         The <structfield>private_values</structfield> field contains
3468       an arbitrary long integer value for this record. When using
3469       generic <structfield>info</structfield>,
3470       <structfield>get</structfield> and
3471       <structfield>put</structfield> callbacks, you can pass a value 
3472       through this field. If several small numbers are necessary, you can
3473       combine them in bitwise. Or, it's possible to give a pointer
3474       (casted to unsigned long) of some record to this field, too. 
3475       </para>
3476
3477       <para>
3478         The other three are
3479         <link linkend="control-interface-callbacks"><citetitle>
3480         callback functions</citetitle></link>.
3481       </para>
3482     </section>
3483
3484     <section id="control-interface-control-names">
3485       <title>Control Names</title>
3486       <para>
3487         There are some standards for defining the control names. A
3488       control is usually defined from the three parts as
3489       <quote>SOURCE DIRECTION FUNCTION</quote>. 
3490       </para>
3491
3492       <para>
3493         The first, <constant>SOURCE</constant>, specifies the source
3494       of the control, and is a string such as <quote>Master</quote>,
3495       <quote>PCM</quote>, <quote>CD</quote> or
3496       <quote>Line</quote>. There are many pre-defined sources. 
3497       </para>
3498
3499       <para>
3500         The second, <constant>DIRECTION</constant>, is one of the
3501       following strings according to the direction of the control:
3502       <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3503       Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3504       be omitted, meaning both playback and capture directions. 
3505       </para>
3506
3507       <para>
3508         The third, <constant>FUNCTION</constant>, is one of the
3509       following strings according to the function of the control:
3510       <quote>Switch</quote>, <quote>Volume</quote> and
3511       <quote>Route</quote>. 
3512       </para>
3513
3514       <para>
3515         The example of control names are, thus, <quote>Master Capture
3516       Switch</quote> or <quote>PCM Playback Volume</quote>. 
3517       </para>
3518
3519       <para>
3520         There are some exceptions:
3521       </para>
3522
3523       <section id="control-interface-control-names-global">
3524         <title>Global capture and playback</title>
3525         <para>