About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / writing-an-alsa-driver.tmpl




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.