About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 4.0. Page generated on 2015-04-14 21:23 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		/* -- interrupt callbacks -- */
2185		void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2186		void (*transfer_ack_end)(struct snd_pcm_substream *substream);
2187	
2188		/* -- timer -- */
2189		unsigned int timer_resolution;	/* timer resolution */
2190	
2191		/* -- DMA -- */           
2192		unsigned char *dma_area;	/* DMA area */
2193		dma_addr_t dma_addr;		/* physical bus address (not accessible from main CPU) */
2194		size_t dma_bytes;		/* size of DMA area */
2195	
2196		struct snd_dma_buffer *dma_buffer_p;	/* allocated buffer */
2197	
2198	#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2199		/* -- OSS things -- */
2200		struct snd_pcm_oss_runtime oss;
2201	#endif
2202	};
2203	]]>
2204	            </programlisting>
2205	          </informalexample>
2206		</para>
2207	
2208		<para>
2209		  For the operators (callbacks) of each sound driver, most of
2210		these records are supposed to be read-only.  Only the PCM
2211		middle-layer changes / updates them.  The exceptions are
2212		the hardware description (hw), interrupt callbacks
2213		(transfer_ack_xxx), DMA buffer information, and the private
2214		data.  Besides, if you use the standard buffer allocation
2215		method via <function>snd_pcm_lib_malloc_pages()</function>,
2216		you don't need to set the DMA buffer information by yourself.
2217		</para>
2218	
2219		<para>
2220		In the sections below, important records are explained.
2221		</para>
2222	
2223		<section id="pcm-interface-runtime-hw">
2224		<title>Hardware Description</title>
2225		<para>
2226		  The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
2227		contains the definitions of the fundamental hardware
2228		configuration.  Above all, you'll need to define this in
2229		<link linkend="pcm-interface-operators-open-callback"><citetitle>
2230		the open callback</citetitle></link>.
2231		Note that the runtime instance holds the copy of the
2232		descriptor, not the pointer to the existing descriptor.  That
2233		is, in the open callback, you can modify the copied descriptor
2234		(<constant>runtime-&gt;hw</constant>) as you need.  For example, if the maximum
2235		number of channels is 1 only on some chip models, you can
2236		still use the same hardware descriptor and change the
2237		channels_max later:
2238	          <informalexample>
2239	            <programlisting>
2240	<![CDATA[
2241	          struct snd_pcm_runtime *runtime = substream->runtime;
2242	          ...
2243	          runtime->hw = snd_mychip_playback_hw; /* common definition */
2244	          if (chip->model == VERY_OLD_ONE)
2245	                  runtime->hw.channels_max = 1;
2246	]]>
2247	            </programlisting>
2248	          </informalexample>
2249		</para>
2250	
2251		<para>
2252		  Typically, you'll have a hardware descriptor as below:
2253	          <informalexample>
2254	            <programlisting>
2255	<![CDATA[
2256	  static struct snd_pcm_hardware snd_mychip_playback_hw = {
2257	          .info = (SNDRV_PCM_INFO_MMAP |
2258	                   SNDRV_PCM_INFO_INTERLEAVED |
2259	                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
2260	                   SNDRV_PCM_INFO_MMAP_VALID),
2261	          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
2262	          .rates =            SNDRV_PCM_RATE_8000_48000,
2263	          .rate_min =         8000,
2264	          .rate_max =         48000,
2265	          .channels_min =     2,
2266	          .channels_max =     2,
2267	          .buffer_bytes_max = 32768,
2268	          .period_bytes_min = 4096,
2269	          .period_bytes_max = 32768,
2270	          .periods_min =      1,
2271	          .periods_max =      1024,
2272	  };
2273	]]>
2274	            </programlisting>
2275	          </informalexample>
2276	        </para>
2277	
2278	        <para>
2279		<itemizedlist>
2280		<listitem><para>
2281	          The <structfield>info</structfield> field contains the type and
2282	        capabilities of this pcm. The bit flags are defined in
2283	        <filename>&lt;sound/asound.h&gt;</filename> as
2284	        <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2285	        have to specify whether the mmap is supported and which
2286	        interleaved format is supported.
2287	        When the hardware supports mmap, add the
2288	        <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2289	        hardware supports the interleaved or the non-interleaved
2290	        formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2291	        <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2292	        be set, respectively. If both are supported, you can set both,
2293	        too. 
2294	        </para>
2295	
2296	        <para>
2297	          In the above example, <constant>MMAP_VALID</constant> and
2298	        <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
2299	        mode. Usually both are set. Of course,
2300	        <constant>MMAP_VALID</constant> is set only if the mmap is
2301	        really supported. 
2302	        </para>
2303	
2304	        <para>
2305	          The other possible flags are
2306	        <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2307	        <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2308	        <constant>PAUSE</constant> bit means that the pcm supports the
2309	        <quote>pause</quote> operation, while the
2310	        <constant>RESUME</constant> bit means that the pcm supports
2311	        the full <quote>suspend/resume</quote> operation.
2312		If the <constant>PAUSE</constant> flag is set,
2313		the <structfield>trigger</structfield> callback below
2314	        must handle the corresponding (pause push/release) commands.
2315		The suspend/resume trigger commands can be defined even without
2316		the <constant>RESUME</constant> flag.  See <link
2317		linkend="power-management"><citetitle>
2318		Power Management</citetitle></link> section for details.
2319	        </para>
2320	
2321		<para>
2322		  When the PCM substreams can be synchronized (typically,
2323		synchronized start/stop of a playback and a capture streams),
2324		you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2325		too.  In this case, you'll need to check the linked-list of
2326		PCM substreams in the trigger callback.  This will be
2327		described in the later section.
2328		</para>
2329		</listitem>
2330	
2331		<listitem>
2332	        <para>
2333	          <structfield>formats</structfield> field contains the bit-flags
2334	        of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2335	        If the hardware supports more than one format, give all or'ed
2336	        bits.  In the example above, the signed 16bit little-endian
2337	        format is specified.
2338	        </para>
2339		</listitem>
2340	
2341		<listitem>
2342	        <para>
2343	        <structfield>rates</structfield> field contains the bit-flags of
2344	        supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2345	        When the chip supports continuous rates, pass
2346	        <constant>CONTINUOUS</constant> bit additionally.
2347	        The pre-defined rate bits are provided only for typical
2348		rates. If your chip supports unconventional rates, you need to add
2349	        the <constant>KNOT</constant> bit and set up the hardware
2350	        constraint manually (explained later).
2351	        </para>
2352		</listitem>
2353	
2354		<listitem>
2355		<para>
2356		<structfield>rate_min</structfield> and
2357		<structfield>rate_max</structfield> define the minimum and
2358		maximum sample rate.  This should correspond somehow to
2359		<structfield>rates</structfield> bits.
2360		</para>
2361		</listitem>
2362	
2363		<listitem>
2364		<para>
2365		<structfield>channel_min</structfield> and
2366		<structfield>channel_max</structfield> 
2367		define, as you might already expected, the minimum and maximum
2368		number of channels.
2369		</para>
2370		</listitem>
2371	
2372		<listitem>
2373		<para>
2374		<structfield>buffer_bytes_max</structfield> defines the
2375		maximum buffer size in bytes.  There is no
2376		<structfield>buffer_bytes_min</structfield> field, since
2377		it can be calculated from the minimum period size and the
2378		minimum number of periods.
2379		Meanwhile, <structfield>period_bytes_min</structfield> and
2380		define the minimum and maximum size of the period in bytes.
2381		<structfield>periods_max</structfield> and
2382		<structfield>periods_min</structfield> define the maximum and
2383		minimum number of periods in the buffer.
2384	        </para>
2385	
2386		<para>
2387		The <quote>period</quote> is a term that corresponds to
2388		a fragment in the OSS world. The period defines the size at
2389		which a PCM interrupt is generated. This size strongly
2390		depends on the hardware. 
2391		Generally, the smaller period size will give you more
2392		interrupts, that is, more controls. 
2393		In the case of capture, this size defines the input latency.
2394		On the other hand, the whole buffer size defines the
2395		output latency for the playback direction.
2396		</para>
2397		</listitem>
2398	
2399		<listitem>
2400		<para>
2401		There is also a field <structfield>fifo_size</structfield>.
2402		This specifies the size of the hardware FIFO, but currently it
2403		is neither used in the driver nor in the alsa-lib.  So, you
2404		can ignore this field.
2405		</para>
2406		</listitem>
2407		</itemizedlist>
2408		</para>
2409		</section>
2410	
2411		<section id="pcm-interface-runtime-config">
2412		<title>PCM Configurations</title>
2413		<para>
2414		Ok, let's go back again to the PCM runtime records.
2415		The most frequently referred records in the runtime instance are
2416		the PCM configurations.
2417		The PCM configurations are stored in the runtime instance
2418		after the application sends <type>hw_params</type> data via
2419		alsa-lib.  There are many fields copied from hw_params and
2420		sw_params structs.  For example,
2421		<structfield>format</structfield> holds the format type
2422		chosen by the application.  This field contains the enum value
2423		<constant>SNDRV_PCM_FORMAT_XXX</constant>.
2424		</para>
2425	
2426		<para>
2427		One thing to be noted is that the configured buffer and period
2428		sizes are stored in <quote>frames</quote> in the runtime.
2429	        In the ALSA world, 1 frame = channels * samples-size.
2430		For conversion between frames and bytes, you can use the
2431		<function>frames_to_bytes()</function> and
2432	          <function>bytes_to_frames()</function> helper functions. 
2433	          <informalexample>
2434	            <programlisting>
2435	<![CDATA[
2436	  period_bytes = frames_to_bytes(runtime, runtime->period_size);
2437	]]>
2438	            </programlisting>
2439	          </informalexample>
2440	        </para>
2441	
2442		<para>
2443		Also, many software parameters (sw_params) are
2444		stored in frames, too.  Please check the type of the field.
2445		<type>snd_pcm_uframes_t</type> is for the frames as unsigned
2446		integer while <type>snd_pcm_sframes_t</type> is for the frames
2447		as signed integer.
2448		</para>
2449		</section>
2450	
2451		<section id="pcm-interface-runtime-dma">
2452		<title>DMA Buffer Information</title>
2453		<para>
2454		The DMA buffer is defined by the following four fields,
2455		<structfield>dma_area</structfield>,
2456		<structfield>dma_addr</structfield>,
2457		<structfield>dma_bytes</structfield> and
2458		<structfield>dma_private</structfield>.
2459		The <structfield>dma_area</structfield> holds the buffer
2460		pointer (the logical address).  You can call
2461		<function>memcpy</function> from/to 
2462		this pointer.  Meanwhile, <structfield>dma_addr</structfield>
2463		holds the physical address of the buffer.  This field is
2464		specified only when the buffer is a linear buffer.
2465		<structfield>dma_bytes</structfield> holds the size of buffer
2466		in bytes.  <structfield>dma_private</structfield> is used for
2467		the ALSA DMA allocator.
2468		</para>
2469	
2470		<para>
2471		If you use a standard ALSA function,
2472		<function>snd_pcm_lib_malloc_pages()</function>, for
2473		allocating the buffer, these fields are set by the ALSA middle
2474		layer, and you should <emphasis>not</emphasis> change them by
2475		yourself.  You can read them but not write them.
2476		On the other hand, if you want to allocate the buffer by
2477		yourself, you'll need to manage it in hw_params callback.
2478		At least, <structfield>dma_bytes</structfield> is mandatory.
2479		<structfield>dma_area</structfield> is necessary when the
2480		buffer is mmapped.  If your driver doesn't support mmap, this
2481		field is not necessary.  <structfield>dma_addr</structfield>
2482		is also optional.  You can use
2483		<structfield>dma_private</structfield> as you like, too.
2484		</para>
2485		</section>
2486	
2487		<section id="pcm-interface-runtime-status">
2488		<title>Running Status</title>
2489		<para>
2490		The running status can be referred via <constant>runtime-&gt;status</constant>.
2491		This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
2492		record.  For example, you can get the current DMA hardware
2493		pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2494		</para>
2495	
2496		<para>
2497		The DMA application pointer can be referred via
2498		<constant>runtime-&gt;control</constant>, which points to the
2499		struct <structname>snd_pcm_mmap_control</structname> record.
2500		However, accessing directly to this value is not recommended.
2501		</para>
2502		</section>
2503	
2504		<section id="pcm-interface-runtime-private">
2505		<title>Private Data</title> 
2506		<para>
2507		You can allocate a record for the substream and store it in
2508		<constant>runtime-&gt;private_data</constant>.  Usually, this
2509		is done in
2510		<link linkend="pcm-interface-operators-open-callback"><citetitle>
2511		the open callback</citetitle></link>.
2512		Don't mix this with <constant>pcm-&gt;private_data</constant>.
2513		The <constant>pcm-&gt;private_data</constant> usually points to the
2514		chip instance assigned statically at the creation of PCM, while the 
2515		<constant>runtime-&gt;private_data</constant> points to a dynamic
2516		data structure created at the PCM open callback.
2517	
2518	          <informalexample>
2519	            <programlisting>
2520	<![CDATA[
2521	  static int snd_xxx_open(struct snd_pcm_substream *substream)
2522	  {
2523	          struct my_pcm_data *data;
2524	          ....
2525	          data = kmalloc(sizeof(*data), GFP_KERNEL);
2526	          substream->runtime->private_data = data;
2527	          ....
2528	  }
2529	]]>
2530	            </programlisting>
2531	          </informalexample>
2532	        </para>
2533	
2534	        <para>
2535	          The allocated object must be released in
2536		<link linkend="pcm-interface-operators-open-callback"><citetitle>
2537		the close callback</citetitle></link>.
2538	        </para>
2539		</section>
2540	
2541		<section id="pcm-interface-runtime-intr">
2542		<title>Interrupt Callbacks</title>
2543		<para>
2544		The field <structfield>transfer_ack_begin</structfield> and
2545		<structfield>transfer_ack_end</structfield> are called at
2546		the beginning and at the end of
2547		<function>snd_pcm_period_elapsed()</function>, respectively. 
2548		</para>
2549		</section>
2550	
2551	    </section>
2552	
2553	    <section id="pcm-interface-operators">
2554	      <title>Operators</title>
2555	      <para>
2556	        OK, now let me give details about each pcm callback
2557	      (<parameter>ops</parameter>). In general, every callback must
2558	      return 0 if successful, or a negative error number
2559	      such as <constant>-EINVAL</constant>. To choose an appropriate
2560	      error number, it is advised to check what value other parts of
2561	      the kernel return when the same kind of request fails.
2562	      </para>
2563	
2564	      <para>
2565	        The callback function takes at least the argument with
2566	        <structname>snd_pcm_substream</structname> pointer. To retrieve
2567	        the chip record from the given substream instance, you can use the
2568	        following macro. 
2569	
2570	        <informalexample>
2571	          <programlisting>
2572	<![CDATA[
2573	  int xxx() {
2574	          struct mychip *chip = snd_pcm_substream_chip(substream);
2575	          ....
2576	  }
2577	]]>
2578	          </programlisting>
2579	        </informalexample>
2580	
2581		The macro reads <constant>substream-&gt;private_data</constant>,
2582		which is a copy of <constant>pcm-&gt;private_data</constant>.
2583		You can override the former if you need to assign different data
2584		records per PCM substream.  For example, the cmi8330 driver assigns
2585		different private_data for playback and capture directions,
2586		because it uses two different codecs (SB- and AD-compatible) for
2587		different directions.
2588	      </para>
2589	
2590	      <section id="pcm-interface-operators-open-callback">
2591	        <title>open callback</title>
2592	        <para>
2593	          <informalexample>
2594	            <programlisting>
2595	<![CDATA[
2596	  static int snd_xxx_open(struct snd_pcm_substream *substream);
2597	]]>
2598	            </programlisting>
2599	          </informalexample>
2600	
2601	          This is called when a pcm substream is opened.
2602	        </para>
2603	
2604	        <para>
2605	          At least, here you have to initialize the runtime-&gt;hw
2606	          record. Typically, this is done by like this: 
2607	
2608	          <informalexample>
2609	            <programlisting>
2610	<![CDATA[
2611	  static int snd_xxx_open(struct snd_pcm_substream *substream)
2612	  {
2613	          struct mychip *chip = snd_pcm_substream_chip(substream);
2614	          struct snd_pcm_runtime *runtime = substream->runtime;
2615	
2616	          runtime->hw = snd_mychip_playback_hw;
2617	          return 0;
2618	  }
2619	]]>
2620	            </programlisting>
2621	          </informalexample>
2622	
2623	          where <parameter>snd_mychip_playback_hw</parameter> is the
2624	          pre-defined hardware description.
2625		</para>
2626	
2627		<para>
2628		You can allocate a private data in this callback, as described
2629		in <link linkend="pcm-interface-runtime-private"><citetitle>
2630		Private Data</citetitle></link> section.
2631		</para>
2632	
2633		<para>
2634		If the hardware configuration needs more constraints, set the
2635		hardware constraints here, too.
2636		See <link linkend="pcm-interface-constraints"><citetitle>
2637		Constraints</citetitle></link> for more details.
2638		</para>
2639	      </section>
2640	
2641	      <section id="pcm-interface-operators-close-callback">
2642	        <title>close callback</title>
2643	        <para>
2644	          <informalexample>
2645	            <programlisting>
2646	<![CDATA[
2647	  static int snd_xxx_close(struct snd_pcm_substream *substream);
2648	]]>
2649	            </programlisting>
2650	          </informalexample>
2651	
2652	          Obviously, this is called when a pcm substream is closed.
2653	        </para>
2654	
2655	        <para>
2656	          Any private instance for a pcm substream allocated in the
2657	          open callback will be released here. 
2658	
2659	          <informalexample>
2660	            <programlisting>
2661	<![CDATA[
2662	  static int snd_xxx_close(struct snd_pcm_substream *substream)
2663	  {
2664	          ....
2665	          kfree(substream->runtime->private_data);
2666	          ....
2667	  }
2668	]]>
2669	            </programlisting>
2670	          </informalexample>
2671	        </para>
2672	      </section>
2673	
2674	      <section id="pcm-interface-operators-ioctl-callback">
2675	        <title>ioctl callback</title>
2676	        <para>
2677	          This is used for any special call to pcm ioctls. But
2678	        usually you can pass a generic ioctl callback, 
2679	        <function>snd_pcm_lib_ioctl</function>.
2680	        </para>
2681	      </section>
2682	
2683	      <section id="pcm-interface-operators-hw-params-callback">
2684	        <title>hw_params callback</title>
2685	        <para>
2686	          <informalexample>
2687	            <programlisting>
2688	<![CDATA[
2689	  static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2690	                               struct snd_pcm_hw_params *hw_params);
2691	]]>
2692	            </programlisting>
2693	          </informalexample>
2694	        </para>
2695	
2696	        <para>
2697	          This is called when the hardware parameter
2698	        (<structfield>hw_params</structfield>) is set
2699	        up by the application, 
2700	        that is, once when the buffer size, the period size, the
2701	        format, etc. are defined for the pcm substream. 
2702	        </para>
2703	
2704	        <para>
2705	          Many hardware setups should be done in this callback,
2706	        including the allocation of buffers. 
2707	        </para>
2708	
2709	        <para>
2710	          Parameters to be initialized are retrieved by
2711	          <function>params_xxx()</function> macros. To allocate
2712	          buffer, you can call a helper function, 
2713	
2714	          <informalexample>
2715	            <programlisting>
2716	<![CDATA[
2717	  snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2718	]]>
2719	            </programlisting>
2720	          </informalexample>
2721	
2722	          <function>snd_pcm_lib_malloc_pages()</function> is available
2723		  only when the DMA buffers have been pre-allocated.
2724		  See the section <link
2725		  linkend="buffer-and-memory-buffer-types"><citetitle>
2726		  Buffer Types</citetitle></link> for more details.
2727	        </para>
2728	
2729	        <para>
2730	          Note that this and <structfield>prepare</structfield> callbacks
2731	        may be called multiple times per initialization.
2732	        For example, the OSS emulation may
2733	        call these callbacks at each change via its ioctl. 
2734	        </para>
2735	
2736	        <para>
2737	          Thus, you need to be careful not to allocate the same buffers
2738	        many times, which will lead to memory leaks!  Calling the
2739	        helper function above many times is OK. It will release the
2740	        previous buffer automatically when it was already allocated. 
2741	        </para>
2742	
2743	        <para>
2744	          Another note is that this callback is non-atomic
2745	        (schedulable) as default, i.e. when no
2746		<structfield>nonatomic</structfield> flag set.
2747		This is important, because the
2748	        <structfield>trigger</structfield> callback 
2749	        is atomic (non-schedulable). That is, mutexes or any
2750	        schedule-related functions are not available in
2751	        <structfield>trigger</structfield> callback.
2752		Please see the subsection
2753		<link linkend="pcm-interface-atomicity"><citetitle>
2754		Atomicity</citetitle></link> for details.
2755	        </para>
2756	      </section>
2757	
2758	      <section id="pcm-interface-operators-hw-free-callback">
2759	        <title>hw_free callback</title>
2760	        <para>
2761	          <informalexample>
2762	            <programlisting>
2763	<![CDATA[
2764	  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2765	]]>
2766	            </programlisting>
2767	          </informalexample>
2768	        </para>
2769	
2770	        <para>
2771	          This is called to release the resources allocated via
2772	          <structfield>hw_params</structfield>. For example, releasing the
2773	          buffer via 
2774	          <function>snd_pcm_lib_malloc_pages()</function> is done by
2775	          calling the following: 
2776	
2777	          <informalexample>
2778	            <programlisting>
2779	<![CDATA[
2780	  snd_pcm_lib_free_pages(substream);
2781	]]>
2782	            </programlisting>
2783	          </informalexample>
2784	        </para>
2785	
2786	        <para>
2787	          This function is always called before the close callback is called.
2788	          Also, the callback may be called multiple times, too.
2789	          Keep track whether the resource was already released. 
2790	        </para>
2791	      </section>
2792	
2793	      <section id="pcm-interface-operators-prepare-callback">
2794	       <title>prepare callback</title>
2795	        <para>
2796	          <informalexample>
2797	            <programlisting>
2798	<![CDATA[
2799	  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2800	]]>
2801	            </programlisting>
2802	          </informalexample>
2803	        </para>
2804	
2805	        <para>
2806	          This callback is called when the pcm is
2807	        <quote>prepared</quote>. You can set the format type, sample
2808	        rate, etc. here. The difference from
2809	        <structfield>hw_params</structfield> is that the 
2810	        <structfield>prepare</structfield> callback will be called each
2811	        time 
2812	        <function>snd_pcm_prepare()</function> is called, i.e. when
2813	        recovering after underruns, etc. 
2814	        </para>
2815	
2816	        <para>
2817		Note that this callback is now non-atomic.
2818		You can use schedule-related functions safely in this callback.
2819	        </para>
2820	
2821	        <para>
2822	          In this and the following callbacks, you can refer to the
2823	        values via the runtime record,
2824	        substream-&gt;runtime.
2825	        For example, to get the current
2826	        rate, format or channels, access to
2827	        runtime-&gt;rate,
2828	        runtime-&gt;format or
2829	        runtime-&gt;channels, respectively. 
2830	        The physical address of the allocated buffer is set to
2831		runtime-&gt;dma_area.  The buffer and period sizes are
2832		in runtime-&gt;buffer_size and runtime-&gt;period_size,
2833		respectively.
2834	        </para>
2835	
2836	        <para>
2837	          Be careful that this callback will be called many times at
2838	        each setup, too. 
2839	        </para>
2840	      </section>
2841	
2842	      <section id="pcm-interface-operators-trigger-callback">
2843	        <title>trigger callback</title>
2844	        <para>
2845	          <informalexample>
2846	            <programlisting>
2847	<![CDATA[
2848	  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2849	]]>
2850	            </programlisting>
2851	          </informalexample>
2852	
2853	          This is called when the pcm is started, stopped or paused.
2854	        </para>
2855	
2856	        <para>
2857	          Which action is specified in the second argument,
2858	          <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2859	          <filename>&lt;sound/pcm.h&gt;</filename>. At least,
2860	          the <constant>START</constant> and <constant>STOP</constant>
2861	          commands must be defined in this callback. 
2862	
2863	          <informalexample>
2864	            <programlisting>
2865	<![CDATA[
2866	  switch (cmd) {
2867	  case SNDRV_PCM_TRIGGER_START:
2868	          /* do something to start the PCM engine */
2869	          break;
2870	  case SNDRV_PCM_TRIGGER_STOP:
2871	          /* do something to stop the PCM engine */
2872	          break;
2873	  default:
2874	          return -EINVAL;
2875	  }
2876	]]>
2877	            </programlisting>
2878	          </informalexample>
2879	        </para>
2880	
2881	        <para>
2882	          When the pcm supports the pause operation (given in the info
2883	        field of the hardware table), the <constant>PAUSE_PUSH</constant>
2884	        and <constant>PAUSE_RELEASE</constant> commands must be
2885	        handled here, too. The former is the command to pause the pcm,
2886	        and the latter to restart the pcm again. 
2887	        </para>
2888	
2889	        <para>
2890	          When the pcm supports the suspend/resume operation,
2891		regardless of full or partial suspend/resume support,
2892	        the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2893	        commands must be handled, too.
2894	        These commands are issued when the power-management status is
2895	        changed.  Obviously, the <constant>SUSPEND</constant> and
2896	        <constant>RESUME</constant> commands
2897	        suspend and resume the pcm substream, and usually, they
2898	        are identical to the <constant>STOP</constant> and
2899	        <constant>START</constant> commands, respectively.
2900		  See the <link linkend="power-management"><citetitle>
2901		Power Management</citetitle></link> section for details.
2902	        </para>
2903	
2904	        <para>
2905	          As mentioned, this callback is atomic as default unless
2906		  <structfield>nonatomic</structfield> flag set, and
2907		  you cannot call functions which may sleep.
2908		  The trigger callback should be as minimal as possible,
2909		  just really triggering the DMA.  The other stuff should be
2910		  initialized hw_params and prepare callbacks properly
2911		  beforehand.
2912	        </para>
2913	      </section>
2914	
2915	      <section id="pcm-interface-operators-pointer-callback">
2916	        <title>pointer callback</title>
2917	        <para>
2918	          <informalexample>
2919	            <programlisting>
2920	<![CDATA[
2921	  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2922	]]>
2923	            </programlisting>
2924	          </informalexample>
2925	
2926	          This callback is called when the PCM middle layer inquires
2927	        the current hardware position on the buffer. The position must
2928	        be returned in frames,
2929	        ranging from 0 to buffer_size - 1.
2930	        </para>
2931	
2932	        <para>
2933	          This is called usually from the buffer-update routine in the
2934	        pcm middle layer, which is invoked when
2935	        <function>snd_pcm_period_elapsed()</function> is called in the
2936	        interrupt routine. Then the pcm middle layer updates the
2937	        position and calculates the available space, and wakes up the
2938	        sleeping poll threads, etc. 
2939	        </para>
2940	
2941	        <para>
2942	          This callback is also atomic as default.
2943	        </para>
2944	      </section>
2945	
2946	      <section id="pcm-interface-operators-copy-silence">
2947	        <title>copy and silence callbacks</title>
2948	        <para>
2949	          These callbacks are not mandatory, and can be omitted in
2950	        most cases. These callbacks are used when the hardware buffer
2951	        cannot be in the normal memory space. Some chips have their
2952	        own buffer on the hardware which is not mappable. In such a
2953	        case, you have to transfer the data manually from the memory
2954	        buffer to the hardware buffer. Or, if the buffer is
2955	        non-contiguous on both physical and virtual memory spaces,
2956	        these callbacks must be defined, too. 
2957	        </para>
2958	
2959	        <para>
2960	          If these two callbacks are defined, copy and set-silence
2961	        operations are done by them. The detailed will be described in
2962	        the later section <link
2963	        linkend="buffer-and-memory"><citetitle>Buffer and Memory
2964	        Management</citetitle></link>. 
2965	        </para>
2966	      </section>
2967	
2968	      <section id="pcm-interface-operators-ack">
2969	        <title>ack callback</title>
2970	        <para>
2971	          This callback is also not mandatory. This callback is called
2972	        when the appl_ptr is updated in read or write operations.
2973	        Some drivers like emu10k1-fx and cs46xx need to track the
2974		current appl_ptr for the internal buffer, and this callback
2975		is useful only for such a purpose.
2976		</para>
2977		<para>
2978		  This callback is atomic as default.
2979		</para>
2980	      </section>
2981	
2982	      <section id="pcm-interface-operators-page-callback">
2983	        <title>page callback</title>
2984	
2985	        <para>
2986	          This callback is optional too. This callback is used
2987	        mainly for non-contiguous buffers. The mmap calls this
2988	        callback to get the page address. Some examples will be
2989	        explained in the later section <link
2990	        linkend="buffer-and-memory"><citetitle>Buffer and Memory
2991	        Management</citetitle></link>, too. 
2992	        </para>
2993	      </section>
2994	    </section>
2995	
2996	    <section id="pcm-interface-interrupt-handler">
2997	      <title>Interrupt Handler</title>
2998	      <para>
2999	        The rest of pcm stuff is the PCM interrupt handler. The
3000	      role of PCM interrupt handler in the sound driver is to update
3001	      the buffer position and to tell the PCM middle layer when the
3002	      buffer position goes across the prescribed period size. To
3003	      inform this, call the <function>snd_pcm_period_elapsed()</function>
3004	      function. 
3005	      </para>
3006	
3007	      <para>
3008	        There are several types of sound chips to generate the interrupts.
3009	      </para>
3010	
3011	      <section id="pcm-interface-interrupt-handler-boundary">
3012	        <title>Interrupts at the period (fragment) boundary</title>
3013	        <para>
3014	          This is the most frequently found type:  the hardware
3015	        generates an interrupt at each period boundary.
3016		In this case, you can call
3017	        <function>snd_pcm_period_elapsed()</function> at each 
3018	        interrupt. 
3019	        </para>
3020	
3021	        <para>
3022	          <function>snd_pcm_period_elapsed()</function> takes the
3023	        substream pointer as its argument. Thus, you need to keep the
3024	        substream pointer accessible from the chip instance. For
3025	        example, define substream field in the chip record to hold the
3026	        current running substream pointer, and set the pointer value
3027	        at open callback (and reset at close callback). 
3028	        </para>
3029	
3030	        <para>
3031	          If you acquire a spinlock in the interrupt handler, and the
3032	        lock is used in other pcm callbacks, too, then you have to
3033	        release the lock before calling
3034	        <function>snd_pcm_period_elapsed()</function>, because
3035	        <function>snd_pcm_period_elapsed()</function> calls other pcm
3036	        callbacks inside. 
3037	        </para>
3038	
3039	        <para>
3040	          Typical code would be like:
3041	
3042	          <example>
3043		    <title>Interrupt Handler Case #1</title>
3044	            <programlisting>
3045	<![CDATA[
3046	  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3047	  {
3048	          struct mychip *chip = dev_id;
3049	          spin_lock(&chip->lock);
3050	          ....
3051	          if (pcm_irq_invoked(chip)) {
3052	                  /* call updater, unlock before it */
3053	                  spin_unlock(&chip->lock);
3054	                  snd_pcm_period_elapsed(chip->substream);
3055	                  spin_lock(&chip->lock);
3056	                  /* acknowledge the interrupt if necessary */
3057	          }
3058	          ....
3059	          spin_unlock(&chip->lock);
3060	          return IRQ_HANDLED;
3061	  }
3062	]]>
3063	            </programlisting>
3064	          </example>
3065	        </para>
3066	      </section>
3067	
3068	      <section id="pcm-interface-interrupt-handler-timer">
3069	        <title>High frequency timer interrupts</title>
3070	        <para>
3071		This happens when the hardware doesn't generate interrupts
3072	        at the period boundary but issues timer interrupts at a fixed
3073	        timer rate (e.g. es1968 or ymfpci drivers). 
3074	        In this case, you need to check the current hardware
3075	        position and accumulate the processed sample length at each
3076	        interrupt.  When the accumulated size exceeds the period
3077	        size, call 
3078	        <function>snd_pcm_period_elapsed()</function> and reset the
3079	        accumulator. 
3080	        </para>
3081	
3082	        <para>
3083	          Typical code would be like the following.
3084	
3085	          <example>
3086		    <title>Interrupt Handler Case #2</title>
3087	            <programlisting>
3088	<![CDATA[
3089	  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3090	  {
3091	          struct mychip *chip = dev_id;
3092	          spin_lock(&chip->lock);
3093	          ....
3094	          if (pcm_irq_invoked(chip)) {
3095	                  unsigned int last_ptr, size;
3096	                  /* get the current hardware pointer (in frames) */
3097	                  last_ptr = get_hw_ptr(chip);
3098	                  /* calculate the processed frames since the
3099	                   * last update
3100	                   */
3101	                  if (last_ptr < chip->last_ptr)
3102	                          size = runtime->buffer_size + last_ptr 
3103	                                   - chip->last_ptr; 
3104	                  else
3105	                          size = last_ptr - chip->last_ptr;
3106	                  /* remember the last updated point */
3107	                  chip->last_ptr = last_ptr;
3108	                  /* accumulate the size */
3109	                  chip->size += size;
3110	                  /* over the period boundary? */
3111	                  if (chip->size >= runtime->period_size) {
3112	                          /* reset the accumulator */
3113	                          chip->size %= runtime->period_size;
3114	                          /* call updater */
3115	                          spin_unlock(&chip->lock);
3116	                          snd_pcm_period_elapsed(substream);
3117	                          spin_lock(&chip->lock);
3118	                  }
3119	                  /* acknowledge the interrupt if necessary */
3120	          }
3121	          ....
3122	          spin_unlock(&chip->lock);
3123	          return IRQ_HANDLED;
3124	  }
3125	]]>
3126	            </programlisting>
3127	          </example>
3128	        </para>
3129	      </section>
3130	
3131	      <section id="pcm-interface-interrupt-handler-both">
3132	        <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3133	        <para>
3134	          In both cases, even if more than one period are elapsed, you
3135	        don't have to call
3136	        <function>snd_pcm_period_elapsed()</function> many times. Call
3137	        only once. And the pcm layer will check the current hardware
3138	        pointer and update to the latest status. 
3139	        </para>
3140	      </section>
3141	    </section>
3142	
3143	    <section id="pcm-interface-atomicity">
3144	      <title>Atomicity</title>
3145	      <para>
3146	      One of the most important (and thus difficult to debug) problems
3147	      in kernel programming are race conditions.
3148	      In the Linux kernel, they are usually avoided via spin-locks, mutexes
3149	      or semaphores.  In general, if a race condition can happen
3150	      in an interrupt handler, it has to be managed atomically, and you
3151	      have to use a spinlock to protect the critical session. If the
3152	      critical section is not in interrupt handler code and
3153	      if taking a relatively long time to execute is acceptable, you
3154	      should use mutexes or semaphores instead.
3155	      </para>
3156	
3157	      <para>
3158	      As already seen, some pcm callbacks are atomic and some are
3159	      not.  For example, the <parameter>hw_params</parameter> callback is
3160	      non-atomic, while <parameter>trigger</parameter> callback is
3161	      atomic.  This means, the latter is called already in a spinlock
3162	      held by the PCM middle layer. Please take this atomicity into
3163	      account when you choose a locking scheme in the callbacks.
3164	      </para>
3165	
3166	      <para>
3167	      In the atomic callbacks, you cannot use functions which may call
3168	      <function>schedule</function> or go to
3169	      <function>sleep</function>.  Semaphores and mutexes can sleep,
3170	      and hence they cannot be used inside the atomic callbacks
3171	      (e.g. <parameter>trigger</parameter> callback).
3172	      To implement some delay in such a callback, please use
3173	      <function>udelay()</function> or <function>mdelay()</function>.
3174	      </para>
3175	
3176	      <para>
3177	      All three atomic callbacks (trigger, pointer, and ack) are
3178	      called with local interrupts disabled.
3179	      </para>
3180	
3181	      <para>
3182	      The recent changes in PCM core code, however, allow all PCM
3183	      operations to be non-atomic.  This assumes that the all caller
3184	      sides are in non-atomic contexts.  For example, the function
3185	      <function>snd_pcm_period_elapsed()</function> is called
3186	      typically from the interrupt handler.  But, if you set up the
3187	      driver to use a threaded interrupt handler, this call can be in
3188	      non-atomic context, too.  In such a case, you can set
3189	      <structfield>nonatomic</structfield> filed of
3190	      <structname>snd_pcm</structname> object after creating it.
3191	      When this flag is set, mutex and rwsem are used internally in
3192	      the PCM core instead of spin and rwlocks, so that you can call
3193	      all PCM functions safely in a non-atomic context.
3194	      </para>
3195	
3196	    </section>
3197	    <section id="pcm-interface-constraints">
3198	      <title>Constraints</title>
3199	      <para>
3200	        If your chip supports unconventional sample rates, or only the
3201	      limited samples, you need to set a constraint for the
3202	      condition. 
3203	      </para>
3204	
3205	      <para>
3206	        For example, in order to restrict the sample rates in the some
3207	        supported values, use
3208		<function>snd_pcm_hw_constraint_list()</function>.
3209		You need to call this function in the open callback.
3210	
3211	        <example>
3212		  <title>Example of Hardware Constraints</title>
3213	          <programlisting>
3214	<![CDATA[
3215	  static unsigned int rates[] =
3216	          {4000, 10000, 22050, 44100};
3217	  static struct snd_pcm_hw_constraint_list constraints_rates = {
3218	          .count = ARRAY_SIZE(rates),
3219	          .list = rates,
3220	          .mask = 0,
3221	  };
3222	
3223	  static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3224	  {
3225	          int err;
3226	          ....
3227	          err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3228	                                           SNDRV_PCM_HW_PARAM_RATE,
3229	                                           &constraints_rates);
3230	          if (err < 0)
3231	                  return err;
3232	          ....
3233	  }
3234	]]>
3235	          </programlisting>
3236	        </example>
3237	      </para>
3238	
3239	      <para>
3240	        There are many different constraints.
3241	        Look at <filename>sound/pcm.h</filename> for a complete list.
3242	        You can even define your own constraint rules.
3243	        For example, let's suppose my_chip can manage a substream of 1 channel
3244	        if and only if the format is S16_LE, otherwise it supports any format
3245	        specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3246	        other constraint_list). You can build a rule like this:
3247	
3248	        <example>
3249		  <title>Example of Hardware Constraints for Channels</title>
3250		  <programlisting>
3251	<![CDATA[
3252	  static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3253	                                        struct snd_pcm_hw_rule *rule)
3254	  {
3255	          struct snd_interval *c = hw_param_interval(params,
3256	                        SNDRV_PCM_HW_PARAM_CHANNELS);
3257	          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3258	          struct snd_interval ch;
3259	
3260	          snd_interval_any(&ch);
3261	          if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3262	                  ch.min = ch.max = 1;
3263	                  ch.integer = 1;
3264	                  return snd_interval_refine(c, &ch);
3265	          }
3266	          return 0;
3267	  }
3268	]]>
3269	          </programlisting>
3270	        </example>
3271	      </para>
3272	 
3273	      <para>
3274	        Then you need to call this function to add your rule:
3275	
3276	       <informalexample>
3277		 <programlisting>
3278	<![CDATA[
3279	  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3280	                      hw_rule_channels_by_format, NULL,
3281	                      SNDRV_PCM_HW_PARAM_FORMAT, -1);
3282	]]>
3283	          </programlisting>
3284	        </informalexample>
3285	      </para>
3286	
3287	      <para>
3288	        The rule function is called when an application sets the PCM
3289		format, and it refines the number of channels accordingly.
3290	        But an application may set the number of channels before
3291		setting the format. Thus you also need to define the inverse rule:
3292	
3293	       <example>
3294		 <title>Example of Hardware Constraints for Formats</title>
3295		 <programlisting>
3296	<![CDATA[
3297	  static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3298	                                        struct snd_pcm_hw_rule *rule)
3299	  {
3300	          struct snd_interval *c = hw_param_interval(params,
3301	                SNDRV_PCM_HW_PARAM_CHANNELS);
3302	          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3303	          struct snd_mask fmt;
3304	
3305	          snd_mask_any(&fmt);    /* Init the struct */
3306	          if (c->min < 2) {
3307	                  fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3308	                  return snd_mask_refine(f, &fmt);
3309	          }
3310	          return 0;
3311	  }
3312	]]>
3313	          </programlisting>
3314	        </example>
3315	      </para>
3316	
3317	      <para>
3318	      ...and in the open callback:
3319	       <informalexample>
3320		 <programlisting>
3321	<![CDATA[
3322	  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3323	                      hw_rule_format_by_channels, NULL,
3324	                      SNDRV_PCM_HW_PARAM_CHANNELS, -1);
3325	]]>
3326	          </programlisting>
3327	        </informalexample>
3328	      </para>
3329	
3330	      <para>
3331	        I won't give more details here, rather I
3332	        would like to say, <quote>Luke, use the source.</quote>
3333	      </para>
3334	    </section>
3335	
3336	  </chapter>
3337	
3338	
3339	<!-- ****************************************************** -->
3340	<!-- Control Interface  -->
3341	<!-- ****************************************************** -->
3342	  <chapter id="control-interface">
3343	    <title>Control Interface</title>
3344	
3345	    <section id="control-interface-general">
3346	      <title>General</title>
3347	      <para>
3348	        The control interface is used widely for many switches,
3349	      sliders, etc. which are accessed from user-space. Its most
3350	      important use is the mixer interface. In other words, since ALSA
3351	      0.9.x, all the mixer stuff is implemented on the control kernel API.
3352	      </para>
3353	
3354	      <para>
3355	        ALSA has a well-defined AC97 control module. If your chip
3356	      supports only the AC97 and nothing else, you can skip this
3357	      section. 
3358	      </para>
3359	
3360	      <para>
3361	        The control API is defined in
3362	      <filename>&lt;sound/control.h&gt;</filename>.
3363	      Include this file if you want to add your own controls.
3364	      </para>
3365	    </section>
3366	
3367	    <section id="control-interface-definition">
3368	      <title>Definition of Controls</title>
3369	      <para>
3370	        To create a new control, you need to define the
3371		following three
3372	      callbacks: <structfield>info</structfield>,
3373	      <structfield>get</structfield> and
3374	      <structfield>put</structfield>. Then, define a
3375	      struct <structname>snd_kcontrol_new</structname> record, such as: 
3376	
3377	        <example>
3378		  <title>Definition of a Control</title>
3379	          <programlisting>
3380	<![CDATA[
3381	  static struct snd_kcontrol_new my_control = {
3382	          .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3383	          .name = "PCM Playback Switch",
3384	          .index = 0,
3385	          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3386	          .private_value = 0xffff,
3387	          .info = my_control_info,
3388	          .get = my_control_get,
3389	          .put = my_control_put
3390	  };
3391	]]>
3392	          </programlisting>
3393	        </example>
3394	      </para>
3395	
3396	      <para>
3397	        The <structfield>iface</structfield> field specifies the control
3398	      type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3399	      is usually <constant>MIXER</constant>.
3400	      Use <constant>CARD</constant> for global controls that are not
3401	      logically part of the mixer.
3402	      If the control is closely associated with some specific device on
3403	      the sound card, use <constant>HWDEP</constant>,
3404	      <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3405	      <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3406	      specify the device number with the
3407	      <structfield>device</structfield> and
3408	      <structfield>subdevice</structfield> fields.
3409	      </para>
3410	
3411	      <para>
3412	        The <structfield>name</structfield> is the name identifier
3413	      string. Since ALSA 0.9.x, the control name is very important,
3414	      because its role is classified from its name. There are
3415	      pre-defined standard control names. The details are described in
3416	      the <link linkend="control-interface-control-names"><citetitle>
3417	      Control Names</citetitle></link> subsection.
3418	      </para>
3419	
3420	      <para>
3421	        The <structfield>index</structfield> field holds the index number
3422	      of this control. If there are several different controls with
3423	      the same name, they can be distinguished by the index
3424	      number. This is the case when 
3425	      several codecs exist on the card. If the index is zero, you can
3426	      omit the definition above. 
3427	      </para>
3428	
3429	      <para>
3430	        The <structfield>access</structfield> field contains the access
3431	      type of this control. Give the combination of bit masks,
3432	      <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3433	      The details will be explained in
3434	      the <link linkend="control-interface-access-flags"><citetitle>
3435	      Access Flags</citetitle></link> subsection.
3436	      </para>
3437	
3438	      <para>
3439	        The <structfield>private_value</structfield> field contains
3440	      an arbitrary long integer value for this record. When using
3441	      the generic <structfield>info</structfield>,
3442	      <structfield>get</structfield> and
3443	      <structfield>put</structfield> callbacks, you can pass a value 
3444	      through this field. If several small numbers are necessary, you can
3445	      combine them in bitwise. Or, it's possible to give a pointer
3446	      (casted to unsigned long) of some record to this field, too. 
3447	      </para>
3448	
3449	      <para>
3450	      The <structfield>tlv</structfield> field can be used to provide
3451	      metadata about the control; see the
3452	      <link linkend="control-interface-tlv">
3453	      <citetitle>Metadata</citetitle></link> subsection.
3454	      </para>
3455	
3456	      <para>
3457	        The other three are
3458		<link linkend="control-interface-callbacks"><citetitle>
3459		callback functions</citetitle></link>.
3460	      </para>
3461	    </section>
3462	
3463	    <section id="control-interface-control-names">
3464	      <title>Control Names</title>
3465	      <para>
3466	        There are some standards to define the control names. A
3467	      control is usually defined from the three parts as
3468	      <quote>SOURCE DIRECTION FUNCTION</quote>. 
3469	      </para>
3470	
3471	      <para>
3472	        The first, <constant>SOURCE</constant>, specifies the source
3473	      of the control, and is a string such as <quote>Master</quote>,
3474	      <quote>PCM</quote>, <quote>CD</quote> and
3475	      <quote>Line</quote>. There are many pre-defined sources. 
3476	      </para>
3477	
3478	      <para>
3479	        The second, <constant>DIRECTION</constant>, is one of the
3480	      following strings according to the direction of the control:
3481	      <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3482	      Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3483	      be omitted, meaning both playback and capture directions. 
3484	      </para>
3485	
3486	      <para>
3487	        The third, <constant>FUNCTION</constant>, is one of the
3488	      following strings according to the function of the control:
3489	      <quote>Switch</quote>, <quote>Volume</quote> and
3490	      <quote>Route</quote>. 
3491	      </para>
3492	
3493	      <para>
3494	        The example of control names are, thus, <quote>Master Capture
3495	      Switch</quote> or <quote>PCM Playback Volume</quote>. 
3496	      </para>
3497	
3498	      <para>
3499	        There are some exceptions:
3500	      </para>
3501	
3502	      <section id="control-interface-control-names-global">
3503	        <title>Global capture and playback</title>
3504	        <para>
3505	          <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3506	        and <quote>Capture Volume</quote> are used for the global
3507	        capture (input) source, switch and volume. Similarly,
3508	        <quote>Playback Switch</quote> and <quote>Playback
3509	        Volume</quote> are used for the global output gain switch and
3510	        volume. 
3511	        </para>
3512	      </section>
3513	
3514	      <section id="control-interface-control-names-tone">
3515	        <title>Tone-controls</title>
3516	        <para>
3517	          tone-control switch and volumes are specified like
3518	        <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3519	        Switch</quote>, <quote>Tone Control - Bass</quote>,
3520	        <quote>Tone Control - Center</quote>.  
3521	        </para>
3522	      </section>
3523	
3524	      <section id="control-interface-control-names-3d">
3525	        <title>3D controls</title>
3526	        <para>
3527	          3D-control switches and volumes are specified like <quote>3D
3528	        Control - XXX</quote>, e.g. <quote>3D Control -
3529	        Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3530	        Control - Space</quote>. 
3531	        </para>
3532	      </section>
3533	
3534	      <section id="control-interface-control-names-mic">
3535	        <title>Mic boost</title>
3536	        <para>
3537	          Mic-boost switch is set as <quote>Mic Boost</quote> or
3538	        <quote>Mic Boost (6dB)</quote>. 
3539	        </para>
3540	
3541	        <para>
3542	          More precise information can be found in
3543	        <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3544	        </para>
3545	      </section>
3546	    </section>
3547	
3548	    <section id="control-interface-access-flags">
3549	      <title>Access Flags</title>
3550	
3551	      <para>
3552	      The access flag is the bitmask which specifies the access type
3553	      of the given control.  The default access type is
3554	      <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 
3555	      which means both read and write are allowed to this control.
3556	      When the access flag is omitted (i.e. = 0), it is
3557	      considered as <constant>READWRITE</constant> access as default. 
3558	      </para>
3559	
3560	      <para>
3561	      When the control is read-only, pass
3562	      <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3563	      In this case, you don't have to define
3564	      the <structfield>put</structfield> callback.
3565	      Similarly, when the control is write-only (although it's a rare
3566	      case), you can use the <constant>WRITE</constant> flag instead, and
3567	      you don't need the <structfield>get</structfield> callback.
3568	      </para>
3569	
3570	      <para>
3571	      If the control value changes frequently (e.g. the VU meter),
3572	      <constant>VOLATILE</constant> flag should be given.  This means
3573	      that the control may be changed without
3574	      <link linkend="control-interface-change-notification"><citetitle>
3575	      notification</citetitle></link>. Applications should poll such
3576	      a control constantly.
3577	      </para>
3578	
3579	      <para>
3580	      When the control is inactive, set
3581	      the <constant>INACTIVE</constant> flag, too.
3582	      There are <constant>LOCK</constant> and
3583	      <constant>OWNER</constant> flags to change the write
3584	      permissions.
3585	      </para>
3586	
3587	    </section>
3588	
3589	    <section id="control-interface-callbacks">
3590	      <title>Callbacks</title>
3591	
3592	      <section id="control-interface-callbacks-info">
3593	        <title>info callback</title>
3594	        <para>
3595	          The <structfield>info</structfield> callback is used to get
3596	        detailed information on this control. This must store the
3597	        values of the given struct <structname>snd_ctl_elem_info</structname>
3598	        object. For example, for a boolean control with a single
3599	        element: 
3600	
3601	          <example>
3602		    <title>Example of info callback</title>
3603	            <programlisting>
3604	<![CDATA[
3605	  static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3606	                          struct snd_ctl_elem_info *uinfo)
3607	  {
3608	          uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3609	          uinfo->count = 1;
3610	          uinfo->value.integer.min = 0;
3611	          uinfo->value.integer.max = 1;
3612	          return 0;
3613	  }
3614	]]>
3615	            </programlisting>
3616	          </example>
3617	        </para>
3618	
3619	        <para>
3620	          The <structfield>type</structfield> field specifies the type
3621	        of the control. There are <constant>BOOLEAN</constant>,
3622	        <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3623	        <constant>BYTES</constant>, <constant>IEC958</constant> and
3624	        <constant>INTEGER64</constant>. The
3625	        <structfield>count</structfield> field specifies the 
3626	        number of elements in this control. For example, a stereo
3627	        volume would have count = 2. The
3628	        <structfield>value</structfield> field is a union, and 
3629	        the values stored are depending on the type. The boolean and
3630	        integer types are identical. 
3631	        </para>
3632	
3633	        <para>
3634	          The enumerated type is a bit different from others.  You'll
3635	          need to set the string for the currently given item index. 
3636	
3637	          <informalexample>
3638	            <programlisting>
3639	<![CDATA[
3640	  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3641	                          struct snd_ctl_elem_info *uinfo)
3642	  {
3643	          static char *texts[4] = {
3644	                  "First", "Second", "Third", "Fourth"
3645	          };
3646	          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3647	          uinfo->count = 1;
3648	          uinfo->value.enumerated.items = 4;
3649	          if (uinfo->value.enumerated.item > 3)
3650	                  uinfo->value.enumerated.item = 3;
3651	          strcpy(uinfo->value.enumerated.name,
3652	                 texts[uinfo->value.enumerated.item]);
3653	          return 0;
3654	  }
3655	]]>
3656	            </programlisting>
3657	          </informalexample>
3658	        </para>
3659	
3660	        <para>
3661		  The above callback can be simplified with a helper function,
3662		  <function>snd_ctl_enum_info</function>.  The final code
3663		  looks like below.
3664		  (You can pass ARRAY_SIZE(texts) instead of 4 in the third
3665		   argument; it's a matter of taste.)
3666	
3667	          <informalexample>
3668	            <programlisting>
3669	<![CDATA[
3670	  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3671	                          struct snd_ctl_elem_info *uinfo)
3672	  {
3673	          static char *texts[4] = {
3674	                  "First", "Second", "Third", "Fourth"
3675	          };
3676	          return snd_ctl_enum_info(uinfo, 1, 4, texts);
3677	  }
3678	]]>
3679	            </programlisting>
3680	          </informalexample>
3681	        </para>
3682	
3683	        <para>
3684		  Some common info callbacks are available for your convenience:
3685		<function>snd_ctl_boolean_mono_info()</function> and
3686		<function>snd_ctl_boolean_stereo_info()</function>.
3687		Obviously, the former is an info callback for a mono channel
3688		boolean item, just like <function>snd_myctl_mono_info</function>
3689		above, and the latter is for a stereo channel boolean item.
3690		</para>
3691	
3692	      </section>
3693	
3694	      <section id="control-interface-callbacks-get">
3695	        <title>get callback</title>
3696	
3697	        <para>
3698	          This callback is used to read the current value of the
3699	        control and to return to user-space. 
3700	        </para>
3701	
3702	        <para>
3703	          For example,
3704	
3705	          <example>
3706		    <title>Example of get callback</title>
3707	            <programlisting>
3708	<![CDATA[
3709	  static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3710	                           struct snd_ctl_elem_value *ucontrol)
3711	  {
3712	          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3713	          ucontrol->value.integer.value[0] = get_some_value(chip);
3714	          return 0;
3715	  }
3716	]]>
3717	            </programlisting>
3718	          </example>
3719	        </para>
3720	
3721	        <para>
3722		The <structfield>value</structfield> field depends on 
3723	        the type of control as well as on the info callback.  For example,
3724		the sb driver uses this field to store the register offset,
3725	        the bit-shift and the bit-mask.  The
3726	        <structfield>private_value</structfield> field is set as follows:
3727	          <informalexample>
3728	            <programlisting>
3729	<![CDATA[
3730	  .private_value = reg | (shift << 16) | (mask << 24)
3731	]]>
3732	            </programlisting>
3733	          </informalexample>
3734		and is retrieved in callbacks like
3735	          <informalexample>
3736	            <programlisting>
3737	<![CDATA[
3738	  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3739	                                    struct snd_ctl_elem_value *ucontrol)
3740	  {
3741	          int reg = kcontrol->private_value & 0xff;
3742	          int shift = (kcontrol->private_value >> 16) & 0xff;
3743	          int mask = (kcontrol->private_value >> 24) & 0xff;
3744	          ....
3745	  }
3746	]]>
3747	            </programlisting>
3748	          </informalexample>
3749		</para>
3750	
3751		<para>
3752		In the <structfield>get</structfield> callback,
3753		you have to fill all the elements if the
3754	        control has more than one elements,
3755	        i.e. <structfield>count</structfield> &gt; 1.
3756		In the example above, we filled only one element
3757	        (<structfield>value.integer.value[0]</structfield>) since it's
3758	        assumed as <structfield>count</structfield> = 1.
3759	        </para>
3760	      </section>
3761	
3762	      <section id="control-interface-callbacks-put">
3763	        <title>put callback</title>
3764	
3765	        <para>
3766	          This callback is used to write a value from user-space.
3767	        </para>
3768	
3769	        <para>
3770	          For example,
3771	
3772	          <example>
3773		    <title>Example of put callback</title>
3774	            <programlisting>
3775	<![CDATA[
3776	  static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3777	                           struct snd_ctl_elem_value *ucontrol)
3778	  {
3779	          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3780	          int changed = 0;
3781	          if (chip->current_value !=
3782	               ucontrol->value.integer.value[0]) {
3783	                  change_current_value(chip,
3784	                              ucontrol->value.integer.value[0]);
3785	                  changed = 1;
3786	          }
3787	          return changed;
3788	  }
3789	]]>
3790	            </programlisting>
3791	          </example>
3792	
3793	          As seen above, you have to return 1 if the value is
3794	        changed. If the value is not changed, return 0 instead. 
3795		If any fatal error happens, return a negative error code as
3796	        usual.
3797	        </para>
3798	
3799	        <para>
3800		As in the <structfield>get</structfield> callback,
3801		when the control has more than one elements,
3802		all elements must be evaluated in this callback, too.
3803	        </para>
3804	      </section>
3805	
3806	      <section id="control-interface-callbacks-all">
3807	        <title>Callbacks are not atomic</title>
3808	        <para>
3809	          All these three callbacks are basically not atomic.
3810	        </para>
3811	      </section>
3812	    </section>
3813	
3814	    <section id="control-interface-constructor">
3815	      <title>Constructor</title>
3816	      <para>
3817	        When everything is ready, finally we can create a new
3818	      control. To create a control, there are two functions to be
3819	      called, <function>snd_ctl_new1()</function> and
3820	      <function>snd_ctl_add()</function>. 
3821	      </para>
3822	
3823	      <para>
3824	        In the simplest way, you can do like this:
3825	
3826	        <informalexample>
3827	          <programlisting>
3828	<![CDATA[
3829	  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3830	  if (err < 0)
3831	          return err;
3832	]]>
3833	          </programlisting>
3834	        </informalexample>
3835	
3836	        where <parameter>my_control</parameter> is the
3837	      struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3838	      is the object pointer to be passed to
3839	      kcontrol-&gt;private_data 
3840	      which can be referred to in callbacks. 
3841	      </para>
3842	
3843	      <para>
3844	        <function>snd_ctl_new1()</function> allocates a new
3845	      <structname>snd_kcontrol</structname> instance,
3846	      and <function>snd_ctl_add</function> assigns the given
3847	      control component to the card. 
3848	      </para>
3849	    </section>
3850	
3851	    <section id="control-interface-change-notification">
3852	      <title>Change Notification</title>
3853	      <para>
3854	        If you need to change and update a control in the interrupt
3855	      routine, you can call <function>snd_ctl_notify()</function>. For
3856	      example, 
3857	
3858	        <informalexample>
3859	          <programlisting>
3860	<![CDATA[
3861	  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3862	]]>
3863	          </programlisting>
3864	        </informalexample>
3865	
3866	        This function takes the card pointer, the event-mask, and the
3867	      control id pointer for the notification. The event-mask
3868	      specifies the types of notification, for example, in the above
3869	      example, the change of control values is notified.
3870	      The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3871	      to be notified.
3872	      You can find some examples in <filename>es1938.c</filename> or
3873	      <filename>es1968.c</filename> for hardware volume interrupts. 
3874	      </para>
3875	    </section>
3876	
3877	    <section id="control-interface-tlv">
3878	      <title>Metadata</title>
3879	      <para>
3880	      To provide information about the dB values of a mixer control, use
3881	      on of the <constant>DECLARE_TLV_xxx</constant> macros from
3882	      <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3883	      containing this information, set the<structfield>tlv.p
3884	      </structfield> field to point to this variable, and include the
3885	      <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3886	      <structfield>access</structfield> field; like this:
3887	      <informalexample>
3888	        <programlisting>
3889	<![CDATA[
3890	  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3891	
3892	  static struct snd_kcontrol_new my_control = {
3893	          ...
3894	          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3895	                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3896	          ...
3897	          .tlv.p = db_scale_my_control,
3898	  };
3899	]]>
3900	        </programlisting>
3901	      </informalexample>
3902	      </para>
3903	
3904	      <para>
3905	      The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3906	      information about a mixer control where each step in the control's
3907	      value changes the dB value by a constant dB amount.
3908	      The first parameter is the name of the variable to be defined.
3909	      The second parameter is the minimum value, in units of 0.01 dB.
3910	      The third parameter is the step size, in units of 0.01 dB.
3911	      Set the fourth parameter to 1 if the minimum value actually mutes
3912	      the control.
3913	      </para>
3914	
3915	      <para>
3916	      The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3917	      information about a mixer control where the control's value affects
3918	      the output linearly.
3919	      The first parameter is the name of the variable to be defined.
3920	      The second parameter is the minimum value, in units of 0.01 dB.
3921	      The third parameter is the maximum value, in units of 0.01 dB.
3922	      If the minimum value mutes the control, set the second parameter to
3923	      <constant>TLV_DB_GAIN_MUTE</constant>.
3924	      </para>
3925	    </section>
3926	
3927	  </chapter>
3928	
3929	
3930	<!-- ****************************************************** -->
3931	<!-- API for AC97 Codec  -->
3932	<!-- ****************************************************** -->
3933	  <chapter id="api-ac97">
3934	    <title>API for AC97 Codec</title>
3935	
3936	    <section>
3937	      <title>General</title>
3938	      <para>
3939	        The ALSA AC97 codec layer is a well-defined one, and you don't
3940	      have to write much code to control it. Only low-level control
3941	      routines are necessary. The AC97 codec API is defined in
3942	      <filename>&lt;sound/ac97_codec.h&gt;</filename>. 
3943	      </para>
3944	    </section>
3945	
3946	    <section id="api-ac97-example">
3947	      <title>Full Code Example</title>
3948	      <para>
3949	          <example>
3950		    <title>Example of AC97 Interface</title>
3951	            <programlisting>
3952	<![CDATA[
3953	  struct mychip {
3954	          ....
3955	          struct snd_ac97 *ac97;
3956	          ....
3957	  };
3958	
3959	  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3960	                                             unsigned short reg)
3961	  {
3962	          struct mychip *chip = ac97->private_data;
3963	          ....
3964	          /* read a register value here from the codec */
3965	          return the_register_value;
3966	  }
3967	
3968	  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3969	                                   unsigned short reg, unsigned short val)
3970	  {
3971	          struct mychip *chip = ac97->private_data;
3972	          ....
3973	          /* write the given register value to the codec */
3974	  }
3975	
3976	  static int snd_mychip_ac97(struct mychip *chip)
3977	  {
3978	          struct snd_ac97_bus *bus;
3979	          struct snd_ac97_template ac97;
3980	          int err;
3981	          static struct snd_ac97_bus_ops ops = {
3982	                  .write = snd_mychip_ac97_write,
3983	                  .read = snd_mychip_ac97_read,
3984	          };
3985	
3986	          err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3987	          if (err < 0)
3988	                  return err;
3989	          memset(&ac97, 0, sizeof(ac97));
3990	          ac97.private_data = chip;
3991	          return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3992	  }
3993	
3994	]]>
3995	          </programlisting>
3996	        </example>
3997	      </para>
3998	    </section>
3999	
4000	    <section id="api-ac97-constructor">
4001	      <title>Constructor</title>
4002	      <para>
4003	        To create an ac97 instance, first call <function>snd_ac97_bus</function>
4004	      with an <type>ac97_bus_ops_t</type> record with callback functions.
4005	
4006	        <informalexample>
4007	          <programlisting>
4008	<![CDATA[
4009	  struct snd_ac97_bus *bus;
4010	  static struct snd_ac97_bus_ops ops = {
4011	        .write = snd_mychip_ac97_write,
4012	        .read = snd_mychip_ac97_read,
4013	  };
4014	
4015	  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
4016	]]>
4017	          </programlisting>
4018	        </informalexample>
4019	
4020	      The bus record is shared among all belonging ac97 instances.
4021	      </para>
4022	
4023	      <para>
4024	      And then call <function>snd_ac97_mixer()</function> with an
4025	      struct <structname>snd_ac97_template</structname>
4026	      record together with the bus pointer created above.
4027	
4028	        <informalexample>
4029	          <programlisting>
4030	<![CDATA[
4031	  struct snd_ac97_template ac97;
4032	  int err;
4033	
4034	  memset(&ac97, 0, sizeof(ac97));
4035	  ac97.private_data = chip;
4036	  snd_ac97_mixer(bus, &ac97, &chip->ac97);
4037	]]>
4038	          </programlisting>
4039	        </informalexample>
4040	
4041	        where chip-&gt;ac97 is a pointer to a newly created
4042	        <type>ac97_t</type> instance.
4043	        In this case, the chip pointer is set as the private data, so that
4044	        the read/write callback functions can refer to this chip instance.
4045	        This instance is not necessarily stored in the chip
4046		record.  If you need to change the register values from the
4047	        driver, or need the suspend/resume of ac97 codecs, keep this
4048	        pointer to pass to the corresponding functions.
4049	      </para>
4050	    </section>
4051	
4052	    <section id="api-ac97-callbacks">
4053	      <title>Callbacks</title>
4054	      <para>
4055	        The standard callbacks are <structfield>read</structfield> and
4056	      <structfield>write</structfield>. Obviously they 
4057	      correspond to the functions for read and write accesses to the
4058	      hardware low-level codes. 
4059	      </para>
4060	
4061	      <para>
4062	        The <structfield>read</structfield> callback returns the
4063	        register value specified in the argument. 
4064	
4065	        <informalexample>
4066	          <programlisting>
4067	<![CDATA[
4068	  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4069	                                             unsigned short reg)
4070	  {
4071	          struct mychip *chip = ac97->private_data;
4072	          ....
4073	          return the_register_value;
4074	  }
4075	]]>
4076	          </programlisting>
4077	        </informalexample>
4078	
4079	        Here, the chip can be cast from ac97-&gt;private_data.
4080	      </para>
4081	
4082	      <para>
4083	        Meanwhile, the <structfield>write</structfield> callback is
4084	        used to set the register value. 
4085	
4086	        <informalexample>
4087	          <programlisting>
4088	<![CDATA[
4089	  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4090	                       unsigned short reg, unsigned short val)
4091	]]>
4092	          </programlisting>
4093	        </informalexample>
4094	      </para>
4095	
4096	      <para>
4097	      These callbacks are non-atomic like the control API callbacks.
4098	      </para>
4099	
4100	      <para>
4101	        There are also other callbacks:
4102	      <structfield>reset</structfield>,
4103	      <structfield>wait</structfield> and
4104	      <structfield>init</structfield>. 
4105	      </para>
4106	
4107	      <para>
4108	        The <structfield>reset</structfield> callback is used to reset
4109	      the codec. If the chip requires a special kind of reset, you can
4110	      define this callback. 
4111	      </para>
4112	
4113	      <para>
4114	        The <structfield>wait</structfield> callback is used to
4115	      add some waiting time in the standard initialization of the codec. If the
4116	      chip requires the extra waiting time, define this callback. 
4117	      </para>
4118	
4119	      <para>
4120	        The <structfield>init</structfield> callback is used for
4121	      additional initialization of the codec.
4122	      </para>
4123	    </section>
4124	
4125	    <section id="api-ac97-updating-registers">
4126	      <title>Updating Registers in The Driver</title>
4127	      <para>
4128	        If you need to access to the codec from the driver, you can
4129	      call the following functions:
4130	      <function>snd_ac97_write()</function>,
4131	      <function>snd_ac97_read()</function>,
4132	      <function>snd_ac97_update()</function> and
4133	      <function>snd_ac97_update_bits()</function>. 
4134	      </para>
4135	
4136	      <para>
4137	        Both <function>snd_ac97_write()</function> and
4138	        <function>snd_ac97_update()</function> functions are used to
4139	        set a value to the given register
4140	        (<constant>AC97_XXX</constant>). The difference between them is
4141	        that <function>snd_ac97_update()</function> doesn't write a
4142	        value if the given value has been already set, while
4143	        <function>snd_ac97_write()</function> always rewrites the
4144	        value. 
4145	
4146	        <informalexample>
4147	          <programlisting>
4148	<![CDATA[
4149	  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4150	  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4151	]]>
4152	          </programlisting>
4153	        </informalexample>
4154	      </para>
4155	
4156	      <para>
4157	        <function>snd_ac97_read()</function> is used to read the value
4158	        of the given register. For example, 
4159	
4160	        <informalexample>
4161	          <programlisting>
4162	<![CDATA[
4163	  value = snd_ac97_read(ac97, AC97_MASTER);
4164	]]>
4165	          </programlisting>
4166	        </informalexample>
4167	      </para>
4168	
4169	      <para>
4170	        <function>snd_ac97_update_bits()</function> is used to update
4171	        some bits in the given register.  
4172	
4173	        <informalexample>
4174	          <programlisting>
4175	<![CDATA[
4176	  snd_ac97_update_bits(ac97, reg, mask, value);
4177	]]>
4178	          </programlisting>
4179	        </informalexample>
4180	      </para>
4181	
4182	      <para>
4183	        Also, there is a function to change the sample rate (of a
4184	        given register such as
4185	        <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4186	        DRA is supported by the codec:
4187	        <function>snd_ac97_set_rate()</function>. 
4188	
4189	        <informalexample>
4190	          <programlisting>
4191	<![CDATA[
4192	  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4193	]]>
4194	          </programlisting>
4195	        </informalexample>
4196	      </para>
4197	
4198	      <para>
4199	        The following registers are available to set the rate:
4200	      <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4201	      <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4202	      <constant>AC97_PCM_LR_ADC_RATE</constant>,
4203	      <constant>AC97_SPDIF</constant>. When
4204	      <constant>AC97_SPDIF</constant> is specified, the register is
4205	      not really changed but the corresponding IEC958 status bits will
4206	      be updated. 
4207	      </para>
4208	    </section>
4209	
4210	    <section id="api-ac97-clock-adjustment">
4211	      <title>Clock Adjustment</title>
4212	      <para>
4213	        In some chips, the clock of the codec isn't 48000 but using a
4214	      PCI clock (to save a quartz!). In this case, change the field
4215	      bus-&gt;clock to the corresponding
4216	      value. For example, intel8x0 
4217	      and es1968 drivers have their own function to read from the clock.
4218	      </para>
4219	    </section>
4220	
4221	    <section id="api-ac97-proc-files">
4222	      <title>Proc Files</title>
4223	      <para>
4224	        The ALSA AC97 interface will create a proc file such as
4225	      <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4226	      <filename>ac97#0-0+regs</filename>. You can refer to these files to
4227	      see the current status and registers of the codec. 
4228	      </para>
4229	    </section>
4230	
4231	    <section id="api-ac97-multiple-codecs">
4232	      <title>Multiple Codecs</title>
4233	      <para>
4234	        When there are several codecs on the same card, you need to
4235	      call <function>snd_ac97_mixer()</function> multiple times with
4236	      ac97.num=1 or greater. The <structfield>num</structfield> field
4237	      specifies the codec number. 
4238	      </para>
4239	
4240	      <para>
4241	        If you set up multiple codecs, you either need to write
4242	      different callbacks for each codec or check
4243	      ac97-&gt;num in the callback routines. 
4244	      </para>
4245	    </section>
4246	
4247	  </chapter>
4248	
4249	
4250	<!-- ****************************************************** -->
4251	<!-- MIDI (MPU401-UART) Interface  -->
4252	<!-- ****************************************************** -->
4253	  <chapter id="midi-interface">
4254	    <title>MIDI (MPU401-UART) Interface</title>
4255	
4256	    <section id="midi-interface-general">
4257	      <title>General</title>
4258	      <para>
4259	        Many soundcards have built-in MIDI (MPU401-UART)
4260	      interfaces. When the soundcard supports the standard MPU401-UART
4261	      interface, most likely you can use the ALSA MPU401-UART API. The
4262	      MPU401-UART API is defined in
4263	      <filename>&lt;sound/mpu401.h&gt;</filename>. 
4264	      </para>
4265	
4266	      <para>
4267	        Some soundchips have a similar but slightly different
4268	      implementation of mpu401 stuff. For example, emu10k1 has its own
4269	      mpu401 routines. 
4270	      </para>
4271	    </section>
4272	
4273	    <section id="midi-interface-constructor">
4274	      <title>Constructor</title>
4275	      <para>
4276	        To create a rawmidi object, call
4277	      <function>snd_mpu401_uart_new()</function>. 
4278	
4279	        <informalexample>
4280	          <programlisting>
4281	<![CDATA[
4282	  struct snd_rawmidi *rmidi;
4283	  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4284	                      irq, &rmidi);
4285	]]>
4286	          </programlisting>
4287	        </informalexample>
4288	      </para>
4289	
4290	      <para>
4291	        The first argument is the card pointer, and the second is the
4292	      index of this component. You can create up to 8 rawmidi
4293	      devices. 
4294	      </para>
4295	
4296	      <para>
4297	        The third argument is the type of the hardware,
4298	      <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4299	      you can use <constant>MPU401_HW_MPU401</constant>. 
4300	      </para>
4301	
4302	      <para>
4303	        The 4th argument is the I/O port address. Many
4304	      backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4305	      might be a part of its own PCI I/O region. It depends on the
4306	      chip design. 
4307	      </para>
4308	
4309	      <para>
4310		The 5th argument is a bitflag for additional information.
4311	        When the I/O port address above is part of the PCI I/O
4312	      region, the MPU401 I/O port might have been already allocated
4313	      (reserved) by the driver itself. In such a case, pass a bit flag
4314	      <constant>MPU401_INFO_INTEGRATED</constant>,
4315	      and the mpu401-uart layer will allocate the I/O ports by itself. 
4316	      </para>
4317	
4318		<para>
4319		When the controller supports only the input or output MIDI stream,
4320		pass the <constant>MPU401_INFO_INPUT</constant> or
4321		<constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4322		Then the rawmidi instance is created as a single stream.
4323		</para>
4324	
4325		<para>
4326		<constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4327		the access method to MMIO (via readb and writeb) instead of
4328		iob and outb. In this case, you have to pass the iomapped address
4329		to <function>snd_mpu401_uart_new()</function>.
4330		</para>
4331	
4332		<para>
4333		When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4334		stream isn't checked in the default interrupt handler.  The driver
4335		needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4336		by itself to start processing the output stream in the irq handler.
4337		</para>
4338	
4339		<para>
4340		If the MPU-401 interface shares its interrupt with the other logical
4341		devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4342		(see <link linkend="midi-interface-interrupt-handler"><citetitle>
4343		below</citetitle></link>).
4344		</para>
4345	
4346	      <para>
4347	        Usually, the port address corresponds to the command port and
4348	        port + 1 corresponds to the data port. If not, you may change
4349	        the <structfield>cport</structfield> field of
4350	        struct <structname>snd_mpu401</structname> manually 
4351	        afterward. However, <structname>snd_mpu401</structname> pointer is not
4352	        returned explicitly by
4353	        <function>snd_mpu401_uart_new()</function>. You need to cast
4354	        rmidi-&gt;private_data to
4355	        <structname>snd_mpu401</structname> explicitly, 
4356	
4357	        <informalexample>
4358	          <programlisting>
4359	<![CDATA[
4360	  struct snd_mpu401 *mpu;
4361	  mpu = rmidi->private_data;
4362	]]>
4363	          </programlisting>
4364	        </informalexample>
4365	
4366	        and reset the cport as you like:
4367	
4368	        <informalexample>
4369	          <programlisting>
4370	<![CDATA[
4371	  mpu->cport = my_own_control_port;
4372	]]>
4373	          </programlisting>
4374	        </informalexample>
4375	      </para>
4376	
4377	      <para>
4378		The 6th argument specifies the ISA irq number that will be
4379		allocated.  If no interrupt is to be allocated (because your
4380		code is already allocating a shared interrupt, or because the
4381		device does not use interrupts), pass -1 instead.
4382		For a MPU-401 device without an interrupt, a polling timer
4383		will be used instead.
4384	      </para>
4385	    </section>
4386	
4387	    <section id="midi-interface-interrupt-handler">
4388	      <title>Interrupt Handler</title>
4389	      <para>
4390	        When the interrupt is allocated in
4391	      <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4392	      interrupt handler is automatically used, hence you don't have
4393	      anything else to do than creating the mpu401 stuff.  Otherwise, you
4394	      have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4395	      <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4396	      own interrupt handler when it has determined that a UART interrupt
4397	      has occurred.
4398	      </para>
4399	
4400	      <para>
4401	        In this case, you need to pass the private_data of the
4402	        returned rawmidi object from
4403	        <function>snd_mpu401_uart_new()</function> as the second
4404	        argument of <function>snd_mpu401_uart_interrupt()</function>. 
4405	
4406	        <informalexample>
4407	          <programlisting>
4408	<![CDATA[
4409	  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4410	]]>
4411	          </programlisting>
4412	        </informalexample>
4413	      </para>
4414	    </section>
4415	
4416	  </chapter>
4417	
4418	
4419	<!-- ****************************************************** -->
4420	<!-- RawMIDI Interface  -->
4421	<!-- ****************************************************** -->
4422	  <chapter id="rawmidi-interface">
4423	    <title>RawMIDI Interface</title>
4424	
4425	    <section id="rawmidi-interface-overview">
4426	      <title>Overview</title>
4427	
4428	      <para>
4429	      The raw MIDI interface is used for hardware MIDI ports that can
4430	      be accessed as a byte stream.  It is not used for synthesizer
4431	      chips that do not directly understand MIDI.
4432	      </para>
4433	
4434	      <para>
4435	      ALSA handles file and buffer management.  All you have to do is
4436	      to write some code to move data between the buffer and the
4437	      hardware.
4438	      </para>
4439	
4440	      <para>
4441	      The rawmidi API is defined in
4442	      <filename>&lt;sound/rawmidi.h&gt;</filename>.
4443	      </para>
4444	    </section>
4445	
4446	    <section id="rawmidi-interface-constructor">
4447	      <title>Constructor</title>
4448	
4449	      <para>
4450	      To create a rawmidi device, call the
4451	      <function>snd_rawmidi_new</function> function:
4452	        <informalexample>
4453	          <programlisting>
4454	<![CDATA[
4455	  struct snd_rawmidi *rmidi;
4456	  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4457	  if (err < 0)
4458	          return err;
4459	  rmidi->private_data = chip;
4460	  strcpy(rmidi->name, "My MIDI");
4461	  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4462	                      SNDRV_RAWMIDI_INFO_INPUT |
4463	                      SNDRV_RAWMIDI_INFO_DUPLEX;
4464	]]>
4465	          </programlisting>
4466	        </informalexample>
4467	      </para>
4468	
4469	      <para>
4470	      The first argument is the card pointer, the second argument is
4471	      the ID string.
4472	      </para>
4473	
4474	      <para>
4475	      The third argument is the index of this component.  You can
4476	      create up to 8 rawmidi devices.
4477	      </para>
4478	
4479	      <para>
4480	      The fourth and fifth arguments are the number of output and
4481	      input substreams, respectively, of this device (a substream is
4482	      the equivalent of a MIDI port).
4483	      </para>
4484	
4485	      <para>
4486	      Set the <structfield>info_flags</structfield> field to specify
4487	      the capabilities of the device.
4488	      Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4489	      at least one output port,
4490	      <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4491	      least one input port,
4492	      and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4493	      can handle output and input at the same time.
4494	      </para>
4495	
4496	      <para>
4497	      After the rawmidi device is created, you need to set the
4498	      operators (callbacks) for each substream.  There are helper
4499	      functions to set the operators for all the substreams of a device:
4500	        <informalexample>
4501	          <programlisting>
4502	<![CDATA[
4503	  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4504	  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4505	]]>
4506	          </programlisting>
4507	        </informalexample>
4508	      </para>
4509	
4510	      <para>
4511	      The operators are usually defined like this:
4512	        <informalexample>
4513	          <programlisting>
4514	<![CDATA[
4515	  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4516	          .open =    snd_mymidi_output_open,
4517	          .close =   snd_mymidi_output_close,
4518	          .trigger = snd_mymidi_output_trigger,
4519	  };
4520	]]>
4521	          </programlisting>
4522	        </informalexample>
4523	      These callbacks are explained in the <link
4524	      linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4525	      section.
4526	      </para>
4527	
4528	      <para>
4529	      If there are more than one substream, you should give a
4530	      unique name to each of them:
4531	        <informalexample>
4532	          <programlisting>
4533	<![CDATA[
4534	  struct snd_rawmidi_substream *substream;
4535	  list_for_each_entry(substream,
4536	                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4537	                      list {
4538	          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4539	  }
4540	  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4541	]]>
4542	          </programlisting>
4543	        </informalexample>
4544	      </para>
4545	    </section>
4546	
4547	    <section id="rawmidi-interface-callbacks">
4548	      <title>Callbacks</title>
4549	
4550	      <para>
4551	      In all the callbacks, the private data that you've set for the
4552	      rawmidi device can be accessed as
4553	      substream-&gt;rmidi-&gt;private_data.
4554	      <!-- <code> isn't available before DocBook 4.3 -->
4555	      </para>
4556	
4557	      <para>
4558	      If there is more than one port, your callbacks can determine the
4559	      port index from the struct snd_rawmidi_substream data passed to each
4560	      callback:
4561	        <informalexample>
4562	          <programlisting>
4563	<![CDATA[
4564	  struct snd_rawmidi_substream *substream;
4565	  int index = substream->number;
4566	]]>
4567	          </programlisting>
4568	        </informalexample>
4569	      </para>
4570	
4571	      <section id="rawmidi-interface-op-open">
4572	      <title><function>open</function> callback</title>
4573	
4574	        <informalexample>
4575	          <programlisting>
4576	<![CDATA[
4577	  static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4578	]]>
4579	          </programlisting>
4580	        </informalexample>
4581	
4582	        <para>
4583	        This is called when a substream is opened.
4584	        You can initialize the hardware here, but you shouldn't
4585	        start transmitting/receiving data yet.
4586	        </para>
4587	      </section>
4588	
4589	      <section id="rawmidi-interface-op-close">
4590	      <title><function>close</function> callback</title>
4591	
4592	        <informalexample>
4593	          <programlisting>
4594	<![CDATA[
4595	  static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4596	]]>
4597	          </programlisting>
4598	        </informalexample>
4599	
4600	        <para>
4601	        Guess what.
4602	        </para>
4603	
4604	        <para>
4605	        The <function>open</function> and <function>close</function>
4606	        callbacks of a rawmidi device are serialized with a mutex,
4607	        and can sleep.
4608	        </para>
4609	      </section>
4610	
4611	      <section id="rawmidi-interface-op-trigger-out">
4612	      <title><function>trigger</function> callback for output
4613	      substreams</title>
4614	
4615	        <informalexample>
4616	          <programlisting>
4617	<![CDATA[
4618	  static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4619	]]>
4620	          </programlisting>
4621	        </informalexample>
4622	
4623	        <para>
4624	        This is called with a nonzero <parameter>up</parameter>
4625	        parameter when there is some data in the substream buffer that
4626	        must be transmitted.
4627	        </para>
4628	
4629	        <para>
4630	        To read data from the buffer, call
4631	        <function>snd_rawmidi_transmit_peek</function>.  It will
4632	        return the number of bytes that have been read; this will be
4633	        less than the number of bytes requested when there are no more
4634	        data in the buffer.
4635	        After the data have been transmitted successfully, call
4636	        <function>snd_rawmidi_transmit_ack</function> to remove the
4637	        data from the substream buffer:
4638	          <informalexample>
4639	            <programlisting>
4640	<![CDATA[
4641	  unsigned char data;
4642	  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4643	          if (snd_mychip_try_to_transmit(data))
4644	                  snd_rawmidi_transmit_ack(substream, 1);
4645	          else
4646	                  break; /* hardware FIFO full */
4647	  }
4648	]]>
4649	            </programlisting>
4650	          </informalexample>
4651	        </para>
4652	
4653	        <para>
4654	        If you know beforehand that the hardware will accept data, you
4655	        can use the <function>snd_rawmidi_transmit</function> function
4656	        which reads some data and removes them from the buffer at once:
4657	          <informalexample>
4658	            <programlisting>
4659	<![CDATA[
4660	  while (snd_mychip_transmit_possible()) {
4661	          unsigned char data;
4662	          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4663	                  break; /* no more data */
4664	          snd_mychip_transmit(data);
4665	  }
4666	]]>
4667	            </programlisting>
4668	          </informalexample>
4669	        </para>
4670	
4671	        <para>
4672	        If you know beforehand how many bytes you can accept, you can
4673	        use a buffer size greater than one with the
4674	        <function>snd_rawmidi_transmit*</function> functions.
4675	        </para>
4676	
4677	        <para>
4678	        The <function>trigger</function> callback must not sleep.  If
4679	        the hardware FIFO is full before the substream buffer has been
4680	        emptied, you have to continue transmitting data later, either
4681	        in an interrupt handler, or with a timer if the hardware
4682	        doesn't have a MIDI transmit interrupt.
4683	        </para>
4684	
4685	        <para>
4686	        The <function>trigger</function> callback is called with a
4687	        zero <parameter>up</parameter> parameter when the transmission
4688	        of data should be aborted.
4689	        </para>
4690	      </section>
4691	
4692	      <section id="rawmidi-interface-op-trigger-in">
4693	      <title><function>trigger</function> callback for input
4694	      substreams</title>
4695	
4696	        <informalexample>
4697	          <programlisting>
4698	<![CDATA[
4699	  static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4700	]]>
4701	          </programlisting>
4702	        </informalexample>
4703	
4704	        <para>
4705	        This is called with a nonzero <parameter>up</parameter>
4706	        parameter to enable receiving data, or with a zero
4707	        <parameter>up</parameter> parameter do disable receiving data.
4708	        </para>
4709	
4710	        <para>
4711	        The <function>trigger</function> callback must not sleep; the
4712	        actual reading of data from the device is usually done in an
4713	        interrupt handler.
4714	        </para>
4715	
4716	        <para>
4717	        When data reception is enabled, your interrupt handler should
4718	        call <function>snd_rawmidi_receive</function> for all received
4719	        data:
4720	          <informalexample>
4721	            <programlisting>
4722	<![CDATA[
4723	  void snd_mychip_midi_interrupt(...)
4724	  {
4725	          while (mychip_midi_available()) {
4726	                  unsigned char data;
4727	                  data = mychip_midi_read();
4728	                  snd_rawmidi_receive(substream, &data, 1);
4729	          }
4730	  }
4731	]]>
4732	            </programlisting>
4733	          </informalexample>
4734	        </para>
4735	      </section>
4736	
4737	      <section id="rawmidi-interface-op-drain">
4738	      <title><function>drain</function> callback</title>
4739	
4740	        <informalexample>
4741	          <programlisting>
4742	<![CDATA[
4743	  static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4744	]]>
4745	          </programlisting>
4746	        </informalexample>
4747	
4748	        <para>
4749	        This is only used with output substreams.  This function should wait
4750	        until all data read from the substream buffer have been transmitted.
4751	        This ensures that the device can be closed and the driver unloaded
4752	        without losing data.
4753	        </para>
4754	
4755	        <para>
4756	        This callback is optional. If you do not set
4757	        <structfield>drain</structfield> in the struct snd_rawmidi_ops
4758	        structure, ALSA will simply wait for 50&nbsp;milliseconds
4759	        instead.
4760	        </para>
4761	      </section>
4762	    </section>
4763	
4764	  </chapter>
4765	
4766	
4767	<!-- ****************************************************** -->
4768	<!-- Miscellaneous Devices  -->
4769	<!-- ****************************************************** -->
4770	  <chapter id="misc-devices">
4771	    <title>Miscellaneous Devices</title>
4772	
4773	    <section id="misc-devices-opl3">
4774	      <title>FM OPL3</title>
4775	      <para>
4776	        The FM OPL3 is still used in many chips (mainly for backward
4777	      compatibility). ALSA has a nice OPL3 FM control layer, too. The
4778	      OPL3 API is defined in
4779	      <filename>&lt;sound/opl3.h&gt;</filename>. 
4780	      </para>
4781	
4782	      <para>
4783	        FM registers can be directly accessed through the direct-FM API,
4784	      defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4785	      ALSA native mode, FM registers are accessed through
4786	      the Hardware-Dependent Device direct-FM extension API, whereas in
4787	      OSS compatible mode, FM registers can be accessed with the OSS
4788	      direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 
4789	      </para>
4790	
4791	      <para>
4792	        To create the OPL3 component, you have two functions to
4793	        call. The first one is a constructor for the <type>opl3_t</type>
4794	        instance. 
4795	
4796	        <informalexample>
4797	          <programlisting>
4798	<![CDATA[
4799	  struct snd_opl3 *opl3;
4800	  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4801	                  integrated, &opl3);
4802	]]>
4803	          </programlisting>
4804	        </informalexample>
4805	      </para>
4806	
4807	      <para>
4808	        The first argument is the card pointer, the second one is the
4809	      left port address, and the third is the right port address. In
4810	      most cases, the right port is placed at the left port + 2. 
4811	      </para>
4812	
4813	      <para>
4814	        The fourth argument is the hardware type.
4815	      </para>
4816	
4817	      <para>
4818	        When the left and right ports have been already allocated by
4819	      the card driver, pass non-zero to the fifth argument
4820	      (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4821	      allocate the specified ports by itself. 
4822	      </para>
4823	
4824	      <para>
4825	        When the accessing the hardware requires special method
4826	        instead of the standard I/O access, you can create opl3 instance
4827	        separately with <function>snd_opl3_new()</function>.
4828	
4829	        <informalexample>
4830	          <programlisting>
4831	<![CDATA[
4832	  struct snd_opl3 *opl3;
4833	  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4834	]]>
4835	          </programlisting>
4836	        </informalexample>
4837	      </para>
4838	
4839	      <para>
4840		Then set <structfield>command</structfield>,
4841		<structfield>private_data</structfield> and
4842		<structfield>private_free</structfield> for the private
4843		access function, the private data and the destructor.
4844		The l_port and r_port are not necessarily set.  Only the
4845		command must be set properly.  You can retrieve the data
4846		from the opl3-&gt;private_data field.
4847	      </para>
4848	
4849	      <para>
4850		After creating the opl3 instance via <function>snd_opl3_new()</function>,
4851		call <function>snd_opl3_init()</function> to initialize the chip to the
4852		proper state. Note that <function>snd_opl3_create()</function> always
4853		calls it internally.
4854	      </para>
4855	
4856	      <para>
4857	        If the opl3 instance is created successfully, then create a
4858	        hwdep device for this opl3. 
4859	
4860	        <informalexample>
4861	          <programlisting>
4862	<![CDATA[
4863	  struct snd_hwdep *opl3hwdep;
4864	  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4865	]]>
4866	          </programlisting>
4867	        </informalexample>
4868	      </para>
4869	
4870	      <para>
4871	        The first argument is the <type>opl3_t</type> instance you
4872	      created, and the second is the index number, usually 0. 
4873	      </para>
4874	
4875	      <para>
4876	        The third argument is the index-offset for the sequencer
4877	      client assigned to the OPL3 port. When there is an MPU401-UART,
4878	      give 1 for here (UART always takes 0). 
4879	      </para>
4880	    </section>
4881	
4882	    <section id="misc-devices-hardware-dependent">
4883	      <title>Hardware-Dependent Devices</title>
4884	      <para>
4885	        Some chips need user-space access for special
4886	      controls or for loading the micro code. In such a case, you can
4887	      create a hwdep (hardware-dependent) device. The hwdep API is
4888	      defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4889	      find examples in opl3 driver or
4890	      <filename>isa/sb/sb16_csp.c</filename>. 
4891	      </para>
4892	
4893	      <para>
4894	        The creation of the <type>hwdep</type> instance is done via
4895	        <function>snd_hwdep_new()</function>. 
4896	
4897	        <informalexample>
4898	          <programlisting>
4899	<![CDATA[
4900	  struct snd_hwdep *hw;
4901	  snd_hwdep_new(card, "My HWDEP", 0, &hw);
4902	]]>
4903	          </programlisting>
4904	        </informalexample>
4905	
4906	        where the third argument is the index number.
4907	      </para>
4908	
4909	      <para>
4910	        You can then pass any pointer value to the
4911	        <parameter>private_data</parameter>.
4912	        If you assign a private data, you should define the
4913	        destructor, too. The destructor function is set in
4914	        the <structfield>private_free</structfield> field.  
4915	
4916	        <informalexample>
4917	          <programlisting>
4918	<![CDATA[
4919	  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4920	  hw->private_data = p;
4921	  hw->private_free = mydata_free;
4922	]]>
4923	          </programlisting>
4924	        </informalexample>
4925	
4926	        and the implementation of the destructor would be:
4927	
4928	        <informalexample>
4929	          <programlisting>
4930	<![CDATA[
4931	  static void mydata_free(struct snd_hwdep *hw)
4932	  {
4933	          struct mydata *p = hw->private_data;
4934	          kfree(p);
4935	  }
4936	]]>
4937	          </programlisting>
4938	        </informalexample>
4939	      </para>
4940	
4941	      <para>
4942	        The arbitrary file operations can be defined for this
4943	        instance. The file operators are defined in
4944	        the <parameter>ops</parameter> table. For example, assume that
4945	        this chip needs an ioctl. 
4946	
4947	        <informalexample>
4948	          <programlisting>
4949	<![CDATA[
4950	  hw->ops.open = mydata_open;
4951	  hw->ops.ioctl = mydata_ioctl;
4952	  hw->ops.release = mydata_release;
4953	]]>
4954	          </programlisting>
4955	        </informalexample>
4956	
4957	        And implement the callback functions as you like.
4958	      </para>
4959	    </section>
4960	
4961	    <section id="misc-devices-IEC958">
4962	      <title>IEC958 (S/PDIF)</title>
4963	      <para>
4964	        Usually the controls for IEC958 devices are implemented via
4965	      the control interface. There is a macro to compose a name string for
4966	      IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4967	      defined in <filename>&lt;include/asound.h&gt;</filename>.  
4968	      </para>
4969	
4970	      <para>
4971	        There are some standard controls for IEC958 status bits. These
4972	      controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4973	      and the size of element is fixed as 4 bytes array
4974	      (value.iec958.status[x]). For the <structfield>info</structfield>
4975	      callback, you don't specify 
4976	      the value field for this type (the count field must be set,
4977	      though). 
4978	      </para>
4979	
4980	      <para>
4981	        <quote>IEC958 Playback Con Mask</quote> is used to return the
4982	      bit-mask for the IEC958 status bits of consumer mode. Similarly,
4983	      <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4984	      professional mode. They are read-only controls, and are defined
4985	      as MIXER controls (iface =
4986	      <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).  
4987	      </para>
4988	
4989	      <para>
4990	        Meanwhile, <quote>IEC958 Playback Default</quote> control is
4991	      defined for getting and setting the current default IEC958
4992	      bits. Note that this one is usually defined as a PCM control
4993	      (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4994	      although in some places it's defined as a MIXER control. 
4995	      </para>
4996	
4997	      <para>
4998	        In addition, you can define the control switches to
4999	      enable/disable or to set the raw bit mode. The implementation
5000	      will depend on the chip, but the control should be named as
5001	      <quote>IEC958 xxx</quote>, preferably using
5002	      the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 
5003	      </para>
5004	
5005	      <para>
5006	        You can find several cases, for example,
5007	      <filename>pci/emu10k1</filename>,
5008	      <filename>pci/ice1712</filename>, or
5009	      <filename>pci/cmipci.c</filename>.  
5010	      </para>
5011	    </section>
5012	
5013	  </chapter>
5014	
5015	
5016	<!-- ****************************************************** -->
5017	<!-- Buffer and Memory Management  -->
5018	<!-- ****************************************************** -->
5019	  <chapter id="buffer-and-memory">
5020	    <title>Buffer and Memory Management</title>
5021	
5022	    <section id="buffer-and-memory-buffer-types">
5023	      <title>Buffer Types</title>
5024	      <para>
5025	        ALSA provides several different buffer allocation functions
5026	      depending on the bus and the architecture. All these have a
5027	      consistent API. The allocation of physically-contiguous pages is
5028	      done via 
5029	      <function>snd_malloc_xxx_pages()</function> function, where xxx
5030	      is the bus type. 
5031	      </para>
5032	
5033	      <para>
5034	        The allocation of pages with fallback is
5035	      <function>snd_malloc_xxx_pages_fallback()</function>. This
5036	      function tries to allocate the specified pages but if the pages
5037	      are not available, it tries to reduce the page sizes until
5038	      enough space is found.
5039	      </para>
5040	
5041	      <para>
5042	      The release the pages, call
5043	      <function>snd_free_xxx_pages()</function> function. 
5044	      </para>
5045	
5046	      <para>
5047	      Usually, ALSA drivers try to allocate and reserve
5048	       a large contiguous physical space
5049	       at the time the module is loaded for the later use.
5050	       This is called <quote>pre-allocation</quote>.
5051	       As already written, you can call the following function at 
5052	       pcm instance construction time (in the case of PCI bus). 
5053	
5054	        <informalexample>
5055	          <programlisting>
5056	<![CDATA[
5057	  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5058	                                        snd_dma_pci_data(pci), size, max);
5059	]]>
5060	          </programlisting>
5061	        </informalexample>
5062	
5063	        where <parameter>size</parameter> is the byte size to be
5064	      pre-allocated and the <parameter>max</parameter> is the maximum
5065	      size to be changed via the <filename>prealloc</filename> proc file.
5066	      The allocator will try to get an area as large as possible
5067	      within the given size. 
5068	      </para>
5069	
5070	      <para>
5071	      The second argument (type) and the third argument (device pointer)
5072	      are dependent on the bus.
5073	      In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5074	      as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5075	      For the continuous buffer unrelated to the bus can be pre-allocated
5076	      with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5077	      <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5078	      where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5079	      use.
5080	      For the PCI scatter-gather buffers, use
5081	      <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5082	      <function>snd_dma_pci_data(pci)</function>
5083	      (see the 
5084	          <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5085	          </citetitle></link> section).
5086	      </para>
5087	
5088	      <para>
5089	        Once the buffer is pre-allocated, you can use the
5090	        allocator in the <structfield>hw_params</structfield> callback: 
5091	
5092	        <informalexample>
5093	          <programlisting>
5094	<![CDATA[
5095	  snd_pcm_lib_malloc_pages(substream, size);
5096	]]>
5097	          </programlisting>
5098	        </informalexample>
5099	
5100	        Note that you have to pre-allocate to use this function.
5101	      </para>
5102	    </section>
5103	
5104	    <section id="buffer-and-memory-external-hardware">
5105	      <title>External Hardware Buffers</title>
5106	      <para>
5107	        Some chips have their own hardware buffers and the DMA
5108	      transfer from the host memory is not available. In such a case,
5109	      you need to either 1) copy/set the audio data directly to the
5110	      external hardware buffer, or 2) make an intermediate buffer and
5111	      copy/set the data from it to the external hardware buffer in
5112	      interrupts (or in tasklets, preferably).
5113	      </para>
5114	
5115	      <para>
5116	        The first case works fine if the external hardware buffer is large
5117	      enough.  This method doesn't need any extra buffers and thus is
5118	      more effective. You need to define the
5119	      <structfield>copy</structfield> and
5120	      <structfield>silence</structfield> callbacks for 
5121	      the data transfer. However, there is a drawback: it cannot
5122	      be mmapped. The examples are GUS's GF1 PCM or emu8000's
5123	      wavetable PCM. 
5124	      </para>
5125	
5126	      <para>
5127	        The second case allows for mmap on the buffer, although you have
5128	      to handle an interrupt or a tasklet to transfer the data
5129	      from the intermediate buffer to the hardware buffer. You can find an
5130	      example in the vxpocket driver. 
5131	      </para>
5132	
5133	      <para>
5134	        Another case is when the chip uses a PCI memory-map
5135	      region for the buffer instead of the host memory. In this case,
5136	      mmap is available only on certain architectures like the Intel one.
5137	      In non-mmap mode, the data cannot be transferred as in the normal
5138	      way. Thus you need to define the <structfield>copy</structfield> and
5139	      <structfield>silence</structfield> callbacks as well, 
5140	      as in the cases above. The examples are found in
5141	      <filename>rme32.c</filename> and <filename>rme96.c</filename>. 
5142	      </para>
5143	
5144	      <para>
5145	        The implementation of the <structfield>copy</structfield> and
5146	        <structfield>silence</structfield> callbacks depends upon 
5147	        whether the hardware supports interleaved or non-interleaved
5148	        samples. The <structfield>copy</structfield> callback is
5149	        defined like below, a bit 
5150	        differently depending whether the direction is playback or
5151	        capture: 
5152	
5153	        <informalexample>
5154	          <programlisting>
5155	<![CDATA[
5156	  static int playback_copy(struct snd_pcm_substream *substream, int channel,
5157	               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5158	  static int capture_copy(struct snd_pcm_substream *substream, int channel,
5159	               snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5160	]]>
5161	          </programlisting>
5162	        </informalexample>
5163	      </para>
5164	
5165	      <para>
5166	        In the case of interleaved samples, the second argument
5167	      (<parameter>channel</parameter>) is not used. The third argument
5168	      (<parameter>pos</parameter>) points the 
5169	      current position offset in frames. 
5170	      </para>
5171	
5172	      <para>
5173	        The meaning of the fourth argument is different between
5174	      playback and capture. For playback, it holds the source data
5175	      pointer, and for capture, it's the destination data pointer. 
5176	      </para>
5177	
5178	      <para>
5179	        The last argument is the number of frames to be copied.
5180	      </para>
5181	
5182	      <para>
5183	        What you have to do in this callback is again different
5184	        between playback and capture directions. In the
5185	        playback case, you copy the given amount of data
5186	        (<parameter>count</parameter>) at the specified pointer
5187	        (<parameter>src</parameter>) to the specified offset
5188	        (<parameter>pos</parameter>) on the hardware buffer. When
5189	        coded like memcpy-like way, the copy would be like: 
5190	
5191	        <informalexample>
5192	          <programlisting>
5193	<![CDATA[
5194	  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5195	            frames_to_bytes(runtime, count));
5196	]]>
5197	          </programlisting>
5198	        </informalexample>
5199	      </para>
5200	
5201	      <para>
5202	        For the capture direction, you copy the given amount of
5203	        data (<parameter>count</parameter>) at the specified offset
5204	        (<parameter>pos</parameter>) on the hardware buffer to the
5205	        specified pointer (<parameter>dst</parameter>). 
5206	
5207	        <informalexample>
5208	          <programlisting>
5209	<![CDATA[
5210	  my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5211	            frames_to_bytes(runtime, count));
5212	]]>
5213	          </programlisting>
5214	        </informalexample>
5215	
5216	        Note that both the position and the amount of data are given
5217	      in frames. 
5218	      </para>
5219	
5220	      <para>
5221	        In the case of non-interleaved samples, the implementation
5222	      will be a bit more complicated. 
5223	      </para>
5224	
5225	      <para>
5226	        You need to check the channel argument, and if it's -1, copy
5227	      the whole channels. Otherwise, you have to copy only the
5228	      specified channel. Please check
5229	      <filename>isa/gus/gus_pcm.c</filename> as an example. 
5230	      </para>
5231	
5232	      <para>
5233	        The <structfield>silence</structfield> callback is also
5234	        implemented in a similar way. 
5235	
5236	        <informalexample>
5237	          <programlisting>
5238	<![CDATA[
5239	  static int silence(struct snd_pcm_substream *substream, int channel,
5240	                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5241	]]>
5242	          </programlisting>
5243	        </informalexample>
5244	      </para>
5245	
5246	      <para>
5247	        The meanings of arguments are the same as in the
5248	      <structfield>copy</structfield> 
5249	      callback, although there is no <parameter>src/dst</parameter>
5250	      argument. In the case of interleaved samples, the channel
5251	      argument has no meaning, as well as on
5252	      <structfield>copy</structfield> callback.  
5253	      </para>
5254	
5255	      <para>
5256	        The role of <structfield>silence</structfield> callback is to
5257	        set the given amount 
5258	        (<parameter>count</parameter>) of silence data at the
5259	        specified offset (<parameter>pos</parameter>) on the hardware
5260	        buffer. Suppose that the data format is signed (that is, the
5261	        silent-data is 0), and the implementation using a memset-like
5262	        function would be like: 
5263	
5264	        <informalexample>
5265	          <programlisting>
5266	<![CDATA[
5267	  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5268	            frames_to_bytes(runtime, count));
5269	]]>
5270	          </programlisting>
5271	        </informalexample>
5272	      </para>
5273	
5274	      <para>
5275	        In the case of non-interleaved samples, again, the
5276	      implementation becomes a bit more complicated. See, for example,
5277	      <filename>isa/gus/gus_pcm.c</filename>. 
5278	      </para>
5279	    </section>
5280	
5281	    <section id="buffer-and-memory-non-contiguous">
5282	      <title>Non-Contiguous Buffers</title>
5283	      <para>
5284	        If your hardware supports the page table as in emu10k1 or the
5285	      buffer descriptors as in via82xx, you can use the scatter-gather
5286	      (SG) DMA. ALSA provides an interface for handling SG-buffers.
5287	      The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>. 
5288	      </para>
5289	
5290	      <para>
5291	        For creating the SG-buffer handler, call
5292	        <function>snd_pcm_lib_preallocate_pages()</function> or
5293	        <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5294	        with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5295		in the PCM constructor like other PCI pre-allocator.
5296	        You need to pass <function>snd_dma_pci_data(pci)</function>,
5297	        where pci is the struct <structname>pci_dev</structname> pointer
5298	        of the chip as well.
5299	        The <type>struct snd_sg_buf</type> instance is created as
5300	        substream-&gt;dma_private. You can cast
5301	        the pointer like: 
5302	
5303	        <informalexample>
5304	          <programlisting>
5305	<![CDATA[
5306	  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5307	]]>
5308	          </programlisting>
5309	        </informalexample>
5310	      </para>
5311	
5312	      <para>
5313	        Then call <function>snd_pcm_lib_malloc_pages()</function>
5314	      in the <structfield>hw_params</structfield> callback
5315	      as well as in the case of normal PCI buffer.
5316	      The SG-buffer handler will allocate the non-contiguous kernel
5317	      pages of the given size and map them onto the virtually contiguous
5318	      memory.  The virtual pointer is addressed in runtime-&gt;dma_area.
5319	      The physical address (runtime-&gt;dma_addr) is set to zero,
5320	      because the buffer is physically non-contiguous.
5321	      The physical address table is set up in sgbuf-&gt;table.
5322	      You can get the physical address at a certain offset via
5323	      <function>snd_pcm_sgbuf_get_addr()</function>. 
5324	      </para>
5325	
5326	      <para>
5327	        When a SG-handler is used, you need to set
5328	      <function>snd_pcm_sgbuf_ops_page</function> as
5329	      the <structfield>page</structfield> callback.
5330	      (See <link linkend="pcm-interface-operators-page-callback">
5331	      <citetitle>page callback section</citetitle></link>.)
5332	      </para>
5333	
5334	      <para>
5335	        To release the data, call
5336	      <function>snd_pcm_lib_free_pages()</function> in the
5337	      <structfield>hw_free</structfield> callback as usual.
5338	      </para>
5339	    </section>
5340	
5341	    <section id="buffer-and-memory-vmalloced">
5342	      <title>Vmalloc'ed Buffers</title>
5343	      <para>
5344	        It's possible to use a buffer allocated via
5345	      <function>vmalloc</function>, for example, for an intermediate
5346	      buffer. Since the allocated pages are not contiguous, you need
5347	      to set the <structfield>page</structfield> callback to obtain
5348	      the physical address at every offset. 
5349	      </para>
5350	
5351	      <para>
5352	        The implementation of <structfield>page</structfield> callback
5353	        would be like this: 
5354	
5355	        <informalexample>
5356	          <programlisting>
5357	<![CDATA[
5358	  #include <linux/vmalloc.h>
5359	
5360	  /* get the physical page pointer on the given offset */
5361	  static struct page *mychip_page(struct snd_pcm_substream *substream,
5362	                                  unsigned long offset)
5363	  {
5364	          void *pageptr = substream->runtime->dma_area + offset;
5365	          return vmalloc_to_page(pageptr);
5366	  }
5367	]]>
5368	          </programlisting>
5369	        </informalexample>
5370	      </para>
5371	    </section>
5372	
5373	  </chapter>
5374	
5375	
5376	<!-- ****************************************************** -->
5377	<!-- Proc Interface  -->
5378	<!-- ****************************************************** -->
5379	  <chapter id="proc-interface">
5380	    <title>Proc Interface</title>
5381	    <para>
5382	      ALSA provides an easy interface for procfs. The proc files are
5383	      very useful for debugging. I recommend you set up proc files if
5384	      you write a driver and want to get a running status or register
5385	      dumps. The API is found in
5386	      <filename>&lt;sound/info.h&gt;</filename>. 
5387	    </para>
5388	
5389	    <para>
5390	      To create a proc file, call
5391	      <function>snd_card_proc_new()</function>. 
5392	
5393	      <informalexample>
5394	        <programlisting>
5395	<![CDATA[
5396	  struct snd_info_entry *entry;
5397	  int err = snd_card_proc_new(card, "my-file", &entry);
5398	]]>
5399	        </programlisting>
5400	      </informalexample>
5401	
5402	      where the second argument specifies the name of the proc file to be
5403	    created. The above example will create a file
5404	    <filename>my-file</filename> under the card directory,
5405	    e.g. <filename>/proc/asound/card0/my-file</filename>. 
5406	    </para>
5407	
5408	    <para>
5409	    Like other components, the proc entry created via
5410	    <function>snd_card_proc_new()</function> will be registered and
5411	    released automatically in the card registration and release
5412	    functions.
5413	    </para>
5414	
5415	    <para>
5416	      When the creation is successful, the function stores a new
5417	    instance in the pointer given in the third argument.
5418	    It is initialized as a text proc file for read only.  To use
5419	    this proc file as a read-only text file as it is, set the read
5420	    callback with a private data via 
5421	     <function>snd_info_set_text_ops()</function>.
5422	
5423	      <informalexample>
5424	        <programlisting>
5425	<![CDATA[
5426	  snd_info_set_text_ops(entry, chip, my_proc_read);
5427	]]>
5428	        </programlisting>
5429	      </informalexample>
5430	    
5431	    where the second argument (<parameter>chip</parameter>) is the
5432	    private data to be used in the callbacks. The third parameter
5433	    specifies the read buffer size and the fourth
5434	    (<parameter>my_proc_read</parameter>) is the callback function, which
5435	    is defined like
5436	
5437	      <informalexample>
5438	        <programlisting>
5439	<![CDATA[
5440	  static void my_proc_read(struct snd_info_entry *entry,
5441	                           struct snd_info_buffer *buffer);
5442	]]>
5443	        </programlisting>
5444	      </informalexample>
5445	    
5446	    </para>
5447	
5448	    <para>
5449	    In the read callback, use <function>snd_iprintf()</function> for
5450	    output strings, which works just like normal
5451	    <function>printf()</function>.  For example,
5452	
5453	      <informalexample>
5454	        <programlisting>
5455	<![CDATA[
5456	  static void my_proc_read(struct snd_info_entry *entry,
5457	                           struct snd_info_buffer *buffer)
5458	  {
5459	          struct my_chip *chip = entry->private_data;
5460	
5461	          snd_iprintf(buffer, "This is my chip!\n");
5462	          snd_iprintf(buffer, "Port = %ld\n", chip->port);
5463	  }
5464	]]>
5465	        </programlisting>
5466	      </informalexample>
5467	    </para>
5468	
5469	    <para>
5470	    The file permissions can be changed afterwards.  As default, it's
5471	    set as read only for all users.  If you want to add write
5472	    permission for the user (root as default), do as follows:
5473	
5474	      <informalexample>
5475	        <programlisting>
5476	<![CDATA[
5477	 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5478	]]>
5479	        </programlisting>
5480	      </informalexample>
5481	
5482	    and set the write buffer size and the callback
5483	
5484	      <informalexample>
5485	        <programlisting>
5486	<![CDATA[
5487	  entry->c.text.write = my_proc_write;
5488	]]>
5489	        </programlisting>
5490	      </informalexample>
5491	    </para>
5492	
5493	    <para>
5494	      For the write callback, you can use
5495	    <function>snd_info_get_line()</function> to get a text line, and
5496	    <function>snd_info_get_str()</function> to retrieve a string from
5497	    the line. Some examples are found in
5498	    <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5499	    <filename>pcm_oss.c</filename>. 
5500	    </para>
5501	
5502	    <para>
5503	      For a raw-data proc-file, set the attributes as follows:
5504	
5505	      <informalexample>
5506	        <programlisting>
5507	<![CDATA[
5508	  static struct snd_info_entry_ops my_file_io_ops = {
5509	          .read = my_file_io_read,
5510	  };
5511	
5512	  entry->content = SNDRV_INFO_CONTENT_DATA;
5513	  entry->private_data = chip;
5514	  entry->c.ops = &my_file_io_ops;
5515	  entry->size = 4096;
5516	  entry->mode = S_IFREG | S_IRUGO;
5517	]]>
5518	        </programlisting>
5519	      </informalexample>
5520	
5521	      For the raw data, <structfield>size</structfield> field must be
5522	      set properly.  This specifies the maximum size of the proc file access.
5523	    </para>
5524	
5525	    <para>
5526	      The read/write callbacks of raw mode are more direct than the text mode.
5527	      You need to use a low-level I/O functions such as
5528	      <function>copy_from/to_user()</function> to transfer the
5529	      data.
5530	
5531	      <informalexample>
5532	        <programlisting>
5533	<![CDATA[
5534	  static ssize_t my_file_io_read(struct snd_info_entry *entry,
5535	                              void *file_private_data,
5536	                              struct file *file,
5537	                              char *buf,
5538	                              size_t count,
5539	                              loff_t pos)
5540	  {
5541	          if (copy_to_user(buf, local_data + pos, count))
5542	                  return -EFAULT;
5543	          return count;
5544	  }
5545	]]>
5546	        </programlisting>
5547	      </informalexample>
5548	
5549	      If the size of the info entry has been set up properly,
5550	      <structfield>count</structfield> and <structfield>pos</structfield> are
5551	      guaranteed to fit within 0 and the given size.
5552	      You don't have to check the range in the callbacks unless any
5553	      other condition is required.
5554	
5555	    </para>
5556	
5557	  </chapter>
5558	
5559	
5560	<!-- ****************************************************** -->
5561	<!-- Power Management  -->
5562	<!-- ****************************************************** -->
5563	  <chapter id="power-management">
5564	    <title>Power Management</title>
5565	    <para>
5566	      If the chip is supposed to work with suspend/resume
5567	      functions, you need to add power-management code to the
5568	      driver. The additional code for power-management should be
5569	      <function>ifdef</function>'ed with
5570	      <constant>CONFIG_PM</constant>. 
5571	    </para>
5572	
5573		<para>
5574		If the driver <emphasis>fully</emphasis> supports suspend/resume
5575		that is, the device can be
5576		properly resumed to its state when suspend was called,
5577		you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5578		in the pcm info field.  Usually, this is possible when the
5579		registers of the chip can be safely saved and restored to
5580		RAM. If this is set, the trigger callback is called with
5581		<constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5582		callback completes. 
5583		</para>
5584	
5585		<para>
5586		Even if the driver doesn't support PM fully but 
5587		partial suspend/resume is still possible, it's still worthy to
5588		implement suspend/resume callbacks. In such a case, applications
5589		would reset the status by calling
5590		<function>snd_pcm_prepare()</function> and restart the stream
5591		appropriately.  Hence, you can define suspend/resume callbacks
5592		below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5593		info flag to the PCM.
5594		</para>
5595		
5596		<para>
5597		Note that the trigger with SUSPEND can always be called when
5598		<function>snd_pcm_suspend_all</function> is called,
5599		regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5600		The <constant>RESUME</constant> flag affects only the behavior
5601		of <function>snd_pcm_resume()</function>.
5602		(Thus, in theory,
5603		<constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5604		to be handled in the trigger callback when no
5605		<constant>SNDRV_PCM_INFO_RESUME</constant> flag is set.  But,
5606		it's better to keep it for compatibility reasons.)
5607		</para>
5608	    <para>
5609	      In the earlier version of ALSA drivers, a common
5610	      power-management layer was provided, but it has been removed.
5611	      The driver needs to define the suspend/resume hooks according to
5612	      the bus the device is connected to.  In the case of PCI drivers, the
5613	      callbacks look like below:
5614	
5615	      <informalexample>
5616	        <programlisting>
5617	<![CDATA[
5618	  #ifdef CONFIG_PM
5619	  static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5620	  {
5621	          .... /* do things for suspend */
5622	          return 0;
5623	  }
5624	  static int snd_my_resume(struct pci_dev *pci)
5625	  {
5626	          .... /* do things for suspend */
5627	          return 0;
5628	  }
5629	  #endif
5630	]]>
5631	        </programlisting>
5632	      </informalexample>
5633	    </para>
5634	
5635	    <para>
5636	      The scheme of the real suspend job is as follows.
5637	
5638	      <orderedlist>
5639	        <listitem><para>Retrieve the card and the chip data.</para></listitem>
5640	        <listitem><para>Call <function>snd_power_change_state()</function> with
5641		  <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5642		  power status.</para></listitem>
5643	        <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5644		<listitem><para>If AC97 codecs are used, call
5645		<function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5646	        <listitem><para>Save the register values if necessary.</para></listitem>
5647	        <listitem><para>Stop the hardware if necessary.</para></listitem>
5648	        <listitem><para>Disable the PCI device by calling
5649		  <function>pci_disable_device()</function>.  Then, call
5650	          <function>pci_save_state()</function> at last.</para></listitem>
5651	      </orderedlist>
5652	    </para>
5653	
5654	    <para>
5655	      A typical code would be like:
5656	
5657	      <informalexample>
5658	        <programlisting>
5659	<![CDATA[
5660	  static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5661	  {
5662	          /* (1) */
5663	          struct snd_card *card = pci_get_drvdata(pci);
5664	          struct mychip *chip = card->private_data;
5665	          /* (2) */
5666	          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5667	          /* (3) */
5668	          snd_pcm_suspend_all(chip->pcm);
5669	          /* (4) */
5670	          snd_ac97_suspend(chip->ac97);
5671	          /* (5) */
5672	          snd_mychip_save_registers(chip);
5673	          /* (6) */
5674	          snd_mychip_stop_hardware(chip);
5675	          /* (7) */
5676	          pci_disable_device(pci);
5677	          pci_save_state(pci);
5678	          return 0;
5679	  }
5680	]]>
5681	        </programlisting>
5682	      </informalexample>
5683	    </para>
5684	
5685	    <para>
5686	    The scheme of the real resume job is as follows.
5687	
5688	    <orderedlist>
5689	    <listitem><para>Retrieve the card and the chip data.</para></listitem>
5690	    <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5691	    	Then enable the pci device again by calling <function>pci_enable_device()</function>.
5692		Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5693	    <listitem><para>Re-initialize the chip.</para></listitem>
5694	    <listitem><para>Restore the saved registers if necessary.</para></listitem>
5695	    <listitem><para>Resume the mixer, e.g. calling
5696	    <function>snd_ac97_resume()</function>.</para></listitem>
5697	    <listitem><para>Restart the hardware (if any).</para></listitem>
5698	    <listitem><para>Call <function>snd_power_change_state()</function> with
5699		<constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5700	    </orderedlist>
5701	    </para>
5702	
5703	    <para>
5704	    A typical code would be like:
5705	
5706	      <informalexample>
5707	        <programlisting>
5708	<![CDATA[
5709	  static int mychip_resume(struct pci_dev *pci)
5710	  {
5711	          /* (1) */
5712	          struct snd_card *card = pci_get_drvdata(pci);
5713	          struct mychip *chip = card->private_data;
5714	          /* (2) */
5715	          pci_restore_state(pci);
5716	          pci_enable_device(pci);
5717	          pci_set_master(pci);
5718	          /* (3) */
5719	          snd_mychip_reinit_chip(chip);
5720	          /* (4) */
5721	          snd_mychip_restore_registers(chip);
5722	          /* (5) */
5723	          snd_ac97_resume(chip->ac97);
5724	          /* (6) */
5725	          snd_mychip_restart_chip(chip);
5726	          /* (7) */
5727	          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5728	          return 0;
5729	  }
5730	]]>
5731	        </programlisting>
5732	      </informalexample>
5733	    </para>
5734	
5735	    <para>
5736		As shown in the above, it's better to save registers after
5737		suspending the PCM operations via
5738		<function>snd_pcm_suspend_all()</function> or
5739		<function>snd_pcm_suspend()</function>.  It means that the PCM
5740		streams are already stopped when the register snapshot is
5741		taken.  But, remember that you don't have to restart the PCM
5742		stream in the resume callback. It'll be restarted via 
5743		trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5744		when necessary.
5745	    </para>
5746	
5747	    <para>
5748	      OK, we have all callbacks now. Let's set them up. In the
5749	      initialization of the card, make sure that you can get the chip
5750	      data from the card instance, typically via
5751	      <structfield>private_data</structfield> field, in case you
5752	      created the chip data individually.
5753	
5754	      <informalexample>
5755	        <programlisting>
5756	<![CDATA[
5757	  static int snd_mychip_probe(struct pci_dev *pci,
5758	                              const struct pci_device_id *pci_id)
5759	  {
5760	          ....
5761	          struct snd_card *card;
5762	          struct mychip *chip;
5763	          int err;
5764	          ....
5765	          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5766	                             0, &card);
5767	          ....
5768	          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5769	          ....
5770	          card->private_data = chip;
5771	          ....
5772	  }
5773	]]>
5774	        </programlisting>
5775	      </informalexample>
5776	
5777		When you created the chip data with
5778		<function>snd_card_new()</function>, it's anyway accessible
5779		via <structfield>private_data</structfield> field.
5780	
5781	      <informalexample>
5782	        <programlisting>
5783	<![CDATA[
5784	  static int snd_mychip_probe(struct pci_dev *pci,
5785	                              const struct pci_device_id *pci_id)
5786	  {
5787	          ....
5788	          struct snd_card *card;
5789	          struct mychip *chip;
5790	          int err;
5791	          ....
5792	          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5793	                             sizeof(struct mychip), &card);
5794	          ....
5795	          chip = card->private_data;
5796	          ....
5797	  }
5798	]]>
5799	        </programlisting>
5800	      </informalexample>
5801	
5802	    </para>
5803	
5804	    <para>
5805	      If you need a space to save the registers, allocate the
5806		buffer for it here, too, since it would be fatal
5807	    if you cannot allocate a memory in the suspend phase.
5808	    The allocated buffer should be released in the corresponding
5809	    destructor.
5810	    </para>
5811	
5812	    <para>
5813	      And next, set suspend/resume callbacks to the pci_driver.
5814	
5815	      <informalexample>
5816	        <programlisting>
5817	<![CDATA[
5818	  static struct pci_driver driver = {
5819	          .name = KBUILD_MODNAME,
5820	          .id_table = snd_my_ids,
5821	          .probe = snd_my_probe,
5822	          .remove = snd_my_remove,
5823	  #ifdef CONFIG_PM
5824	          .suspend = snd_my_suspend,
5825	          .resume = snd_my_resume,
5826	  #endif
5827	  };
5828	]]>
5829	        </programlisting>
5830	      </informalexample>
5831	    </para>
5832	
5833	  </chapter>
5834	
5835	
5836	<!-- ****************************************************** -->
5837	<!-- Module Parameters  -->
5838	<!-- ****************************************************** -->
5839	  <chapter id="module-parameters">
5840	    <title>Module Parameters</title>
5841	    <para>
5842	      There are standard module options for ALSA. At least, each
5843	      module should have the <parameter>index</parameter>,
5844	      <parameter>id</parameter> and <parameter>enable</parameter>
5845	      options. 
5846	    </para>
5847	
5848	    <para>
5849	      If the module supports multiple cards (usually up to
5850	      8 = <constant>SNDRV_CARDS</constant> cards), they should be
5851	      arrays. The default initial values are defined already as
5852	      constants for easier programming:
5853	
5854	      <informalexample>
5855	        <programlisting>
5856	<![CDATA[
5857	  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5858	  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5859	  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5860	]]>
5861	        </programlisting>
5862	      </informalexample>
5863	    </para>
5864	
5865	    <para>
5866	      If the module supports only a single card, they could be single
5867	    variables, instead.  <parameter>enable</parameter> option is not
5868	    always necessary in this case, but it would be better to have a
5869	    dummy option for compatibility.
5870	    </para>
5871	
5872	    <para>
5873	      The module parameters must be declared with the standard
5874	    <function>module_param()()</function>,
5875	    <function>module_param_array()()</function> and
5876	    <function>MODULE_PARM_DESC()</function> macros.
5877	    </para>
5878	
5879	    <para>
5880	      The typical coding would be like below:
5881	
5882	      <informalexample>
5883	        <programlisting>
5884	<![CDATA[
5885	  #define CARD_NAME "My Chip"
5886	
5887	  module_param_array(index, int, NULL, 0444);
5888	  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5889	  module_param_array(id, charp, NULL, 0444);
5890	  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5891	  module_param_array(enable, bool, NULL, 0444);
5892	  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5893	]]>
5894	        </programlisting>
5895	      </informalexample>
5896	    </para>
5897	
5898	    <para>
5899	      Also, don't forget to define the module description, classes,
5900	      license and devices. Especially, the recent modprobe requires to
5901	      define the module license as GPL, etc., otherwise the system is
5902	      shown as <quote>tainted</quote>. 
5903	
5904	      <informalexample>
5905	        <programlisting>
5906	<![CDATA[
5907	  MODULE_DESCRIPTION("My Chip");
5908	  MODULE_LICENSE("GPL");
5909	  MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5910	]]>
5911	        </programlisting>
5912	      </informalexample>
5913	    </para>
5914	
5915	  </chapter>
5916	
5917	
5918	<!-- ****************************************************** -->
5919	<!-- How To Put Your Driver  -->
5920	<!-- ****************************************************** -->
5921	  <chapter id="how-to-put-your-driver">
5922	    <title>How To Put Your Driver Into ALSA Tree</title>
5923		<section>
5924		<title>General</title>
5925		<para>
5926		So far, you've learned how to write the driver codes.
5927		And you might have a question now: how to put my own
5928		driver into the ALSA driver tree?
5929		Here (finally :) the standard procedure is described briefly.
5930		</para>
5931	
5932		<para>
5933		Suppose that you create a new PCI driver for the card
5934		<quote>xyz</quote>.  The card module name would be
5935		snd-xyz.  The new driver is usually put into the alsa-driver
5936		tree, <filename>alsa-driver/pci</filename> directory in
5937		the case of PCI cards.
5938		Then the driver is evaluated, audited and tested
5939		by developers and users.  After a certain time, the driver
5940		will go to the alsa-kernel tree (to the corresponding directory,
5941		such as <filename>alsa-kernel/pci</filename>) and eventually
5942	 	will be integrated into the Linux 2.6 tree (the directory would be
5943		<filename>linux/sound/pci</filename>).
5944		</para>
5945	
5946		<para>
5947		In the following sections, the driver code is supposed
5948		to be put into alsa-driver tree. The two cases are covered:
5949		a driver consisting of a single source file and one consisting
5950		of several source files.
5951		</para>
5952		</section>
5953	
5954		<section>
5955		<title>Driver with A Single Source File</title>
5956		<para>
5957		<orderedlist>
5958		<listitem>
5959		<para>
5960		Modify alsa-driver/pci/Makefile
5961		</para>
5962	
5963		<para>
5964		Suppose you have a file xyz.c.  Add the following
5965		two lines
5966	      <informalexample>
5967	        <programlisting>
5968	<![CDATA[
5969	  snd-xyz-objs := xyz.o
5970	  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5971	]]>
5972	        </programlisting>
5973	      </informalexample>
5974		</para>
5975		</listitem>
5976	
5977		<listitem>
5978		<para>
5979		Create the Kconfig entry
5980		</para>
5981	
5982		<para>
5983		Add the new entry of Kconfig for your xyz driver.
5984	      <informalexample>
5985	        <programlisting>
5986	<![CDATA[
5987	  config SND_XYZ
5988	          tristate "Foobar XYZ"
5989	          depends on SND
5990	          select SND_PCM
5991	          help
5992	            Say Y here to include support for Foobar XYZ soundcard.
5993	
5994	            To compile this driver as a module, choose M here: the module
5995	            will be called snd-xyz.
5996	]]>
5997	        </programlisting>
5998	      </informalexample>
5999	
6000		the line, select SND_PCM, specifies that the driver xyz supports
6001		PCM.  In addition to SND_PCM, the following components are
6002		supported for select command:
6003		SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
6004		SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
6005		Add the select command for each supported component.
6006		</para>
6007	
6008		<para>
6009		Note that some selections imply the lowlevel selections.
6010		For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
6011		AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
6012		You don't need to give the lowlevel selections again.
6013		</para>
6014	
6015		<para>
6016		For the details of Kconfig script, refer to the kbuild
6017		documentation.
6018		</para>
6019	
6020		</listitem>
6021	
6022		<listitem>
6023		<para>
6024		Run cvscompile script to re-generate the configure script and
6025		build the whole stuff again.
6026		</para>
6027		</listitem>
6028		</orderedlist>
6029		</para>
6030		</section>
6031	
6032		<section>
6033		<title>Drivers with Several Source Files</title>
6034		<para>
6035		Suppose that the driver snd-xyz have several source files.
6036		They are located in the new subdirectory,
6037		pci/xyz.
6038	
6039		<orderedlist>
6040		<listitem>
6041		<para>
6042		Add a new directory (<filename>xyz</filename>) in
6043		<filename>alsa-driver/pci/Makefile</filename> as below
6044	
6045	      <informalexample>
6046	        <programlisting>
6047	<![CDATA[
6048	  obj-$(CONFIG_SND) += xyz/
6049	]]>
6050	        </programlisting>
6051	      </informalexample>
6052		</para>
6053		</listitem>
6054	
6055		<listitem>
6056		<para>
6057		Under the directory <filename>xyz</filename>, create a Makefile
6058	
6059	      <example>
6060		<title>Sample Makefile for a driver xyz</title>
6061	        <programlisting>
6062	<![CDATA[
6063	  ifndef SND_TOPDIR
6064	  SND_TOPDIR=../..
6065	  endif
6066	
6067	  include $(SND_TOPDIR)/toplevel.config
6068	  include $(SND_TOPDIR)/Makefile.conf
6069	
6070	  snd-xyz-objs := xyz.o abc.o def.o
6071	
6072	  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6073	
6074	  include $(SND_TOPDIR)/Rules.make
6075	]]>
6076	        </programlisting>
6077	      </example>
6078		</para>
6079		</listitem>
6080	
6081		<listitem>
6082		<para>
6083		Create the Kconfig entry
6084		</para>
6085	
6086		<para>
6087		This procedure is as same as in the last section.
6088		</para>
6089		</listitem>
6090	
6091		<listitem>
6092		<para>
6093		Run cvscompile script to re-generate the configure script and
6094		build the whole stuff again.
6095		</para>
6096		</listitem>
6097		</orderedlist>
6098		</para>
6099		</section>
6100	
6101	  </chapter>
6102	
6103	<!-- ****************************************************** -->
6104	<!-- Useful Functions  -->
6105	<!-- ****************************************************** -->
6106	  <chapter id="useful-functions">
6107	    <title>Useful Functions</title>
6108	
6109	    <section id="useful-functions-snd-printk">
6110	      <title><function>snd_printk()</function> and friends</title>
6111	      <para>
6112	        ALSA provides a verbose version of the
6113	      <function>printk()</function> function. If a kernel config
6114	      <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6115	      function prints the given message together with the file name
6116	      and the line of the caller. The <constant>KERN_XXX</constant>
6117	      prefix is processed as 
6118	      well as the original <function>printk()</function> does, so it's
6119	      recommended to add this prefix, e.g. 
6120	
6121	        <informalexample>
6122	          <programlisting>
6123	<![CDATA[
6124	  snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6125	]]>
6126	          </programlisting>
6127	        </informalexample>
6128	      </para>
6129	
6130	      <para>
6131	        There are also <function>printk()</function>'s for
6132	      debugging. <function>snd_printd()</function> can be used for
6133	      general debugging purposes. If
6134	      <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6135	      compiled, and works just like
6136	      <function>snd_printk()</function>. If the ALSA is compiled
6137	      without the debugging flag, it's ignored. 
6138	      </para>
6139	
6140	      <para>
6141	        <function>snd_printdd()</function> is compiled in only when
6142	      <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6143	      that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6144	      even if you configure the alsa-driver with
6145	      <option>--with-debug=full</option> option. You need to give
6146	      explicitly <option>--with-debug=detect</option> option instead. 
6147	      </para>
6148	    </section>
6149	
6150	    <section id="useful-functions-snd-bug">
6151	      <title><function>snd_BUG()</function></title>
6152	      <para>
6153	        It shows the <computeroutput>BUG?</computeroutput> message and
6154	      stack trace as well as <function>snd_BUG_ON</function> at the point.
6155	      It's useful to show that a fatal error happens there. 
6156	      </para>
6157	      <para>
6158		 When no debug flag is set, this macro is ignored. 
6159	      </para>
6160	    </section>
6161	
6162	    <section id="useful-functions-snd-bug-on">
6163	      <title><function>snd_BUG_ON()</function></title>
6164	      <para>
6165	        <function>snd_BUG_ON()</function> macro is similar with
6166		<function>WARN_ON()</function> macro. For example,  
6167	
6168	        <informalexample>
6169	          <programlisting>
6170	<![CDATA[
6171	  snd_BUG_ON(!pointer);
6172	]]>
6173	          </programlisting>
6174	        </informalexample>
6175	
6176		or it can be used as the condition,
6177	        <informalexample>
6178	          <programlisting>
6179	<![CDATA[
6180	  if (snd_BUG_ON(non_zero_is_bug))
6181	          return -EINVAL;
6182	]]>
6183	          </programlisting>
6184	        </informalexample>
6185	
6186	      </para>
6187	
6188	      <para>
6189	        The macro takes an conditional expression to evaluate.
6190		When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
6191		expression is non-zero, it shows the warning message such as
6192		<computeroutput>BUG? (xxx)</computeroutput>
6193		normally followed by stack trace.
6194	
6195		In both cases it returns the evaluated value.
6196	      </para>
6197	
6198	    </section>
6199	
6200	  </chapter>
6201	
6202	
6203	<!-- ****************************************************** -->
6204	<!-- Acknowledgments  -->
6205	<!-- ****************************************************** -->
6206	  <chapter id="acknowledgments">
6207	    <title>Acknowledgments</title>
6208	    <para>
6209	      I would like to thank Phil Kerr for his help for improvement and
6210	      corrections of this document. 
6211	    </para>
6212	    <para>
6213	    Kevin Conder reformatted the original plain-text to the
6214	    DocBook format.
6215	    </para>
6216	    <para>
6217	    Giuliano Pochini corrected typos and contributed the example codes
6218	    in the hardware constraints section.
6219	    </para>
6220	  </chapter>
6221	</book>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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