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