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