About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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


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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog