About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3		"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4	
5	<!-- ****************************************************** -->
6	<!-- Header  -->
7	<!-- ****************************************************** -->
8	<book id="Writing-an-ALSA-Driver">
9	  <bookinfo>
10	    <title>Writing an ALSA Driver</title>
11	    <author>
12	      <firstname>Takashi</firstname>
13	      <surname>Iwai</surname>
14	      <affiliation>
15	        <address>
16	          <email>tiwai@suse.de</email>
17	        </address>
18	      </affiliation>
19	     </author>
20	
21	     <date>Oct 15, 2007</date>
22	     <edition>0.3.7</edition>
23	
24	    <abstract>
25	      <para>
26	        This document describes how to write an ALSA (Advanced Linux
27	        Sound Architecture) driver.
28	      </para>
29	    </abstract>
30	
31	    <legalnotice>
32	    <para>
33	    Copyright (c) 2002-2005  Takashi Iwai <email>tiwai@suse.de</email>
34	    </para>
35	
36	    <para>
37	    This document is free; you can redistribute it and/or modify it
38	    under the terms of the GNU General Public License as published by
39	    the Free Software Foundation; either version 2 of the License, or
40	    (at your option) any later version. 
41	    </para>
42	
43	    <para>
44	    This document is distributed in the hope that it will be useful,
45	    but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
46	    implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
47	    PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
48	    for more details.
49	    </para>
50	
51	    <para>
52	    You should have received a copy of the GNU General Public
53	    License along with this program; if not, write to the Free
54	    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
55	    MA 02111-1307 USA
56	    </para>
57	    </legalnotice>
58	
59	  </bookinfo>
60	
61	<!-- ****************************************************** -->
62	<!-- Preface  -->
63	<!-- ****************************************************** -->
64	  <preface id="preface">
65	    <title>Preface</title>
66	    <para>
67	      This document describes how to write an
68	      <ulink url="http://www.alsa-project.org/"><citetitle>
69	      ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
70	      driver. The document focuses mainly on PCI soundcards.
71	      In the case of other device types, the API might
72	      be different, too. However, at least the ALSA kernel API is
73	      consistent, and therefore it would be still a bit help for
74	      writing them.
75	    </para>
76	
77	    <para>
78	    This document targets people who already have enough
79	    C language skills and have basic linux kernel programming
80	    knowledge.  This document doesn't explain the general
81	    topic of linux kernel coding and doesn't cover low-level
82	    driver implementation details. It only describes
83	    the standard way to write a PCI sound driver on ALSA.
84	    </para>
85	
86	    <para>
87	      If you are already familiar with the older ALSA ver.0.5.x API, you
88	    can check the drivers such as <filename>sound/pci/es1938.c</filename> or
89	    <filename>sound/pci/maestro3.c</filename> which have also almost the same
90	    code-base in the ALSA 0.5.x tree, so you can compare the differences.
91	    </para>
92	
93	    <para>
94	      This document is still a draft version. Any feedback and
95	    corrections, please!!
96	    </para>
97	  </preface>
98	
99	
100	<!-- ****************************************************** -->
101	<!-- File Tree Structure  -->
102	<!-- ****************************************************** -->
103	  <chapter id="file-tree">
104	    <title>File Tree Structure</title>
105	
106	    <section id="file-tree-general">
107	      <title>General</title>
108	      <para>
109	        The ALSA drivers are provided in two ways.
110	      </para>
111	
112	      <para>
113	        One is the trees provided as a tarball or via cvs from the
114	      ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
115	      tree. To synchronize both, the ALSA driver tree is split into
116	      two different trees: alsa-kernel and alsa-driver. The former
117	      contains purely the source code for the Linux 2.6 (or later)
118	      tree. This tree is designed only for compilation on 2.6 or
119	      later environment. The latter, alsa-driver, contains many subtle
120	      files for compiling ALSA drivers outside of the Linux kernel tree,
121	      wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
122	      and additional drivers which are still in development or in
123	      tests.  The drivers in alsa-driver tree will be moved to
124	      alsa-kernel (and eventually to the 2.6 kernel tree) when they are
125	      finished and confirmed to work fine.
126	      </para>
127	
128	      <para>
129	        The file tree structure of ALSA driver is depicted below. Both
130	        alsa-kernel and alsa-driver have almost the same file
131	        structure, except for <quote>core</quote> directory. It's
132	        named as <quote>acore</quote> in alsa-driver tree. 
133	
134	        <example>
135	          <title>ALSA File Tree Structure</title>
136	          <literallayout>
137	        sound
138	                /core
139	                        /oss
140	                        /seq
141	                                /oss
142	                                /instr
143	                /ioctl32
144	                /include
145	                /drivers
146	                        /mpu401
147	                        /opl3
148	                /i2c
149	                        /l3
150	                /synth
151	                        /emux
152	                /pci
153	                        /(cards)
154	                /isa
155	                        /(cards)
156	                /arm
157	                /ppc
158	                /sparc
159	                /usb
160	                /pcmcia /(cards)
161	                /oss
162	          </literallayout>
163	        </example>
164	      </para>
165	    </section>
166	
167	    <section id="file-tree-core-directory">
168	      <title>core directory</title>
169	      <para>
170	        This directory contains the middle layer which is the heart
171	      of ALSA drivers. In this directory, the native ALSA modules are
172	      stored. The sub-directories contain different modules and are
173	      dependent upon the kernel config. 
174	      </para>
175	
176	      <section id="file-tree-core-directory-oss">
177	        <title>core/oss</title>
178	
179	        <para>
180	          The codes for PCM and mixer OSS emulation modules are stored
181	        in this directory. The rawmidi OSS emulation is included in
182	        the ALSA rawmidi code since it's quite small. The sequencer
183	        code is stored in <filename>core/seq/oss</filename> directory (see
184	        <link linkend="file-tree-core-directory-seq-oss"><citetitle>
185	        below</citetitle></link>).
186	        </para>
187	      </section>
188	
189	      <section id="file-tree-core-directory-ioctl32">
190	        <title>core/ioctl32</title>
191	
192	        <para>
193	          This directory contains the 32bit-ioctl wrappers for 64bit
194	        architectures such like x86-64, ppc64 and sparc64. For 32bit
195	        and alpha architectures, these are not compiled. 
196	        </para>
197	      </section>
198	
199	      <section id="file-tree-core-directory-seq">
200	        <title>core/seq</title>
201	        <para>
202	          This directory and its sub-directories are for the ALSA
203	        sequencer. This directory contains the sequencer core and
204	        primary sequencer modules such like snd-seq-midi,
205	        snd-seq-virmidi, etc. They are compiled only when
206	        <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
207	        config. 
208	        </para>
209	      </section>
210	
211	      <section id="file-tree-core-directory-seq-oss">
212	        <title>core/seq/oss</title>
213	        <para>
214	          This contains the OSS sequencer emulation codes.
215	        </para>
216	      </section>
217	
218	      <section id="file-tree-core-directory-deq-instr">
219	        <title>core/seq/instr</title>
220	        <para>
221	          This directory contains the modules for the sequencer
222	        instrument layer. 
223	        </para>
224	      </section>
225	    </section>
226	
227	    <section id="file-tree-include-directory">
228	      <title>include directory</title>
229	      <para>
230	        This is the place for the public header files of ALSA drivers,
231	      which are to be exported to user-space, or included by
232	      several files at different directories. Basically, the private
233	      header files should not be placed in this directory, but you may
234	      still find files there, due to historical reasons :) 
235	      </para>
236	    </section>
237	
238	    <section id="file-tree-drivers-directory">
239	      <title>drivers directory</title>
240	      <para>
241	        This directory contains code shared among different drivers
242	      on different architectures.  They are hence supposed not to be
243	      architecture-specific.
244	      For example, the dummy pcm driver and the serial MIDI
245	      driver are found in this directory. In the sub-directories,
246	      there is code for components which are independent from
247	      bus and cpu architectures. 
248	      </para>
249	
250	      <section id="file-tree-drivers-directory-mpu401">
251	        <title>drivers/mpu401</title>
252	        <para>
253	          The MPU401 and MPU401-UART modules are stored here.
254	        </para>
255	      </section>
256	
257	      <section id="file-tree-drivers-directory-opl3">
258	        <title>drivers/opl3 and opl4</title>
259	        <para>
260	          The OPL3 and OPL4 FM-synth stuff is found here.
261	        </para>
262	      </section>
263	    </section>
264	
265	    <section id="file-tree-i2c-directory">
266	      <title>i2c directory</title>
267	      <para>
268	        This contains the ALSA i2c components.
269	      </para>
270	
271	      <para>
272	        Although there is a standard i2c layer on Linux, ALSA has its
273	      own i2c code for some cards, because the soundcard needs only a
274	      simple operation and the standard i2c API is too complicated for
275	      such a purpose. 
276	      </para>
277	
278	      <section id="file-tree-i2c-directory-l3">
279	        <title>i2c/l3</title>
280	        <para>
281	          This is a sub-directory for ARM L3 i2c.
282	        </para>
283	      </section>
284	    </section>
285	
286	    <section id="file-tree-synth-directory">
287	        <title>synth directory</title>
288	        <para>
289	          This contains the synth middle-level modules.
290	        </para>
291	
292	        <para>
293	          So far, there is only Emu8000/Emu10k1 synth driver under
294	        the <filename>synth/emux</filename> sub-directory. 
295	        </para>
296	    </section>
297	
298	    <section id="file-tree-pci-directory">
299	      <title>pci directory</title>
300	      <para>
301	        This directory and its sub-directories hold the top-level card modules
302	      for PCI soundcards and the code specific to the PCI BUS.
303	      </para>
304	
305	      <para>
306	        The drivers compiled from a single file are stored directly
307	      in the pci directory, while the drivers with several source files are
308	      stored on their own sub-directory (e.g. emu10k1, ice1712). 
309	      </para>
310	    </section>
311	
312	    <section id="file-tree-isa-directory">
313	      <title>isa directory</title>
314	      <para>
315	        This directory and its sub-directories hold the top-level card modules
316	      for ISA soundcards. 
317	      </para>
318	    </section>
319	
320	    <section id="file-tree-arm-ppc-sparc-directories">
321	      <title>arm, ppc, and sparc directories</title>
322	      <para>
323	        They are used for top-level card modules which are
324	      specific to one of these architectures. 
325	      </para>
326	    </section>
327	
328	    <section id="file-tree-usb-directory">
329	      <title>usb directory</title>
330	      <para>
331	        This directory contains the USB-audio driver. In the latest version, the
332	      USB MIDI driver is integrated in the usb-audio driver. 
333	      </para>
334	    </section>
335	
336	    <section id="file-tree-pcmcia-directory">
337	      <title>pcmcia directory</title>
338	      <para>
339	        The PCMCIA, especially PCCard drivers will go here. CardBus
340	      drivers will be in the pci directory, because their API is identical
341	      to that of standard PCI cards. 
342	      </para>
343	    </section>
344	
345	    <section id="file-tree-oss-directory">
346	      <title>oss directory</title>
347	      <para>
348	        The OSS/Lite source files are stored here in Linux 2.6 (or
349	      later) tree. In the ALSA driver tarball, this directory is empty,
350	      of course :) 
351	      </para>
352	    </section>
353	  </chapter>
354	
355	
356	<!-- ****************************************************** -->
357	<!-- Basic Flow for PCI Drivers  -->
358	<!-- ****************************************************** -->
359	  <chapter id="basic-flow">
360	    <title>Basic Flow for PCI Drivers</title>
361	
362	    <section id="basic-flow-outline">
363	      <title>Outline</title>
364	      <para>
365	        The minimum flow for PCI soundcards is as follows:
366	
367	        <itemizedlist>
368	          <listitem><para>define the PCI ID table (see the section
369	          <link linkend="pci-resource-entries"><citetitle>PCI Entries
370	          </citetitle></link>).</para></listitem> 
371	          <listitem><para>create <function>probe()</function> callback.</para></listitem>
372	          <listitem><para>create <function>remove()</function> callback.</para></listitem>
373	          <listitem><para>create a <structname>pci_driver</structname> structure
374		  containing the three pointers above.</para></listitem>
375	          <listitem><para>create an <function>init()</function> function just calling
376		  the <function>pci_register_driver()</function> to register the pci_driver table
377		  defined above.</para></listitem>
378	          <listitem><para>create an <function>exit()</function> function to call
379		  the <function>pci_unregister_driver()</function> function.</para></listitem>
380	        </itemizedlist>
381	      </para>
382	    </section>
383	
384	    <section id="basic-flow-example">
385	      <title>Full Code Example</title>
386	      <para>
387	        The code example is shown below. Some parts are kept
388	      unimplemented at this moment but will be filled in the
389	      next sections. The numbers in the comment lines of the
390	      <function>snd_mychip_probe()</function> function
391	      refer to details explained in the following section. 
392	
393	        <example>
394	          <title>Basic Flow for PCI Drivers - Example</title>
395	          <programlisting>
396	<![CDATA[
397	  #include <linux/init.h>
398	  #include <linux/pci.h>
399	  #include <linux/slab.h>
400	  #include <sound/core.h>
401	  #include <sound/initval.h>
402	
403	  /* module parameters (see "Module Parameters") */
404	  /* SNDRV_CARDS: maximum number of cards supported by this module */
405	  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
406	  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
407	  static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
408	
409	  /* definition of the chip-specific record */
410	  struct mychip {
411	          struct snd_card *card;
412	          /* the rest of the implementation will be in section
413	           * "PCI Resource Management"
414	           */
415	  };
416	
417	  /* chip-specific destructor
418	   * (see "PCI Resource Management")
419	   */
420	  static int snd_mychip_free(struct mychip *chip)
421	  {
422	          .... /* will be implemented later... */
423	  }
424	
425	  /* component-destructor
426	   * (see "Management of Cards and Components")
427	   */
428	  static int snd_mychip_dev_free(struct snd_device *device)
429	  {
430	          return snd_mychip_free(device->device_data);
431	  }
432	
433	  /* chip-specific constructor
434	   * (see "Management of Cards and Components")
435	   */
436	  static int snd_mychip_create(struct snd_card *card,
437	                               struct pci_dev *pci,
438	                               struct mychip **rchip)
439	  {
440	          struct mychip *chip;
441	          int err;
442	          static struct snd_device_ops ops = {
443	                 .dev_free = snd_mychip_dev_free,
444	          };
445	
446	          *rchip = NULL;
447	
448	          /* check PCI availability here
449	           * (see "PCI Resource Management")
450	           */
451	          ....
452	
453	          /* allocate a chip-specific data with zero filled */
454	          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
455	          if (chip == NULL)
456	                  return -ENOMEM;
457	
458	          chip->card = card;
459	
460	          /* rest of initialization here; will be implemented
461	           * later, see "PCI Resource Management"
462	           */
463	          ....
464	
465	          err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
466	          if (err < 0) {
467	                  snd_mychip_free(chip);
468	                  return err;
469	          }
470	
471	          *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). This is important, because the
2746	        <structfield>trigger</structfield> callback 
2747	        is atomic (non-schedulable). That is, mutexes or any
2748	        schedule-related functions are not available in
2749	        <structfield>trigger</structfield> callback.
2750		Please see the subsection
2751		<link linkend="pcm-interface-atomicity"><citetitle>
2752		Atomicity</citetitle></link> for details.
2753	        </para>
2754	      </section>
2755	
2756	      <section id="pcm-interface-operators-hw-free-callback">
2757	        <title>hw_free callback</title>
2758	        <para>
2759	          <informalexample>
2760	            <programlisting>
2761	<![CDATA[
2762	  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2763	]]>
2764	            </programlisting>
2765	          </informalexample>
2766	        </para>
2767	
2768	        <para>
2769	          This is called to release the resources allocated via
2770	          <structfield>hw_params</structfield>. For example, releasing the
2771	          buffer via 
2772	          <function>snd_pcm_lib_malloc_pages()</function> is done by
2773	          calling the following: 
2774	
2775	          <informalexample>
2776	            <programlisting>
2777	<![CDATA[
2778	  snd_pcm_lib_free_pages(substream);
2779	]]>
2780	            </programlisting>
2781	          </informalexample>
2782	        </para>
2783	
2784	        <para>
2785	          This function is always called before the close callback is called.
2786	          Also, the callback may be called multiple times, too.
2787	          Keep track whether the resource was already released. 
2788	        </para>
2789	      </section>
2790	
2791	      <section id="pcm-interface-operators-prepare-callback">
2792	       <title>prepare callback</title>
2793	        <para>
2794	          <informalexample>
2795	            <programlisting>
2796	<![CDATA[
2797	  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2798	]]>
2799	            </programlisting>
2800	          </informalexample>
2801	        </para>
2802	
2803	        <para>
2804	          This callback is called when the pcm is
2805	        <quote>prepared</quote>. You can set the format type, sample
2806	        rate, etc. here. The difference from
2807	        <structfield>hw_params</structfield> is that the 
2808	        <structfield>prepare</structfield> callback will be called each
2809	        time 
2810	        <function>snd_pcm_prepare()</function> is called, i.e. when
2811	        recovering after underruns, etc. 
2812	        </para>
2813	
2814	        <para>
2815		Note that this callback is now non-atomic.
2816		You can use schedule-related functions safely in this callback.
2817	        </para>
2818	
2819	        <para>
2820	          In this and the following callbacks, you can refer to the
2821	        values via the runtime record,
2822	        substream-&gt;runtime.
2823	        For example, to get the current
2824	        rate, format or channels, access to
2825	        runtime-&gt;rate,
2826	        runtime-&gt;format or
2827	        runtime-&gt;channels, respectively. 
2828	        The physical address of the allocated buffer is set to
2829		runtime-&gt;dma_area.  The buffer and period sizes are
2830		in runtime-&gt;buffer_size and runtime-&gt;period_size,
2831		respectively.
2832	        </para>
2833	
2834	        <para>
2835	          Be careful that this callback will be called many times at
2836	        each setup, too. 
2837	        </para>
2838	      </section>
2839	
2840	      <section id="pcm-interface-operators-trigger-callback">
2841	        <title>trigger callback</title>
2842	        <para>
2843	          <informalexample>
2844	            <programlisting>
2845	<![CDATA[
2846	  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2847	]]>
2848	            </programlisting>
2849	          </informalexample>
2850	
2851	          This is called when the pcm is started, stopped or paused.
2852	        </para>
2853	
2854	        <para>
2855	          Which action is specified in the second argument,
2856	          <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2857	          <filename>&lt;sound/pcm.h&gt;</filename>. At least,
2858	          the <constant>START</constant> and <constant>STOP</constant>
2859	          commands must be defined in this callback. 
2860	
2861	          <informalexample>
2862	            <programlisting>
2863	<![CDATA[
2864	  switch (cmd) {
2865	  case SNDRV_PCM_TRIGGER_START:
2866	          /* do something to start the PCM engine */
2867	          break;
2868	  case SNDRV_PCM_TRIGGER_STOP:
2869	          /* do something to stop the PCM engine */
2870	          break;
2871	  default:
2872	          return -EINVAL;
2873	  }
2874	]]>
2875	            </programlisting>
2876	          </informalexample>
2877	        </para>
2878	
2879	        <para>
2880	          When the pcm supports the pause operation (given in the info
2881	        field of the hardware table), the <constant>PAUSE_PUSH</constant>
2882	        and <constant>PAUSE_RELEASE</constant> commands must be
2883	        handled here, too. The former is the command to pause the pcm,
2884	        and the latter to restart the pcm again. 
2885	        </para>
2886	
2887	        <para>
2888	          When the pcm supports the suspend/resume operation,
2889		regardless of full or partial suspend/resume support,
2890	        the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2891	        commands must be handled, too.
2892	        These commands are issued when the power-management status is
2893	        changed.  Obviously, the <constant>SUSPEND</constant> and
2894	        <constant>RESUME</constant> commands
2895	        suspend and resume the pcm substream, and usually, they
2896	        are identical to the <constant>STOP</constant> and
2897	        <constant>START</constant> commands, respectively.
2898		  See the <link linkend="power-management"><citetitle>
2899		Power Management</citetitle></link> section for details.
2900	        </para>
2901	
2902	        <para>
2903	          As mentioned, this callback is atomic.  You cannot call
2904		  functions which may sleep.
2905		  The trigger callback should be as minimal as possible,
2906		  just really triggering the DMA.  The other stuff should be
2907		  initialized hw_params and prepare callbacks properly
2908		  beforehand.
2909	        </para>
2910	      </section>
2911	
2912	      <section id="pcm-interface-operators-pointer-callback">
2913	        <title>pointer callback</title>
2914	        <para>
2915	          <informalexample>
2916	            <programlisting>
2917	<![CDATA[
2918	  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2919	]]>
2920	            </programlisting>
2921	          </informalexample>
2922	
2923	          This callback is called when the PCM middle layer inquires
2924	        the current hardware position on the buffer. The position must
2925	        be returned in frames,
2926	        ranging from 0 to buffer_size - 1.
2927	        </para>
2928	
2929	        <para>
2930	          This is called usually from the buffer-update routine in the
2931	        pcm middle layer, which is invoked when
2932	        <function>snd_pcm_period_elapsed()</function> is called in the
2933	        interrupt routine. Then the pcm middle layer updates the
2934	        position and calculates the available space, and wakes up the
2935	        sleeping poll threads, etc. 
2936	        </para>
2937	
2938	        <para>
2939	          This callback is also atomic.
2940	        </para>
2941	      </section>
2942	
2943	      <section id="pcm-interface-operators-copy-silence">
2944	        <title>copy and silence callbacks</title>
2945	        <para>
2946	          These callbacks are not mandatory, and can be omitted in
2947	        most cases. These callbacks are used when the hardware buffer
2948	        cannot be in the normal memory space. Some chips have their
2949	        own buffer on the hardware which is not mappable. In such a
2950	        case, you have to transfer the data manually from the memory
2951	        buffer to the hardware buffer. Or, if the buffer is
2952	        non-contiguous on both physical and virtual memory spaces,
2953	        these callbacks must be defined, too. 
2954	        </para>
2955	
2956	        <para>
2957	          If these two callbacks are defined, copy and set-silence
2958	        operations are done by them. The detailed will be described in
2959	        the later section <link
2960	        linkend="buffer-and-memory"><citetitle>Buffer and Memory
2961	        Management</citetitle></link>. 
2962	        </para>
2963	      </section>
2964	
2965	      <section id="pcm-interface-operators-ack">
2966	        <title>ack callback</title>
2967	        <para>
2968	          This callback is also not mandatory. This callback is called
2969	        when the appl_ptr is updated in read or write operations.
2970	        Some drivers like emu10k1-fx and cs46xx need to track the
2971		current appl_ptr for the internal buffer, and this callback
2972		is useful only for such a purpose.
2973		</para>
2974		<para>
2975		  This callback is atomic.
2976		</para>
2977	      </section>
2978	
2979	      <section id="pcm-interface-operators-page-callback">
2980	        <title>page callback</title>
2981	
2982	        <para>
2983	          This callback is optional too. This callback is used
2984	        mainly for non-contiguous buffers. The mmap calls this
2985	        callback to get the page address. Some examples will be
2986	        explained in the later section <link
2987	        linkend="buffer-and-memory"><citetitle>Buffer and Memory
2988	        Management</citetitle></link>, too. 
2989	        </para>
2990	      </section>
2991	    </section>
2992	
2993	    <section id="pcm-interface-interrupt-handler">
2994	      <title>Interrupt Handler</title>
2995	      <para>
2996	        The rest of pcm stuff is the PCM interrupt handler. The
2997	      role of PCM interrupt handler in the sound driver is to update
2998	      the buffer position and to tell the PCM middle layer when the
2999	      buffer position goes across the prescribed period size. To
3000	      inform this, call the <function>snd_pcm_period_elapsed()</function>
3001	      function. 
3002	      </para>
3003	
3004	      <para>
3005	        There are several types of sound chips to generate the interrupts.
3006	      </para>
3007	
3008	      <section id="pcm-interface-interrupt-handler-boundary">
3009	        <title>Interrupts at the period (fragment) boundary</title>
3010	        <para>
3011	          This is the most frequently found type:  the hardware
3012	        generates an interrupt at each period boundary.
3013		In this case, you can call
3014	        <function>snd_pcm_period_elapsed()</function> at each 
3015	        interrupt. 
3016	        </para>
3017	
3018	        <para>
3019	          <function>snd_pcm_period_elapsed()</function> takes the
3020	        substream pointer as its argument. Thus, you need to keep the
3021	        substream pointer accessible from the chip instance. For
3022	        example, define substream field in the chip record to hold the
3023	        current running substream pointer, and set the pointer value
3024	        at open callback (and reset at close callback). 
3025	        </para>
3026	
3027	        <para>
3028	          If you acquire a spinlock in the interrupt handler, and the
3029	        lock is used in other pcm callbacks, too, then you have to
3030	        release the lock before calling
3031	        <function>snd_pcm_period_elapsed()</function>, because
3032	        <function>snd_pcm_period_elapsed()</function> calls other pcm
3033	        callbacks inside. 
3034	        </para>
3035	
3036	        <para>
3037	          Typical code would be like:
3038	
3039	          <example>
3040		    <title>Interrupt Handler Case #1</title>
3041	            <programlisting>
3042	<![CDATA[
3043	  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3044	  {
3045	          struct mychip *chip = dev_id;
3046	          spin_lock(&chip->lock);
3047	          ....
3048	          if (pcm_irq_invoked(chip)) {
3049	                  /* call updater, unlock before it */
3050	                  spin_unlock(&chip->lock);
3051	                  snd_pcm_period_elapsed(chip->substream);
3052	                  spin_lock(&chip->lock);
3053	                  /* acknowledge the interrupt if necessary */
3054	          }
3055	          ....
3056	          spin_unlock(&chip->lock);
3057	          return IRQ_HANDLED;
3058	  }
3059	]]>
3060	            </programlisting>
3061	          </example>
3062	        </para>
3063	      </section>
3064	
3065	      <section id="pcm-interface-interrupt-handler-timer">
3066	        <title>High frequency timer interrupts</title>
3067	        <para>
3068		This happens when the hardware doesn't generate interrupts
3069	        at the period boundary but issues timer interrupts at a fixed
3070	        timer rate (e.g. es1968 or ymfpci drivers). 
3071	        In this case, you need to check the current hardware
3072	        position and accumulate the processed sample length at each
3073	        interrupt.  When the accumulated size exceeds the period
3074	        size, call 
3075	        <function>snd_pcm_period_elapsed()</function> and reset the
3076	        accumulator. 
3077	        </para>
3078	
3079	        <para>
3080	          Typical code would be like the following.
3081	
3082	          <example>
3083		    <title>Interrupt Handler Case #2</title>
3084	            <programlisting>
3085	<![CDATA[
3086	  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3087	  {
3088	          struct mychip *chip = dev_id;
3089	          spin_lock(&chip->lock);
3090	          ....
3091	          if (pcm_irq_invoked(chip)) {
3092	                  unsigned int last_ptr, size;
3093	                  /* get the current hardware pointer (in frames) */
3094	                  last_ptr = get_hw_ptr(chip);
3095	                  /* calculate the processed frames since the
3096	                   * last update
3097	                   */
3098	                  if (last_ptr < chip->last_ptr)
3099	                          size = runtime->buffer_size + last_ptr 
3100	                                   - chip->last_ptr; 
3101	                  else
3102	                          size = last_ptr - chip->last_ptr;
3103	                  /* remember the last updated point */
3104	                  chip->last_ptr = last_ptr;
3105	                  /* accumulate the size */
3106	                  chip->size += size;
3107	                  /* over the period boundary? */
3108	                  if (chip->size >= runtime->period_size) {
3109	                          /* reset the accumulator */
3110	                          chip->size %= runtime->period_size;
3111	                          /* call updater */
3112	                          spin_unlock(&chip->lock);
3113	                          snd_pcm_period_elapsed(substream);
3114	                          spin_lock(&chip->lock);
3115	                  }
3116	                  /* acknowledge the interrupt if necessary */
3117	          }
3118	          ....
3119	          spin_unlock(&chip->lock);
3120	          return IRQ_HANDLED;
3121	  }
3122	]]>
3123	            </programlisting>
3124	          </example>
3125	        </para>
3126	      </section>
3127	
3128	      <section id="pcm-interface-interrupt-handler-both">
3129	        <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3130	        <para>
3131	          In both cases, even if more than one period are elapsed, you
3132	        don't have to call
3133	        <function>snd_pcm_period_elapsed()</function> many times. Call
3134	        only once. And the pcm layer will check the current hardware
3135	        pointer and update to the latest status. 
3136	        </para>
3137	      </section>
3138	    </section>
3139	
3140	    <section id="pcm-interface-atomicity">
3141	      <title>Atomicity</title>
3142	      <para>
3143	      One of the most important (and thus difficult to debug) problems
3144	      in kernel programming are race conditions.
3145	      In the Linux kernel, they are usually avoided via spin-locks, mutexes
3146	      or semaphores.  In general, if a race condition can happen
3147	      in an interrupt handler, it has to be managed atomically, and you
3148	      have to use a spinlock to protect the critical session. If the
3149	      critical section is not in interrupt handler code and
3150	      if taking a relatively long time to execute is acceptable, you
3151	      should use mutexes or semaphores instead.
3152	      </para>
3153	
3154	      <para>
3155	      As already seen, some pcm callbacks are atomic and some are
3156	      not.  For example, the <parameter>hw_params</parameter> callback is
3157	      non-atomic, while <parameter>trigger</parameter> callback is
3158	      atomic.  This means, the latter is called already in a spinlock
3159	      held by the PCM middle layer. Please take this atomicity into
3160	      account when you choose a locking scheme in the callbacks.
3161	      </para>
3162	
3163	      <para>
3164	      In the atomic callbacks, you cannot use functions which may call
3165	      <function>schedule</function> or go to
3166	      <function>sleep</function>.  Semaphores and mutexes can sleep,
3167	      and hence they cannot be used inside the atomic callbacks
3168	      (e.g. <parameter>trigger</parameter> callback).
3169	      To implement some delay in such a callback, please use
3170	      <function>udelay()</function> or <function>mdelay()</function>.
3171	      </para>
3172	
3173	      <para>
3174	      All three atomic callbacks (trigger, pointer, and ack) are
3175	      called with local interrupts disabled.
3176	      </para>
3177	
3178	    </section>
3179	    <section id="pcm-interface-constraints">
3180	      <title>Constraints</title>
3181	      <para>
3182	        If your chip supports unconventional sample rates, or only the
3183	      limited samples, you need to set a constraint for the
3184	      condition. 
3185	      </para>
3186	
3187	      <para>
3188	        For example, in order to restrict the sample rates in the some
3189	        supported values, use
3190		<function>snd_pcm_hw_constraint_list()</function>.
3191		You need to call this function in the open callback.
3192	
3193	        <example>
3194		  <title>Example of Hardware Constraints</title>
3195	          <programlisting>
3196	<![CDATA[
3197	  static unsigned int rates[] =
3198	          {4000, 10000, 22050, 44100};
3199	  static struct snd_pcm_hw_constraint_list constraints_rates = {
3200	          .count = ARRAY_SIZE(rates),
3201	          .list = rates,
3202	          .mask = 0,
3203	  };
3204	
3205	  static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3206	  {
3207	          int err;
3208	          ....
3209	          err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3210	                                           SNDRV_PCM_HW_PARAM_RATE,
3211	                                           &constraints_rates);
3212	          if (err < 0)
3213	                  return err;
3214	          ....
3215	  }
3216	]]>
3217	          </programlisting>
3218	        </example>
3219	      </para>
3220	
3221	      <para>
3222	        There are many different constraints.
3223	        Look at <filename>sound/pcm.h</filename> for a complete list.
3224	        You can even define your own constraint rules.
3225	        For example, let's suppose my_chip can manage a substream of 1 channel
3226	        if and only if the format is S16_LE, otherwise it supports any format
3227	        specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3228	        other constraint_list). You can build a rule like this:
3229	
3230	        <example>
3231		  <title>Example of Hardware Constraints for Channels</title>
3232		  <programlisting>
3233	<![CDATA[
3234	  static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3235	                                        struct snd_pcm_hw_rule *rule)
3236	  {
3237	          struct snd_interval *c = hw_param_interval(params,
3238	                        SNDRV_PCM_HW_PARAM_CHANNELS);
3239	          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3240	          struct snd_interval ch;
3241	
3242	          snd_interval_any(&ch);
3243	          if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3244	                  ch.min = ch.max = 1;
3245	                  ch.integer = 1;
3246	                  return snd_interval_refine(c, &ch);
3247	          }
3248	          return 0;
3249	  }
3250	]]>
3251	          </programlisting>
3252	        </example>
3253	      </para>
3254	 
3255	      <para>
3256	        Then you need to call this function to add your rule:
3257	
3258	       <informalexample>
3259		 <programlisting>
3260	<![CDATA[
3261	  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3262	                      hw_rule_channels_by_format, NULL,
3263	                      SNDRV_PCM_HW_PARAM_FORMAT, -1);
3264	]]>
3265	          </programlisting>
3266	        </informalexample>
3267	      </para>
3268	
3269	      <para>
3270	        The rule function is called when an application sets the PCM
3271		format, and it refines the number of channels accordingly.
3272	        But an application may set the number of channels before
3273		setting the format. Thus you also need to define the inverse rule:
3274	
3275	       <example>
3276		 <title>Example of Hardware Constraints for Formats</title>
3277		 <programlisting>
3278	<![CDATA[
3279	  static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3280	                                        struct snd_pcm_hw_rule *rule)
3281	  {
3282	          struct snd_interval *c = hw_param_interval(params,
3283	                SNDRV_PCM_HW_PARAM_CHANNELS);
3284	          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3285	          struct snd_mask fmt;
3286	
3287	          snd_mask_any(&fmt);    /* Init the struct */
3288	          if (c->min < 2) {
3289	                  fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3290	                  return snd_mask_refine(f, &fmt);
3291	          }
3292	          return 0;
3293	  }
3294	]]>
3295	          </programlisting>
3296	        </example>
3297	      </para>
3298	
3299	      <para>
3300	      ...and in the open callback:
3301	       <informalexample>
3302		 <programlisting>
3303	<![CDATA[
3304	  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3305	                      hw_rule_format_by_channels, NULL,
3306	                      SNDRV_PCM_HW_PARAM_CHANNELS, -1);
3307	]]>
3308	          </programlisting>
3309	        </informalexample>
3310	      </para>
3311	
3312	      <para>
3313	        I won't give more details here, rather I
3314	        would like to say, <quote>Luke, use the source.</quote>
3315	      </para>
3316	    </section>
3317	
3318	  </chapter>
3319	
3320	
3321	<!-- ****************************************************** -->
3322	<!-- Control Interface  -->
3323	<!-- ****************************************************** -->
3324	  <chapter id="control-interface">
3325	    <title>Control Interface</title>
3326	
3327	    <section id="control-interface-general">
3328	      <title>General</title>
3329	      <para>
3330	        The control interface is used widely for many switches,
3331	      sliders, etc. which are accessed from user-space. Its most
3332	      important use is the mixer interface. In other words, since ALSA
3333	      0.9.x, all the mixer stuff is implemented on the control kernel API.
3334	      </para>
3335	
3336	      <para>
3337	        ALSA has a well-defined AC97 control module. If your chip
3338	      supports only the AC97 and nothing else, you can skip this
3339	      section. 
3340	      </para>
3341	
3342	      <para>
3343	        The control API is defined in
3344	      <filename>&lt;sound/control.h&gt;</filename>.
3345	      Include this file if you want to add your own controls.
3346	      </para>
3347	    </section>
3348	
3349	    <section id="control-interface-definition">
3350	      <title>Definition of Controls</title>
3351	      <para>
3352	        To create a new control, you need to define the
3353		following three
3354	      callbacks: <structfield>info</structfield>,
3355	      <structfield>get</structfield> and
3356	      <structfield>put</structfield>. Then, define a
3357	      struct <structname>snd_kcontrol_new</structname> record, such as: 
3358	
3359	        <example>
3360		  <title>Definition of a Control</title>
3361	          <programlisting>
3362	<![CDATA[
3363	  static struct snd_kcontrol_new my_control = {
3364	          .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3365	          .name = "PCM Playback Switch",
3366	          .index = 0,
3367	          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3368	          .private_value = 0xffff,
3369	          .info = my_control_info,
3370	          .get = my_control_get,
3371	          .put = my_control_put
3372	  };
3373	]]>
3374	          </programlisting>
3375	        </example>
3376	      </para>
3377	
3378	      <para>
3379	        The <structfield>iface</structfield> field specifies the control
3380	      type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3381	      is usually <constant>MIXER</constant>.
3382	      Use <constant>CARD</constant> for global controls that are not
3383	      logically part of the mixer.
3384	      If the control is closely associated with some specific device on
3385	      the sound card, use <constant>HWDEP</constant>,
3386	      <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3387	      <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3388	      specify the device number with the
3389	      <structfield>device</structfield> and
3390	      <structfield>subdevice</structfield> fields.
3391	      </para>
3392	
3393	      <para>
3394	        The <structfield>name</structfield> is the name identifier
3395	      string. Since ALSA 0.9.x, the control name is very important,
3396	      because its role is classified from its name. There are
3397	      pre-defined standard control names. The details are described in
3398	      the <link linkend="control-interface-control-names"><citetitle>
3399	      Control Names</citetitle></link> subsection.
3400	      </para>
3401	
3402	      <para>
3403	        The <structfield>index</structfield> field holds the index number
3404	      of this control. If there are several different controls with
3405	      the same name, they can be distinguished by the index
3406	      number. This is the case when 
3407	      several codecs exist on the card. If the index is zero, you can
3408	      omit the definition above. 
3409	      </para>
3410	
3411	      <para>
3412	        The <structfield>access</structfield> field contains the access
3413	      type of this control. Give the combination of bit masks,
3414	      <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3415	      The details will be explained in
3416	      the <link linkend="control-interface-access-flags"><citetitle>
3417	      Access Flags</citetitle></link> subsection.
3418	      </para>
3419	
3420	      <para>
3421	        The <structfield>private_value</structfield> field contains
3422	      an arbitrary long integer value for this record. When using
3423	      the generic <structfield>info</structfield>,
3424	      <structfield>get</structfield> and
3425	      <structfield>put</structfield> callbacks, you can pass a value 
3426	      through this field. If several small numbers are necessary, you can
3427	      combine them in bitwise. Or, it's possible to give a pointer
3428	      (casted to unsigned long) of some record to this field, too. 
3429	      </para>
3430	
3431	      <para>
3432	      The <structfield>tlv</structfield> field can be used to provide
3433	      metadata about the control; see the
3434	      <link linkend="control-interface-tlv">
3435	      <citetitle>Metadata</citetitle></link> subsection.
3436	      </para>
3437	
3438	      <para>
3439	        The other three are
3440		<link linkend="control-interface-callbacks"><citetitle>
3441		callback functions</citetitle></link>.
3442	      </para>
3443	    </section>
3444	
3445	    <section id="control-interface-control-names">
3446	      <title>Control Names</title>
3447	      <para>
3448	        There are some standards to define the control names. A
3449	      control is usually defined from the three parts as
3450	      <quote>SOURCE DIRECTION FUNCTION</quote>. 
3451	      </para>
3452	
3453	      <para>
3454	        The first, <constant>SOURCE</constant>, specifies the source
3455	      of the control, and is a string such as <quote>Master</quote>,
3456	      <quote>PCM</quote>, <quote>CD</quote> and
3457	      <quote>Line</quote>. There are many pre-defined sources. 
3458	      </para>
3459	
3460	      <para>
3461	        The second, <constant>DIRECTION</constant>, is one of the
3462	      following strings according to the direction of the control:
3463	      <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3464	      Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3465	      be omitted, meaning both playback and capture directions. 
3466	      </para>
3467	
3468	      <para>
3469	        The third, <constant>FUNCTION</constant>, is one of the
3470	      following strings according to the function of the control:
3471	      <quote>Switch</quote>, <quote>Volume</quote> and
3472	      <quote>Route</quote>. 
3473	      </para>
3474	
3475	      <para>
3476	        The example of control names are, thus, <quote>Master Capture
3477	      Switch</quote> or <quote>PCM Playback Volume</quote>. 
3478	      </para>
3479	
3480	      <para>
3481	        There are some exceptions:
3482	      </para>
3483	
3484	      <section id="control-interface-control-names-global">
3485	        <title>Global capture and playback</title>
3486	        <para>
3487	          <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3488	        and <quote>Capture Volume</quote> are used for the global
3489	        capture (input) source, switch and volume. Similarly,
3490	        <quote>Playback Switch</quote> and <quote>Playback
3491	        Volume</quote> are used for the global output gain switch and
3492	        volume. 
3493	        </para>
3494	      </section>
3495	
3496	      <section id="control-interface-control-names-tone">
3497	        <title>Tone-controls</title>
3498	        <para>
3499	          tone-control switch and volumes are specified like
3500	        <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3501	        Switch</quote>, <quote>Tone Control - Bass</quote>,
3502	        <quote>Tone Control - Center</quote>.  
3503	        </para>
3504	      </section>
3505	
3506	      <section id="control-interface-control-names-3d">
3507	        <title>3D controls</title>
3508	        <para>
3509	          3D-control switches and volumes are specified like <quote>3D
3510	        Control - XXX</quote>, e.g. <quote>3D Control -
3511	        Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3512	        Control - Space</quote>. 
3513	        </para>
3514	      </section>
3515	
3516	      <section id="control-interface-control-names-mic">
3517	        <title>Mic boost</title>
3518	        <para>
3519	          Mic-boost switch is set as <quote>Mic Boost</quote> or
3520	        <quote>Mic Boost (6dB)</quote>. 
3521	        </para>
3522	
3523	        <para>
3524	          More precise information can be found in
3525	        <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3526	        </para>
3527	      </section>
3528	    </section>
3529	
3530	    <section id="control-interface-access-flags">
3531	      <title>Access Flags</title>
3532	
3533	      <para>
3534	      The access flag is the bitmask which specifies the access type
3535	      of the given control.  The default access type is
3536	      <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 
3537	      which means both read and write are allowed to this control.
3538	      When the access flag is omitted (i.e. = 0), it is
3539	      considered as <constant>READWRITE</constant> access as default. 
3540	      </para>
3541	
3542	      <para>
3543	      When the control is read-only, pass
3544	      <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3545	      In this case, you don't have to define
3546	      the <structfield>put</structfield> callback.
3547	      Similarly, when the control is write-only (although it's a rare
3548	      case), you can use the <constant>WRITE</constant> flag instead, and
3549	      you don't need the <structfield>get</structfield> callback.
3550	      </para>
3551	
3552	      <para>
3553	      If the control value changes frequently (e.g. the VU meter),
3554	      <constant>VOLATILE</constant> flag should be given.  This means
3555	      that the control may be changed without
3556	      <link linkend="control-interface-change-notification"><citetitle>
3557	      notification</citetitle></link>. Applications should poll such
3558	      a control constantly.
3559	      </para>
3560	
3561	      <para>
3562	      When the control is inactive, set
3563	      the <constant>INACTIVE</constant> flag, too.
3564	      There are <constant>LOCK</constant> and
3565	      <constant>OWNER</constant> flags to change the write
3566	      permissions.
3567	      </para>
3568	
3569	    </section>
3570	
3571	    <section id="control-interface-callbacks">
3572	      <title>Callbacks</title>
3573	
3574	      <section id="control-interface-callbacks-info">
3575	        <title>info callback</title>
3576	        <para>
3577	          The <structfield>info</structfield> callback is used to get
3578	        detailed information on this control. This must store the
3579	        values of the given struct <structname>snd_ctl_elem_info</structname>
3580	        object. For example, for a boolean control with a single
3581	        element: 
3582	
3583	          <example>
3584		    <title>Example of info callback</title>
3585	            <programlisting>
3586	<![CDATA[
3587	  static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3588	                          struct snd_ctl_elem_info *uinfo)
3589	  {
3590	          uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3591	          uinfo->count = 1;
3592	          uinfo->value.integer.min = 0;
3593	          uinfo->value.integer.max = 1;
3594	          return 0;
3595	  }
3596	]]>
3597	            </programlisting>
3598	          </example>
3599	        </para>
3600	
3601	        <para>
3602	          The <structfield>type</structfield> field specifies the type
3603	        of the control. There are <constant>BOOLEAN</constant>,
3604	        <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3605	        <constant>BYTES</constant>, <constant>IEC958</constant> and
3606	        <constant>INTEGER64</constant>. The
3607	        <structfield>count</structfield> field specifies the 
3608	        number of elements in this control. For example, a stereo
3609	        volume would have count = 2. The
3610	        <structfield>value</structfield> field is a union, and 
3611	        the values stored are depending on the type. The boolean and
3612	        integer types are identical. 
3613	        </para>
3614	
3615	        <para>
3616	          The enumerated type is a bit different from others.  You'll
3617	          need to set the string for the currently given item index. 
3618	
3619	          <informalexample>
3620	            <programlisting>
3621	<![CDATA[
3622	  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3623	                          struct snd_ctl_elem_info *uinfo)
3624	  {
3625	          static char *texts[4] = {
3626	                  "First", "Second", "Third", "Fourth"
3627	          };
3628	          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3629	          uinfo->count = 1;
3630	          uinfo->value.enumerated.items = 4;
3631	          if (uinfo->value.enumerated.item > 3)
3632	                  uinfo->value.enumerated.item = 3;
3633	          strcpy(uinfo->value.enumerated.name,
3634	                 texts[uinfo->value.enumerated.item]);
3635	          return 0;
3636	  }
3637	]]>
3638	            </programlisting>
3639	          </informalexample>
3640	        </para>
3641	
3642	        <para>
3643		  Some common info callbacks are available for your convenience:
3644		<function>snd_ctl_boolean_mono_info()</function> and
3645		<function>snd_ctl_boolean_stereo_info()</function>.
3646		Obviously, the former is an info callback for a mono channel
3647		boolean item, just like <function>snd_myctl_mono_info</function>
3648		above, and the latter is for a stereo channel boolean item.
3649		</para>
3650	
3651	      </section>
3652	
3653	      <section id="control-interface-callbacks-get">
3654	        <title>get callback</title>
3655	
3656	        <para>
3657	          This callback is used to read the current value of the
3658	        control and to return to user-space. 
3659	        </para>
3660	
3661	        <para>
3662	          For example,
3663	
3664	          <example>
3665		    <title>Example of get callback</title>
3666	            <programlisting>
3667	<![CDATA[
3668	  static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3669	                           struct snd_ctl_elem_value *ucontrol)
3670	  {
3671	          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3672	          ucontrol->value.integer.value[0] = get_some_value(chip);
3673	          return 0;
3674	  }
3675	]]>
3676	            </programlisting>
3677	          </example>
3678	        </para>
3679	
3680	        <para>
3681		The <structfield>value</structfield> field depends on 
3682	        the type of control as well as on the info callback.  For example,
3683		the sb driver uses this field to store the register offset,
3684	        the bit-shift and the bit-mask.  The
3685	        <structfield>private_value</structfield> field is set as follows:
3686	          <informalexample>
3687	            <programlisting>
3688	<![CDATA[
3689	  .private_value = reg | (shift << 16) | (mask << 24)
3690	]]>
3691	            </programlisting>
3692	          </informalexample>
3693		and is retrieved in callbacks like
3694	          <informalexample>
3695	            <programlisting>
3696	<![CDATA[
3697	  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3698	                                    struct snd_ctl_elem_value *ucontrol)
3699	  {
3700	          int reg = kcontrol->private_value & 0xff;
3701	          int shift = (kcontrol->private_value >> 16) & 0xff;
3702	          int mask = (kcontrol->private_value >> 24) & 0xff;
3703	          ....
3704	  }
3705	]]>
3706	            </programlisting>
3707	          </informalexample>
3708		</para>
3709	
3710		<para>
3711		In the <structfield>get</structfield> callback,
3712		you have to fill all the elements if the
3713	        control has more than one elements,
3714	        i.e. <structfield>count</structfield> &gt; 1.
3715		In the example above, we filled only one element
3716	        (<structfield>value.integer.value[0]</structfield>) since it's
3717	        assumed as <structfield>count</structfield> = 1.
3718	        </para>
3719	      </section>
3720	
3721	      <section id="control-interface-callbacks-put">
3722	        <title>put callback</title>
3723	
3724	        <para>
3725	          This callback is used to write a value from user-space.
3726	        </para>
3727	
3728	        <para>
3729	          For example,
3730	
3731	          <example>
3732		    <title>Example of put callback</title>
3733	            <programlisting>
3734	<![CDATA[
3735	  static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3736	                           struct snd_ctl_elem_value *ucontrol)
3737	  {
3738	          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3739	          int changed = 0;
3740	          if (chip->current_value !=
3741	               ucontrol->value.integer.value[0]) {
3742	                  change_current_value(chip,
3743	                              ucontrol->value.integer.value[0]);
3744	                  changed = 1;
3745	          }
3746	          return changed;
3747	  }
3748	]]>
3749	            </programlisting>
3750	          </example>
3751	
3752	          As seen above, you have to return 1 if the value is
3753	        changed. If the value is not changed, return 0 instead. 
3754		If any fatal error happens, return a negative error code as
3755	        usual.
3756	        </para>
3757	
3758	        <para>
3759		As in the <structfield>get</structfield> callback,
3760		when the control has more than one elements,
3761		all elements must be evaluated in this callback, too.
3762	        </para>
3763	      </section>
3764	
3765	      <section id="control-interface-callbacks-all">
3766	        <title>Callbacks are not atomic</title>
3767	        <para>
3768	          All these three callbacks are basically not atomic.
3769	        </para>
3770	      </section>
3771	    </section>
3772	
3773	    <section id="control-interface-constructor">
3774	      <title>Constructor</title>
3775	      <para>
3776	        When everything is ready, finally we can create a new
3777	      control. To create a control, there are two functions to be
3778	      called, <function>snd_ctl_new1()</function> and
3779	      <function>snd_ctl_add()</function>. 
3780	      </para>
3781	
3782	      <para>
3783	        In the simplest way, you can do like this:
3784	
3785	        <informalexample>
3786	          <programlisting>
3787	<![CDATA[
3788	  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3789	  if (err < 0)
3790	          return err;
3791	]]>
3792	          </programlisting>
3793	        </informalexample>
3794	
3795	        where <parameter>my_control</parameter> is the
3796	      struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3797	      is the object pointer to be passed to
3798	      kcontrol-&gt;private_data 
3799	      which can be referred to in callbacks. 
3800	      </para>
3801	
3802	      <para>
3803	        <function>snd_ctl_new1()</function> allocates a new
3804	      <structname>snd_kcontrol</structname> instance,
3805	      and <function>snd_ctl_add</function> assigns the given
3806	      control component to the card. 
3807	      </para>
3808	    </section>
3809	
3810	    <section id="control-interface-change-notification">
3811	      <title>Change Notification</title>
3812	      <para>
3813	        If you need to change and update a control in the interrupt
3814	      routine, you can call <function>snd_ctl_notify()</function>. For
3815	      example, 
3816	
3817	        <informalexample>
3818	          <programlisting>
3819	<![CDATA[
3820	  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3821	]]>
3822	          </programlisting>
3823	        </informalexample>
3824	
3825	        This function takes the card pointer, the event-mask, and the
3826	      control id pointer for the notification. The event-mask
3827	      specifies the types of notification, for example, in the above
3828	      example, the change of control values is notified.
3829	      The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3830	      to be notified.
3831	      You can find some examples in <filename>es1938.c</filename> or
3832	      <filename>es1968.c</filename> for hardware volume interrupts. 
3833	      </para>
3834	    </section>
3835	
3836	    <section id="control-interface-tlv">
3837	      <title>Metadata</title>
3838	      <para>
3839	      To provide information about the dB values of a mixer control, use
3840	      on of the <constant>DECLARE_TLV_xxx</constant> macros from
3841	      <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3842	      containing this information, set the<structfield>tlv.p
3843	      </structfield> field to point to this variable, and include the
3844	      <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3845	      <structfield>access</structfield> field; like this:
3846	      <informalexample>
3847	        <programlisting>
3848	<![CDATA[
3849	  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3850	
3851	  static struct snd_kcontrol_new my_control = {
3852	          ...
3853	          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3854	                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3855	          ...
3856	          .tlv.p = db_scale_my_control,
3857	  };
3858	]]>
3859	        </programlisting>
3860	      </informalexample>
3861	      </para>
3862	
3863	      <para>
3864	      The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3865	      information about a mixer control where each step in the control's
3866	      value changes the dB value by a constant dB amount.
3867	      The first parameter is the name of the variable to be defined.
3868	      The second parameter is the minimum value, in units of 0.01 dB.
3869	      The third parameter is the step size, in units of 0.01 dB.
3870	      Set the fourth parameter to 1 if the minimum value actually mutes
3871	      the control.
3872	      </para>
3873	
3874	      <para>
3875	      The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3876	      information about a mixer control where the control's value affects
3877	      the output linearly.
3878	      The first parameter is the name of the variable to be defined.
3879	      The second parameter is the minimum value, in units of 0.01 dB.
3880	      The third parameter is the maximum value, in units of 0.01 dB.
3881	      If the minimum value mutes the control, set the second parameter to
3882	      <constant>TLV_DB_GAIN_MUTE</constant>.
3883	      </para>
3884	    </section>
3885	
3886	  </chapter>
3887	
3888	
3889	<!-- ****************************************************** -->
3890	<!-- API for AC97 Codec  -->
3891	<!-- ****************************************************** -->
3892	  <chapter id="api-ac97">
3893	    <title>API for AC97 Codec</title>
3894	
3895	    <section>
3896	      <title>General</title>
3897	      <para>
3898	        The ALSA AC97 codec layer is a well-defined one, and you don't
3899	      have to write much code to control it. Only low-level control
3900	      routines are necessary. The AC97 codec API is defined in
3901	      <filename>&lt;sound/ac97_codec.h&gt;</filename>. 
3902	      </para>
3903	    </section>
3904	
3905	    <section id="api-ac97-example">
3906	      <title>Full Code Example</title>
3907	      <para>
3908	          <example>
3909		    <title>Example of AC97 Interface</title>
3910	            <programlisting>
3911	<![CDATA[
3912	  struct mychip {
3913	          ....
3914	          struct snd_ac97 *ac97;
3915	          ....
3916	  };
3917	
3918	  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3919	                                             unsigned short reg)
3920	  {
3921	          struct mychip *chip = ac97->private_data;
3922	          ....
3923	          /* read a register value here from the codec */
3924	          return the_register_value;
3925	  }
3926	
3927	  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3928	                                   unsigned short reg, unsigned short val)
3929	  {
3930	          struct mychip *chip = ac97->private_data;
3931	          ....
3932	          /* write the given register value to the codec */
3933	  }
3934	
3935	  static int snd_mychip_ac97(struct mychip *chip)
3936	  {
3937	          struct snd_ac97_bus *bus;
3938	          struct snd_ac97_template ac97;
3939	          int err;
3940	          static struct snd_ac97_bus_ops ops = {
3941	                  .write = snd_mychip_ac97_write,
3942	                  .read = snd_mychip_ac97_read,
3943	          };
3944	
3945	          err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3946	          if (err < 0)
3947	                  return err;
3948	          memset(&ac97, 0, sizeof(ac97));
3949	          ac97.private_data = chip;
3950	          return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3951	  }
3952	
3953	]]>
3954	          </programlisting>
3955	        </example>
3956	      </para>
3957	    </section>
3958	
3959	    <section id="api-ac97-constructor">
3960	      <title>Constructor</title>
3961	      <para>
3962	        To create an ac97 instance, first call <function>snd_ac97_bus</function>
3963	      with an <type>ac97_bus_ops_t</type> record with callback functions.
3964	
3965	        <informalexample>
3966	          <programlisting>
3967	<![CDATA[
3968	  struct snd_ac97_bus *bus;
3969	  static struct snd_ac97_bus_ops ops = {
3970	        .write = snd_mychip_ac97_write,
3971	        .read = snd_mychip_ac97_read,
3972	  };
3973	
3974	  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
3975	]]>
3976	          </programlisting>
3977	        </informalexample>
3978	
3979	      The bus record is shared among all belonging ac97 instances.
3980	      </para>
3981	
3982	      <para>
3983	      And then call <function>snd_ac97_mixer()</function> with an
3984	      struct <structname>snd_ac97_template</structname>
3985	      record together with the bus pointer created above.
3986	
3987	        <informalexample>
3988	          <programlisting>
3989	<![CDATA[
3990	  struct snd_ac97_template ac97;
3991	  int err;
3992	
3993	  memset(&ac97, 0, sizeof(ac97));
3994	  ac97.private_data = chip;
3995	  snd_ac97_mixer(bus, &ac97, &chip->ac97);
3996	]]>
3997	          </programlisting>
3998	        </informalexample>
3999	
4000	        where chip-&gt;ac97 is a pointer to a newly created
4001	        <type>ac97_t</type> instance.
4002	        In this case, the chip pointer is set as the private data, so that
4003	        the read/write callback functions can refer to this chip instance.
4004	        This instance is not necessarily stored in the chip
4005		record.  If you need to change the register values from the
4006	        driver, or need the suspend/resume of ac97 codecs, keep this
4007	        pointer to pass to the corresponding functions.
4008	      </para>
4009	    </section>
4010	
4011	    <section id="api-ac97-callbacks">
4012	      <title>Callbacks</title>
4013	      <para>
4014	        The standard callbacks are <structfield>read</structfield> and
4015	      <structfield>write</structfield>. Obviously they 
4016	      correspond to the functions for read and write accesses to the
4017	      hardware low-level codes. 
4018	      </para>
4019	
4020	      <para>
4021	        The <structfield>read</structfield> callback returns the
4022	        register value specified in the argument. 
4023	
4024	        <informalexample>
4025	          <programlisting>
4026	<![CDATA[
4027	  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4028	                                             unsigned short reg)
4029	  {
4030	          struct mychip *chip = ac97->private_data;
4031	          ....
4032	          return the_register_value;
4033	  }
4034	]]>
4035	          </programlisting>
4036	        </informalexample>
4037	
4038	        Here, the chip can be cast from ac97-&gt;private_data.
4039	      </para>
4040	
4041	      <para>
4042	        Meanwhile, the <structfield>write</structfield> callback is
4043	        used to set the register value. 
4044	
4045	        <informalexample>
4046	          <programlisting>
4047	<![CDATA[
4048	  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4049	                       unsigned short reg, unsigned short val)
4050	]]>
4051	          </programlisting>
4052	        </informalexample>
4053	      </para>
4054	
4055	      <para>
4056	      These callbacks are non-atomic like the control API callbacks.
4057	      </para>
4058	
4059	      <para>
4060	        There are also other callbacks:
4061	      <structfield>reset</structfield>,
4062	      <structfield>wait</structfield> and
4063	      <structfield>init</structfield>. 
4064	      </para>
4065	
4066	      <para>
4067	        The <structfield>reset</structfield> callback is used to reset
4068	      the codec. If the chip requires a special kind of reset, you can
4069	      define this callback. 
4070	      </para>
4071	
4072	      <para>
4073	        The <structfield>wait</structfield> callback is used to
4074	      add some waiting time in the standard initialization of the codec. If the
4075	      chip requires the extra waiting time, define this callback. 
4076	      </para>
4077	
4078	      <para>
4079	        The <structfield>init</structfield> callback is used for
4080	      additional initialization of the codec.
4081	      </para>
4082	    </section>
4083	
4084	    <section id="api-ac97-updating-registers">
4085	      <title>Updating Registers in The Driver</title>
4086	      <para>
4087	        If you need to access to the codec from the driver, you can
4088	      call the following functions:
4089	      <function>snd_ac97_write()</function>,
4090	      <function>snd_ac97_read()</function>,
4091	      <function>snd_ac97_update()</function> and
4092	      <function>snd_ac97_update_bits()</function>. 
4093	      </para>
4094	
4095	      <para>
4096	        Both <function>snd_ac97_write()</function> and
4097	        <function>snd_ac97_update()</function> functions are used to
4098	        set a value to the given register
4099	        (<constant>AC97_XXX</constant>). The difference between them is
4100	        that <function>snd_ac97_update()</function> doesn't write a
4101	        value if the given value has been already set, while
4102	        <function>snd_ac97_write()</function> always rewrites the
4103	        value. 
4104	
4105	        <informalexample>
4106	          <programlisting>
4107	<![CDATA[
4108	  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4109	  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4110	]]>
4111	          </programlisting>
4112	        </informalexample>
4113	      </para>
4114	
4115	      <para>
4116	        <function>snd_ac97_read()</function> is used to read the value
4117	        of the given register. For example, 
4118	
4119	        <informalexample>
4120	          <programlisting>
4121	<![CDATA[
4122	  value = snd_ac97_read(ac97, AC97_MASTER);
4123	]]>
4124	          </programlisting>
4125	        </informalexample>
4126	      </para>
4127	
4128	      <para>
4129	        <function>snd_ac97_update_bits()</function> is used to update
4130	        some bits in the given register.  
4131	
4132	        <informalexample>
4133	          <programlisting>
4134	<![CDATA[
4135	  snd_ac97_update_bits(ac97, reg, mask, value);
4136	]]>
4137	          </programlisting>
4138	        </informalexample>
4139	      </para>
4140	
4141	      <para>
4142	        Also, there is a function to change the sample rate (of a
4143	        given register such as
4144	        <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4145	        DRA is supported by the codec:
4146	        <function>snd_ac97_set_rate()</function>. 
4147	
4148	        <informalexample>
4149	          <programlisting>
4150	<![CDATA[
4151	  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4152	]]>
4153	          </programlisting>
4154	        </informalexample>
4155	      </para>
4156	
4157	      <para>
4158	        The following registers are available to set the rate:
4159	      <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4160	      <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4161	      <constant>AC97_PCM_LR_ADC_RATE</constant>,
4162	      <constant>AC97_SPDIF</constant>. When
4163	      <constant>AC97_SPDIF</constant> is specified, the register is
4164	      not really changed but the corresponding IEC958 status bits will
4165	      be updated. 
4166	      </para>
4167	    </section>
4168	
4169	    <section id="api-ac97-clock-adjustment">
4170	      <title>Clock Adjustment</title>
4171	      <para>
4172	        In some chips, the clock of the codec isn't 48000 but using a
4173	      PCI clock (to save a quartz!). In this case, change the field
4174	      bus-&gt;clock to the corresponding
4175	      value. For example, intel8x0 
4176	      and es1968 drivers have their own function to read from the clock.
4177	      </para>
4178	    </section>
4179	
4180	    <section id="api-ac97-proc-files">
4181	      <title>Proc Files</title>
4182	      <para>
4183	        The ALSA AC97 interface will create a proc file such as
4184	      <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4185	      <filename>ac97#0-0+regs</filename>. You can refer to these files to
4186	      see the current status and registers of the codec. 
4187	      </para>
4188	    </section>
4189	
4190	    <section id="api-ac97-multiple-codecs">
4191	      <title>Multiple Codecs</title>
4192	      <para>
4193	        When there are several codecs on the same card, you need to
4194	      call <function>snd_ac97_mixer()</function> multiple times with
4195	      ac97.num=1 or greater. The <structfield>num</structfield> field
4196	      specifies the codec number. 
4197	      </para>
4198	
4199	      <para>
4200	        If you set up multiple codecs, you either need to write
4201	      different callbacks for each codec or check
4202	      ac97-&gt;num in the callback routines. 
4203	      </para>
4204	    </section>
4205	
4206	  </chapter>
4207	
4208	
4209	<!-- ****************************************************** -->
4210	<!-- MIDI (MPU401-UART) Interface  -->
4211	<!-- ****************************************************** -->
4212	  <chapter id="midi-interface">
4213	    <title>MIDI (MPU401-UART) Interface</title>
4214	
4215	    <section id="midi-interface-general">
4216	      <title>General</title>
4217	      <para>
4218	        Many soundcards have built-in MIDI (MPU401-UART)
4219	      interfaces. When the soundcard supports the standard MPU401-UART
4220	      interface, most likely you can use the ALSA MPU401-UART API. The
4221	      MPU401-UART API is defined in
4222	      <filename>&lt;sound/mpu401.h&gt;</filename>. 
4223	      </para>
4224	
4225	      <para>
4226	        Some soundchips have a similar but slightly different
4227	      implementation of mpu401 stuff. For example, emu10k1 has its own
4228	      mpu401 routines. 
4229	      </para>
4230	    </section>
4231	
4232	    <section id="midi-interface-constructor">
4233	      <title>Constructor</title>
4234	      <para>
4235	        To create a rawmidi object, call
4236	      <function>snd_mpu401_uart_new()</function>. 
4237	
4238	        <informalexample>
4239	          <programlisting>
4240	<![CDATA[
4241	  struct snd_rawmidi *rmidi;
4242	  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4243	                      irq, &rmidi);
4244	]]>
4245	          </programlisting>
4246	        </informalexample>
4247	      </para>
4248	
4249	      <para>
4250	        The first argument is the card pointer, and the second is the
4251	      index of this component. You can create up to 8 rawmidi
4252	      devices. 
4253	      </para>
4254	
4255	      <para>
4256	        The third argument is the type of the hardware,
4257	      <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4258	      you can use <constant>MPU401_HW_MPU401</constant>. 
4259	      </para>
4260	
4261	      <para>
4262	        The 4th argument is the I/O port address. Many
4263	      backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4264	      might be a part of its own PCI I/O region. It depends on the
4265	      chip design. 
4266	      </para>
4267	
4268	      <para>
4269		The 5th argument is a bitflag for additional information.
4270	        When the I/O port address above is part of the PCI I/O
4271	      region, the MPU401 I/O port might have been already allocated
4272	      (reserved) by the driver itself. In such a case, pass a bit flag
4273	      <constant>MPU401_INFO_INTEGRATED</constant>,
4274	      and the mpu401-uart layer will allocate the I/O ports by itself. 
4275	      </para>
4276	
4277		<para>
4278		When the controller supports only the input or output MIDI stream,
4279		pass the <constant>MPU401_INFO_INPUT</constant> or
4280		<constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4281		Then the rawmidi instance is created as a single stream.
4282		</para>
4283	
4284		<para>
4285		<constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4286		the access method to MMIO (via readb and writeb) instead of
4287		iob and outb. In this case, you have to pass the iomapped address
4288		to <function>snd_mpu401_uart_new()</function>.
4289		</para>
4290	
4291		<para>
4292		When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4293		stream isn't checked in the default interrupt handler.  The driver
4294		needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4295		by itself to start processing the output stream in the irq handler.
4296		</para>
4297	
4298		<para>
4299		If the MPU-401 interface shares its interrupt with the other logical
4300		devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4301		(see <link linkend="midi-interface-interrupt-handler"><citetitle>
4302		below</citetitle></link>).
4303		</para>
4304	
4305	      <para>
4306	        Usually, the port address corresponds to the command port and
4307	        port + 1 corresponds to the data port. If not, you may change
4308	        the <structfield>cport</structfield> field of
4309	        struct <structname>snd_mpu401</structname> manually 
4310	        afterward. However, <structname>snd_mpu401</structname> pointer is not
4311	        returned explicitly by
4312	        <function>snd_mpu401_uart_new()</function>. You need to cast
4313	        rmidi-&gt;private_data to
4314	        <structname>snd_mpu401</structname> explicitly, 
4315	
4316	        <informalexample>
4317	          <programlisting>
4318	<![CDATA[
4319	  struct snd_mpu401 *mpu;
4320	  mpu = rmidi->private_data;
4321	]]>
4322	          </programlisting>
4323	        </informalexample>
4324	
4325	        and reset the cport as you like:
4326	
4327	        <informalexample>
4328	          <programlisting>
4329	<![CDATA[
4330	  mpu->cport = my_own_control_port;
4331	]]>
4332	          </programlisting>
4333	        </informalexample>
4334	      </para>
4335	
4336	      <para>
4337		The 6th argument specifies the ISA irq number that will be
4338		allocated.  If no interrupt is to be allocated (because your
4339		code is already allocating a shared interrupt, or because the
4340		device does not use interrupts), pass -1 instead.
4341		For a MPU-401 device without an interrupt, a polling timer
4342		will be used instead.
4343	      </para>
4344	    </section>
4345	
4346	    <section id="midi-interface-interrupt-handler">
4347	      <title>Interrupt Handler</title>
4348	      <para>
4349	        When the interrupt is allocated in
4350	      <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4351	      interrupt handler is automatically used, hence you don't have
4352	      anything else to do than creating the mpu401 stuff.  Otherwise, you
4353	      have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4354	      <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4355	      own interrupt handler when it has determined that a UART interrupt
4356	      has occurred.
4357	      </para>
4358	
4359	      <para>
4360	        In this case, you need to pass the private_data of the
4361	        returned rawmidi object from
4362	        <function>snd_mpu401_uart_new()</function> as the second
4363	        argument of <function>snd_mpu401_uart_interrupt()</function>. 
4364	
4365	        <informalexample>
4366	          <programlisting>
4367	<![CDATA[
4368	  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4369	]]>
4370	          </programlisting>
4371	        </informalexample>
4372	      </para>
4373	    </section>
4374	
4375	  </chapter>
4376	
4377	
4378	<!-- ****************************************************** -->
4379	<!-- RawMIDI Interface  -->
4380	<!-- ****************************************************** -->
4381	  <chapter id="rawmidi-interface">
4382	    <title>RawMIDI Interface</title>
4383	
4384	    <section id="rawmidi-interface-overview">
4385	      <title>Overview</title>
4386	
4387	      <para>
4388	      The raw MIDI interface is used for hardware MIDI ports that can
4389	      be accessed as a byte stream.  It is not used for synthesizer
4390	      chips that do not directly understand MIDI.
4391	      </para>
4392	
4393	      <para>
4394	      ALSA handles file and buffer management.  All you have to do is
4395	      to write some code to move data between the buffer and the
4396	      hardware.
4397	      </para>
4398	
4399	      <para>
4400	      The rawmidi API is defined in
4401	      <filename>&lt;sound/rawmidi.h&gt;</filename>.
4402	      </para>
4403	    </section>
4404	
4405	    <section id="rawmidi-interface-constructor">
4406	      <title>Constructor</title>
4407	
4408	      <para>
4409	      To create a rawmidi device, call the
4410	      <function>snd_rawmidi_new</function> function:
4411	        <informalexample>
4412	          <programlisting>
4413	<![CDATA[
4414	  struct snd_rawmidi *rmidi;
4415	  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4416	  if (err < 0)
4417	          return err;
4418	  rmidi->private_data = chip;
4419	  strcpy(rmidi->name, "My MIDI");
4420	  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4421	                      SNDRV_RAWMIDI_INFO_INPUT |
4422	                      SNDRV_RAWMIDI_INFO_DUPLEX;
4423	]]>
4424	          </programlisting>
4425	        </informalexample>
4426	      </para>
4427	
4428	      <para>
4429	      The first argument is the card pointer, the second argument is
4430	      the ID string.
4431	      </para>
4432	
4433	      <para>
4434	      The third argument is the index of this component.  You can
4435	      create up to 8 rawmidi devices.
4436	      </para>
4437	
4438	      <para>
4439	      The fourth and fifth arguments are the number of output and
4440	      input substreams, respectively, of this device (a substream is
4441	      the equivalent of a MIDI port).
4442	      </para>
4443	
4444	      <para>
4445	      Set the <structfield>info_flags</structfield> field to specify
4446	      the capabilities of the device.
4447	      Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4448	      at least one output port,
4449	      <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4450	      least one input port,
4451	      and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4452	      can handle output and input at the same time.
4453	      </para>
4454	
4455	      <para>
4456	      After the rawmidi device is created, you need to set the
4457	      operators (callbacks) for each substream.  There are helper
4458	      functions to set the operators for all the substreams of a device:
4459	        <informalexample>
4460	          <programlisting>
4461	<![CDATA[
4462	  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4463	  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4464	]]>
4465	          </programlisting>
4466	        </informalexample>
4467	      </para>
4468	
4469	      <para>
4470	      The operators are usually defined like this:
4471	        <informalexample>
4472	          <programlisting>
4473	<![CDATA[
4474	  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4475	          .open =    snd_mymidi_output_open,
4476	          .close =   snd_mymidi_output_close,
4477	          .trigger = snd_mymidi_output_trigger,
4478	  };
4479	]]>
4480	          </programlisting>
4481	        </informalexample>
4482	      These callbacks are explained in the <link
4483	      linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4484	      section.
4485	      </para>
4486	
4487	      <para>
4488	      If there are more than one substream, you should give a
4489	      unique name to each of them:
4490	        <informalexample>
4491	          <programlisting>
4492	<![CDATA[
4493	  struct snd_rawmidi_substream *substream;
4494	  list_for_each_entry(substream,
4495	                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4496	                      list {
4497	          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4498	  }
4499	  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4500	]]>
4501	          </programlisting>
4502	        </informalexample>
4503	      </para>
4504	    </section>
4505	
4506	    <section id="rawmidi-interface-callbacks">
4507	      <title>Callbacks</title>
4508	
4509	      <para>
4510	      In all the callbacks, the private data that you've set for the
4511	      rawmidi device can be accessed as
4512	      substream-&gt;rmidi-&gt;private_data.
4513	      <!-- <code> isn't available before DocBook 4.3 -->
4514	      </para>
4515	
4516	      <para>
4517	      If there is more than one port, your callbacks can determine the
4518	      port index from the struct snd_rawmidi_substream data passed to each
4519	      callback:
4520	        <informalexample>
4521	          <programlisting>
4522	<![CDATA[
4523	  struct snd_rawmidi_substream *substream;
4524	  int index = substream->number;
4525	]]>
4526	          </programlisting>
4527	        </informalexample>
4528	      </para>
4529	
4530	      <section id="rawmidi-interface-op-open">
4531	      <title><function>open</function> callback</title>
4532	
4533	        <informalexample>
4534	          <programlisting>
4535	<![CDATA[
4536	  static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4537	]]>
4538	          </programlisting>
4539	        </informalexample>
4540	
4541	        <para>
4542	        This is called when a substream is opened.
4543	        You can initialize the hardware here, but you shouldn't
4544	        start transmitting/receiving data yet.
4545	        </para>
4546	      </section>
4547	
4548	      <section id="rawmidi-interface-op-close">
4549	      <title><function>close</function> callback</title>
4550	
4551	        <informalexample>
4552	          <programlisting>
4553	<![CDATA[
4554	  static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4555	]]>
4556	          </programlisting>
4557	        </informalexample>
4558	
4559	        <para>
4560	        Guess what.
4561	        </para>
4562	
4563	        <para>
4564	        The <function>open</function> and <function>close</function>
4565	        callbacks of a rawmidi device are serialized with a mutex,
4566	        and can sleep.
4567	        </para>
4568	      </section>
4569	
4570	      <section id="rawmidi-interface-op-trigger-out">
4571	      <title><function>trigger</function> callback for output
4572	      substreams</title>
4573	
4574	        <informalexample>
4575	          <programlisting>
4576	<![CDATA[
4577	  static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4578	]]>
4579	          </programlisting>
4580	        </informalexample>
4581	
4582	        <para>
4583	        This is called with a nonzero <parameter>up</parameter>
4584	        parameter when there is some data in the substream buffer that
4585	        must be transmitted.
4586	        </para>
4587	
4588	        <para>
4589	        To read data from the buffer, call
4590	        <function>snd_rawmidi_transmit_peek</function>.  It will
4591	        return the number of bytes that have been read; this will be
4592	        less than the number of bytes requested when there are no more
4593	        data in the buffer.
4594	        After the data have been transmitted successfully, call
4595	        <function>snd_rawmidi_transmit_ack</function> to remove the
4596	        data from the substream buffer:
4597	          <informalexample>
4598	            <programlisting>
4599	<![CDATA[
4600	  unsigned char data;
4601	  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4602	          if (snd_mychip_try_to_transmit(data))
4603	                  snd_rawmidi_transmit_ack(substream, 1);
4604	          else
4605	                  break; /* hardware FIFO full */
4606	  }
4607	]]>
4608	            </programlisting>
4609	          </informalexample>
4610	        </para>
4611	
4612	        <para>
4613	        If you know beforehand that the hardware will accept data, you
4614	        can use the <function>snd_rawmidi_transmit</function> function
4615	        which reads some data and removes them from the buffer at once:
4616	          <informalexample>
4617	            <programlisting>
4618	<![CDATA[
4619	  while (snd_mychip_transmit_possible()) {
4620	          unsigned char data;
4621	          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4622	                  break; /* no more data */
4623	          snd_mychip_transmit(data);
4624	  }
4625	]]>
4626	            </programlisting>
4627	          </informalexample>
4628	        </para>
4629	
4630	        <para>
4631	        If you know beforehand how many bytes you can accept, you can
4632	        use a buffer size greater than one with the
4633	        <function>snd_rawmidi_transmit*</function> functions.
4634	        </para>
4635	
4636	        <para>
4637	        The <function>trigger</function> callback must not sleep.  If
4638	        the hardware FIFO is full before the substream buffer has been
4639	        emptied, you have to continue transmitting data later, either
4640	        in an interrupt handler, or with a timer if the hardware
4641	        doesn't have a MIDI transmit interrupt.
4642	        </para>
4643	
4644	        <para>
4645	        The <function>trigger</function> callback is called with a
4646	        zero <parameter>up</parameter> parameter when the transmission
4647	        of data should be aborted.
4648	        </para>
4649	      </section>
4650	
4651	      <section id="rawmidi-interface-op-trigger-in">
4652	      <title><function>trigger</function> callback for input
4653	      substreams</title>
4654	
4655	        <informalexample>
4656	          <programlisting>
4657	<![CDATA[
4658	  static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4659	]]>
4660	          </programlisting>
4661	        </informalexample>
4662	
4663	        <para>
4664	        This is called with a nonzero <parameter>up</parameter>
4665	        parameter to enable receiving data, or with a zero
4666	        <parameter>up</parameter> parameter do disable receiving data.
4667	        </para>
4668	
4669	        <para>
4670	        The <function>trigger</function> callback must not sleep; the
4671	        actual reading of data from the device is usually done in an
4672	        interrupt handler.
4673	        </para>
4674	
4675	        <para>
4676	        When data reception is enabled, your interrupt handler should
4677	        call <function>snd_rawmidi_receive</function> for all received
4678	        data:
4679	          <informalexample>
4680	            <programlisting>
4681	<![CDATA[
4682	  void snd_mychip_midi_interrupt(...)
4683	  {
4684	          while (mychip_midi_available()) {
4685	                  unsigned char data;
4686	                  data = mychip_midi_read();
4687	                  snd_rawmidi_receive(substream, &data, 1);
4688	          }
4689	  }
4690	]]>
4691	            </programlisting>
4692	          </informalexample>
4693	        </para>
4694	      </section>
4695	
4696	      <section id="rawmidi-interface-op-drain">
4697	      <title><function>drain</function> callback</title>
4698	
4699	        <informalexample>
4700	          <programlisting>
4701	<![CDATA[
4702	  static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4703	]]>
4704	          </programlisting>
4705	        </informalexample>
4706	
4707	        <para>
4708	        This is only used with output substreams.  This function should wait
4709	        until all data read from the substream buffer have been transmitted.
4710	        This ensures that the device can be closed and the driver unloaded
4711	        without losing data.
4712	        </para>
4713	
4714	        <para>
4715	        This callback is optional. If you do not set
4716	        <structfield>drain</structfield> in the struct snd_rawmidi_ops
4717	        structure, ALSA will simply wait for 50&nbsp;milliseconds
4718	        instead.
4719	        </para>
4720	      </section>
4721	    </section>
4722	
4723	  </chapter>
4724	
4725	
4726	<!-- ****************************************************** -->
4727	<!-- Miscellaneous Devices  -->
4728	<!-- ****************************************************** -->
4729	  <chapter id="misc-devices">
4730	    <title>Miscellaneous Devices</title>
4731	
4732	    <section id="misc-devices-opl3">
4733	      <title>FM OPL3</title>
4734	      <para>
4735	        The FM OPL3 is still used in many chips (mainly for backward
4736	      compatibility). ALSA has a nice OPL3 FM control layer, too. The
4737	      OPL3 API is defined in
4738	      <filename>&lt;sound/opl3.h&gt;</filename>. 
4739	      </para>
4740	
4741	      <para>
4742	        FM registers can be directly accessed through the direct-FM API,
4743	      defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4744	      ALSA native mode, FM registers are accessed through
4745	      the Hardware-Dependent Device direct-FM extension API, whereas in
4746	      OSS compatible mode, FM registers can be accessed with the OSS
4747	      direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 
4748	      </para>
4749	
4750	      <para>
4751	        To create the OPL3 component, you have two functions to
4752	        call. The first one is a constructor for the <type>opl3_t</type>
4753	        instance. 
4754	
4755	        <informalexample>
4756	          <programlisting>
4757	<![CDATA[
4758	  struct snd_opl3 *opl3;
4759	  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4760	                  integrated, &opl3);
4761	]]>
4762	          </programlisting>
4763	        </informalexample>
4764	      </para>
4765	
4766	      <para>
4767	        The first argument is the card pointer, the second one is the
4768	      left port address, and the third is the right port address. In
4769	      most cases, the right port is placed at the left port + 2. 
4770	      </para>
4771	
4772	      <para>
4773	        The fourth argument is the hardware type.
4774	      </para>
4775	
4776	      <para>
4777	        When the left and right ports have been already allocated by
4778	      the card driver, pass non-zero to the fifth argument
4779	      (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4780	      allocate the specified ports by itself. 
4781	      </para>
4782	
4783	      <para>
4784	        When the accessing the hardware requires special method
4785	        instead of the standard I/O access, you can create opl3 instance
4786	        separately with <function>snd_opl3_new()</function>.
4787	
4788	        <informalexample>
4789	          <programlisting>
4790	<![CDATA[
4791	  struct snd_opl3 *opl3;
4792	  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4793	]]>
4794	          </programlisting>
4795	        </informalexample>
4796	      </para>
4797	
4798	      <para>
4799		Then set <structfield>command</structfield>,
4800		<structfield>private_data</structfield> and
4801		<structfield>private_free</structfield> for the private
4802		access function, the private data and the destructor.
4803		The l_port and r_port are not necessarily set.  Only the
4804		command must be set properly.  You can retrieve the data
4805		from the opl3-&gt;private_data field.
4806	      </para>
4807	
4808	      <para>
4809		After creating the opl3 instance via <function>snd_opl3_new()</function>,
4810		call <function>snd_opl3_init()</function> to initialize the chip to the
4811		proper state. Note that <function>snd_opl3_create()</function> always
4812		calls it internally.
4813	      </para>
4814	
4815	      <para>
4816	        If the opl3 instance is created successfully, then create a
4817	        hwdep device for this opl3. 
4818	
4819	        <informalexample>
4820	          <programlisting>
4821	<![CDATA[
4822	  struct snd_hwdep *opl3hwdep;
4823	  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4824	]]>
4825	          </programlisting>
4826	        </informalexample>
4827	      </para>
4828	
4829	      <para>
4830	        The first argument is the <type>opl3_t</type> instance you
4831	      created, and the second is the index number, usually 0. 
4832	      </para>
4833	
4834	      <para>
4835	        The third argument is the index-offset for the sequencer
4836	      client assigned to the OPL3 port. When there is an MPU401-UART,
4837	      give 1 for here (UART always takes 0). 
4838	      </para>
4839	    </section>
4840	
4841	    <section id="misc-devices-hardware-dependent">
4842	      <title>Hardware-Dependent Devices</title>
4843	      <para>
4844	        Some chips need user-space access for special
4845	      controls or for loading the micro code. In such a case, you can
4846	      create a hwdep (hardware-dependent) device. The hwdep API is
4847	      defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4848	      find examples in opl3 driver or
4849	      <filename>isa/sb/sb16_csp.c</filename>. 
4850	      </para>
4851	
4852	      <para>
4853	        The creation of the <type>hwdep</type> instance is done via
4854	        <function>snd_hwdep_new()</function>. 
4855	
4856	        <informalexample>
4857	          <programlisting>
4858	<![CDATA[
4859	  struct snd_hwdep *hw;
4860	  snd_hwdep_new(card, "My HWDEP", 0, &hw);
4861	]]>
4862	          </programlisting>
4863	        </informalexample>
4864	
4865	        where the third argument is the index number.
4866	      </para>
4867	
4868	      <para>
4869	        You can then pass any pointer value to the
4870	        <parameter>private_data</parameter>.
4871	        If you assign a private data, you should define the
4872	        destructor, too. The destructor function is set in
4873	        the <structfield>private_free</structfield> field.  
4874	
4875	        <informalexample>
4876	          <programlisting>
4877	<![CDATA[
4878	  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4879	  hw->private_data = p;
4880	  hw->private_free = mydata_free;
4881	]]>
4882	          </programlisting>
4883	        </informalexample>
4884	
4885	        and the implementation of the destructor would be:
4886	
4887	        <informalexample>
4888	          <programlisting>
4889	<![CDATA[
4890	  static void mydata_free(struct snd_hwdep *hw)
4891	  {
4892	          struct mydata *p = hw->private_data;
4893	          kfree(p);
4894	  }
4895	]]>
4896	          </programlisting>
4897	        </informalexample>
4898	      </para>
4899	
4900	      <para>
4901	        The arbitrary file operations can be defined for this
4902	        instance. The file operators are defined in
4903	        the <parameter>ops</parameter> table. For example, assume that
4904	        this chip needs an ioctl. 
4905	
4906	        <informalexample>
4907	          <programlisting>
4908	<![CDATA[
4909	  hw->ops.open = mydata_open;
4910	  hw->ops.ioctl = mydata_ioctl;
4911	  hw->ops.release = mydata_release;
4912	]]>
4913	          </programlisting>
4914	        </informalexample>
4915	
4916	        And implement the callback functions as you like.
4917	      </para>
4918	    </section>
4919	
4920	    <section id="misc-devices-IEC958">
4921	      <title>IEC958 (S/PDIF)</title>
4922	      <para>
4923	        Usually the controls for IEC958 devices are implemented via
4924	      the control interface. There is a macro to compose a name string for
4925	      IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4926	      defined in <filename>&lt;include/asound.h&gt;</filename>.  
4927	      </para>
4928	
4929	      <para>
4930	        There are some standard controls for IEC958 status bits. These
4931	      controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4932	      and the size of element is fixed as 4 bytes array
4933	      (value.iec958.status[x]). For the <structfield>info</structfield>
4934	      callback, you don't specify 
4935	      the value field for this type (the count field must be set,
4936	      though). 
4937	      </para>
4938	
4939	      <para>
4940	        <quote>IEC958 Playback Con Mask</quote> is used to return the
4941	      bit-mask for the IEC958 status bits of consumer mode. Similarly,
4942	      <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4943	      professional mode. They are read-only controls, and are defined
4944	      as MIXER controls (iface =
4945	      <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).  
4946	      </para>
4947	
4948	      <para>
4949	        Meanwhile, <quote>IEC958 Playback Default</quote> control is
4950	      defined for getting and setting the current default IEC958
4951	      bits. Note that this one is usually defined as a PCM control
4952	      (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4953	      although in some places it's defined as a MIXER control. 
4954	      </para>
4955	
4956	      <para>
4957	        In addition, you can define the control switches to
4958	      enable/disable or to set the raw bit mode. The implementation
4959	      will depend on the chip, but the control should be named as
4960	      <quote>IEC958 xxx</quote>, preferably using
4961	      the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 
4962	      </para>
4963	
4964	      <para>
4965	        You can find several cases, for example,
4966	      <filename>pci/emu10k1</filename>,
4967	      <filename>pci/ice1712</filename>, or
4968	      <filename>pci/cmipci.c</filename>.  
4969	      </para>
4970	    </section>
4971	
4972	  </chapter>
4973	
4974	
4975	<!-- ****************************************************** -->
4976	<!-- Buffer and Memory Management  -->
4977	<!-- ****************************************************** -->
4978	  <chapter id="buffer-and-memory">
4979	    <title>Buffer and Memory Management</title>
4980	
4981	    <section id="buffer-and-memory-buffer-types">
4982	      <title>Buffer Types</title>
4983	      <para>
4984	        ALSA provides several different buffer allocation functions
4985	      depending on the bus and the architecture. All these have a
4986	      consistent API. The allocation of physically-contiguous pages is
4987	      done via 
4988	      <function>snd_malloc_xxx_pages()</function> function, where xxx
4989	      is the bus type. 
4990	      </para>
4991	
4992	      <para>
4993	        The allocation of pages with fallback is
4994	      <function>snd_malloc_xxx_pages_fallback()</function>. This
4995	      function tries to allocate the specified pages but if the pages
4996	      are not available, it tries to reduce the page sizes until
4997	      enough space is found.
4998	      </para>
4999	
5000	      <para>
5001	      The release the pages, call
5002	      <function>snd_free_xxx_pages()</function> function. 
5003	      </para>
5004	
5005	      <para>
5006	      Usually, ALSA drivers try to allocate and reserve
5007	       a large contiguous physical space
5008	       at the time the module is loaded for the later use.
5009	       This is called <quote>pre-allocation</quote>.
5010	       As already written, you can call the following function at 
5011	       pcm instance construction time (in the case of PCI bus). 
5012	
5013	        <informalexample>
5014	          <programlisting>
5015	<![CDATA[
5016	  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5017	                                        snd_dma_pci_data(pci), size, max);
5018	]]>
5019	          </programlisting>
5020	        </informalexample>
5021	
5022	        where <parameter>size</parameter> is the byte size to be
5023	      pre-allocated and the <parameter>max</parameter> is the maximum
5024	      size to be changed via the <filename>prealloc</filename> proc file.
5025	      The allocator will try to get an area as large as possible
5026	      within the given size. 
5027	      </para>
5028	
5029	      <para>
5030	      The second argument (type) and the third argument (device pointer)
5031	      are dependent on the bus.
5032	      In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5033	      as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5034	      For the continuous buffer unrelated to the bus can be pre-allocated
5035	      with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5036	      <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5037	      where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5038	      use.
5039	      For the PCI scatter-gather buffers, use
5040	      <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5041	      <function>snd_dma_pci_data(pci)</function>
5042	      (see the 
5043	          <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5044	          </citetitle></link> section).
5045	      </para>
5046	
5047	      <para>
5048	        Once the buffer is pre-allocated, you can use the
5049	        allocator in the <structfield>hw_params</structfield> callback: 
5050	
5051	        <informalexample>
5052	          <programlisting>
5053	<![CDATA[
5054	  snd_pcm_lib_malloc_pages(substream, size);
5055	]]>
5056	          </programlisting>
5057	        </informalexample>
5058	
5059	        Note that you have to pre-allocate to use this function.
5060	      </para>
5061	    </section>
5062	
5063	    <section id="buffer-and-memory-external-hardware">
5064	      <title>External Hardware Buffers</title>
5065	      <para>
5066	        Some chips have their own hardware buffers and the DMA
5067	      transfer from the host memory is not available. In such a case,
5068	      you need to either 1) copy/set the audio data directly to the
5069	      external hardware buffer, or 2) make an intermediate buffer and
5070	      copy/set the data from it to the external hardware buffer in
5071	      interrupts (or in tasklets, preferably).
5072	      </para>
5073	
5074	      <para>
5075	        The first case works fine if the external hardware buffer is large
5076	      enough.  This method doesn't need any extra buffers and thus is
5077	      more effective. You need to define the
5078	      <structfield>copy</structfield> and
5079	      <structfield>silence</structfield> callbacks for 
5080	      the data transfer. However, there is a drawback: it cannot
5081	      be mmapped. The examples are GUS's GF1 PCM or emu8000's
5082	      wavetable PCM. 
5083	      </para>
5084	
5085	      <para>
5086	        The second case allows for mmap on the buffer, although you have
5087	      to handle an interrupt or a tasklet to transfer the data
5088	      from the intermediate buffer to the hardware buffer. You can find an
5089	      example in the vxpocket driver. 
5090	      </para>
5091	
5092	      <para>
5093	        Another case is when the chip uses a PCI memory-map
5094	      region for the buffer instead of the host memory. In this case,
5095	      mmap is available only on certain architectures like the Intel one.
5096	      In non-mmap mode, the data cannot be transferred as in the normal
5097	      way. Thus you need to define the <structfield>copy</structfield> and
5098	      <structfield>silence</structfield> callbacks as well, 
5099	      as in the cases above. The examples are found in
5100	      <filename>rme32.c</filename> and <filename>rme96.c</filename>. 
5101	      </para>
5102	
5103	      <para>
5104	        The implementation of the <structfield>copy</structfield> and
5105	        <structfield>silence</structfield> callbacks depends upon 
5106	        whether the hardware supports interleaved or non-interleaved
5107	        samples. The <structfield>copy</structfield> callback is
5108	        defined like below, a bit 
5109	        differently depending whether the direction is playback or
5110	        capture: 
5111	
5112	        <informalexample>
5113	          <programlisting>
5114	<![CDATA[
5115	  static int playback_copy(struct snd_pcm_substream *substream, int channel,
5116	               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5117	  static int capture_copy(struct snd_pcm_substream *substream, int channel,
5118	               snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5119	]]>
5120	          </programlisting>
5121	        </informalexample>
5122	      </para>
5123	
5124	      <para>
5125	        In the case of interleaved samples, the second argument
5126	      (<parameter>channel</parameter>) is not used. The third argument
5127	      (<parameter>pos</parameter>) points the 
5128	      current position offset in frames. 
5129	      </para>
5130	
5131	      <para>
5132	        The meaning of the fourth argument is different between
5133	      playback and capture. For playback, it holds the source data
5134	      pointer, and for capture, it's the destination data pointer. 
5135	      </para>
5136	
5137	      <para>
5138	        The last argument is the number of frames to be copied.
5139	      </para>
5140	
5141	      <para>
5142	        What you have to do in this callback is again different
5143	        between playback and capture directions. In the
5144	        playback case, you copy the given amount of data
5145	        (<parameter>count</parameter>) at the specified pointer
5146	        (<parameter>src</parameter>) to the specified offset
5147	        (<parameter>pos</parameter>) on the hardware buffer. When
5148	        coded like memcpy-like way, the copy would be like: 
5149	
5150	        <informalexample>
5151	          <programlisting>
5152	<![CDATA[
5153	  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5154	            frames_to_bytes(runtime, count));
5155	]]>
5156	          </programlisting>
5157	        </informalexample>
5158	      </para>
5159	
5160	      <para>
5161	        For the capture direction, you copy the given amount of
5162	        data (<parameter>count</parameter>) at the specified offset
5163	        (<parameter>pos</parameter>) on the hardware buffer to the
5164	        specified pointer (<parameter>dst</parameter>). 
5165	
5166	        <informalexample>
5167	          <programlisting>
5168	<![CDATA[
5169	  my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5170	            frames_to_bytes(runtime, count));
5171	]]>
5172	          </programlisting>
5173	        </informalexample>
5174	
5175	        Note that both the position and the amount of data are given
5176	      in frames. 
5177	      </para>
5178	
5179	      <para>
5180	        In the case of non-interleaved samples, the implementation
5181	      will be a bit more complicated. 
5182	      </para>
5183	
5184	      <para>
5185	        You need to check the channel argument, and if it's -1, copy
5186	      the whole channels. Otherwise, you have to copy only the
5187	      specified channel. Please check
5188	      <filename>isa/gus/gus_pcm.c</filename> as an example. 
5189	      </para>
5190	
5191	      <para>
5192	        The <structfield>silence</structfield> callback is also
5193	        implemented in a similar way. 
5194	
5195	        <informalexample>
5196	          <programlisting>
5197	<![CDATA[
5198	  static int silence(struct snd_pcm_substream *substream, int channel,
5199	                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5200	]]>
5201	          </programlisting>
5202	        </informalexample>
5203	      </para>
5204	
5205	      <para>
5206	        The meanings of arguments are the same as in the
5207	      <structfield>copy</structfield> 
5208	      callback, although there is no <parameter>src/dst</parameter>
5209	      argument. In the case of interleaved samples, the channel
5210	      argument has no meaning, as well as on
5211	      <structfield>copy</structfield> callback.  
5212	      </para>
5213	
5214	      <para>
5215	        The role of <structfield>silence</structfield> callback is to
5216	        set the given amount 
5217	        (<parameter>count</parameter>) of silence data at the
5218	        specified offset (<parameter>pos</parameter>) on the hardware
5219	        buffer. Suppose that the data format is signed (that is, the
5220	        silent-data is 0), and the implementation using a memset-like
5221	        function would be like: 
5222	
5223	        <informalexample>
5224	          <programlisting>
5225	<![CDATA[
5226	  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5227	            frames_to_bytes(runtime, count));
5228	]]>
5229	          </programlisting>
5230	        </informalexample>
5231	      </para>
5232	
5233	      <para>
5234	        In the case of non-interleaved samples, again, the
5235	      implementation becomes a bit more complicated. See, for example,
5236	      <filename>isa/gus/gus_pcm.c</filename>. 
5237	      </para>
5238	    </section>
5239	
5240	    <section id="buffer-and-memory-non-contiguous">
5241	      <title>Non-Contiguous Buffers</title>
5242	      <para>
5243	        If your hardware supports the page table as in emu10k1 or the
5244	      buffer descriptors as in via82xx, you can use the scatter-gather
5245	      (SG) DMA. ALSA provides an interface for handling SG-buffers.
5246	      The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>. 
5247	      </para>
5248	
5249	      <para>
5250	        For creating the SG-buffer handler, call
5251	        <function>snd_pcm_lib_preallocate_pages()</function> or
5252	        <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5253	        with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5254		in the PCM constructor like other PCI pre-allocator.
5255	        You need to pass <function>snd_dma_pci_data(pci)</function>,
5256	        where pci is the struct <structname>pci_dev</structname> pointer
5257	        of the chip as well.
5258	        The <type>struct snd_sg_buf</type> instance is created as
5259	        substream-&gt;dma_private. You can cast
5260	        the pointer like: 
5261	
5262	        <informalexample>
5263	          <programlisting>
5264	<![CDATA[
5265	  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5266	]]>
5267	          </programlisting>
5268	        </informalexample>
5269	      </para>
5270	
5271	      <para>
5272	        Then call <function>snd_pcm_lib_malloc_pages()</function>
5273	      in the <structfield>hw_params</structfield> callback
5274	      as well as in the case of normal PCI buffer.
5275	      The SG-buffer handler will allocate the non-contiguous kernel
5276	      pages of the given size and map them onto the virtually contiguous
5277	      memory.  The virtual pointer is addressed in runtime-&gt;dma_area.
5278	      The physical address (runtime-&gt;dma_addr) is set to zero,
5279	      because the buffer is physically non-contiguous.
5280	      The physical address table is set up in sgbuf-&gt;table.
5281	      You can get the physical address at a certain offset via
5282	      <function>snd_pcm_sgbuf_get_addr()</function>. 
5283	      </para>
5284	
5285	      <para>
5286	        When a SG-handler is used, you need to set
5287	      <function>snd_pcm_sgbuf_ops_page</function> as
5288	      the <structfield>page</structfield> callback.
5289	      (See <link linkend="pcm-interface-operators-page-callback">
5290	      <citetitle>page callback section</citetitle></link>.)
5291	      </para>
5292	
5293	      <para>
5294	        To release the data, call
5295	      <function>snd_pcm_lib_free_pages()</function> in the
5296	      <structfield>hw_free</structfield> callback as usual.
5297	      </para>
5298	    </section>
5299	
5300	    <section id="buffer-and-memory-vmalloced">
5301	      <title>Vmalloc'ed Buffers</title>
5302	      <para>
5303	        It's possible to use a buffer allocated via
5304	      <function>vmalloc</function>, for example, for an intermediate
5305	      buffer. Since the allocated pages are not contiguous, you need
5306	      to set the <structfield>page</structfield> callback to obtain
5307	      the physical address at every offset. 
5308	      </para>
5309	
5310	      <para>
5311	        The implementation of <structfield>page</structfield> callback
5312	        would be like this: 
5313	
5314	        <informalexample>
5315	          <programlisting>
5316	<![CDATA[
5317	  #include <linux/vmalloc.h>
5318	
5319	  /* get the physical page pointer on the given offset */
5320	  static struct page *mychip_page(struct snd_pcm_substream *substream,
5321	                                  unsigned long offset)
5322	  {
5323	          void *pageptr = substream->runtime->dma_area + offset;
5324	          return vmalloc_to_page(pageptr);
5325	  }
5326	]]>
5327	          </programlisting>
5328	        </informalexample>
5329	      </para>
5330	    </section>
5331	
5332	  </chapter>
5333	
5334	
5335	<!-- ****************************************************** -->
5336	<!-- Proc Interface  -->
5337	<!-- ****************************************************** -->
5338	  <chapter id="proc-interface">
5339	    <title>Proc Interface</title>
5340	    <para>
5341	      ALSA provides an easy interface for procfs. The proc files are
5342	      very useful for debugging. I recommend you set up proc files if
5343	      you write a driver and want to get a running status or register
5344	      dumps. The API is found in
5345	      <filename>&lt;sound/info.h&gt;</filename>. 
5346	    </para>
5347	
5348	    <para>
5349	      To create a proc file, call
5350	      <function>snd_card_proc_new()</function>. 
5351	
5352	      <informalexample>
5353	        <programlisting>
5354	<![CDATA[
5355	  struct snd_info_entry *entry;
5356	  int err = snd_card_proc_new(card, "my-file", &entry);
5357	]]>
5358	        </programlisting>
5359	      </informalexample>
5360	
5361	      where the second argument specifies the name of the proc file to be
5362	    created. The above example will create a file
5363	    <filename>my-file</filename> under the card directory,
5364	    e.g. <filename>/proc/asound/card0/my-file</filename>. 
5365	    </para>
5366	
5367	    <para>
5368	    Like other components, the proc entry created via
5369	    <function>snd_card_proc_new()</function> will be registered and
5370	    released automatically in the card registration and release
5371	    functions.
5372	    </para>
5373	
5374	    <para>
5375	      When the creation is successful, the function stores a new
5376	    instance in the pointer given in the third argument.
5377	    It is initialized as a text proc file for read only.  To use
5378	    this proc file as a read-only text file as it is, set the read
5379	    callback with a private data via 
5380	     <function>snd_info_set_text_ops()</function>.
5381	
5382	      <informalexample>
5383	        <programlisting>
5384	<![CDATA[
5385	  snd_info_set_text_ops(entry, chip, my_proc_read);
5386	]]>
5387	        </programlisting>
5388	      </informalexample>
5389	    
5390	    where the second argument (<parameter>chip</parameter>) is the
5391	    private data to be used in the callbacks. The third parameter
5392	    specifies the read buffer size and the fourth
5393	    (<parameter>my_proc_read</parameter>) is the callback function, which
5394	    is defined like
5395	
5396	      <informalexample>
5397	        <programlisting>
5398	<![CDATA[
5399	  static void my_proc_read(struct snd_info_entry *entry,
5400	                           struct snd_info_buffer *buffer);
5401	]]>
5402	        </programlisting>
5403	      </informalexample>
5404	    
5405	    </para>
5406	
5407	    <para>
5408	    In the read callback, use <function>snd_iprintf()</function> for
5409	    output strings, which works just like normal
5410	    <function>printf()</function>.  For example,
5411	
5412	      <informalexample>
5413	        <programlisting>
5414	<![CDATA[
5415	  static void my_proc_read(struct snd_info_entry *entry,
5416	                           struct snd_info_buffer *buffer)
5417	  {
5418	          struct my_chip *chip = entry->private_data;
5419	
5420	          snd_iprintf(buffer, "This is my chip!\n");
5421	          snd_iprintf(buffer, "Port = %ld\n", chip->port);
5422	  }
5423	]]>
5424	        </programlisting>
5425	      </informalexample>
5426	    </para>
5427	
5428	    <para>
5429	    The file permissions can be changed afterwards.  As default, it's
5430	    set as read only for all users.  If you want to add write
5431	    permission for the user (root as default), do as follows:
5432	
5433	      <informalexample>
5434	        <programlisting>
5435	<![CDATA[
5436	 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5437	]]>
5438	        </programlisting>
5439	      </informalexample>
5440	
5441	    and set the write buffer size and the callback
5442	
5443	      <informalexample>
5444	        <programlisting>
5445	<![CDATA[
5446	  entry->c.text.write = my_proc_write;
5447	]]>
5448	        </programlisting>
5449	      </informalexample>
5450	    </para>
5451	
5452	    <para>
5453	      For the write callback, you can use
5454	    <function>snd_info_get_line()</function> to get a text line, and
5455	    <function>snd_info_get_str()</function> to retrieve a string from
5456	    the line. Some examples are found in
5457	    <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5458	    <filename>pcm_oss.c</filename>. 
5459	    </para>
5460	
5461	    <para>
5462	      For a raw-data proc-file, set the attributes as follows:
5463	
5464	      <informalexample>
5465	        <programlisting>
5466	<![CDATA[
5467	  static struct snd_info_entry_ops my_file_io_ops = {
5468	          .read = my_file_io_read,
5469	  };
5470	
5471	  entry->content = SNDRV_INFO_CONTENT_DATA;
5472	  entry->private_data = chip;
5473	  entry->c.ops = &my_file_io_ops;
5474	  entry->size = 4096;
5475	  entry->mode = S_IFREG | S_IRUGO;
5476	]]>
5477	        </programlisting>
5478	      </informalexample>
5479	
5480	      For the raw data, <structfield>size</structfield> field must be
5481	      set properly.  This specifies the maximum size of the proc file access.
5482	    </para>
5483	
5484	    <para>
5485	      The read/write callbacks of raw mode are more direct than the text mode.
5486	      You need to use a low-level I/O functions such as
5487	      <function>copy_from/to_user()</function> to transfer the
5488	      data.
5489	
5490	      <informalexample>
5491	        <programlisting>
5492	<![CDATA[
5493	  static ssize_t my_file_io_read(struct snd_info_entry *entry,
5494	                              void *file_private_data,
5495	                              struct file *file,
5496	                              char *buf,
5497	                              size_t count,
5498	                              loff_t pos)
5499	  {
5500	          if (copy_to_user(buf, local_data + pos, count))
5501	                  return -EFAULT;
5502	          return count;
5503	  }
5504	]]>
5505	        </programlisting>
5506	      </informalexample>
5507	
5508	      If the size of the info entry has been set up properly,
5509	      <structfield>count</structfield> and <structfield>pos</structfield> are
5510	      guaranteed to fit within 0 and the given size.
5511	      You don't have to check the range in the callbacks unless any
5512	      other condition is required.
5513	
5514	    </para>
5515	
5516	  </chapter>
5517	
5518	
5519	<!-- ****************************************************** -->
5520	<!-- Power Management  -->
5521	<!-- ****************************************************** -->
5522	  <chapter id="power-management">
5523	    <title>Power Management</title>
5524	    <para>
5525	      If the chip is supposed to work with suspend/resume
5526	      functions, you need to add power-management code to the
5527	      driver. The additional code for power-management should be
5528	      <function>ifdef</function>'ed with
5529	      <constant>CONFIG_PM</constant>. 
5530	    </para>
5531	
5532		<para>
5533		If the driver <emphasis>fully</emphasis> supports suspend/resume
5534		that is, the device can be
5535		properly resumed to its state when suspend was called,
5536		you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5537		in the pcm info field.  Usually, this is possible when the
5538		registers of the chip can be safely saved and restored to
5539		RAM. If this is set, the trigger callback is called with
5540		<constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5541		callback completes. 
5542		</para>
5543	
5544		<para>
5545		Even if the driver doesn't support PM fully but 
5546		partial suspend/resume is still possible, it's still worthy to
5547		implement suspend/resume callbacks. In such a case, applications
5548		would reset the status by calling
5549		<function>snd_pcm_prepare()</function> and restart the stream
5550		appropriately.  Hence, you can define suspend/resume callbacks
5551		below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5552		info flag to the PCM.
5553		</para>
5554		
5555		<para>
5556		Note that the trigger with SUSPEND can always be called when
5557		<function>snd_pcm_suspend_all</function> is called,
5558		regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5559		The <constant>RESUME</constant> flag affects only the behavior
5560		of <function>snd_pcm_resume()</function>.
5561		(Thus, in theory,
5562		<constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5563		to be handled in the trigger callback when no
5564		<constant>SNDRV_PCM_INFO_RESUME</constant> flag is set.  But,
5565		it's better to keep it for compatibility reasons.)
5566		</para>
5567	    <para>
5568	      In the earlier version of ALSA drivers, a common
5569	      power-management layer was provided, but it has been removed.
5570	      The driver needs to define the suspend/resume hooks according to
5571	      the bus the device is connected to.  In the case of PCI drivers, the
5572	      callbacks look like below:
5573	
5574	      <informalexample>
5575	        <programlisting>
5576	<![CDATA[
5577	  #ifdef CONFIG_PM
5578	  static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5579	  {
5580	          .... /* do things for suspend */
5581	          return 0;
5582	  }
5583	  static int snd_my_resume(struct pci_dev *pci)
5584	  {
5585	          .... /* do things for suspend */
5586	          return 0;
5587	  }
5588	  #endif
5589	]]>
5590	        </programlisting>
5591	      </informalexample>
5592	    </para>
5593	
5594	    <para>
5595	      The scheme of the real suspend job is as follows.
5596	
5597	      <orderedlist>
5598	        <listitem><para>Retrieve the card and the chip data.</para></listitem>
5599	        <listitem><para>Call <function>snd_power_change_state()</function> with
5600		  <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5601		  power status.</para></listitem>
5602	        <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5603		<listitem><para>If AC97 codecs are used, call
5604		<function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5605	        <listitem><para>Save the register values if necessary.</para></listitem>
5606	        <listitem><para>Stop the hardware if necessary.</para></listitem>
5607	        <listitem><para>Disable the PCI device by calling
5608		  <function>pci_disable_device()</function>.  Then, call
5609	          <function>pci_save_state()</function> at last.</para></listitem>
5610	      </orderedlist>
5611	    </para>
5612	
5613	    <para>
5614	      A typical code would be like:
5615	
5616	      <informalexample>
5617	        <programlisting>
5618	<![CDATA[
5619	  static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5620	  {
5621	          /* (1) */
5622	          struct snd_card *card = pci_get_drvdata(pci);
5623	          struct mychip *chip = card->private_data;
5624	          /* (2) */
5625	          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5626	          /* (3) */
5627	          snd_pcm_suspend_all(chip->pcm);
5628	          /* (4) */
5629	          snd_ac97_suspend(chip->ac97);
5630	          /* (5) */
5631	          snd_mychip_save_registers(chip);
5632	          /* (6) */
5633	          snd_mychip_stop_hardware(chip);
5634	          /* (7) */
5635	          pci_disable_device(pci);
5636	          pci_save_state(pci);
5637	          return 0;
5638	  }
5639	]]>
5640	        </programlisting>
5641	      </informalexample>
5642	    </para>
5643	
5644	    <para>
5645	    The scheme of the real resume job is as follows.
5646	
5647	    <orderedlist>
5648	    <listitem><para>Retrieve the card and the chip data.</para></listitem>
5649	    <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5650	    	Then enable the pci device again by calling <function>pci_enable_device()</function>.
5651		Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5652	    <listitem><para>Re-initialize the chip.</para></listitem>
5653	    <listitem><para>Restore the saved registers if necessary.</para></listitem>
5654	    <listitem><para>Resume the mixer, e.g. calling
5655	    <function>snd_ac97_resume()</function>.</para></listitem>
5656	    <listitem><para>Restart the hardware (if any).</para></listitem>
5657	    <listitem><para>Call <function>snd_power_change_state()</function> with
5658		<constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5659	    </orderedlist>
5660	    </para>
5661	
5662	    <para>
5663	    A typical code would be like:
5664	
5665	      <informalexample>
5666	        <programlisting>
5667	<![CDATA[
5668	  static int mychip_resume(struct pci_dev *pci)
5669	  {
5670	          /* (1) */
5671	          struct snd_card *card = pci_get_drvdata(pci);
5672	          struct mychip *chip = card->private_data;
5673	          /* (2) */
5674	          pci_restore_state(pci);
5675	          pci_enable_device(pci);
5676	          pci_set_master(pci);
5677	          /* (3) */
5678	          snd_mychip_reinit_chip(chip);
5679	          /* (4) */
5680	          snd_mychip_restore_registers(chip);
5681	          /* (5) */
5682	          snd_ac97_resume(chip->ac97);
5683	          /* (6) */
5684	          snd_mychip_restart_chip(chip);
5685	          /* (7) */
5686	          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5687	          return 0;
5688	  }
5689	]]>
5690	        </programlisting>
5691	      </informalexample>
5692	    </para>
5693	
5694	    <para>
5695		As shown in the above, it's better to save registers after
5696		suspending the PCM operations via
5697		<function>snd_pcm_suspend_all()</function> or
5698		<function>snd_pcm_suspend()</function>.  It means that the PCM
5699		streams are already stoppped when the register snapshot is
5700		taken.  But, remember that you don't have to restart the PCM
5701		stream in the resume callback. It'll be restarted via 
5702		trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5703		when necessary.
5704	    </para>
5705	
5706	    <para>
5707	      OK, we have all callbacks now. Let's set them up. In the
5708	      initialization of the card, make sure that you can get the chip
5709	      data from the card instance, typically via
5710	      <structfield>private_data</structfield> field, in case you
5711	      created the chip data individually.
5712	
5713	      <informalexample>
5714	        <programlisting>
5715	<![CDATA[
5716	  static int snd_mychip_probe(struct pci_dev *pci,
5717	                              const struct pci_device_id *pci_id)
5718	  {
5719	          ....
5720	          struct snd_card *card;
5721	          struct mychip *chip;
5722	          int err;
5723	          ....
5724	          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5725	                             0, &card);
5726	          ....
5727	          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5728	          ....
5729	          card->private_data = chip;
5730	          ....
5731	  }
5732	]]>
5733	        </programlisting>
5734	      </informalexample>
5735	
5736		When you created the chip data with
5737		<function>snd_card_new()</function>, it's anyway accessible
5738		via <structfield>private_data</structfield> field.
5739	
5740	      <informalexample>
5741	        <programlisting>
5742	<![CDATA[
5743	  static int snd_mychip_probe(struct pci_dev *pci,
5744	                              const struct pci_device_id *pci_id)
5745	  {
5746	          ....
5747	          struct snd_card *card;
5748	          struct mychip *chip;
5749	          int err;
5750	          ....
5751	          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5752	                             sizeof(struct mychip), &card);
5753	          ....
5754	          chip = card->private_data;
5755	          ....
5756	  }
5757	]]>
5758	        </programlisting>
5759	      </informalexample>
5760	
5761	    </para>
5762	
5763	    <para>
5764	      If you need a space to save the registers, allocate the
5765		buffer for it here, too, since it would be fatal
5766	    if you cannot allocate a memory in the suspend phase.
5767	    The allocated buffer should be released in the corresponding
5768	    destructor.
5769	    </para>
5770	
5771	    <para>
5772	      And next, set suspend/resume callbacks to the pci_driver.
5773	
5774	      <informalexample>
5775	        <programlisting>
5776	<![CDATA[
5777	  static struct pci_driver driver = {
5778	          .name = KBUILD_MODNAME,
5779	          .id_table = snd_my_ids,
5780	          .probe = snd_my_probe,
5781	          .remove = snd_my_remove,
5782	  #ifdef CONFIG_PM
5783	          .suspend = snd_my_suspend,
5784	          .resume = snd_my_resume,
5785	  #endif
5786	  };
5787	]]>
5788	        </programlisting>
5789	      </informalexample>
5790	    </para>
5791	
5792	  </chapter>
5793	
5794	
5795	<!-- ****************************************************** -->
5796	<!-- Module Parameters  -->
5797	<!-- ****************************************************** -->
5798	  <chapter id="module-parameters">
5799	    <title>Module Parameters</title>
5800	    <para>
5801	      There are standard module options for ALSA. At least, each
5802	      module should have the <parameter>index</parameter>,
5803	      <parameter>id</parameter> and <parameter>enable</parameter>
5804	      options. 
5805	    </para>
5806	
5807	    <para>
5808	      If the module supports multiple cards (usually up to
5809	      8 = <constant>SNDRV_CARDS</constant> cards), they should be
5810	      arrays. The default initial values are defined already as
5811	      constants for easier programming:
5812	
5813	      <informalexample>
5814	        <programlisting>
5815	<![CDATA[
5816	  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5817	  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5818	  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5819	]]>
5820	        </programlisting>
5821	      </informalexample>
5822	    </para>
5823	
5824	    <para>
5825	      If the module supports only a single card, they could be single
5826	    variables, instead.  <parameter>enable</parameter> option is not
5827	    always necessary in this case, but it would be better to have a
5828	    dummy option for compatibility.
5829	    </para>
5830	
5831	    <para>
5832	      The module parameters must be declared with the standard
5833	    <function>module_param()()</function>,
5834	    <function>module_param_array()()</function> and
5835	    <function>MODULE_PARM_DESC()</function> macros.
5836	    </para>
5837	
5838	    <para>
5839	      The typical coding would be like below:
5840	
5841	      <informalexample>
5842	        <programlisting>
5843	<![CDATA[
5844	  #define CARD_NAME "My Chip"
5845	
5846	  module_param_array(index, int, NULL, 0444);
5847	  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5848	  module_param_array(id, charp, NULL, 0444);
5849	  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5850	  module_param_array(enable, bool, NULL, 0444);
5851	  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5852	]]>
5853	        </programlisting>
5854	      </informalexample>
5855	    </para>
5856	
5857	    <para>
5858	      Also, don't forget to define the module description, classes,
5859	      license and devices. Especially, the recent modprobe requires to
5860	      define the module license as GPL, etc., otherwise the system is
5861	      shown as <quote>tainted</quote>. 
5862	
5863	      <informalexample>
5864	        <programlisting>
5865	<![CDATA[
5866	  MODULE_DESCRIPTION("My Chip");
5867	  MODULE_LICENSE("GPL");
5868	  MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5869	]]>
5870	        </programlisting>
5871	      </informalexample>
5872	    </para>
5873	
5874	  </chapter>
5875	
5876	
5877	<!-- ****************************************************** -->
5878	<!-- How To Put Your Driver  -->
5879	<!-- ****************************************************** -->
5880	  <chapter id="how-to-put-your-driver">
5881	    <title>How To Put Your Driver Into ALSA Tree</title>
5882		<section>
5883		<title>General</title>
5884		<para>
5885		So far, you've learned how to write the driver codes.
5886		And you might have a question now: how to put my own
5887		driver into the ALSA driver tree?
5888		Here (finally :) the standard procedure is described briefly.
5889		</para>
5890	
5891		<para>
5892		Suppose that you create a new PCI driver for the card
5893		<quote>xyz</quote>.  The card module name would be
5894		snd-xyz.  The new driver is usually put into the alsa-driver
5895		tree, <filename>alsa-driver/pci</filename> directory in
5896		the case of PCI cards.
5897		Then the driver is evaluated, audited and tested
5898		by developers and users.  After a certain time, the driver
5899		will go to the alsa-kernel tree (to the corresponding directory,
5900		such as <filename>alsa-kernel/pci</filename>) and eventually
5901	 	will be integrated into the Linux 2.6 tree (the directory would be
5902		<filename>linux/sound/pci</filename>).
5903		</para>
5904	
5905		<para>
5906		In the following sections, the driver code is supposed
5907		to be put into alsa-driver tree. The two cases are covered:
5908		a driver consisting of a single source file and one consisting
5909		of several source files.
5910		</para>
5911		</section>
5912	
5913		<section>
5914		<title>Driver with A Single Source File</title>
5915		<para>
5916		<orderedlist>
5917		<listitem>
5918		<para>
5919		Modify alsa-driver/pci/Makefile
5920		</para>
5921	
5922		<para>
5923		Suppose you have a file xyz.c.  Add the following
5924		two lines
5925	      <informalexample>
5926	        <programlisting>
5927	<![CDATA[
5928	  snd-xyz-objs := xyz.o
5929	  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5930	]]>
5931	        </programlisting>
5932	      </informalexample>
5933		</para>
5934		</listitem>
5935	
5936		<listitem>
5937		<para>
5938		Create the Kconfig entry
5939		</para>
5940	
5941		<para>
5942		Add the new entry of Kconfig for your xyz driver.
5943	      <informalexample>
5944	        <programlisting>
5945	<![CDATA[
5946	  config SND_XYZ
5947	          tristate "Foobar XYZ"
5948	          depends on SND
5949	          select SND_PCM
5950	          help
5951	            Say Y here to include support for Foobar XYZ soundcard.
5952	
5953	            To compile this driver as a module, choose M here: the module
5954	            will be called snd-xyz.
5955	]]>
5956	        </programlisting>
5957	      </informalexample>
5958	
5959		the line, select SND_PCM, specifies that the driver xyz supports
5960		PCM.  In addition to SND_PCM, the following components are
5961		supported for select command:
5962		SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5963		SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5964		Add the select command for each supported component.
5965		</para>
5966	
5967		<para>
5968		Note that some selections imply the lowlevel selections.
5969		For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5970		AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5971		You don't need to give the lowlevel selections again.
5972		</para>
5973	
5974		<para>
5975		For the details of Kconfig script, refer to the kbuild
5976		documentation.
5977		</para>
5978	
5979		</listitem>
5980	
5981		<listitem>
5982		<para>
5983		Run cvscompile script to re-generate the configure script and
5984		build the whole stuff again.
5985		</para>
5986		</listitem>
5987		</orderedlist>
5988		</para>
5989		</section>
5990	
5991		<section>
5992		<title>Drivers with Several Source Files</title>
5993		<para>
5994		Suppose that the driver snd-xyz have several source files.
5995		They are located in the new subdirectory,
5996		pci/xyz.
5997	
5998		<orderedlist>
5999		<listitem>
6000		<para>
6001		Add a new directory (<filename>xyz</filename>) in
6002		<filename>alsa-driver/pci/Makefile</filename> as below
6003	
6004	      <informalexample>
6005	        <programlisting>
6006	<![CDATA[
6007	  obj-$(CONFIG_SND) += xyz/
6008	]]>
6009	        </programlisting>
6010	      </informalexample>
6011		</para>
6012		</listitem>
6013	
6014		<listitem>
6015		<para>
6016		Under the directory <filename>xyz</filename>, create a Makefile
6017	
6018	      <example>
6019		<title>Sample Makefile for a driver xyz</title>
6020	        <programlisting>
6021	<![CDATA[
6022	  ifndef SND_TOPDIR
6023	  SND_TOPDIR=../..
6024	  endif
6025	
6026	  include $(SND_TOPDIR)/toplevel.config
6027	  include $(SND_TOPDIR)/Makefile.conf
6028	
6029	  snd-xyz-objs := xyz.o abc.o def.o
6030	
6031	  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6032	
6033	  include $(SND_TOPDIR)/Rules.make
6034	]]>
6035	        </programlisting>
6036	      </example>
6037		</para>
6038		</listitem>
6039	
6040		<listitem>
6041		<para>
6042		Create the Kconfig entry
6043		</para>
6044	
6045		<para>
6046		This procedure is as same as in the last section.
6047		</para>
6048		</listitem>
6049	
6050		<listitem>
6051		<para>
6052		Run cvscompile script to re-generate the configure script and
6053		build the whole stuff again.
6054		</para>
6055		</listitem>
6056		</orderedlist>
6057		</para>
6058		</section>
6059	
6060	  </chapter>
6061	
6062	<!-- ****************************************************** -->
6063	<!-- Useful Functions  -->
6064	<!-- ****************************************************** -->
6065	  <chapter id="useful-functions">
6066	    <title>Useful Functions</title>
6067	
6068	    <section id="useful-functions-snd-printk">
6069	      <title><function>snd_printk()</function> and friends</title>
6070	      <para>
6071	        ALSA provides a verbose version of the
6072	      <function>printk()</function> function. If a kernel config
6073	      <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6074	      function prints the given message together with the file name
6075	      and the line of the caller. The <constant>KERN_XXX</constant>
6076	      prefix is processed as 
6077	      well as the original <function>printk()</function> does, so it's
6078	      recommended to add this prefix, e.g. 
6079	
6080	        <informalexample>
6081	          <programlisting>
6082	<![CDATA[
6083	  snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6084	]]>
6085	          </programlisting>
6086	        </informalexample>
6087	      </para>
6088	
6089	      <para>
6090	        There are also <function>printk()</function>'s for
6091	      debugging. <function>snd_printd()</function> can be used for
6092	      general debugging purposes. If
6093	      <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6094	      compiled, and works just like
6095	      <function>snd_printk()</function>. If the ALSA is compiled
6096	      without the debugging flag, it's ignored. 
6097	      </para>
6098	
6099	      <para>
6100	        <function>snd_printdd()</function> is compiled in only when
6101	      <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6102	      that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6103	      even if you configure the alsa-driver with
6104	      <option>--with-debug=full</option> option. You need to give
6105	      explicitly <option>--with-debug=detect</option> option instead. 
6106	      </para>
6107	    </section>
6108	
6109	    <section id="useful-functions-snd-bug">
6110	      <title><function>snd_BUG()</function></title>
6111	      <para>
6112	        It shows the <computeroutput>BUG?</computeroutput> message and
6113	      stack trace as well as <function>snd_BUG_ON</function> at the point.
6114	      It's useful to show that a fatal error happens there. 
6115	      </para>
6116	      <para>
6117		 When no debug flag is set, this macro is ignored. 
6118	      </para>
6119	    </section>
6120	
6121	    <section id="useful-functions-snd-bug-on">
6122	      <title><function>snd_BUG_ON()</function></title>
6123	      <para>
6124	        <function>snd_BUG_ON()</function> macro is similar with
6125		<function>WARN_ON()</function> macro. For example,  
6126	
6127	        <informalexample>
6128	          <programlisting>
6129	<![CDATA[
6130	  snd_BUG_ON(!pointer);
6131	]]>
6132	          </programlisting>
6133	        </informalexample>
6134	
6135		or it can be used as the condition,
6136	        <informalexample>
6137	          <programlisting>
6138	<![CDATA[
6139	  if (snd_BUG_ON(non_zero_is_bug))
6140	          return -EINVAL;
6141	]]>
6142	          </programlisting>
6143	        </informalexample>
6144	
6145	      </para>
6146	
6147	      <para>
6148	        The macro takes an conditional expression to evaluate.
6149		When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
6150		expression is non-zero, it shows the warning message such as
6151		<computeroutput>BUG? (xxx)</computeroutput>
6152		normally followed by stack trace.
6153	
6154		In both cases it returns the evaluated value.
6155	      </para>
6156	
6157	    </section>
6158	
6159	  </chapter>
6160	
6161	
6162	<!-- ****************************************************** -->
6163	<!-- Acknowledgments  -->
6164	<!-- ****************************************************** -->
6165	  <chapter id="acknowledgments">
6166	    <title>Acknowledgments</title>
6167	    <para>
6168	      I would like to thank Phil Kerr for his help for improvement and
6169	      corrections of this document. 
6170	    </para>
6171	    <para>
6172	    Kevin Conder reformatted the original plain-text to the
6173	    DocBook format.
6174	    </para>
6175	    <para>
6176	    Giuliano Pochini corrected typos and contributed the example codes
6177	    in the hardware constraints section.
6178	    </para>
6179	  </chapter>
6180	</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.