blob: cab4ec58e46e6570be19d7f343bfc5671804684f [file] [log] [blame]
Takashi Iwai5f8206c2009-02-09 08:50:43 +01001<?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" []>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004
5<!-- ****************************************************** -->
6<!-- Header -->
7<!-- ****************************************************** -->
Takashi Iwai5f8206c2009-02-09 08:50:43 +01008<book id="Writing-an-ALSA-Driver">
Linus Torvalds1da177e2005-04-16 15:20:36 -07009 <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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +020021 <date>Oct 15, 2007</date>
Clemens Ladischd1761d12007-09-10 08:05:19 +020022 <edition>0.3.7</edition>
Linus Torvalds1da177e2005-04-16 15:20:36 -070023
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>
Takashi Iwai7c22f1a2005-10-10 11:46:31 +020033 Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email>
Linus Torvalds1da177e2005-04-16 15:20:36 -070034 </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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +020070 driver. The document focuses mainly on PCI soundcards.
Linus Torvalds1da177e2005-04-16 15:20:36 -070071 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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +020078 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070083 the standard way to write a PCI sound driver on ALSA.
84 </para>
85
86 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +020087 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070090 code-base in the ALSA 0.5.x tree, so you can compare the differences.
91 </para>
92
93 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +020094 This document is still a draft version. Any feedback and
Linus Torvalds1da177e2005-04-16 15:20:36 -070095 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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200109 The ALSA drivers are provided in two ways.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110 </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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200117 contains purely the source code for the Linux 2.6 (or later)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700118 tree. This tree is designed only for compilation on 2.6 or
119 later environment. The latter, alsa-driver, contains many subtle
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200120 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,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700122 and additional drivers which are still in development or in
123 tests. The drivers in alsa-driver tree will be moved to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200124 alsa-kernel (and eventually to the 2.6 kernel tree) when they are
Linus Torvalds1da177e2005-04-16 15:20:36 -0700125 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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200170 This directory contains the middle layer which is the heart
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171 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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200183 code is stored in <filename>core/seq/oss</filename> directory (see
Linus Torvalds1da177e2005-04-16 15:20:36 -0700184 <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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200202 This directory and its sub-directories are for the ALSA
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203 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,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200231 which are to be exported to user-space, or included by
Linus Torvalds1da177e2005-04-16 15:20:36 -0700232 several files at different directories. Basically, the private
233 header files should not be placed in this directory, but you may
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200234 still find files there, due to historical reasons :)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235 </para>
236 </section>
237
238 <section id="file-tree-drivers-directory">
239 <title>drivers directory</title>
240 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200241 This directory contains code shared among different drivers
242 on different architectures. They are hence supposed not to be
Linus Torvalds1da177e2005-04-16 15:20:36 -0700243 architecture-specific.
244 For example, the dummy pcm driver and the serial MIDI
245 driver are found in this directory. In the sub-directories,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200246 there is code for components which are independent from
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247 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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200273 own i2c code for some cards, because the soundcard needs only a
Linus Torvalds1da177e2005-04-16 15:20:36 -0700274 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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200294 the <filename>synth/emux</filename> sub-directory.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700295 </para>
296 </section>
297
298 <section id="file-tree-pci-directory">
299 <title>pci directory</title>
300 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200301 This directory and its sub-directories hold the top-level card modules
302 for PCI soundcards and the code specific to the PCI BUS.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700303 </para>
304
305 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200306 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).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700309 </para>
310 </section>
311
312 <section id="file-tree-isa-directory">
313 <title>isa directory</title>
314 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200315 This directory and its sub-directories hold the top-level card modules
Linus Torvalds1da177e2005-04-16 15:20:36 -0700316 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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200323 They are used for top-level card modules which are
324 specific to one of these architectures.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700325 </para>
326 </section>
327
328 <section id="file-tree-usb-directory">
329 <title>usb directory</title>
330 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200331 This directory contains the USB-audio driver. In the latest version, the
332 USB MIDI driver is integrated in the usb-audio driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700333 </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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200340 drivers will be in the pci directory, because their API is identical
341 to that of standard PCI cards.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700342 </para>
343 </section>
344
345 <section id="file-tree-oss-directory">
346 <title>oss directory</title>
347 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200348 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 :)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700351 </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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200365 The minimum flow for PCI soundcards is as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700366
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>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200373 <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>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700380 </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
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200389 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700392
393 <example>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200394 <title>Basic Flow for PCI Drivers - Example</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700395 <programlisting>
396<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -0700397 #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") */
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200404 /* SNDRV_CARDS: maximum number of cards supported by this module */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
Rusty Russella67ff6a2011-12-15 13:49:36 +1030407 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700408
409 /* definition of the chip-specific record */
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100410 struct mychip {
411 struct snd_card *card;
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200412 /* the rest of the implementation will be in section
413 * "PCI Resource Management"
Takashi Iwai95a5b082007-07-26 16:50:09 +0200414 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700415 };
416
417 /* chip-specific destructor
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200418 * (see "PCI Resource Management")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700419 */
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100420 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700421 {
Takashi Iwai95a5b082007-07-26 16:50:09 +0200422 .... /* will be implemented later... */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700423 }
424
425 /* component-destructor
426 * (see "Management of Cards and Components")
427 */
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100428 static int snd_mychip_dev_free(struct snd_device *device)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700429 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100430 return snd_mychip_free(device->device_data);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700431 }
432
433 /* chip-specific constructor
434 * (see "Management of Cards and Components")
435 */
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100436 static int __devinit snd_mychip_create(struct snd_card *card,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700437 struct pci_dev *pci,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100438 struct mychip **rchip)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700439 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100440 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700441 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100442 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700443 .dev_free = snd_mychip_dev_free,
444 };
445
446 *rchip = NULL;
447
Takashi Iwai95a5b082007-07-26 16:50:09 +0200448 /* check PCI availability here
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200449 * (see "PCI Resource Management")
Takashi Iwai95a5b082007-07-26 16:50:09 +0200450 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700451 ....
452
453 /* allocate a chip-specific data with zero filled */
Takashi Iwai561b2202005-09-09 14:22:34 +0200454 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700455 if (chip == NULL)
456 return -ENOMEM;
457
458 chip->card = card;
459
Takashi Iwai95a5b082007-07-26 16:50:09 +0200460 /* rest of initialization here; will be implemented
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200461 * later, see "PCI Resource Management"
Takashi Iwai95a5b082007-07-26 16:50:09 +0200462 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700463 ....
464
Takashi Iwai95a5b082007-07-26 16:50:09 +0200465 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
466 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700467 snd_mychip_free(chip);
468 return err;
469 }
470
471 snd_card_set_dev(card, &pci->dev);
472
473 *rchip = chip;
474 return 0;
475 }
476
477 /* constructor -- see "Constructor" sub-section */
478 static int __devinit snd_mychip_probe(struct pci_dev *pci,
479 const struct pci_device_id *pci_id)
480 {
481 static int dev;
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100482 struct snd_card *card;
483 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700484 int err;
485
486 /* (1) */
487 if (dev >= SNDRV_CARDS)
488 return -ENODEV;
489 if (!enable[dev]) {
490 dev++;
491 return -ENOENT;
492 }
493
494 /* (2) */
Takashi Iwaid4533792008-12-28 16:45:34 +0100495 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
496 if (err < 0)
497 return err;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700498
499 /* (3) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200500 err = snd_mychip_create(card, pci, &chip);
501 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700502 snd_card_free(card);
503 return err;
504 }
505
506 /* (4) */
507 strcpy(card->driver, "My Chip");
508 strcpy(card->shortname, "My Own Chip 123");
509 sprintf(card->longname, "%s at 0x%lx irq %i",
510 card->shortname, chip->ioport, chip->irq);
511
512 /* (5) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200513 .... /* implemented later */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700514
515 /* (6) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200516 err = snd_card_register(card);
517 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700518 snd_card_free(card);
519 return err;
520 }
521
522 /* (7) */
523 pci_set_drvdata(pci, card);
524 dev++;
525 return 0;
526 }
527
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200528 /* destructor -- see the "Destructor" sub-section */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700529 static void __devexit snd_mychip_remove(struct pci_dev *pci)
530 {
531 snd_card_free(pci_get_drvdata(pci));
532 pci_set_drvdata(pci, NULL);
533 }
534]]>
535 </programlisting>
536 </example>
537 </para>
538 </section>
539
540 <section id="basic-flow-constructor">
541 <title>Constructor</title>
542 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200543 The real constructor of PCI drivers is the <function>probe</function> callback.
544 The <function>probe</function> callback and other component-constructors which are called
545 from the <function>probe</function> callback should be defined with
546 the <parameter>__devinit</parameter> prefix. You
547 cannot use the <parameter>__init</parameter> prefix for them,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700548 because any PCI device could be a hotplug device.
549 </para>
550
551 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200552 In the <function>probe</function> callback, the following scheme is often used.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700553 </para>
554
555 <section id="basic-flow-constructor-device-index">
556 <title>1) Check and increment the device index.</title>
557 <para>
558 <informalexample>
559 <programlisting>
560<![CDATA[
561 static int dev;
562 ....
563 if (dev >= SNDRV_CARDS)
564 return -ENODEV;
565 if (!enable[dev]) {
566 dev++;
567 return -ENOENT;
568 }
569]]>
570 </programlisting>
571 </informalexample>
572
573 where enable[dev] is the module option.
574 </para>
575
576 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200577 Each time the <function>probe</function> callback is called, check the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700578 availability of the device. If not available, simply increment
579 the device index and returns. dev will be incremented also
580 later (<link
581 linkend="basic-flow-constructor-set-pci"><citetitle>step
582 7</citetitle></link>).
583 </para>
584 </section>
585
586 <section id="basic-flow-constructor-create-card">
587 <title>2) Create a card instance</title>
588 <para>
589 <informalexample>
590 <programlisting>
591<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100592 struct snd_card *card;
Takashi Iwaid4533792008-12-28 16:45:34 +0100593 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700594 ....
Takashi Iwaid4533792008-12-28 16:45:34 +0100595 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700596]]>
597 </programlisting>
598 </informalexample>
599 </para>
600
601 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200602 The details will be explained in the section
Linus Torvalds1da177e2005-04-16 15:20:36 -0700603 <link linkend="card-management-card-instance"><citetitle>
604 Management of Cards and Components</citetitle></link>.
605 </para>
606 </section>
607
608 <section id="basic-flow-constructor-create-main">
609 <title>3) Create a main component</title>
610 <para>
611 In this part, the PCI resources are allocated.
612
613 <informalexample>
614 <programlisting>
615<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100616 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700617 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +0200618 err = snd_mychip_create(card, pci, &chip);
619 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700620 snd_card_free(card);
621 return err;
622 }
623]]>
624 </programlisting>
625 </informalexample>
626
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200627 The details will be explained in the section <link
Linus Torvalds1da177e2005-04-16 15:20:36 -0700628 linkend="pci-resource"><citetitle>PCI Resource
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200629 Management</citetitle></link>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700630 </para>
631 </section>
632
633 <section id="basic-flow-constructor-main-component">
634 <title>4) Set the driver ID and name strings.</title>
635 <para>
636 <informalexample>
637 <programlisting>
638<![CDATA[
639 strcpy(card->driver, "My Chip");
640 strcpy(card->shortname, "My Own Chip 123");
641 sprintf(card->longname, "%s at 0x%lx irq %i",
642 card->shortname, chip->ioport, chip->irq);
643]]>
644 </programlisting>
645 </informalexample>
646
647 The driver field holds the minimal ID string of the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200648 chip. This is used by alsa-lib's configurator, so keep it
Linus Torvalds1da177e2005-04-16 15:20:36 -0700649 simple but unique.
650 Even the same driver can have different driver IDs to
651 distinguish the functionality of each chip type.
652 </para>
653
654 <para>
655 The shortname field is a string shown as more verbose
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200656 name. The longname field contains the information
Linus Torvalds1da177e2005-04-16 15:20:36 -0700657 shown in <filename>/proc/asound/cards</filename>.
658 </para>
659 </section>
660
661 <section id="basic-flow-constructor-create-other">
662 <title>5) Create other components, such as mixer, MIDI, etc.</title>
663 <para>
664 Here you define the basic components such as
665 <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
666 mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
667 MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
668 and other interfaces.
669 Also, if you want a <link linkend="proc-interface"><citetitle>proc
670 file</citetitle></link>, define it here, too.
671 </para>
672 </section>
673
674 <section id="basic-flow-constructor-register-card">
675 <title>6) Register the card instance.</title>
676 <para>
677 <informalexample>
678 <programlisting>
679<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +0200680 err = snd_card_register(card);
681 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700682 snd_card_free(card);
683 return err;
684 }
685]]>
686 </programlisting>
687 </informalexample>
688 </para>
689
690 <para>
691 Will be explained in the section <link
692 linkend="card-management-registration"><citetitle>Management
693 of Cards and Components</citetitle></link>, too.
694 </para>
695 </section>
696
697 <section id="basic-flow-constructor-set-pci">
698 <title>7) Set the PCI driver data and return zero.</title>
699 <para>
700 <informalexample>
701 <programlisting>
702<![CDATA[
703 pci_set_drvdata(pci, card);
704 dev++;
705 return 0;
706]]>
707 </programlisting>
708 </informalexample>
709
710 In the above, the card record is stored. This pointer is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200711 used in the remove callback and power-management
Linus Torvalds1da177e2005-04-16 15:20:36 -0700712 callbacks, too.
713 </para>
714 </section>
715 </section>
716
717 <section id="basic-flow-destructor">
718 <title>Destructor</title>
719 <para>
720 The destructor, remove callback, simply releases the card
721 instance. Then the ALSA middle layer will release all the
722 attached components automatically.
723 </para>
724
725 <para>
726 It would be typically like the following:
727
728 <informalexample>
729 <programlisting>
730<![CDATA[
731 static void __devexit snd_mychip_remove(struct pci_dev *pci)
732 {
733 snd_card_free(pci_get_drvdata(pci));
734 pci_set_drvdata(pci, NULL);
735 }
736]]>
737 </programlisting>
738 </informalexample>
739
740 The above code assumes that the card pointer is set to the PCI
741 driver data.
742 </para>
743 </section>
744
745 <section id="basic-flow-header-files">
746 <title>Header Files</title>
747 <para>
748 For the above example, at least the following include files
749 are necessary.
750
751 <informalexample>
752 <programlisting>
753<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -0700754 #include <linux/init.h>
755 #include <linux/pci.h>
756 #include <linux/slab.h>
757 #include <sound/core.h>
758 #include <sound/initval.h>
759]]>
760 </programlisting>
761 </informalexample>
762
763 where the last one is necessary only when module options are
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200764 defined in the source file. If the code is split into several
765 files, the files without module options don't need them.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700766 </para>
767
768 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200769 In addition to these headers, you'll need
770 <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
771 handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
772 access. If you use the <function>mdelay()</function> or
Linus Torvalds1da177e2005-04-16 15:20:36 -0700773 <function>udelay()</function> functions, you'll need to include
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200774 <filename>&lt;linux/delay.h&gt;</filename> too.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700775 </para>
776
777 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200778 The ALSA interfaces like the PCM and control APIs are defined in other
779 <filename>&lt;sound/xxx.h&gt;</filename> header files.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700780 They have to be included after
781 <filename>&lt;sound/core.h&gt;</filename>.
782 </para>
783
784 </section>
785 </chapter>
786
787
788<!-- ****************************************************** -->
789<!-- Management of Cards and Components -->
790<!-- ****************************************************** -->
791 <chapter id="card-management">
792 <title>Management of Cards and Components</title>
793
794 <section id="card-management-card-instance">
795 <title>Card Instance</title>
796 <para>
797 For each soundcard, a <quote>card</quote> record must be allocated.
798 </para>
799
800 <para>
801 A card record is the headquarters of the soundcard. It manages
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200802 the whole list of devices (components) on the soundcard, such as
Linus Torvalds1da177e2005-04-16 15:20:36 -0700803 PCM, mixers, MIDI, synthesizer, and so on. Also, the card
804 record holds the ID and the name strings of the card, manages
805 the root of proc files, and controls the power-management states
806 and hotplug disconnections. The component list on the card
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200807 record is used to manage the correct release of resources at
Linus Torvalds1da177e2005-04-16 15:20:36 -0700808 destruction.
809 </para>
810
811 <para>
812 As mentioned above, to create a card instance, call
Takashi Iwaid4533792008-12-28 16:45:34 +0100813 <function>snd_card_create()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700814
815 <informalexample>
816 <programlisting>
817<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100818 struct snd_card *card;
Takashi Iwaid4533792008-12-28 16:45:34 +0100819 int err;
820 err = snd_card_create(index, id, module, extra_size, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700821]]>
822 </programlisting>
823 </informalexample>
824 </para>
825
826 <para>
Takashi Iwaid4533792008-12-28 16:45:34 +0100827 The function takes five arguments, the card-index number, the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700828 id string, the module pointer (usually
829 <constant>THIS_MODULE</constant>),
Takashi Iwaid4533792008-12-28 16:45:34 +0100830 the size of extra-data space, and the pointer to return the
831 card instance. The extra_size argument is used to
Linus Torvalds1da177e2005-04-16 15:20:36 -0700832 allocate card-&gt;private_data for the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200833 chip-specific data. Note that these data
Takashi Iwaid4533792008-12-28 16:45:34 +0100834 are allocated by <function>snd_card_create()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700835 </para>
836 </section>
837
838 <section id="card-management-component">
839 <title>Components</title>
840 <para>
841 After the card is created, you can attach the components
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200842 (devices) to the card instance. In an ALSA driver, a component is
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100843 represented as a struct <structname>snd_device</structname> object.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700844 A component can be a PCM instance, a control interface, a raw
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200845 MIDI interface, etc. Each such instance has one component
Linus Torvalds1da177e2005-04-16 15:20:36 -0700846 entry.
847 </para>
848
849 <para>
850 A component can be created via
851 <function>snd_device_new()</function> function.
852
853 <informalexample>
854 <programlisting>
855<![CDATA[
856 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
857]]>
858 </programlisting>
859 </informalexample>
860 </para>
861
862 <para>
863 This takes the card pointer, the device-level
864 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
865 callback pointers (<parameter>&amp;ops</parameter>). The
866 device-level defines the type of components and the order of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200867 registration and de-registration. For most components, the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700868 device-level is already defined. For a user-defined component,
869 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
870 </para>
871
872 <para>
873 This function itself doesn't allocate the data space. The data
874 must be allocated manually beforehand, and its pointer is passed
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200875 as the argument. This pointer is used as the
876 (<parameter>chip</parameter> identifier in the above example)
877 for the instance.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700878 </para>
879
880 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200881 Each pre-defined ALSA component such as ac97 and pcm calls
Linus Torvalds1da177e2005-04-16 15:20:36 -0700882 <function>snd_device_new()</function> inside its
883 constructor. The destructor for each component is defined in the
884 callback pointers. Hence, you don't need to take care of
885 calling a destructor for such a component.
886 </para>
887
888 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200889 If you wish to create your own component, you need to
890 set the destructor function to the dev_free callback in
891 the <parameter>ops</parameter>, so that it can be released
892 automatically via <function>snd_card_free()</function>.
893 The next example will show an implementation of chip-specific
894 data.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700895 </para>
896 </section>
897
898 <section id="card-management-chip-specific">
899 <title>Chip-Specific Data</title>
900 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200901 Chip-specific information, e.g. the I/O port address, its
Linus Torvalds1da177e2005-04-16 15:20:36 -0700902 resource pointer, or the irq number, is stored in the
903 chip-specific record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700904
905 <informalexample>
906 <programlisting>
907<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100908 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700909 ....
910 };
911]]>
912 </programlisting>
913 </informalexample>
914 </para>
915
916 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200917 In general, there are two ways of allocating the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700918 </para>
919
920 <section id="card-management-chip-specific-snd-card-new">
Takashi Iwaid4533792008-12-28 16:45:34 +0100921 <title>1. Allocating via <function>snd_card_create()</function>.</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700922 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200923 As mentioned above, you can pass the extra-data-length
Takashi Iwaid4533792008-12-28 16:45:34 +0100924 to the 4th argument of <function>snd_card_create()</function>, i.e.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700925
926 <informalexample>
927 <programlisting>
928<![CDATA[
Takashi Iwaid4533792008-12-28 16:45:34 +0100929 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
930 sizeof(struct mychip), &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700931]]>
932 </programlisting>
933 </informalexample>
934
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200935 struct <structname>mychip</structname> is the type of the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700936 </para>
937
938 <para>
939 In return, the allocated record can be accessed as
940
941 <informalexample>
942 <programlisting>
943<![CDATA[
Takashi Iwai437a5a42006-11-21 12:14:23 +0100944 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700945]]>
946 </programlisting>
947 </informalexample>
948
949 With this method, you don't have to allocate twice.
950 The record is released together with the card instance.
951 </para>
952 </section>
953
954 <section id="card-management-chip-specific-allocate-extra">
955 <title>2. Allocating an extra device.</title>
956
957 <para>
958 After allocating a card instance via
Takashi Iwaid4533792008-12-28 16:45:34 +0100959 <function>snd_card_create()</function> (with
960 <constant>0</constant> on the 4th arg), call
Takashi Iwai561b2202005-09-09 14:22:34 +0200961 <function>kzalloc()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700962
963 <informalexample>
964 <programlisting>
965<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100966 struct snd_card *card;
967 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +0100968 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700969 .....
Takashi Iwai561b2202005-09-09 14:22:34 +0200970 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700971]]>
972 </programlisting>
973 </informalexample>
974 </para>
975
976 <para>
977 The chip record should have the field to hold the card
978 pointer at least,
979
980 <informalexample>
981 <programlisting>
982<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100983 struct mychip {
984 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700985 ....
986 };
987]]>
988 </programlisting>
989 </informalexample>
990 </para>
991
992 <para>
993 Then, set the card pointer in the returned chip instance.
994
995 <informalexample>
996 <programlisting>
997<![CDATA[
998 chip->card = card;
999]]>
1000 </programlisting>
1001 </informalexample>
1002 </para>
1003
1004 <para>
1005 Next, initialize the fields, and register this chip
1006 record as a low-level device with a specified
1007 <parameter>ops</parameter>,
1008
1009 <informalexample>
1010 <programlisting>
1011<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001012 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001013 .dev_free = snd_mychip_dev_free,
1014 };
1015 ....
1016 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1017]]>
1018 </programlisting>
1019 </informalexample>
1020
1021 <function>snd_mychip_dev_free()</function> is the
1022 device-destructor function, which will call the real
1023 destructor.
1024 </para>
1025
1026 <para>
1027 <informalexample>
1028 <programlisting>
1029<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001030 static int snd_mychip_dev_free(struct snd_device *device)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001031 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001032 return snd_mychip_free(device->device_data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001033 }
1034]]>
1035 </programlisting>
1036 </informalexample>
1037
1038 where <function>snd_mychip_free()</function> is the real destructor.
1039 </para>
1040 </section>
1041 </section>
1042
1043 <section id="card-management-registration">
1044 <title>Registration and Release</title>
1045 <para>
1046 After all components are assigned, register the card instance
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001047 by calling <function>snd_card_register()</function>. Access
1048 to the device files is enabled at this point. That is, before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001049 <function>snd_card_register()</function> is called, the
1050 components are safely inaccessible from external side. If this
1051 call fails, exit the probe function after releasing the card via
1052 <function>snd_card_free()</function>.
1053 </para>
1054
1055 <para>
1056 For releasing the card instance, you can call simply
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001057 <function>snd_card_free()</function>. As mentioned earlier, all
Linus Torvalds1da177e2005-04-16 15:20:36 -07001058 components are released automatically by this call.
1059 </para>
1060
1061 <para>
1062 As further notes, the destructors (both
1063 <function>snd_mychip_dev_free</function> and
1064 <function>snd_mychip_free</function>) cannot be defined with
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001065 the <parameter>__devexit</parameter> prefix, because they may be
Linus Torvalds1da177e2005-04-16 15:20:36 -07001066 called from the constructor, too, at the false path.
1067 </para>
1068
1069 <para>
1070 For a device which allows hotplugging, you can use
Takashi Iwai2b29b132006-06-23 14:38:26 +02001071 <function>snd_card_free_when_closed</function>. This one will
1072 postpone the destruction until all devices are closed.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001073 </para>
1074
1075 </section>
1076
1077 </chapter>
1078
1079
1080<!-- ****************************************************** -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001081<!-- PCI Resource Management -->
Linus Torvalds1da177e2005-04-16 15:20:36 -07001082<!-- ****************************************************** -->
1083 <chapter id="pci-resource">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001084 <title>PCI Resource Management</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001085
1086 <section id="pci-resource-example">
1087 <title>Full Code Example</title>
1088 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001089 In this section, we'll complete the chip-specific constructor,
1090 destructor and PCI entries. Example code is shown first,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001091 below.
1092
1093 <example>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001094 <title>PCI Resource Management Example</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001095 <programlisting>
1096<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001097 struct mychip {
1098 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001099 struct pci_dev *pci;
1100
1101 unsigned long port;
1102 int irq;
1103 };
1104
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001105 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001106 {
1107 /* disable hardware here if any */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001108 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001109
1110 /* release the irq */
1111 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001112 free_irq(chip->irq, chip);
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001113 /* release the I/O ports & memory */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001114 pci_release_regions(chip->pci);
1115 /* disable the PCI entry */
1116 pci_disable_device(chip->pci);
1117 /* release the data */
1118 kfree(chip);
1119 return 0;
1120 }
1121
1122 /* chip-specific constructor */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001123 static int __devinit snd_mychip_create(struct snd_card *card,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001124 struct pci_dev *pci,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001125 struct mychip **rchip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001126 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001127 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001128 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001129 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001130 .dev_free = snd_mychip_dev_free,
1131 };
1132
1133 *rchip = NULL;
1134
1135 /* initialize the PCI entry */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001136 err = pci_enable_device(pci);
1137 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001138 return err;
1139 /* check PCI availability (28bit DMA) */
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001140 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1141 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001142 printk(KERN_ERR "error to set 28bit mask DMA\n");
1143 pci_disable_device(pci);
1144 return -ENXIO;
1145 }
1146
Takashi Iwai561b2202005-09-09 14:22:34 +02001147 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001148 if (chip == NULL) {
1149 pci_disable_device(pci);
1150 return -ENOMEM;
1151 }
1152
1153 /* initialize the stuff */
1154 chip->card = card;
1155 chip->pci = pci;
1156 chip->irq = -1;
1157
1158 /* (1) PCI resource allocation */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001159 err = pci_request_regions(pci, "My Chip");
1160 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001161 kfree(chip);
1162 pci_disable_device(pci);
1163 return err;
1164 }
1165 chip->port = pci_resource_start(pci, 0);
1166 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001167 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001168 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1169 snd_mychip_free(chip);
1170 return -EBUSY;
1171 }
1172 chip->irq = pci->irq;
1173
1174 /* (2) initialization of the chip hardware */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001175 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001176
Takashi Iwai95a5b082007-07-26 16:50:09 +02001177 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1178 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001179 snd_mychip_free(chip);
1180 return err;
1181 }
1182
1183 snd_card_set_dev(card, &pci->dev);
1184
1185 *rchip = chip;
1186 return 0;
1187 }
1188
1189 /* PCI IDs */
Takashi Iwaif40b6892006-07-05 16:51:05 +02001190 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001191 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1192 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1193 ....
1194 { 0, }
1195 };
1196 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1197
1198 /* pci_driver definition */
1199 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001200 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001201 .id_table = snd_mychip_ids,
1202 .probe = snd_mychip_probe,
1203 .remove = __devexit_p(snd_mychip_remove),
1204 };
1205
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001206 /* module initialization */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001207 static int __init alsa_card_mychip_init(void)
1208 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001209 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001210 }
1211
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001212 /* module clean up */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001213 static void __exit alsa_card_mychip_exit(void)
1214 {
1215 pci_unregister_driver(&driver);
1216 }
1217
1218 module_init(alsa_card_mychip_init)
1219 module_exit(alsa_card_mychip_exit)
1220
1221 EXPORT_NO_SYMBOLS; /* for old kernels only */
1222]]>
1223 </programlisting>
1224 </example>
1225 </para>
1226 </section>
1227
1228 <section id="pci-resource-some-haftas">
1229 <title>Some Hafta's</title>
1230 <para>
1231 The allocation of PCI resources is done in the
1232 <function>probe()</function> function, and usually an extra
1233 <function>xxx_create()</function> function is written for this
Tobias Klauser56b146d2006-04-10 22:54:21 -07001234 purpose.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001235 </para>
1236
1237 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001238 In the case of PCI devices, you first have to call
1239 the <function>pci_enable_device()</function> function before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001240 allocating resources. Also, you need to set the proper PCI DMA
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001241 mask to limit the accessed I/O range. In some cases, you might
Linus Torvalds1da177e2005-04-16 15:20:36 -07001242 need to call <function>pci_set_master()</function> function,
Tobias Klauser56b146d2006-04-10 22:54:21 -07001243 too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001244 </para>
1245
1246 <para>
1247 Suppose the 28bit mask, and the code to be added would be like:
1248
1249 <informalexample>
1250 <programlisting>
1251<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001252 err = pci_enable_device(pci);
1253 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001254 return err;
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001255 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1256 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001257 printk(KERN_ERR "error to set 28bit mask DMA\n");
1258 pci_disable_device(pci);
1259 return -ENXIO;
1260 }
1261
1262]]>
1263 </programlisting>
1264 </informalexample>
1265 </para>
1266 </section>
1267
1268 <section id="pci-resource-resource-allocation">
1269 <title>Resource Allocation</title>
1270 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001271 The allocation of I/O ports and irqs is done via standard kernel
Linus Torvalds1da177e2005-04-16 15:20:36 -07001272 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1273 that. And these resources must be released in the destructor
1274 function (see below). Also, on ALSA 0.9.x, you don't need to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001275 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001276 </para>
1277
1278 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001279 Now assume that the PCI device has an I/O port with 8 bytes
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001280 and an interrupt. Then struct <structname>mychip</structname> will have the
Tobias Klauser56b146d2006-04-10 22:54:21 -07001281 following fields:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001282
1283 <informalexample>
1284 <programlisting>
1285<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001286 struct mychip {
1287 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001288
1289 unsigned long port;
1290 int irq;
1291 };
1292]]>
1293 </programlisting>
1294 </informalexample>
1295 </para>
1296
1297 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001298 For an I/O port (and also a memory region), you need to have
Linus Torvalds1da177e2005-04-16 15:20:36 -07001299 the resource pointer for the standard resource management. For
1300 an irq, you have to keep only the irq number (integer). But you
1301 need to initialize this number as -1 before actual allocation,
1302 since irq 0 is valid. The port address and its resource pointer
1303 can be initialized as null by
Takashi Iwai561b2202005-09-09 14:22:34 +02001304 <function>kzalloc()</function> automatically, so you
Linus Torvalds1da177e2005-04-16 15:20:36 -07001305 don't have to take care of resetting them.
1306 </para>
1307
1308 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001309 The allocation of an I/O port is done like this:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001310
1311 <informalexample>
1312 <programlisting>
1313<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001314 err = pci_request_regions(pci, "My Chip");
1315 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001316 kfree(chip);
1317 pci_disable_device(pci);
1318 return err;
1319 }
1320 chip->port = pci_resource_start(pci, 0);
1321]]>
1322 </programlisting>
1323 </informalexample>
1324 </para>
1325
1326 <para>
1327 <!-- obsolete -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001328 It will reserve the I/O port region of 8 bytes of the given
Linus Torvalds1da177e2005-04-16 15:20:36 -07001329 PCI device. The returned value, chip-&gt;res_port, is allocated
1330 via <function>kmalloc()</function> by
1331 <function>request_region()</function>. The pointer must be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001332 released via <function>kfree()</function>, but there is a
1333 problem with this. This issue will be explained later.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001334 </para>
1335
1336 <para>
1337 The allocation of an interrupt source is done like this:
1338
1339 <informalexample>
1340 <programlisting>
1341<![CDATA[
1342 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001343 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001344 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1345 snd_mychip_free(chip);
1346 return -EBUSY;
1347 }
1348 chip->irq = pci->irq;
1349]]>
1350 </programlisting>
1351 </informalexample>
1352
1353 where <function>snd_mychip_interrupt()</function> is the
1354 interrupt handler defined <link
1355 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1356 Note that chip-&gt;irq should be defined
1357 only when <function>request_irq()</function> succeeded.
1358 </para>
1359
1360 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001361 On the PCI bus, interrupts can be shared. Thus,
1362 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
Linus Torvalds1da177e2005-04-16 15:20:36 -07001363 <function>request_irq()</function>.
1364 </para>
1365
1366 <para>
1367 The last argument of <function>request_irq()</function> is the
1368 data pointer passed to the interrupt handler. Usually, the
1369 chip-specific record is used for that, but you can use what you
1370 like, too.
1371 </para>
1372
1373 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001374 I won't give details about the interrupt handler at this
Linus Torvalds1da177e2005-04-16 15:20:36 -07001375 point, but at least its appearance can be explained now. The
1376 interrupt handler looks usually like the following:
1377
1378 <informalexample>
1379 <programlisting>
1380<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01001381 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001382 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001383 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001384 ....
1385 return IRQ_HANDLED;
1386 }
1387]]>
1388 </programlisting>
1389 </informalexample>
1390 </para>
1391
1392 <para>
1393 Now let's write the corresponding destructor for the resources
1394 above. The role of destructor is simple: disable the hardware
1395 (if already activated) and release the resources. So far, we
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001396 have no hardware part, so the disabling code is not written here.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001397 </para>
1398
1399 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001400 To release the resources, the <quote>check-and-release</quote>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001401 method is a safer way. For the interrupt, do like this:
1402
1403 <informalexample>
1404 <programlisting>
1405<![CDATA[
1406 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001407 free_irq(chip->irq, chip);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001408]]>
1409 </programlisting>
1410 </informalexample>
1411
1412 Since the irq number can start from 0, you should initialize
1413 chip-&gt;irq with a negative value (e.g. -1), so that you can
1414 check the validity of the irq number as above.
1415 </para>
1416
1417 <para>
1418 When you requested I/O ports or memory regions via
1419 <function>pci_request_region()</function> or
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001420 <function>pci_request_regions()</function> like in this example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001421 release the resource(s) using the corresponding function,
1422 <function>pci_release_region()</function> or
1423 <function>pci_release_regions()</function>.
1424
1425 <informalexample>
1426 <programlisting>
1427<![CDATA[
1428 pci_release_regions(chip->pci);
1429]]>
1430 </programlisting>
1431 </informalexample>
1432 </para>
1433
1434 <para>
1435 When you requested manually via <function>request_region()</function>
1436 or <function>request_mem_region</function>, you can release it via
1437 <function>release_resource()</function>. Suppose that you keep
1438 the resource pointer returned from <function>request_region()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001439 in chip-&gt;res_port, the release procedure looks like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001440
1441 <informalexample>
1442 <programlisting>
1443<![CDATA[
Takashi Iwaib1d57762005-10-10 11:56:31 +02001444 release_and_free_resource(chip->res_port);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001445]]>
1446 </programlisting>
1447 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001448 </para>
1449
1450 <para>
1451 Don't forget to call <function>pci_disable_device()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001452 before the end.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001453 </para>
1454
1455 <para>
1456 And finally, release the chip-specific record.
1457
1458 <informalexample>
1459 <programlisting>
1460<![CDATA[
1461 kfree(chip);
1462]]>
1463 </programlisting>
1464 </informalexample>
1465 </para>
1466
1467 <para>
1468 Again, remember that you cannot
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001469 use the <parameter>__devexit</parameter> prefix for this destructor.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001470 </para>
1471
1472 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001473 We didn't implement the hardware disabling part in the above.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001474 If you need to do this, please note that the destructor may be
1475 called even before the initialization of the chip is completed.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001476 It would be better to have a flag to skip hardware disabling
Linus Torvalds1da177e2005-04-16 15:20:36 -07001477 if the hardware was not initialized yet.
1478 </para>
1479
1480 <para>
1481 When the chip-data is assigned to the card using
1482 <function>snd_device_new()</function> with
1483 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1484 called at the last. That is, it is assured that all other
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001485 components like PCMs and controls have already been released.
1486 You don't have to stop PCMs, etc. explicitly, but just
1487 call low-level hardware stopping.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001488 </para>
1489
1490 <para>
1491 The management of a memory-mapped region is almost as same as
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001492 the management of an I/O port. You'll need three fields like
Linus Torvalds1da177e2005-04-16 15:20:36 -07001493 the following:
1494
1495 <informalexample>
1496 <programlisting>
1497<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001498 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001499 ....
1500 unsigned long iobase_phys;
1501 void __iomem *iobase_virt;
1502 };
1503]]>
1504 </programlisting>
1505 </informalexample>
1506
1507 and the allocation would be like below:
1508
1509 <informalexample>
1510 <programlisting>
1511<![CDATA[
1512 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1513 kfree(chip);
1514 return err;
1515 }
1516 chip->iobase_phys = pci_resource_start(pci, 0);
1517 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1518 pci_resource_len(pci, 0));
1519]]>
1520 </programlisting>
1521 </informalexample>
1522
1523 and the corresponding destructor would be:
1524
1525 <informalexample>
1526 <programlisting>
1527<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001528 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001529 {
1530 ....
1531 if (chip->iobase_virt)
1532 iounmap(chip->iobase_virt);
1533 ....
1534 pci_release_regions(chip->pci);
1535 ....
1536 }
1537]]>
1538 </programlisting>
1539 </informalexample>
1540 </para>
1541
1542 </section>
1543
1544 <section id="pci-resource-device-struct">
1545 <title>Registration of Device Struct</title>
1546 <para>
1547 At some point, typically after calling <function>snd_device_new()</function>,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001548 you need to register the struct <structname>device</structname> of the chip
Linus Torvalds1da177e2005-04-16 15:20:36 -07001549 you're handling for udev and co. ALSA provides a macro for compatibility with
1550 older kernels. Simply call like the following:
1551 <informalexample>
1552 <programlisting>
1553<![CDATA[
1554 snd_card_set_dev(card, &pci->dev);
1555]]>
1556 </programlisting>
1557 </informalexample>
1558 so that it stores the PCI's device pointer to the card. This will be
1559 referred by ALSA core functions later when the devices are registered.
1560 </para>
1561 <para>
1562 In the case of non-PCI, pass the proper device struct pointer of the BUS
1563 instead. (In the case of legacy ISA without PnP, you don't have to do
1564 anything.)
1565 </para>
1566 </section>
1567
1568 <section id="pci-resource-entries">
1569 <title>PCI Entries</title>
1570 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001571 So far, so good. Let's finish the missing PCI
1572 stuff. At first, we need a
Linus Torvalds1da177e2005-04-16 15:20:36 -07001573 <structname>pci_device_id</structname> table for this
1574 chipset. It's a table of PCI vendor/device ID number, and some
1575 masks.
1576 </para>
1577
1578 <para>
1579 For example,
1580
1581 <informalexample>
1582 <programlisting>
1583<![CDATA[
Takashi Iwaif40b6892006-07-05 16:51:05 +02001584 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001585 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1586 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1587 ....
1588 { 0, }
1589 };
1590 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1591]]>
1592 </programlisting>
1593 </informalexample>
1594 </para>
1595
1596 <para>
1597 The first and second fields of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001598 the <structname>pci_device_id</structname> structure are the vendor and
1599 device IDs. If you have no reason to filter the matching
1600 devices, you can leave the remaining fields as above. The last
1601 field of the <structname>pci_device_id</structname> struct contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07001602 private data for this entry. You can specify any value here, for
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001603 example, to define specific operations for supported device IDs.
1604 Such an example is found in the intel8x0 driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001605 </para>
1606
1607 <para>
1608 The last entry of this list is the terminator. You must
1609 specify this all-zero entry.
1610 </para>
1611
1612 <para>
1613 Then, prepare the <structname>pci_driver</structname> record:
1614
1615 <informalexample>
1616 <programlisting>
1617<![CDATA[
1618 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001619 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001620 .id_table = snd_mychip_ids,
1621 .probe = snd_mychip_probe,
1622 .remove = __devexit_p(snd_mychip_remove),
1623 };
1624]]>
1625 </programlisting>
1626 </informalexample>
1627 </para>
1628
1629 <para>
1630 The <structfield>probe</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001631 <structfield>remove</structfield> functions have already
1632 been defined in the previous sections.
1633 The <structfield>remove</structfield> function should
1634 be defined with the
Linus Torvalds1da177e2005-04-16 15:20:36 -07001635 <function>__devexit_p()</function> macro, so that it's not
1636 defined for built-in (and non-hot-pluggable) case. The
1637 <structfield>name</structfield>
1638 field is the name string of this device. Note that you must not
1639 use a slash <quote>/</quote> in this string.
1640 </para>
1641
1642 <para>
1643 And at last, the module entries:
1644
1645 <informalexample>
1646 <programlisting>
1647<![CDATA[
1648 static int __init alsa_card_mychip_init(void)
1649 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001650 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001651 }
1652
1653 static void __exit alsa_card_mychip_exit(void)
1654 {
1655 pci_unregister_driver(&driver);
1656 }
1657
1658 module_init(alsa_card_mychip_init)
1659 module_exit(alsa_card_mychip_exit)
1660]]>
1661 </programlisting>
1662 </informalexample>
1663 </para>
1664
1665 <para>
1666 Note that these module entries are tagged with
1667 <parameter>__init</parameter> and
1668 <parameter>__exit</parameter> prefixes, not
1669 <parameter>__devinit</parameter> nor
1670 <parameter>__devexit</parameter>.
1671 </para>
1672
1673 <para>
1674 Oh, one thing was forgotten. If you have no exported symbols,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001675 you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
Linus Torvalds1da177e2005-04-16 15:20:36 -07001676
1677 <informalexample>
1678 <programlisting>
1679<![CDATA[
1680 EXPORT_NO_SYMBOLS;
1681]]>
1682 </programlisting>
1683 </informalexample>
1684
1685 That's all!
1686 </para>
1687 </section>
1688 </chapter>
1689
1690
1691<!-- ****************************************************** -->
1692<!-- PCM Interface -->
1693<!-- ****************************************************** -->
1694 <chapter id="pcm-interface">
1695 <title>PCM Interface</title>
1696
1697 <section id="pcm-interface-general">
1698 <title>General</title>
1699 <para>
1700 The PCM middle layer of ALSA is quite powerful and it is only
1701 necessary for each driver to implement the low-level functions
1702 to access its hardware.
1703 </para>
1704
1705 <para>
1706 For accessing to the PCM layer, you need to include
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001707 <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001708 <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
1709 if you access to some functions related with hw_param.
1710 </para>
1711
1712 <para>
1713 Each card device can have up to four pcm instances. A pcm
1714 instance corresponds to a pcm device file. The limitation of
1715 number of instances comes only from the available bit size of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001716 the Linux's device numbers. Once when 64bit device number is
1717 used, we'll have more pcm instances available.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001718 </para>
1719
1720 <para>
1721 A pcm instance consists of pcm playback and capture streams,
1722 and each pcm stream consists of one or more pcm substreams. Some
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001723 soundcards support multiple playback functions. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001724 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1725 each open, a free substream is (usually) automatically chosen
1726 and opened. Meanwhile, when only one substream exists and it was
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001727 already opened, the successful open will either block
1728 or error with <constant>EAGAIN</constant> according to the
1729 file open mode. But you don't have to care about such details in your
1730 driver. The PCM middle layer will take care of such work.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001731 </para>
1732 </section>
1733
1734 <section id="pcm-interface-example">
1735 <title>Full Code Example</title>
1736 <para>
1737 The example code below does not include any hardware access
1738 routines but shows only the skeleton, how to build up the PCM
1739 interfaces.
1740
1741 <example>
1742 <title>PCM Example Code</title>
1743 <programlisting>
1744<![CDATA[
1745 #include <sound/pcm.h>
1746 ....
1747
1748 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001749 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001750 .info = (SNDRV_PCM_INFO_MMAP |
1751 SNDRV_PCM_INFO_INTERLEAVED |
1752 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1753 SNDRV_PCM_INFO_MMAP_VALID),
1754 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1755 .rates = SNDRV_PCM_RATE_8000_48000,
1756 .rate_min = 8000,
1757 .rate_max = 48000,
1758 .channels_min = 2,
1759 .channels_max = 2,
1760 .buffer_bytes_max = 32768,
1761 .period_bytes_min = 4096,
1762 .period_bytes_max = 32768,
1763 .periods_min = 1,
1764 .periods_max = 1024,
1765 };
1766
1767 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001768 static struct snd_pcm_hardware snd_mychip_capture_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001769 .info = (SNDRV_PCM_INFO_MMAP |
1770 SNDRV_PCM_INFO_INTERLEAVED |
1771 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1772 SNDRV_PCM_INFO_MMAP_VALID),
1773 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1774 .rates = SNDRV_PCM_RATE_8000_48000,
1775 .rate_min = 8000,
1776 .rate_max = 48000,
1777 .channels_min = 2,
1778 .channels_max = 2,
1779 .buffer_bytes_max = 32768,
1780 .period_bytes_min = 4096,
1781 .period_bytes_max = 32768,
1782 .periods_min = 1,
1783 .periods_max = 1024,
1784 };
1785
1786 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001787 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001788 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001789 struct mychip *chip = snd_pcm_substream_chip(substream);
1790 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001791
1792 runtime->hw = snd_mychip_playback_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001793 /* more hardware-initialization will be done here */
1794 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001795 return 0;
1796 }
1797
1798 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001799 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001800 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001801 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001802 /* the hardware-specific codes will be here */
1803 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001804 return 0;
1805
1806 }
1807
1808 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001809 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001810 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001811 struct mychip *chip = snd_pcm_substream_chip(substream);
1812 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001813
1814 runtime->hw = snd_mychip_capture_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001815 /* more hardware-initialization will be done here */
1816 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001817 return 0;
1818 }
1819
1820 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001821 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001822 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001823 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001824 /* the hardware-specific codes will be here */
1825 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001826 return 0;
1827
1828 }
1829
1830 /* hw_params callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001831 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1832 struct snd_pcm_hw_params *hw_params)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001833 {
1834 return snd_pcm_lib_malloc_pages(substream,
1835 params_buffer_bytes(hw_params));
1836 }
1837
1838 /* hw_free callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001839 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001840 {
1841 return snd_pcm_lib_free_pages(substream);
1842 }
1843
1844 /* prepare callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001845 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001846 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001847 struct mychip *chip = snd_pcm_substream_chip(substream);
1848 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001849
1850 /* set up the hardware with the current configuration
1851 * for example...
1852 */
1853 mychip_set_sample_format(chip, runtime->format);
1854 mychip_set_sample_rate(chip, runtime->rate);
1855 mychip_set_channels(chip, runtime->channels);
Takashi Iwai0b7bed42006-03-02 15:35:55 +01001856 mychip_set_dma_setup(chip, runtime->dma_addr,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001857 chip->buffer_size,
1858 chip->period_size);
1859 return 0;
1860 }
1861
1862 /* trigger callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001863 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001864 int cmd)
1865 {
1866 switch (cmd) {
1867 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001868 /* do something to start the PCM engine */
1869 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001870 break;
1871 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001872 /* do something to stop the PCM engine */
1873 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001874 break;
1875 default:
1876 return -EINVAL;
1877 }
1878 }
1879
1880 /* pointer callback */
1881 static snd_pcm_uframes_t
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001882 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001883 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001884 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001885 unsigned int current_ptr;
1886
1887 /* get the current hardware pointer */
1888 current_ptr = mychip_get_hw_pointer(chip);
1889 return current_ptr;
1890 }
1891
1892 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001893 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001894 .open = snd_mychip_playback_open,
1895 .close = snd_mychip_playback_close,
1896 .ioctl = snd_pcm_lib_ioctl,
1897 .hw_params = snd_mychip_pcm_hw_params,
1898 .hw_free = snd_mychip_pcm_hw_free,
1899 .prepare = snd_mychip_pcm_prepare,
1900 .trigger = snd_mychip_pcm_trigger,
1901 .pointer = snd_mychip_pcm_pointer,
1902 };
1903
1904 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001905 static struct snd_pcm_ops snd_mychip_capture_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001906 .open = snd_mychip_capture_open,
1907 .close = snd_mychip_capture_close,
1908 .ioctl = snd_pcm_lib_ioctl,
1909 .hw_params = snd_mychip_pcm_hw_params,
1910 .hw_free = snd_mychip_pcm_hw_free,
1911 .prepare = snd_mychip_pcm_prepare,
1912 .trigger = snd_mychip_pcm_trigger,
1913 .pointer = snd_mychip_pcm_pointer,
1914 };
1915
1916 /*
1917 * definitions of capture are omitted here...
1918 */
1919
1920 /* create a pcm device */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001921 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001922 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001923 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001924 int err;
1925
Takashi Iwai95a5b082007-07-26 16:50:09 +02001926 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1927 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001928 return err;
1929 pcm->private_data = chip;
1930 strcpy(pcm->name, "My Chip");
1931 chip->pcm = pcm;
1932 /* set operators */
1933 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1934 &snd_mychip_playback_ops);
1935 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1936 &snd_mychip_capture_ops);
1937 /* pre-allocation of buffers */
1938 /* NOTE: this may fail */
1939 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1940 snd_dma_pci_data(chip->pci),
1941 64*1024, 64*1024);
1942 return 0;
1943 }
1944]]>
1945 </programlisting>
1946 </example>
1947 </para>
1948 </section>
1949
1950 <section id="pcm-interface-constructor">
1951 <title>Constructor</title>
1952 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001953 A pcm instance is allocated by the <function>snd_pcm_new()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001954 function. It would be better to create a constructor for pcm,
1955 namely,
1956
1957 <informalexample>
1958 <programlisting>
1959<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001960 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001961 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001962 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001963 int err;
1964
Takashi Iwai95a5b082007-07-26 16:50:09 +02001965 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1966 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001967 return err;
1968 pcm->private_data = chip;
1969 strcpy(pcm->name, "My Chip");
1970 chip->pcm = pcm;
1971 ....
1972 return 0;
1973 }
1974]]>
1975 </programlisting>
1976 </informalexample>
1977 </para>
1978
1979 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001980 The <function>snd_pcm_new()</function> function takes four
Linus Torvalds1da177e2005-04-16 15:20:36 -07001981 arguments. The first argument is the card pointer to which this
1982 pcm is assigned, and the second is the ID string.
1983 </para>
1984
1985 <para>
1986 The third argument (<parameter>index</parameter>, 0 in the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001987 above) is the index of this new pcm. It begins from zero. If
1988 you create more than one pcm instances, specify the
Linus Torvalds1da177e2005-04-16 15:20:36 -07001989 different numbers in this argument. For example,
1990 <parameter>index</parameter> = 1 for the second PCM device.
1991 </para>
1992
1993 <para>
1994 The fourth and fifth arguments are the number of substreams
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001995 for playback and capture, respectively. Here 1 is used for
1996 both arguments. When no playback or capture substreams are available,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001997 pass 0 to the corresponding argument.
1998 </para>
1999
2000 <para>
2001 If a chip supports multiple playbacks or captures, you can
2002 specify more numbers, but they must be handled properly in
2003 open/close, etc. callbacks. When you need to know which
2004 substream you are referring to, then it can be obtained from
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002005 struct <structname>snd_pcm_substream</structname> data passed to each callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07002006 as follows:
2007
2008 <informalexample>
2009 <programlisting>
2010<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002011 struct snd_pcm_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002012 int index = substream->number;
2013]]>
2014 </programlisting>
2015 </informalexample>
2016 </para>
2017
2018 <para>
2019 After the pcm is created, you need to set operators for each
2020 pcm stream.
2021
2022 <informalexample>
2023 <programlisting>
2024<![CDATA[
2025 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
2026 &snd_mychip_playback_ops);
2027 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
2028 &snd_mychip_capture_ops);
2029]]>
2030 </programlisting>
2031 </informalexample>
2032 </para>
2033
2034 <para>
2035 The operators are defined typically like this:
2036
2037 <informalexample>
2038 <programlisting>
2039<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002040 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002041 .open = snd_mychip_pcm_open,
2042 .close = snd_mychip_pcm_close,
2043 .ioctl = snd_pcm_lib_ioctl,
2044 .hw_params = snd_mychip_pcm_hw_params,
2045 .hw_free = snd_mychip_pcm_hw_free,
2046 .prepare = snd_mychip_pcm_prepare,
2047 .trigger = snd_mychip_pcm_trigger,
2048 .pointer = snd_mychip_pcm_pointer,
2049 };
2050]]>
2051 </programlisting>
2052 </informalexample>
2053
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002054 All the callbacks are described in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002055 <link linkend="pcm-interface-operators"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002056 Operators</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002057 </para>
2058
2059 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002060 After setting the operators, you probably will want to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002061 pre-allocate the buffer. For the pre-allocation, simply call
2062 the following:
2063
2064 <informalexample>
2065 <programlisting>
2066<![CDATA[
2067 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2068 snd_dma_pci_data(chip->pci),
2069 64*1024, 64*1024);
2070]]>
2071 </programlisting>
2072 </informalexample>
2073
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002074 It will allocate a buffer up to 64kB as default.
2075 Buffer management details will be described in the later section <link
Linus Torvalds1da177e2005-04-16 15:20:36 -07002076 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2077 Management</citetitle></link>.
2078 </para>
2079
2080 <para>
2081 Additionally, you can set some extra information for this pcm
2082 in pcm-&gt;info_flags.
2083 The available values are defined as
2084 <constant>SNDRV_PCM_INFO_XXX</constant> in
2085 <filename>&lt;sound/asound.h&gt;</filename>, which is used for
2086 the hardware definition (described later). When your soundchip
2087 supports only half-duplex, specify like this:
2088
2089 <informalexample>
2090 <programlisting>
2091<![CDATA[
2092 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2093]]>
2094 </programlisting>
2095 </informalexample>
2096 </para>
2097 </section>
2098
2099 <section id="pcm-interface-destructor">
2100 <title>... And the Destructor?</title>
2101 <para>
2102 The destructor for a pcm instance is not always
2103 necessary. Since the pcm device will be released by the middle
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002104 layer code automatically, you don't have to call the destructor
Linus Torvalds1da177e2005-04-16 15:20:36 -07002105 explicitly.
2106 </para>
2107
2108 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002109 The destructor would be necessary if you created
2110 special records internally and needed to release them. In such a
Linus Torvalds1da177e2005-04-16 15:20:36 -07002111 case, set the destructor function to
2112 pcm-&gt;private_free:
2113
2114 <example>
2115 <title>PCM Instance with a Destructor</title>
2116 <programlisting>
2117<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002118 static void mychip_pcm_free(struct snd_pcm *pcm)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002119 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002120 struct mychip *chip = snd_pcm_chip(pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002121 /* free your own data */
2122 kfree(chip->my_private_pcm_data);
Takashi Iwai95a5b082007-07-26 16:50:09 +02002123 /* do what you like else */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002124 ....
2125 }
2126
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002127 static int __devinit snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002128 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002129 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002130 ....
2131 /* allocate your own data */
2132 chip->my_private_pcm_data = kmalloc(...);
2133 /* set the destructor */
2134 pcm->private_data = chip;
2135 pcm->private_free = mychip_pcm_free;
2136 ....
2137 }
2138]]>
2139 </programlisting>
2140 </example>
2141 </para>
2142 </section>
2143
2144 <section id="pcm-interface-runtime">
2145 <title>Runtime Pointer - The Chest of PCM Information</title>
2146 <para>
2147 When the PCM substream is opened, a PCM runtime instance is
2148 allocated and assigned to the substream. This pointer is
2149 accessible via <constant>substream-&gt;runtime</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002150 This runtime pointer holds most information you need
2151 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2152 pointers, mmap records, spinlocks, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002153 </para>
2154
2155 <para>
2156 The definition of runtime instance is found in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002157 <filename>&lt;sound/pcm.h&gt;</filename>. Here are
2158 the contents of this file:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002159 <informalexample>
2160 <programlisting>
2161<![CDATA[
2162struct _snd_pcm_runtime {
2163 /* -- Status -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002164 struct snd_pcm_substream *trigger_master;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002165 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2166 int overrange;
2167 snd_pcm_uframes_t avail_max;
2168 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2169 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2170
2171 /* -- HW params -- */
2172 snd_pcm_access_t access; /* access mode */
2173 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2174 snd_pcm_subformat_t subformat; /* subformat */
2175 unsigned int rate; /* rate in Hz */
2176 unsigned int channels; /* channels */
2177 snd_pcm_uframes_t period_size; /* period size */
2178 unsigned int periods; /* periods */
2179 snd_pcm_uframes_t buffer_size; /* buffer size */
2180 unsigned int tick_time; /* tick time */
2181 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2182 size_t byte_align;
2183 unsigned int frame_bits;
2184 unsigned int sample_bits;
2185 unsigned int info;
2186 unsigned int rate_num;
2187 unsigned int rate_den;
2188
2189 /* -- SW params -- */
Takashi Iwai07799e72005-10-10 11:49:49 +02002190 struct timespec tstamp_mode; /* mmap timestamp is updated */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002191 unsigned int period_step;
2192 unsigned int sleep_min; /* min ticks to sleep */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002193 snd_pcm_uframes_t start_threshold;
2194 snd_pcm_uframes_t stop_threshold;
2195 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2196 noise is nearest than this */
2197 snd_pcm_uframes_t silence_size; /* Silence filling size */
2198 snd_pcm_uframes_t boundary; /* pointers wrap point */
2199
2200 snd_pcm_uframes_t silenced_start;
2201 snd_pcm_uframes_t silenced_size;
2202
2203 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2204
2205 /* -- mmap -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002206 volatile struct snd_pcm_mmap_status *status;
2207 volatile struct snd_pcm_mmap_control *control;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002208 atomic_t mmap_count;
2209
2210 /* -- locking / scheduling -- */
2211 spinlock_t lock;
2212 wait_queue_head_t sleep;
2213 struct timer_list tick_timer;
2214 struct fasync_struct *fasync;
2215
2216 /* -- private section -- */
2217 void *private_data;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002218 void (*private_free)(struct snd_pcm_runtime *runtime);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002219
2220 /* -- hardware description -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002221 struct snd_pcm_hardware hw;
2222 struct snd_pcm_hw_constraints hw_constraints;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002223
2224 /* -- interrupt callbacks -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002225 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2226 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002227
2228 /* -- timer -- */
2229 unsigned int timer_resolution; /* timer resolution */
2230
2231 /* -- DMA -- */
2232 unsigned char *dma_area; /* DMA area */
2233 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2234 size_t dma_bytes; /* size of DMA area */
2235
2236 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2237
2238#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2239 /* -- OSS things -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002240 struct snd_pcm_oss_runtime oss;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002241#endif
2242};
2243]]>
2244 </programlisting>
2245 </informalexample>
2246 </para>
2247
2248 <para>
2249 For the operators (callbacks) of each sound driver, most of
2250 these records are supposed to be read-only. Only the PCM
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002251 middle-layer changes / updates them. The exceptions are
Linus Torvalds1da177e2005-04-16 15:20:36 -07002252 the hardware description (hw), interrupt callbacks
2253 (transfer_ack_xxx), DMA buffer information, and the private
2254 data. Besides, if you use the standard buffer allocation
2255 method via <function>snd_pcm_lib_malloc_pages()</function>,
2256 you don't need to set the DMA buffer information by yourself.
2257 </para>
2258
2259 <para>
2260 In the sections below, important records are explained.
2261 </para>
2262
2263 <section id="pcm-interface-runtime-hw">
2264 <title>Hardware Description</title>
2265 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002266 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002267 contains the definitions of the fundamental hardware
2268 configuration. Above all, you'll need to define this in
2269 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2270 the open callback</citetitle></link>.
2271 Note that the runtime instance holds the copy of the
2272 descriptor, not the pointer to the existing descriptor. That
2273 is, in the open callback, you can modify the copied descriptor
2274 (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
2275 number of channels is 1 only on some chip models, you can
2276 still use the same hardware descriptor and change the
2277 channels_max later:
2278 <informalexample>
2279 <programlisting>
2280<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002281 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002282 ...
2283 runtime->hw = snd_mychip_playback_hw; /* common definition */
2284 if (chip->model == VERY_OLD_ONE)
2285 runtime->hw.channels_max = 1;
2286]]>
2287 </programlisting>
2288 </informalexample>
2289 </para>
2290
2291 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002292 Typically, you'll have a hardware descriptor as below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002293 <informalexample>
2294 <programlisting>
2295<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002296 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002297 .info = (SNDRV_PCM_INFO_MMAP |
2298 SNDRV_PCM_INFO_INTERLEAVED |
2299 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2300 SNDRV_PCM_INFO_MMAP_VALID),
2301 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2302 .rates = SNDRV_PCM_RATE_8000_48000,
2303 .rate_min = 8000,
2304 .rate_max = 48000,
2305 .channels_min = 2,
2306 .channels_max = 2,
2307 .buffer_bytes_max = 32768,
2308 .period_bytes_min = 4096,
2309 .period_bytes_max = 32768,
2310 .periods_min = 1,
2311 .periods_max = 1024,
2312 };
2313]]>
2314 </programlisting>
2315 </informalexample>
2316 </para>
2317
2318 <para>
2319 <itemizedlist>
2320 <listitem><para>
2321 The <structfield>info</structfield> field contains the type and
2322 capabilities of this pcm. The bit flags are defined in
2323 <filename>&lt;sound/asound.h&gt;</filename> as
2324 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2325 have to specify whether the mmap is supported and which
2326 interleaved format is supported.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002327 When the is supported, add the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002328 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2329 hardware supports the interleaved or the non-interleaved
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002330 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
Linus Torvalds1da177e2005-04-16 15:20:36 -07002331 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2332 be set, respectively. If both are supported, you can set both,
2333 too.
2334 </para>
2335
2336 <para>
2337 In the above example, <constant>MMAP_VALID</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002338 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
Linus Torvalds1da177e2005-04-16 15:20:36 -07002339 mode. Usually both are set. Of course,
2340 <constant>MMAP_VALID</constant> is set only if the mmap is
2341 really supported.
2342 </para>
2343
2344 <para>
2345 The other possible flags are
2346 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2347 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2348 <constant>PAUSE</constant> bit means that the pcm supports the
2349 <quote>pause</quote> operation, while the
2350 <constant>RESUME</constant> bit means that the pcm supports
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002351 the full <quote>suspend/resume</quote> operation.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002352 If the <constant>PAUSE</constant> flag is set,
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002353 the <structfield>trigger</structfield> callback below
2354 must handle the corresponding (pause push/release) commands.
2355 The suspend/resume trigger commands can be defined even without
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002356 the <constant>RESUME</constant> flag. See <link
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002357 linkend="power-management"><citetitle>
2358 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002359 </para>
2360
2361 <para>
2362 When the PCM substreams can be synchronized (typically,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01002363 synchronized start/stop of a playback and a capture streams),
Linus Torvalds1da177e2005-04-16 15:20:36 -07002364 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2365 too. In this case, you'll need to check the linked-list of
2366 PCM substreams in the trigger callback. This will be
2367 described in the later section.
2368 </para>
2369 </listitem>
2370
2371 <listitem>
2372 <para>
2373 <structfield>formats</structfield> field contains the bit-flags
2374 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2375 If the hardware supports more than one format, give all or'ed
2376 bits. In the example above, the signed 16bit little-endian
2377 format is specified.
2378 </para>
2379 </listitem>
2380
2381 <listitem>
2382 <para>
2383 <structfield>rates</structfield> field contains the bit-flags of
2384 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2385 When the chip supports continuous rates, pass
2386 <constant>CONTINUOUS</constant> bit additionally.
2387 The pre-defined rate bits are provided only for typical
2388 rates. If your chip supports unconventional rates, you need to add
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002389 the <constant>KNOT</constant> bit and set up the hardware
Linus Torvalds1da177e2005-04-16 15:20:36 -07002390 constraint manually (explained later).
2391 </para>
2392 </listitem>
2393
2394 <listitem>
2395 <para>
2396 <structfield>rate_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002397 <structfield>rate_max</structfield> define the minimum and
2398 maximum sample rate. This should correspond somehow to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002399 <structfield>rates</structfield> bits.
2400 </para>
2401 </listitem>
2402
2403 <listitem>
2404 <para>
2405 <structfield>channel_min</structfield> and
2406 <structfield>channel_max</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002407 define, as you might already expected, the minimum and maximum
Linus Torvalds1da177e2005-04-16 15:20:36 -07002408 number of channels.
2409 </para>
2410 </listitem>
2411
2412 <listitem>
2413 <para>
2414 <structfield>buffer_bytes_max</structfield> defines the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002415 maximum buffer size in bytes. There is no
Linus Torvalds1da177e2005-04-16 15:20:36 -07002416 <structfield>buffer_bytes_min</structfield> field, since
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002417 it can be calculated from the minimum period size and the
2418 minimum number of periods.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002419 Meanwhile, <structfield>period_bytes_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002420 define the minimum and maximum size of the period in bytes.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002421 <structfield>periods_max</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002422 <structfield>periods_min</structfield> define the maximum and
2423 minimum number of periods in the buffer.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002424 </para>
2425
2426 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002427 The <quote>period</quote> is a term that corresponds to
2428 a fragment in the OSS world. The period defines the size at
2429 which a PCM interrupt is generated. This size strongly
Linus Torvalds1da177e2005-04-16 15:20:36 -07002430 depends on the hardware.
2431 Generally, the smaller period size will give you more
2432 interrupts, that is, more controls.
2433 In the case of capture, this size defines the input latency.
2434 On the other hand, the whole buffer size defines the
2435 output latency for the playback direction.
2436 </para>
2437 </listitem>
2438
2439 <listitem>
2440 <para>
2441 There is also a field <structfield>fifo_size</structfield>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002442 This specifies the size of the hardware FIFO, but currently it
2443 is neither used in the driver nor in the alsa-lib. So, you
Linus Torvalds1da177e2005-04-16 15:20:36 -07002444 can ignore this field.
2445 </para>
2446 </listitem>
2447 </itemizedlist>
2448 </para>
2449 </section>
2450
2451 <section id="pcm-interface-runtime-config">
2452 <title>PCM Configurations</title>
2453 <para>
2454 Ok, let's go back again to the PCM runtime records.
2455 The most frequently referred records in the runtime instance are
2456 the PCM configurations.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002457 The PCM configurations are stored in the runtime instance
Linus Torvalds1da177e2005-04-16 15:20:36 -07002458 after the application sends <type>hw_params</type> data via
2459 alsa-lib. There are many fields copied from hw_params and
2460 sw_params structs. For example,
2461 <structfield>format</structfield> holds the format type
2462 chosen by the application. This field contains the enum value
2463 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2464 </para>
2465
2466 <para>
2467 One thing to be noted is that the configured buffer and period
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002468 sizes are stored in <quote>frames</quote> in the runtime.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002469 In the ALSA world, 1 frame = channels * samples-size.
2470 For conversion between frames and bytes, you can use the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002471 <function>frames_to_bytes()</function> and
2472 <function>bytes_to_frames()</function> helper functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002473 <informalexample>
2474 <programlisting>
2475<![CDATA[
2476 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2477]]>
2478 </programlisting>
2479 </informalexample>
2480 </para>
2481
2482 <para>
2483 Also, many software parameters (sw_params) are
2484 stored in frames, too. Please check the type of the field.
2485 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2486 integer while <type>snd_pcm_sframes_t</type> is for the frames
2487 as signed integer.
2488 </para>
2489 </section>
2490
2491 <section id="pcm-interface-runtime-dma">
2492 <title>DMA Buffer Information</title>
2493 <para>
2494 The DMA buffer is defined by the following four fields,
2495 <structfield>dma_area</structfield>,
2496 <structfield>dma_addr</structfield>,
2497 <structfield>dma_bytes</structfield> and
2498 <structfield>dma_private</structfield>.
2499 The <structfield>dma_area</structfield> holds the buffer
2500 pointer (the logical address). You can call
2501 <function>memcpy</function> from/to
2502 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2503 holds the physical address of the buffer. This field is
2504 specified only when the buffer is a linear buffer.
2505 <structfield>dma_bytes</structfield> holds the size of buffer
2506 in bytes. <structfield>dma_private</structfield> is used for
2507 the ALSA DMA allocator.
2508 </para>
2509
2510 <para>
2511 If you use a standard ALSA function,
2512 <function>snd_pcm_lib_malloc_pages()</function>, for
2513 allocating the buffer, these fields are set by the ALSA middle
2514 layer, and you should <emphasis>not</emphasis> change them by
2515 yourself. You can read them but not write them.
2516 On the other hand, if you want to allocate the buffer by
2517 yourself, you'll need to manage it in hw_params callback.
2518 At least, <structfield>dma_bytes</structfield> is mandatory.
2519 <structfield>dma_area</structfield> is necessary when the
2520 buffer is mmapped. If your driver doesn't support mmap, this
2521 field is not necessary. <structfield>dma_addr</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002522 is also optional. You can use
Linus Torvalds1da177e2005-04-16 15:20:36 -07002523 <structfield>dma_private</structfield> as you like, too.
2524 </para>
2525 </section>
2526
2527 <section id="pcm-interface-runtime-status">
2528 <title>Running Status</title>
2529 <para>
2530 The running status can be referred via <constant>runtime-&gt;status</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002531 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002532 record. For example, you can get the current DMA hardware
2533 pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2534 </para>
2535
2536 <para>
2537 The DMA application pointer can be referred via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002538 <constant>runtime-&gt;control</constant>, which points to the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002539 struct <structname>snd_pcm_mmap_control</structname> record.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002540 However, accessing directly to this value is not recommended.
2541 </para>
2542 </section>
2543
2544 <section id="pcm-interface-runtime-private">
2545 <title>Private Data</title>
2546 <para>
2547 You can allocate a record for the substream and store it in
2548 <constant>runtime-&gt;private_data</constant>. Usually, this
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002549 is done in
Linus Torvalds1da177e2005-04-16 15:20:36 -07002550 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2551 the open callback</citetitle></link>.
2552 Don't mix this with <constant>pcm-&gt;private_data</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002553 The <constant>pcm-&gt;private_data</constant> usually points to the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002554 chip instance assigned statically at the creation of PCM, while the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002555 <constant>runtime-&gt;private_data</constant> points to a dynamic
2556 data structure created at the PCM open callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002557
2558 <informalexample>
2559 <programlisting>
2560<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002561 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002562 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002563 struct my_pcm_data *data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002564 ....
2565 data = kmalloc(sizeof(*data), GFP_KERNEL);
2566 substream->runtime->private_data = data;
2567 ....
2568 }
2569]]>
2570 </programlisting>
2571 </informalexample>
2572 </para>
2573
2574 <para>
2575 The allocated object must be released in
2576 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2577 the close callback</citetitle></link>.
2578 </para>
2579 </section>
2580
2581 <section id="pcm-interface-runtime-intr">
2582 <title>Interrupt Callbacks</title>
2583 <para>
2584 The field <structfield>transfer_ack_begin</structfield> and
2585 <structfield>transfer_ack_end</structfield> are called at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002586 the beginning and at the end of
Linus Torvalds1da177e2005-04-16 15:20:36 -07002587 <function>snd_pcm_period_elapsed()</function>, respectively.
2588 </para>
2589 </section>
2590
2591 </section>
2592
2593 <section id="pcm-interface-operators">
2594 <title>Operators</title>
2595 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002596 OK, now let me give details about each pcm callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07002597 (<parameter>ops</parameter>). In general, every callback must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002598 return 0 if successful, or a negative error number
2599 such as <constant>-EINVAL</constant>. To choose an appropriate
2600 error number, it is advised to check what value other parts of
2601 the kernel return when the same kind of request fails.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002602 </para>
2603
2604 <para>
2605 The callback function takes at least the argument with
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002606 <structname>snd_pcm_substream</structname> pointer. To retrieve
2607 the chip record from the given substream instance, you can use the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002608 following macro.
2609
2610 <informalexample>
2611 <programlisting>
2612<![CDATA[
2613 int xxx() {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002614 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002615 ....
2616 }
2617]]>
2618 </programlisting>
2619 </informalexample>
2620
2621 The macro reads <constant>substream-&gt;private_data</constant>,
2622 which is a copy of <constant>pcm-&gt;private_data</constant>.
2623 You can override the former if you need to assign different data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002624 records per PCM substream. For example, the cmi8330 driver assigns
Linus Torvalds1da177e2005-04-16 15:20:36 -07002625 different private_data for playback and capture directions,
2626 because it uses two different codecs (SB- and AD-compatible) for
2627 different directions.
2628 </para>
2629
2630 <section id="pcm-interface-operators-open-callback">
2631 <title>open callback</title>
2632 <para>
2633 <informalexample>
2634 <programlisting>
2635<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002636 static int snd_xxx_open(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002637]]>
2638 </programlisting>
2639 </informalexample>
2640
2641 This is called when a pcm substream is opened.
2642 </para>
2643
2644 <para>
2645 At least, here you have to initialize the runtime-&gt;hw
2646 record. Typically, this is done by like this:
2647
2648 <informalexample>
2649 <programlisting>
2650<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002651 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002652 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002653 struct mychip *chip = snd_pcm_substream_chip(substream);
2654 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002655
2656 runtime->hw = snd_mychip_playback_hw;
2657 return 0;
2658 }
2659]]>
2660 </programlisting>
2661 </informalexample>
2662
2663 where <parameter>snd_mychip_playback_hw</parameter> is the
2664 pre-defined hardware description.
2665 </para>
2666
2667 <para>
2668 You can allocate a private data in this callback, as described
2669 in <link linkend="pcm-interface-runtime-private"><citetitle>
2670 Private Data</citetitle></link> section.
2671 </para>
2672
2673 <para>
2674 If the hardware configuration needs more constraints, set the
2675 hardware constraints here, too.
2676 See <link linkend="pcm-interface-constraints"><citetitle>
2677 Constraints</citetitle></link> for more details.
2678 </para>
2679 </section>
2680
2681 <section id="pcm-interface-operators-close-callback">
2682 <title>close callback</title>
2683 <para>
2684 <informalexample>
2685 <programlisting>
2686<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002687 static int snd_xxx_close(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002688]]>
2689 </programlisting>
2690 </informalexample>
2691
2692 Obviously, this is called when a pcm substream is closed.
2693 </para>
2694
2695 <para>
2696 Any private instance for a pcm substream allocated in the
2697 open callback will be released here.
2698
2699 <informalexample>
2700 <programlisting>
2701<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002702 static int snd_xxx_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002703 {
2704 ....
2705 kfree(substream->runtime->private_data);
2706 ....
2707 }
2708]]>
2709 </programlisting>
2710 </informalexample>
2711 </para>
2712 </section>
2713
2714 <section id="pcm-interface-operators-ioctl-callback">
2715 <title>ioctl callback</title>
2716 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002717 This is used for any special call to pcm ioctls. But
Linus Torvalds1da177e2005-04-16 15:20:36 -07002718 usually you can pass a generic ioctl callback,
2719 <function>snd_pcm_lib_ioctl</function>.
2720 </para>
2721 </section>
2722
2723 <section id="pcm-interface-operators-hw-params-callback">
2724 <title>hw_params callback</title>
2725 <para>
2726 <informalexample>
2727 <programlisting>
2728<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002729 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2730 struct snd_pcm_hw_params *hw_params);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002731]]>
2732 </programlisting>
2733 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002734 </para>
2735
2736 <para>
2737 This is called when the hardware parameter
2738 (<structfield>hw_params</structfield>) is set
2739 up by the application,
2740 that is, once when the buffer size, the period size, the
2741 format, etc. are defined for the pcm substream.
2742 </para>
2743
2744 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002745 Many hardware setups should be done in this callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07002746 including the allocation of buffers.
2747 </para>
2748
2749 <para>
2750 Parameters to be initialized are retrieved by
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002751 <function>params_xxx()</function> macros. To allocate
Linus Torvalds1da177e2005-04-16 15:20:36 -07002752 buffer, you can call a helper function,
2753
2754 <informalexample>
2755 <programlisting>
2756<![CDATA[
2757 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2758]]>
2759 </programlisting>
2760 </informalexample>
2761
2762 <function>snd_pcm_lib_malloc_pages()</function> is available
2763 only when the DMA buffers have been pre-allocated.
2764 See the section <link
2765 linkend="buffer-and-memory-buffer-types"><citetitle>
2766 Buffer Types</citetitle></link> for more details.
2767 </para>
2768
2769 <para>
2770 Note that this and <structfield>prepare</structfield> callbacks
2771 may be called multiple times per initialization.
2772 For example, the OSS emulation may
2773 call these callbacks at each change via its ioctl.
2774 </para>
2775
2776 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002777 Thus, you need to be careful not to allocate the same buffers
2778 many times, which will lead to memory leaks! Calling the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002779 helper function above many times is OK. It will release the
2780 previous buffer automatically when it was already allocated.
2781 </para>
2782
2783 <para>
2784 Another note is that this callback is non-atomic
2785 (schedulable). This is important, because the
2786 <structfield>trigger</structfield> callback
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002787 is atomic (non-schedulable). That is, mutexes or any
Linus Torvalds1da177e2005-04-16 15:20:36 -07002788 schedule-related functions are not available in
2789 <structfield>trigger</structfield> callback.
2790 Please see the subsection
2791 <link linkend="pcm-interface-atomicity"><citetitle>
2792 Atomicity</citetitle></link> for details.
2793 </para>
2794 </section>
2795
2796 <section id="pcm-interface-operators-hw-free-callback">
2797 <title>hw_free callback</title>
2798 <para>
2799 <informalexample>
2800 <programlisting>
2801<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002802 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002803]]>
2804 </programlisting>
2805 </informalexample>
2806 </para>
2807
2808 <para>
2809 This is called to release the resources allocated via
2810 <structfield>hw_params</structfield>. For example, releasing the
2811 buffer via
2812 <function>snd_pcm_lib_malloc_pages()</function> is done by
2813 calling the following:
2814
2815 <informalexample>
2816 <programlisting>
2817<![CDATA[
2818 snd_pcm_lib_free_pages(substream);
2819]]>
2820 </programlisting>
2821 </informalexample>
2822 </para>
2823
2824 <para>
2825 This function is always called before the close callback is called.
2826 Also, the callback may be called multiple times, too.
2827 Keep track whether the resource was already released.
2828 </para>
2829 </section>
2830
2831 <section id="pcm-interface-operators-prepare-callback">
2832 <title>prepare callback</title>
2833 <para>
2834 <informalexample>
2835 <programlisting>
2836<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002837 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002838]]>
2839 </programlisting>
2840 </informalexample>
2841 </para>
2842
2843 <para>
2844 This callback is called when the pcm is
2845 <quote>prepared</quote>. You can set the format type, sample
2846 rate, etc. here. The difference from
2847 <structfield>hw_params</structfield> is that the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002848 <structfield>prepare</structfield> callback will be called each
Linus Torvalds1da177e2005-04-16 15:20:36 -07002849 time
2850 <function>snd_pcm_prepare()</function> is called, i.e. when
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002851 recovering after underruns, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002852 </para>
2853
2854 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002855 Note that this callback is now non-atomic.
2856 You can use schedule-related functions safely in this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002857 </para>
2858
2859 <para>
2860 In this and the following callbacks, you can refer to the
2861 values via the runtime record,
2862 substream-&gt;runtime.
2863 For example, to get the current
2864 rate, format or channels, access to
2865 runtime-&gt;rate,
2866 runtime-&gt;format or
2867 runtime-&gt;channels, respectively.
2868 The physical address of the allocated buffer is set to
2869 runtime-&gt;dma_area. The buffer and period sizes are
2870 in runtime-&gt;buffer_size and runtime-&gt;period_size,
2871 respectively.
2872 </para>
2873
2874 <para>
2875 Be careful that this callback will be called many times at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002876 each setup, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002877 </para>
2878 </section>
2879
2880 <section id="pcm-interface-operators-trigger-callback">
2881 <title>trigger callback</title>
2882 <para>
2883 <informalexample>
2884 <programlisting>
2885<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002886 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002887]]>
2888 </programlisting>
2889 </informalexample>
2890
2891 This is called when the pcm is started, stopped or paused.
2892 </para>
2893
2894 <para>
2895 Which action is specified in the second argument,
2896 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2897 <filename>&lt;sound/pcm.h&gt;</filename>. At least,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002898 the <constant>START</constant> and <constant>STOP</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002899 commands must be defined in this callback.
2900
2901 <informalexample>
2902 <programlisting>
2903<![CDATA[
2904 switch (cmd) {
2905 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002906 /* do something to start the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002907 break;
2908 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002909 /* do something to stop the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002910 break;
2911 default:
2912 return -EINVAL;
2913 }
2914]]>
2915 </programlisting>
2916 </informalexample>
2917 </para>
2918
2919 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002920 When the pcm supports the pause operation (given in the info
2921 field of the hardware table), the <constant>PAUSE_PUSE</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002922 and <constant>PAUSE_RELEASE</constant> commands must be
2923 handled here, too. The former is the command to pause the pcm,
2924 and the latter to restart the pcm again.
2925 </para>
2926
2927 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002928 When the pcm supports the suspend/resume operation,
2929 regardless of full or partial suspend/resume support,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002930 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002931 commands must be handled, too.
2932 These commands are issued when the power-management status is
2933 changed. Obviously, the <constant>SUSPEND</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002934 <constant>RESUME</constant> commands
2935 suspend and resume the pcm substream, and usually, they
2936 are identical to the <constant>STOP</constant> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07002937 <constant>START</constant> commands, respectively.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002938 See the <link linkend="power-management"><citetitle>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002939 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002940 </para>
2941
2942 <para>
2943 As mentioned, this callback is atomic. You cannot call
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002944 functions which may sleep.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002945 The trigger callback should be as minimal as possible,
2946 just really triggering the DMA. The other stuff should be
2947 initialized hw_params and prepare callbacks properly
2948 beforehand.
2949 </para>
2950 </section>
2951
2952 <section id="pcm-interface-operators-pointer-callback">
2953 <title>pointer callback</title>
2954 <para>
2955 <informalexample>
2956 <programlisting>
2957<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002958 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002959]]>
2960 </programlisting>
2961 </informalexample>
2962
2963 This callback is called when the PCM middle layer inquires
2964 the current hardware position on the buffer. The position must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002965 be returned in frames,
2966 ranging from 0 to buffer_size - 1.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002967 </para>
2968
2969 <para>
2970 This is called usually from the buffer-update routine in the
2971 pcm middle layer, which is invoked when
2972 <function>snd_pcm_period_elapsed()</function> is called in the
2973 interrupt routine. Then the pcm middle layer updates the
2974 position and calculates the available space, and wakes up the
2975 sleeping poll threads, etc.
2976 </para>
2977
2978 <para>
2979 This callback is also atomic.
2980 </para>
2981 </section>
2982
2983 <section id="pcm-interface-operators-copy-silence">
2984 <title>copy and silence callbacks</title>
2985 <para>
2986 These callbacks are not mandatory, and can be omitted in
2987 most cases. These callbacks are used when the hardware buffer
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002988 cannot be in the normal memory space. Some chips have their
Linus Torvalds1da177e2005-04-16 15:20:36 -07002989 own buffer on the hardware which is not mappable. In such a
2990 case, you have to transfer the data manually from the memory
2991 buffer to the hardware buffer. Or, if the buffer is
2992 non-contiguous on both physical and virtual memory spaces,
2993 these callbacks must be defined, too.
2994 </para>
2995
2996 <para>
2997 If these two callbacks are defined, copy and set-silence
2998 operations are done by them. The detailed will be described in
2999 the later section <link
3000 linkend="buffer-and-memory"><citetitle>Buffer and Memory
3001 Management</citetitle></link>.
3002 </para>
3003 </section>
3004
3005 <section id="pcm-interface-operators-ack">
3006 <title>ack callback</title>
3007 <para>
3008 This callback is also not mandatory. This callback is called
3009 when the appl_ptr is updated in read or write operations.
3010 Some drivers like emu10k1-fx and cs46xx need to track the
3011 current appl_ptr for the internal buffer, and this callback
3012 is useful only for such a purpose.
3013 </para>
3014 <para>
3015 This callback is atomic.
3016 </para>
3017 </section>
3018
3019 <section id="pcm-interface-operators-page-callback">
3020 <title>page callback</title>
3021
3022 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003023 This callback is optional too. This callback is used
3024 mainly for non-contiguous buffers. The mmap calls this
Linus Torvalds1da177e2005-04-16 15:20:36 -07003025 callback to get the page address. Some examples will be
3026 explained in the later section <link
3027 linkend="buffer-and-memory"><citetitle>Buffer and Memory
3028 Management</citetitle></link>, too.
3029 </para>
3030 </section>
3031 </section>
3032
3033 <section id="pcm-interface-interrupt-handler">
3034 <title>Interrupt Handler</title>
3035 <para>
3036 The rest of pcm stuff is the PCM interrupt handler. The
3037 role of PCM interrupt handler in the sound driver is to update
3038 the buffer position and to tell the PCM middle layer when the
3039 buffer position goes across the prescribed period size. To
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003040 inform this, call the <function>snd_pcm_period_elapsed()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003041 function.
3042 </para>
3043
3044 <para>
3045 There are several types of sound chips to generate the interrupts.
3046 </para>
3047
3048 <section id="pcm-interface-interrupt-handler-boundary">
3049 <title>Interrupts at the period (fragment) boundary</title>
3050 <para>
3051 This is the most frequently found type: the hardware
3052 generates an interrupt at each period boundary.
3053 In this case, you can call
3054 <function>snd_pcm_period_elapsed()</function> at each
3055 interrupt.
3056 </para>
3057
3058 <para>
3059 <function>snd_pcm_period_elapsed()</function> takes the
3060 substream pointer as its argument. Thus, you need to keep the
3061 substream pointer accessible from the chip instance. For
3062 example, define substream field in the chip record to hold the
3063 current running substream pointer, and set the pointer value
3064 at open callback (and reset at close callback).
3065 </para>
3066
3067 <para>
Adrian Bunk04187262006-06-30 18:23:04 +02003068 If you acquire a spinlock in the interrupt handler, and the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003069 lock is used in other pcm callbacks, too, then you have to
3070 release the lock before calling
3071 <function>snd_pcm_period_elapsed()</function>, because
3072 <function>snd_pcm_period_elapsed()</function> calls other pcm
3073 callbacks inside.
3074 </para>
3075
3076 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003077 Typical code would be like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003078
3079 <example>
3080 <title>Interrupt Handler Case #1</title>
3081 <programlisting>
3082<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003083 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003084 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003085 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003086 spin_lock(&chip->lock);
3087 ....
3088 if (pcm_irq_invoked(chip)) {
3089 /* call updater, unlock before it */
3090 spin_unlock(&chip->lock);
3091 snd_pcm_period_elapsed(chip->substream);
3092 spin_lock(&chip->lock);
Takashi Iwai95a5b082007-07-26 16:50:09 +02003093 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003094 }
3095 ....
3096 spin_unlock(&chip->lock);
3097 return IRQ_HANDLED;
3098 }
3099]]>
3100 </programlisting>
3101 </example>
3102 </para>
3103 </section>
3104
3105 <section id="pcm-interface-interrupt-handler-timer">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003106 <title>High frequency timer interrupts</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003107 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003108 This happense when the hardware doesn't generate interrupts
3109 at the period boundary but issues timer interrupts at a fixed
Linus Torvalds1da177e2005-04-16 15:20:36 -07003110 timer rate (e.g. es1968 or ymfpci drivers).
3111 In this case, you need to check the current hardware
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003112 position and accumulate the processed sample length at each
3113 interrupt. When the accumulated size exceeds the period
Linus Torvalds1da177e2005-04-16 15:20:36 -07003114 size, call
3115 <function>snd_pcm_period_elapsed()</function> and reset the
3116 accumulator.
3117 </para>
3118
3119 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003120 Typical code would be like the following.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003121
3122 <example>
3123 <title>Interrupt Handler Case #2</title>
3124 <programlisting>
3125<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003126 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003127 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003128 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003129 spin_lock(&chip->lock);
3130 ....
3131 if (pcm_irq_invoked(chip)) {
3132 unsigned int last_ptr, size;
3133 /* get the current hardware pointer (in frames) */
3134 last_ptr = get_hw_ptr(chip);
3135 /* calculate the processed frames since the
3136 * last update
3137 */
3138 if (last_ptr < chip->last_ptr)
3139 size = runtime->buffer_size + last_ptr
3140 - chip->last_ptr;
3141 else
3142 size = last_ptr - chip->last_ptr;
3143 /* remember the last updated point */
3144 chip->last_ptr = last_ptr;
3145 /* accumulate the size */
3146 chip->size += size;
3147 /* over the period boundary? */
3148 if (chip->size >= runtime->period_size) {
3149 /* reset the accumulator */
3150 chip->size %= runtime->period_size;
3151 /* call updater */
3152 spin_unlock(&chip->lock);
3153 snd_pcm_period_elapsed(substream);
3154 spin_lock(&chip->lock);
3155 }
Takashi Iwai95a5b082007-07-26 16:50:09 +02003156 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003157 }
3158 ....
3159 spin_unlock(&chip->lock);
3160 return IRQ_HANDLED;
3161 }
3162]]>
3163 </programlisting>
3164 </example>
3165 </para>
3166 </section>
3167
3168 <section id="pcm-interface-interrupt-handler-both">
3169 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3170 <para>
3171 In both cases, even if more than one period are elapsed, you
3172 don't have to call
3173 <function>snd_pcm_period_elapsed()</function> many times. Call
3174 only once. And the pcm layer will check the current hardware
3175 pointer and update to the latest status.
3176 </para>
3177 </section>
3178 </section>
3179
3180 <section id="pcm-interface-atomicity">
3181 <title>Atomicity</title>
3182 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003183 One of the most important (and thus difficult to debug) problems
3184 in kernel programming are race conditions.
3185 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3186 or semaphores. In general, if a race condition can happen
3187 in an interrupt handler, it has to be managed atomically, and you
3188 have to use a spinlock to protect the critical session. If the
3189 critical section is not in interrupt handler code and
3190 if taking a relatively long time to execute is acceptable, you
3191 should use mutexes or semaphores instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003192 </para>
3193
3194 <para>
3195 As already seen, some pcm callbacks are atomic and some are
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003196 not. For example, the <parameter>hw_params</parameter> callback is
Linus Torvalds1da177e2005-04-16 15:20:36 -07003197 non-atomic, while <parameter>trigger</parameter> callback is
3198 atomic. This means, the latter is called already in a spinlock
3199 held by the PCM middle layer. Please take this atomicity into
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003200 account when you choose a locking scheme in the callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003201 </para>
3202
3203 <para>
3204 In the atomic callbacks, you cannot use functions which may call
3205 <function>schedule</function> or go to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003206 <function>sleep</function>. Semaphores and mutexes can sleep,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003207 and hence they cannot be used inside the atomic callbacks
3208 (e.g. <parameter>trigger</parameter> callback).
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003209 To implement some delay in such a callback, please use
Linus Torvalds1da177e2005-04-16 15:20:36 -07003210 <function>udelay()</function> or <function>mdelay()</function>.
3211 </para>
3212
3213 <para>
3214 All three atomic callbacks (trigger, pointer, and ack) are
3215 called with local interrupts disabled.
3216 </para>
3217
3218 </section>
3219 <section id="pcm-interface-constraints">
3220 <title>Constraints</title>
3221 <para>
3222 If your chip supports unconventional sample rates, or only the
3223 limited samples, you need to set a constraint for the
3224 condition.
3225 </para>
3226
3227 <para>
3228 For example, in order to restrict the sample rates in the some
3229 supported values, use
3230 <function>snd_pcm_hw_constraint_list()</function>.
3231 You need to call this function in the open callback.
3232
3233 <example>
3234 <title>Example of Hardware Constraints</title>
3235 <programlisting>
3236<![CDATA[
3237 static unsigned int rates[] =
3238 {4000, 10000, 22050, 44100};
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003239 static struct snd_pcm_hw_constraint_list constraints_rates = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003240 .count = ARRAY_SIZE(rates),
3241 .list = rates,
3242 .mask = 0,
3243 };
3244
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003245 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003246 {
3247 int err;
3248 ....
3249 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3250 SNDRV_PCM_HW_PARAM_RATE,
3251 &constraints_rates);
3252 if (err < 0)
3253 return err;
3254 ....
3255 }
3256]]>
3257 </programlisting>
3258 </example>
3259 </para>
3260
3261 <para>
3262 There are many different constraints.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003263 Look at <filename>sound/pcm.h</filename> for a complete list.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003264 You can even define your own constraint rules.
3265 For example, let's suppose my_chip can manage a substream of 1 channel
3266 if and only if the format is S16_LE, otherwise it supports any format
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003267 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
Linus Torvalds1da177e2005-04-16 15:20:36 -07003268 other constraint_list). You can build a rule like this:
3269
3270 <example>
3271 <title>Example of Hardware Constraints for Channels</title>
3272 <programlisting>
3273<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003274 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3275 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003276 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003277 struct snd_interval *c = hw_param_interval(params,
3278 SNDRV_PCM_HW_PARAM_CHANNELS);
3279 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3280 struct snd_mask fmt;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003281
3282 snd_mask_any(&fmt); /* Init the struct */
3283 if (c->min < 2) {
3284 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3285 return snd_mask_refine(f, &fmt);
3286 }
3287 return 0;
3288 }
3289]]>
3290 </programlisting>
3291 </example>
3292 </para>
3293
3294 <para>
3295 Then you need to call this function to add your rule:
3296
3297 <informalexample>
3298 <programlisting>
3299<![CDATA[
3300 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3301 hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3302 -1);
3303]]>
3304 </programlisting>
3305 </informalexample>
3306 </para>
3307
3308 <para>
3309 The rule function is called when an application sets the number of
3310 channels. But an application can set the format before the number of
3311 channels. Thus you also need to define the inverse rule:
3312
3313 <example>
3314 <title>Example of Hardware Constraints for Channels</title>
3315 <programlisting>
3316<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003317 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3318 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003319 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003320 struct snd_interval *c = hw_param_interval(params,
3321 SNDRV_PCM_HW_PARAM_CHANNELS);
3322 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3323 struct snd_interval ch;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003324
3325 snd_interval_any(&ch);
3326 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3327 ch.min = ch.max = 1;
3328 ch.integer = 1;
3329 return snd_interval_refine(c, &ch);
3330 }
3331 return 0;
3332 }
3333]]>
3334 </programlisting>
3335 </example>
3336 </para>
3337
3338 <para>
3339 ...and in the open callback:
3340 <informalexample>
3341 <programlisting>
3342<![CDATA[
3343 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3344 hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3345 -1);
3346]]>
3347 </programlisting>
3348 </informalexample>
3349 </para>
3350
3351 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003352 I won't give more details here, rather I
Linus Torvalds1da177e2005-04-16 15:20:36 -07003353 would like to say, <quote>Luke, use the source.</quote>
3354 </para>
3355 </section>
3356
3357 </chapter>
3358
3359
3360<!-- ****************************************************** -->
3361<!-- Control Interface -->
3362<!-- ****************************************************** -->
3363 <chapter id="control-interface">
3364 <title>Control Interface</title>
3365
3366 <section id="control-interface-general">
3367 <title>General</title>
3368 <para>
3369 The control interface is used widely for many switches,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003370 sliders, etc. which are accessed from user-space. Its most
3371 important use is the mixer interface. In other words, since ALSA
3372 0.9.x, all the mixer stuff is implemented on the control kernel API.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003373 </para>
3374
3375 <para>
3376 ALSA has a well-defined AC97 control module. If your chip
3377 supports only the AC97 and nothing else, you can skip this
3378 section.
3379 </para>
3380
3381 <para>
3382 The control API is defined in
3383 <filename>&lt;sound/control.h&gt;</filename>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003384 Include this file if you want to add your own controls.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003385 </para>
3386 </section>
3387
3388 <section id="control-interface-definition">
3389 <title>Definition of Controls</title>
3390 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003391 To create a new control, you need to define the
3392 following three
Linus Torvalds1da177e2005-04-16 15:20:36 -07003393 callbacks: <structfield>info</structfield>,
3394 <structfield>get</structfield> and
3395 <structfield>put</structfield>. Then, define a
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003396 struct <structname>snd_kcontrol_new</structname> record, such as:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003397
3398 <example>
3399 <title>Definition of a Control</title>
3400 <programlisting>
3401<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003402 static struct snd_kcontrol_new my_control __devinitdata = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003403 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3404 .name = "PCM Playback Switch",
3405 .index = 0,
3406 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003407 .private_value = 0xffff,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003408 .info = my_control_info,
3409 .get = my_control_get,
3410 .put = my_control_put
3411 };
3412]]>
3413 </programlisting>
3414 </example>
3415 </para>
3416
3417 <para>
3418 Most likely the control is created via
3419 <function>snd_ctl_new1()</function>, and in such a case, you can
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003420 add the <parameter>__devinitdata</parameter> prefix to the
3421 definition as above.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003422 </para>
3423
3424 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003425 The <structfield>iface</structfield> field specifies the control
3426 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
Clemens Ladisch67ed4162005-07-29 15:32:58 +02003427 is usually <constant>MIXER</constant>.
3428 Use <constant>CARD</constant> for global controls that are not
3429 logically part of the mixer.
3430 If the control is closely associated with some specific device on
3431 the sound card, use <constant>HWDEP</constant>,
3432 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3433 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3434 specify the device number with the
3435 <structfield>device</structfield> and
3436 <structfield>subdevice</structfield> fields.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003437 </para>
3438
3439 <para>
3440 The <structfield>name</structfield> is the name identifier
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003441 string. Since ALSA 0.9.x, the control name is very important,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003442 because its role is classified from its name. There are
3443 pre-defined standard control names. The details are described in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003444 the <link linkend="control-interface-control-names"><citetitle>
3445 Control Names</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003446 </para>
3447
3448 <para>
3449 The <structfield>index</structfield> field holds the index number
3450 of this control. If there are several different controls with
3451 the same name, they can be distinguished by the index
3452 number. This is the case when
3453 several codecs exist on the card. If the index is zero, you can
3454 omit the definition above.
3455 </para>
3456
3457 <para>
3458 The <structfield>access</structfield> field contains the access
3459 type of this control. Give the combination of bit masks,
3460 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003461 The details will be explained in
3462 the <link linkend="control-interface-access-flags"><citetitle>
3463 Access Flags</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003464 </para>
3465
3466 <para>
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003467 The <structfield>private_value</structfield> field contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07003468 an arbitrary long integer value for this record. When using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003469 the generic <structfield>info</structfield>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003470 <structfield>get</structfield> and
3471 <structfield>put</structfield> callbacks, you can pass a value
3472 through this field. If several small numbers are necessary, you can
3473 combine them in bitwise. Or, it's possible to give a pointer
3474 (casted to unsigned long) of some record to this field, too.
3475 </para>
3476
3477 <para>
Clemens Ladischd1761d12007-09-10 08:05:19 +02003478 The <structfield>tlv</structfield> field can be used to provide
3479 metadata about the control; see the
3480 <link linkend="control-interface-tlv">
3481 <citetitle>Metadata</citetitle></link> subsection.
3482 </para>
3483
3484 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003485 The other three are
3486 <link linkend="control-interface-callbacks"><citetitle>
3487 callback functions</citetitle></link>.
3488 </para>
3489 </section>
3490
3491 <section id="control-interface-control-names">
3492 <title>Control Names</title>
3493 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003494 There are some standards to define the control names. A
Linus Torvalds1da177e2005-04-16 15:20:36 -07003495 control is usually defined from the three parts as
3496 <quote>SOURCE DIRECTION FUNCTION</quote>.
3497 </para>
3498
3499 <para>
3500 The first, <constant>SOURCE</constant>, specifies the source
3501 of the control, and is a string such as <quote>Master</quote>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003502 <quote>PCM</quote>, <quote>CD</quote> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07003503 <quote>Line</quote>. There are many pre-defined sources.
3504 </para>
3505
3506 <para>
3507 The second, <constant>DIRECTION</constant>, is one of the
3508 following strings according to the direction of the control:
3509 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3510 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3511 be omitted, meaning both playback and capture directions.
3512 </para>
3513
3514 <para>
3515 The third, <constant>FUNCTION</constant>, is one of the
3516 following strings according to the function of the control:
3517 <quote>Switch</quote>, <quote>Volume</quote> and
3518 <quote>Route</quote>.
3519 </para>
3520
3521 <para>
3522 The example of control names are, thus, <quote>Master Capture
3523 Switch</quote> or <quote>PCM Playback Volume</quote>.
3524 </para>
3525
3526 <para>
3527 There are some exceptions:
3528 </para>
3529
3530 <section id="control-interface-control-names-global">
3531 <title>Global capture and playback</title>
3532 <para>
3533 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3534 and <quote>Capture Volume</quote> are used for the global
3535 capture (input) source, switch and volume. Similarly,
3536 <quote>Playback Switch</quote> and <quote>Playback
3537 Volume</quote> are used for the global output gain switch and
3538 volume.
3539 </para>
3540 </section>
3541
3542 <section id="control-interface-control-names-tone">
3543 <title>Tone-controls</title>
3544 <para>
3545 tone-control switch and volumes are specified like
3546 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3547 Switch</quote>, <quote>Tone Control - Bass</quote>,
3548 <quote>Tone Control - Center</quote>.
3549 </para>
3550 </section>
3551
3552 <section id="control-interface-control-names-3d">
3553 <title>3D controls</title>
3554 <para>
3555 3D-control switches and volumes are specified like <quote>3D
3556 Control - XXX</quote>, e.g. <quote>3D Control -
3557 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3558 Control - Space</quote>.
3559 </para>
3560 </section>
3561
3562 <section id="control-interface-control-names-mic">
3563 <title>Mic boost</title>
3564 <para>
3565 Mic-boost switch is set as <quote>Mic Boost</quote> or
3566 <quote>Mic Boost (6dB)</quote>.
3567 </para>
3568
3569 <para>
3570 More precise information can be found in
3571 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3572 </para>
3573 </section>
3574 </section>
3575
3576 <section id="control-interface-access-flags">
3577 <title>Access Flags</title>
3578
3579 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003580 The access flag is the bitmask which specifies the access type
Linus Torvalds1da177e2005-04-16 15:20:36 -07003581 of the given control. The default access type is
3582 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3583 which means both read and write are allowed to this control.
3584 When the access flag is omitted (i.e. = 0), it is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003585 considered as <constant>READWRITE</constant> access as default.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003586 </para>
3587
3588 <para>
3589 When the control is read-only, pass
3590 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3591 In this case, you don't have to define
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003592 the <structfield>put</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003593 Similarly, when the control is write-only (although it's a rare
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003594 case), you can use the <constant>WRITE</constant> flag instead, and
3595 you don't need the <structfield>get</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003596 </para>
3597
3598 <para>
3599 If the control value changes frequently (e.g. the VU meter),
3600 <constant>VOLATILE</constant> flag should be given. This means
3601 that the control may be changed without
3602 <link linkend="control-interface-change-notification"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003603 notification</citetitle></link>. Applications should poll such
Linus Torvalds1da177e2005-04-16 15:20:36 -07003604 a control constantly.
3605 </para>
3606
3607 <para>
3608 When the control is inactive, set
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003609 the <constant>INACTIVE</constant> flag, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003610 There are <constant>LOCK</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003611 <constant>OWNER</constant> flags to change the write
Linus Torvalds1da177e2005-04-16 15:20:36 -07003612 permissions.
3613 </para>
3614
3615 </section>
3616
3617 <section id="control-interface-callbacks">
3618 <title>Callbacks</title>
3619
3620 <section id="control-interface-callbacks-info">
3621 <title>info callback</title>
3622 <para>
3623 The <structfield>info</structfield> callback is used to get
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003624 detailed information on this control. This must store the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003625 values of the given struct <structname>snd_ctl_elem_info</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003626 object. For example, for a boolean control with a single
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003627 element:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003628
3629 <example>
3630 <title>Example of info callback</title>
3631 <programlisting>
3632<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003633 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003634 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003635 {
3636 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3637 uinfo->count = 1;
3638 uinfo->value.integer.min = 0;
3639 uinfo->value.integer.max = 1;
3640 return 0;
3641 }
3642]]>
3643 </programlisting>
3644 </example>
3645 </para>
3646
3647 <para>
3648 The <structfield>type</structfield> field specifies the type
3649 of the control. There are <constant>BOOLEAN</constant>,
3650 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3651 <constant>BYTES</constant>, <constant>IEC958</constant> and
3652 <constant>INTEGER64</constant>. The
3653 <structfield>count</structfield> field specifies the
3654 number of elements in this control. For example, a stereo
3655 volume would have count = 2. The
3656 <structfield>value</structfield> field is a union, and
3657 the values stored are depending on the type. The boolean and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003658 integer types are identical.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003659 </para>
3660
3661 <para>
3662 The enumerated type is a bit different from others. You'll
3663 need to set the string for the currently given item index.
3664
3665 <informalexample>
3666 <programlisting>
3667<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003668 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003669 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003670 {
3671 static char *texts[4] = {
3672 "First", "Second", "Third", "Fourth"
3673 };
3674 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3675 uinfo->count = 1;
3676 uinfo->value.enumerated.items = 4;
3677 if (uinfo->value.enumerated.item > 3)
3678 uinfo->value.enumerated.item = 3;
3679 strcpy(uinfo->value.enumerated.name,
3680 texts[uinfo->value.enumerated.item]);
3681 return 0;
3682 }
3683]]>
3684 </programlisting>
3685 </informalexample>
3686 </para>
Takashi Iwai95a5b082007-07-26 16:50:09 +02003687
3688 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003689 Some common info callbacks are available for your convenience:
Takashi Iwai95a5b082007-07-26 16:50:09 +02003690 <function>snd_ctl_boolean_mono_info()</function> and
3691 <function>snd_ctl_boolean_stereo_info()</function>.
3692 Obviously, the former is an info callback for a mono channel
3693 boolean item, just like <function>snd_myctl_mono_info</function>
3694 above, and the latter is for a stereo channel boolean item.
3695 </para>
3696
Linus Torvalds1da177e2005-04-16 15:20:36 -07003697 </section>
3698
3699 <section id="control-interface-callbacks-get">
3700 <title>get callback</title>
3701
3702 <para>
3703 This callback is used to read the current value of the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003704 control and to return to user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003705 </para>
3706
3707 <para>
3708 For example,
3709
3710 <example>
3711 <title>Example of get callback</title>
3712 <programlisting>
3713<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003714 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3715 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003716 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003717 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003718 ucontrol->value.integer.value[0] = get_some_value(chip);
3719 return 0;
3720 }
3721]]>
3722 </programlisting>
3723 </example>
3724 </para>
3725
3726 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003727 The <structfield>value</structfield> field depends on
3728 the type of control as well as on the info callback. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003729 the sb driver uses this field to store the register offset,
3730 the bit-shift and the bit-mask. The
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003731 <structfield>private_value</structfield> field is set as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003732 <informalexample>
3733 <programlisting>
3734<![CDATA[
3735 .private_value = reg | (shift << 16) | (mask << 24)
3736]]>
3737 </programlisting>
3738 </informalexample>
3739 and is retrieved in callbacks like
3740 <informalexample>
3741 <programlisting>
3742<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003743 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3744 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003745 {
3746 int reg = kcontrol->private_value & 0xff;
3747 int shift = (kcontrol->private_value >> 16) & 0xff;
3748 int mask = (kcontrol->private_value >> 24) & 0xff;
3749 ....
3750 }
3751]]>
3752 </programlisting>
3753 </informalexample>
3754 </para>
3755
3756 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003757 In the <structfield>get</structfield> callback,
3758 you have to fill all the elements if the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003759 control has more than one elements,
3760 i.e. <structfield>count</structfield> &gt; 1.
3761 In the example above, we filled only one element
3762 (<structfield>value.integer.value[0]</structfield>) since it's
3763 assumed as <structfield>count</structfield> = 1.
3764 </para>
3765 </section>
3766
3767 <section id="control-interface-callbacks-put">
3768 <title>put callback</title>
3769
3770 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003771 This callback is used to write a value from user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003772 </para>
3773
3774 <para>
3775 For example,
3776
3777 <example>
3778 <title>Example of put callback</title>
3779 <programlisting>
3780<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003781 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3782 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003783 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003784 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003785 int changed = 0;
3786 if (chip->current_value !=
3787 ucontrol->value.integer.value[0]) {
3788 change_current_value(chip,
3789 ucontrol->value.integer.value[0]);
3790 changed = 1;
3791 }
3792 return changed;
3793 }
3794]]>
3795 </programlisting>
3796 </example>
3797
3798 As seen above, you have to return 1 if the value is
3799 changed. If the value is not changed, return 0 instead.
3800 If any fatal error happens, return a negative error code as
3801 usual.
3802 </para>
3803
3804 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003805 As in the <structfield>get</structfield> callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003806 when the control has more than one elements,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003807 all elements must be evaluated in this callback, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003808 </para>
3809 </section>
3810
3811 <section id="control-interface-callbacks-all">
3812 <title>Callbacks are not atomic</title>
3813 <para>
3814 All these three callbacks are basically not atomic.
3815 </para>
3816 </section>
3817 </section>
3818
3819 <section id="control-interface-constructor">
3820 <title>Constructor</title>
3821 <para>
3822 When everything is ready, finally we can create a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003823 control. To create a control, there are two functions to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07003824 called, <function>snd_ctl_new1()</function> and
3825 <function>snd_ctl_add()</function>.
3826 </para>
3827
3828 <para>
3829 In the simplest way, you can do like this:
3830
3831 <informalexample>
3832 <programlisting>
3833<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003834 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3835 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003836 return err;
3837]]>
3838 </programlisting>
3839 </informalexample>
3840
3841 where <parameter>my_control</parameter> is the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003842 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
Linus Torvalds1da177e2005-04-16 15:20:36 -07003843 is the object pointer to be passed to
3844 kcontrol-&gt;private_data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003845 which can be referred to in callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003846 </para>
3847
3848 <para>
3849 <function>snd_ctl_new1()</function> allocates a new
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003850 <structname>snd_kcontrol</structname> instance (that's why the definition
Linus Torvalds1da177e2005-04-16 15:20:36 -07003851 of <parameter>my_control</parameter> can be with
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003852 the <parameter>__devinitdata</parameter>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003853 prefix), and <function>snd_ctl_add</function> assigns the given
3854 control component to the card.
3855 </para>
3856 </section>
3857
3858 <section id="control-interface-change-notification">
3859 <title>Change Notification</title>
3860 <para>
3861 If you need to change and update a control in the interrupt
3862 routine, you can call <function>snd_ctl_notify()</function>. For
3863 example,
3864
3865 <informalexample>
3866 <programlisting>
3867<![CDATA[
3868 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3869]]>
3870 </programlisting>
3871 </informalexample>
3872
3873 This function takes the card pointer, the event-mask, and the
3874 control id pointer for the notification. The event-mask
3875 specifies the types of notification, for example, in the above
3876 example, the change of control values is notified.
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003877 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003878 to be notified.
3879 You can find some examples in <filename>es1938.c</filename> or
3880 <filename>es1968.c</filename> for hardware volume interrupts.
3881 </para>
3882 </section>
3883
Clemens Ladischd1761d12007-09-10 08:05:19 +02003884 <section id="control-interface-tlv">
3885 <title>Metadata</title>
3886 <para>
3887 To provide information about the dB values of a mixer control, use
3888 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3889 <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3890 containing this information, set the<structfield>tlv.p
3891 </structfield> field to point to this variable, and include the
3892 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3893 <structfield>access</structfield> field; like this:
3894 <informalexample>
3895 <programlisting>
3896<![CDATA[
3897 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3898
3899 static struct snd_kcontrol_new my_control __devinitdata = {
3900 ...
3901 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3902 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3903 ...
3904 .tlv.p = db_scale_my_control,
3905 };
3906]]>
3907 </programlisting>
3908 </informalexample>
3909 </para>
3910
3911 <para>
3912 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3913 information about a mixer control where each step in the control's
3914 value changes the dB value by a constant dB amount.
3915 The first parameter is the name of the variable to be defined.
3916 The second parameter is the minimum value, in units of 0.01 dB.
3917 The third parameter is the step size, in units of 0.01 dB.
3918 Set the fourth parameter to 1 if the minimum value actually mutes
3919 the control.
3920 </para>
3921
3922 <para>
3923 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3924 information about a mixer control where the control's value affects
3925 the output linearly.
3926 The first parameter is the name of the variable to be defined.
3927 The second parameter is the minimum value, in units of 0.01 dB.
3928 The third parameter is the maximum value, in units of 0.01 dB.
3929 If the minimum value mutes the control, set the second parameter to
3930 <constant>TLV_DB_GAIN_MUTE</constant>.
3931 </para>
3932 </section>
3933
Linus Torvalds1da177e2005-04-16 15:20:36 -07003934 </chapter>
3935
3936
3937<!-- ****************************************************** -->
3938<!-- API for AC97 Codec -->
3939<!-- ****************************************************** -->
3940 <chapter id="api-ac97">
3941 <title>API for AC97 Codec</title>
3942
3943 <section>
3944 <title>General</title>
3945 <para>
3946 The ALSA AC97 codec layer is a well-defined one, and you don't
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003947 have to write much code to control it. Only low-level control
Linus Torvalds1da177e2005-04-16 15:20:36 -07003948 routines are necessary. The AC97 codec API is defined in
3949 <filename>&lt;sound/ac97_codec.h&gt;</filename>.
3950 </para>
3951 </section>
3952
3953 <section id="api-ac97-example">
3954 <title>Full Code Example</title>
3955 <para>
3956 <example>
3957 <title>Example of AC97 Interface</title>
3958 <programlisting>
3959<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003960 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003961 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003962 struct snd_ac97 *ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003963 ....
3964 };
3965
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003966 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003967 unsigned short reg)
3968 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003969 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003970 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003971 /* read a register value here from the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003972 return the_register_value;
3973 }
3974
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003975 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003976 unsigned short reg, unsigned short val)
3977 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003978 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003979 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003980 /* write the given register value to the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003981 }
3982
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003983 static int snd_mychip_ac97(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003984 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003985 struct snd_ac97_bus *bus;
3986 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003987 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003988 static struct snd_ac97_bus_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003989 .write = snd_mychip_ac97_write,
3990 .read = snd_mychip_ac97_read,
3991 };
3992
Takashi Iwai95a5b082007-07-26 16:50:09 +02003993 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3994 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003995 return err;
3996 memset(&ac97, 0, sizeof(ac97));
3997 ac97.private_data = chip;
3998 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3999 }
4000
4001]]>
4002 </programlisting>
4003 </example>
4004 </para>
4005 </section>
4006
4007 <section id="api-ac97-constructor">
4008 <title>Constructor</title>
4009 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004010 To create an ac97 instance, first call <function>snd_ac97_bus</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004011 with an <type>ac97_bus_ops_t</type> record with callback functions.
4012
4013 <informalexample>
4014 <programlisting>
4015<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004016 struct snd_ac97_bus *bus;
4017 static struct snd_ac97_bus_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004018 .write = snd_mychip_ac97_write,
4019 .read = snd_mychip_ac97_read,
4020 };
4021
4022 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
4023]]>
4024 </programlisting>
4025 </informalexample>
4026
4027 The bus record is shared among all belonging ac97 instances.
4028 </para>
4029
4030 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004031 And then call <function>snd_ac97_mixer()</function> with an
4032 struct <structname>snd_ac97_template</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004033 record together with the bus pointer created above.
4034
4035 <informalexample>
4036 <programlisting>
4037<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004038 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004039 int err;
4040
4041 memset(&ac97, 0, sizeof(ac97));
4042 ac97.private_data = chip;
4043 snd_ac97_mixer(bus, &ac97, &chip->ac97);
4044]]>
4045 </programlisting>
4046 </informalexample>
4047
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004048 where chip-&gt;ac97 is a pointer to a newly created
Linus Torvalds1da177e2005-04-16 15:20:36 -07004049 <type>ac97_t</type> instance.
4050 In this case, the chip pointer is set as the private data, so that
4051 the read/write callback functions can refer to this chip instance.
4052 This instance is not necessarily stored in the chip
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004053 record. If you need to change the register values from the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004054 driver, or need the suspend/resume of ac97 codecs, keep this
4055 pointer to pass to the corresponding functions.
4056 </para>
4057 </section>
4058
4059 <section id="api-ac97-callbacks">
4060 <title>Callbacks</title>
4061 <para>
4062 The standard callbacks are <structfield>read</structfield> and
4063 <structfield>write</structfield>. Obviously they
4064 correspond to the functions for read and write accesses to the
4065 hardware low-level codes.
4066 </para>
4067
4068 <para>
4069 The <structfield>read</structfield> callback returns the
4070 register value specified in the argument.
4071
4072 <informalexample>
4073 <programlisting>
4074<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004075 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004076 unsigned short reg)
4077 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004078 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004079 ....
4080 return the_register_value;
4081 }
4082]]>
4083 </programlisting>
4084 </informalexample>
4085
4086 Here, the chip can be cast from ac97-&gt;private_data.
4087 </para>
4088
4089 <para>
4090 Meanwhile, the <structfield>write</structfield> callback is
4091 used to set the register value.
4092
4093 <informalexample>
4094 <programlisting>
4095<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004096 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004097 unsigned short reg, unsigned short val)
4098]]>
4099 </programlisting>
4100 </informalexample>
4101 </para>
4102
4103 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004104 These callbacks are non-atomic like the control API callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004105 </para>
4106
4107 <para>
4108 There are also other callbacks:
4109 <structfield>reset</structfield>,
4110 <structfield>wait</structfield> and
4111 <structfield>init</structfield>.
4112 </para>
4113
4114 <para>
4115 The <structfield>reset</structfield> callback is used to reset
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004116 the codec. If the chip requires a special kind of reset, you can
Linus Torvalds1da177e2005-04-16 15:20:36 -07004117 define this callback.
4118 </para>
4119
4120 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004121 The <structfield>wait</structfield> callback is used to
4122 add some waiting time in the standard initialization of the codec. If the
4123 chip requires the extra waiting time, define this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004124 </para>
4125
4126 <para>
4127 The <structfield>init</structfield> callback is used for
4128 additional initialization of the codec.
4129 </para>
4130 </section>
4131
4132 <section id="api-ac97-updating-registers">
4133 <title>Updating Registers in The Driver</title>
4134 <para>
4135 If you need to access to the codec from the driver, you can
4136 call the following functions:
4137 <function>snd_ac97_write()</function>,
4138 <function>snd_ac97_read()</function>,
4139 <function>snd_ac97_update()</function> and
4140 <function>snd_ac97_update_bits()</function>.
4141 </para>
4142
4143 <para>
4144 Both <function>snd_ac97_write()</function> and
4145 <function>snd_ac97_update()</function> functions are used to
4146 set a value to the given register
4147 (<constant>AC97_XXX</constant>). The difference between them is
4148 that <function>snd_ac97_update()</function> doesn't write a
4149 value if the given value has been already set, while
4150 <function>snd_ac97_write()</function> always rewrites the
4151 value.
4152
4153 <informalexample>
4154 <programlisting>
4155<![CDATA[
4156 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4157 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4158]]>
4159 </programlisting>
4160 </informalexample>
4161 </para>
4162
4163 <para>
4164 <function>snd_ac97_read()</function> is used to read the value
4165 of the given register. For example,
4166
4167 <informalexample>
4168 <programlisting>
4169<![CDATA[
4170 value = snd_ac97_read(ac97, AC97_MASTER);
4171]]>
4172 </programlisting>
4173 </informalexample>
4174 </para>
4175
4176 <para>
4177 <function>snd_ac97_update_bits()</function> is used to update
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004178 some bits in the given register.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004179
4180 <informalexample>
4181 <programlisting>
4182<![CDATA[
4183 snd_ac97_update_bits(ac97, reg, mask, value);
4184]]>
4185 </programlisting>
4186 </informalexample>
4187 </para>
4188
4189 <para>
4190 Also, there is a function to change the sample rate (of a
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004191 given register such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07004192 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4193 DRA is supported by the codec:
4194 <function>snd_ac97_set_rate()</function>.
4195
4196 <informalexample>
4197 <programlisting>
4198<![CDATA[
4199 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4200]]>
4201 </programlisting>
4202 </informalexample>
4203 </para>
4204
4205 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004206 The following registers are available to set the rate:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004207 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4208 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4209 <constant>AC97_PCM_LR_ADC_RATE</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004210 <constant>AC97_SPDIF</constant>. When
Linus Torvalds1da177e2005-04-16 15:20:36 -07004211 <constant>AC97_SPDIF</constant> is specified, the register is
4212 not really changed but the corresponding IEC958 status bits will
4213 be updated.
4214 </para>
4215 </section>
4216
4217 <section id="api-ac97-clock-adjustment">
4218 <title>Clock Adjustment</title>
4219 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004220 In some chips, the clock of the codec isn't 48000 but using a
Linus Torvalds1da177e2005-04-16 15:20:36 -07004221 PCI clock (to save a quartz!). In this case, change the field
4222 bus-&gt;clock to the corresponding
4223 value. For example, intel8x0
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004224 and es1968 drivers have their own function to read from the clock.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004225 </para>
4226 </section>
4227
4228 <section id="api-ac97-proc-files">
4229 <title>Proc Files</title>
4230 <para>
4231 The ALSA AC97 interface will create a proc file such as
4232 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4233 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4234 see the current status and registers of the codec.
4235 </para>
4236 </section>
4237
4238 <section id="api-ac97-multiple-codecs">
4239 <title>Multiple Codecs</title>
4240 <para>
4241 When there are several codecs on the same card, you need to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004242 call <function>snd_ac97_mixer()</function> multiple times with
Linus Torvalds1da177e2005-04-16 15:20:36 -07004243 ac97.num=1 or greater. The <structfield>num</structfield> field
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004244 specifies the codec number.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004245 </para>
4246
4247 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004248 If you set up multiple codecs, you either need to write
Linus Torvalds1da177e2005-04-16 15:20:36 -07004249 different callbacks for each codec or check
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004250 ac97-&gt;num in the callback routines.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004251 </para>
4252 </section>
4253
4254 </chapter>
4255
4256
4257<!-- ****************************************************** -->
4258<!-- MIDI (MPU401-UART) Interface -->
4259<!-- ****************************************************** -->
4260 <chapter id="midi-interface">
4261 <title>MIDI (MPU401-UART) Interface</title>
4262
4263 <section id="midi-interface-general">
4264 <title>General</title>
4265 <para>
4266 Many soundcards have built-in MIDI (MPU401-UART)
4267 interfaces. When the soundcard supports the standard MPU401-UART
4268 interface, most likely you can use the ALSA MPU401-UART API. The
4269 MPU401-UART API is defined in
4270 <filename>&lt;sound/mpu401.h&gt;</filename>.
4271 </para>
4272
4273 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004274 Some soundchips have a similar but slightly different
Linus Torvalds1da177e2005-04-16 15:20:36 -07004275 implementation of mpu401 stuff. For example, emu10k1 has its own
4276 mpu401 routines.
4277 </para>
4278 </section>
4279
4280 <section id="midi-interface-constructor">
4281 <title>Constructor</title>
4282 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004283 To create a rawmidi object, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004284 <function>snd_mpu401_uart_new()</function>.
4285
4286 <informalexample>
4287 <programlisting>
4288<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004289 struct snd_rawmidi *rmidi;
Takashi Iwai302e4c22006-05-23 13:24:30 +02004290 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
Clemens Ladischdba8b462011-09-13 11:24:41 +02004291 irq, &rmidi);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004292]]>
4293 </programlisting>
4294 </informalexample>
4295 </para>
4296
4297 <para>
4298 The first argument is the card pointer, and the second is the
4299 index of this component. You can create up to 8 rawmidi
4300 devices.
4301 </para>
4302
4303 <para>
4304 The third argument is the type of the hardware,
4305 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4306 you can use <constant>MPU401_HW_MPU401</constant>.
4307 </para>
4308
4309 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004310 The 4th argument is the I/O port address. Many
4311 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4312 might be a part of its own PCI I/O region. It depends on the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004313 chip design.
4314 </para>
4315
4316 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004317 The 5th argument is a bitflag for additional information.
4318 When the I/O port address above is part of the PCI I/O
4319 region, the MPU401 I/O port might have been already allocated
Takashi Iwai302e4c22006-05-23 13:24:30 +02004320 (reserved) by the driver itself. In such a case, pass a bit flag
4321 <constant>MPU401_INFO_INTEGRATED</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004322 and the mpu401-uart layer will allocate the I/O ports by itself.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004323 </para>
4324
Takashi Iwai302e4c22006-05-23 13:24:30 +02004325 <para>
4326 When the controller supports only the input or output MIDI stream,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004327 pass the <constant>MPU401_INFO_INPUT</constant> or
Takashi Iwai302e4c22006-05-23 13:24:30 +02004328 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4329 Then the rawmidi instance is created as a single stream.
4330 </para>
4331
4332 <para>
4333 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4334 the access method to MMIO (via readb and writeb) instead of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004335 iob and outb. In this case, you have to pass the iomapped address
Takashi Iwai302e4c22006-05-23 13:24:30 +02004336 to <function>snd_mpu401_uart_new()</function>.
4337 </para>
4338
4339 <para>
4340 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4341 stream isn't checked in the default interrupt handler. The driver
4342 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004343 by itself to start processing the output stream in the irq handler.
Takashi Iwai302e4c22006-05-23 13:24:30 +02004344 </para>
4345
Clemens Ladischdba8b462011-09-13 11:24:41 +02004346 <para>
4347 If the MPU-401 interface shares its interrupt with the other logical
4348 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4349 (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4350 below</citetitle></link>).
4351 </para>
4352
Linus Torvalds1da177e2005-04-16 15:20:36 -07004353 <para>
4354 Usually, the port address corresponds to the command port and
4355 port + 1 corresponds to the data port. If not, you may change
4356 the <structfield>cport</structfield> field of
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004357 struct <structname>snd_mpu401</structname> manually
4358 afterward. However, <structname>snd_mpu401</structname> pointer is not
Linus Torvalds1da177e2005-04-16 15:20:36 -07004359 returned explicitly by
4360 <function>snd_mpu401_uart_new()</function>. You need to cast
4361 rmidi-&gt;private_data to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004362 <structname>snd_mpu401</structname> explicitly,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004363
4364 <informalexample>
4365 <programlisting>
4366<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004367 struct snd_mpu401 *mpu;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004368 mpu = rmidi->private_data;
4369]]>
4370 </programlisting>
4371 </informalexample>
4372
4373 and reset the cport as you like:
4374
4375 <informalexample>
4376 <programlisting>
4377<![CDATA[
4378 mpu->cport = my_own_control_port;
4379]]>
4380 </programlisting>
4381 </informalexample>
4382 </para>
4383
4384 <para>
Clemens Ladischdba8b462011-09-13 11:24:41 +02004385 The 6th argument specifies the ISA irq number that will be
4386 allocated. If no interrupt is to be allocated (because your
4387 code is already allocating a shared interrupt, or because the
4388 device does not use interrupts), pass -1 instead.
4389 For a MPU-401 device without an interrupt, a polling timer
4390 will be used instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004391 </para>
4392 </section>
4393
4394 <section id="midi-interface-interrupt-handler">
4395 <title>Interrupt Handler</title>
4396 <para>
4397 When the interrupt is allocated in
Clemens Ladischdba8b462011-09-13 11:24:41 +02004398 <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4399 interrupt handler is automatically used, hence you don't have
4400 anything else to do than creating the mpu401 stuff. Otherwise, you
4401 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4402 <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4403 own interrupt handler when it has determined that a UART interrupt
4404 has occurred.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004405 </para>
4406
4407 <para>
4408 In this case, you need to pass the private_data of the
4409 returned rawmidi object from
4410 <function>snd_mpu401_uart_new()</function> as the second
4411 argument of <function>snd_mpu401_uart_interrupt()</function>.
4412
4413 <informalexample>
4414 <programlisting>
4415<![CDATA[
4416 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4417]]>
4418 </programlisting>
4419 </informalexample>
4420 </para>
4421 </section>
4422
4423 </chapter>
4424
4425
4426<!-- ****************************************************** -->
4427<!-- RawMIDI Interface -->
4428<!-- ****************************************************** -->
4429 <chapter id="rawmidi-interface">
4430 <title>RawMIDI Interface</title>
4431
4432 <section id="rawmidi-interface-overview">
4433 <title>Overview</title>
4434
4435 <para>
4436 The raw MIDI interface is used for hardware MIDI ports that can
4437 be accessed as a byte stream. It is not used for synthesizer
4438 chips that do not directly understand MIDI.
4439 </para>
4440
4441 <para>
4442 ALSA handles file and buffer management. All you have to do is
4443 to write some code to move data between the buffer and the
4444 hardware.
4445 </para>
4446
4447 <para>
4448 The rawmidi API is defined in
4449 <filename>&lt;sound/rawmidi.h&gt;</filename>.
4450 </para>
4451 </section>
4452
4453 <section id="rawmidi-interface-constructor">
4454 <title>Constructor</title>
4455
4456 <para>
4457 To create a rawmidi device, call the
4458 <function>snd_rawmidi_new</function> function:
4459 <informalexample>
4460 <programlisting>
4461<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004462 struct snd_rawmidi *rmidi;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004463 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4464 if (err < 0)
4465 return err;
4466 rmidi->private_data = chip;
4467 strcpy(rmidi->name, "My MIDI");
4468 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4469 SNDRV_RAWMIDI_INFO_INPUT |
4470 SNDRV_RAWMIDI_INFO_DUPLEX;
4471]]>
4472 </programlisting>
4473 </informalexample>
4474 </para>
4475
4476 <para>
4477 The first argument is the card pointer, the second argument is
4478 the ID string.
4479 </para>
4480
4481 <para>
4482 The third argument is the index of this component. You can
4483 create up to 8 rawmidi devices.
4484 </para>
4485
4486 <para>
4487 The fourth and fifth arguments are the number of output and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004488 input substreams, respectively, of this device (a substream is
4489 the equivalent of a MIDI port).
Linus Torvalds1da177e2005-04-16 15:20:36 -07004490 </para>
4491
4492 <para>
4493 Set the <structfield>info_flags</structfield> field to specify
4494 the capabilities of the device.
4495 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4496 at least one output port,
4497 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4498 least one input port,
4499 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4500 can handle output and input at the same time.
4501 </para>
4502
4503 <para>
4504 After the rawmidi device is created, you need to set the
4505 operators (callbacks) for each substream. There are helper
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004506 functions to set the operators for all the substreams of a device:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004507 <informalexample>
4508 <programlisting>
4509<![CDATA[
4510 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4511 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4512]]>
4513 </programlisting>
4514 </informalexample>
4515 </para>
4516
4517 <para>
4518 The operators are usually defined like this:
4519 <informalexample>
4520 <programlisting>
4521<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004522 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004523 .open = snd_mymidi_output_open,
4524 .close = snd_mymidi_output_close,
4525 .trigger = snd_mymidi_output_trigger,
4526 };
4527]]>
4528 </programlisting>
4529 </informalexample>
4530 These callbacks are explained in the <link
4531 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4532 section.
4533 </para>
4534
4535 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004536 If there are more than one substream, you should give a
4537 unique name to each of them:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004538 <informalexample>
4539 <programlisting>
4540<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004541 struct snd_rawmidi_substream *substream;
Takashi Iwai95a5b082007-07-26 16:50:09 +02004542 list_for_each_entry(substream,
4543 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4544 list {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004545 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4546 }
4547 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4548]]>
4549 </programlisting>
4550 </informalexample>
4551 </para>
4552 </section>
4553
4554 <section id="rawmidi-interface-callbacks">
4555 <title>Callbacks</title>
4556
4557 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004558 In all the callbacks, the private data that you've set for the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004559 rawmidi device can be accessed as
4560 substream-&gt;rmidi-&gt;private_data.
4561 <!-- <code> isn't available before DocBook 4.3 -->
4562 </para>
4563
4564 <para>
4565 If there is more than one port, your callbacks can determine the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004566 port index from the struct snd_rawmidi_substream data passed to each
Linus Torvalds1da177e2005-04-16 15:20:36 -07004567 callback:
4568 <informalexample>
4569 <programlisting>
4570<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004571 struct snd_rawmidi_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004572 int index = substream->number;
4573]]>
4574 </programlisting>
4575 </informalexample>
4576 </para>
4577
4578 <section id="rawmidi-interface-op-open">
4579 <title><function>open</function> callback</title>
4580
4581 <informalexample>
4582 <programlisting>
4583<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004584 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004585]]>
4586 </programlisting>
4587 </informalexample>
4588
4589 <para>
4590 This is called when a substream is opened.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004591 You can initialize the hardware here, but you shouldn't
4592 start transmitting/receiving data yet.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004593 </para>
4594 </section>
4595
4596 <section id="rawmidi-interface-op-close">
4597 <title><function>close</function> callback</title>
4598
4599 <informalexample>
4600 <programlisting>
4601<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004602 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004603]]>
4604 </programlisting>
4605 </informalexample>
4606
4607 <para>
4608 Guess what.
4609 </para>
4610
4611 <para>
4612 The <function>open</function> and <function>close</function>
4613 callbacks of a rawmidi device are serialized with a mutex,
4614 and can sleep.
4615 </para>
4616 </section>
4617
4618 <section id="rawmidi-interface-op-trigger-out">
4619 <title><function>trigger</function> callback for output
4620 substreams</title>
4621
4622 <informalexample>
4623 <programlisting>
4624<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004625 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004626]]>
4627 </programlisting>
4628 </informalexample>
4629
4630 <para>
4631 This is called with a nonzero <parameter>up</parameter>
4632 parameter when there is some data in the substream buffer that
4633 must be transmitted.
4634 </para>
4635
4636 <para>
4637 To read data from the buffer, call
4638 <function>snd_rawmidi_transmit_peek</function>. It will
4639 return the number of bytes that have been read; this will be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004640 less than the number of bytes requested when there are no more
Linus Torvalds1da177e2005-04-16 15:20:36 -07004641 data in the buffer.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004642 After the data have been transmitted successfully, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004643 <function>snd_rawmidi_transmit_ack</function> to remove the
4644 data from the substream buffer:
4645 <informalexample>
4646 <programlisting>
4647<![CDATA[
4648 unsigned char data;
4649 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004650 if (snd_mychip_try_to_transmit(data))
Linus Torvalds1da177e2005-04-16 15:20:36 -07004651 snd_rawmidi_transmit_ack(substream, 1);
4652 else
4653 break; /* hardware FIFO full */
4654 }
4655]]>
4656 </programlisting>
4657 </informalexample>
4658 </para>
4659
4660 <para>
4661 If you know beforehand that the hardware will accept data, you
4662 can use the <function>snd_rawmidi_transmit</function> function
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004663 which reads some data and removes them from the buffer at once:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004664 <informalexample>
4665 <programlisting>
4666<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004667 while (snd_mychip_transmit_possible()) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004668 unsigned char data;
4669 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4670 break; /* no more data */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004671 snd_mychip_transmit(data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004672 }
4673]]>
4674 </programlisting>
4675 </informalexample>
4676 </para>
4677
4678 <para>
4679 If you know beforehand how many bytes you can accept, you can
4680 use a buffer size greater than one with the
4681 <function>snd_rawmidi_transmit*</function> functions.
4682 </para>
4683
4684 <para>
4685 The <function>trigger</function> callback must not sleep. If
4686 the hardware FIFO is full before the substream buffer has been
4687 emptied, you have to continue transmitting data later, either
4688 in an interrupt handler, or with a timer if the hardware
4689 doesn't have a MIDI transmit interrupt.
4690 </para>
4691
4692 <para>
4693 The <function>trigger</function> callback is called with a
4694 zero <parameter>up</parameter> parameter when the transmission
4695 of data should be aborted.
4696 </para>
4697 </section>
4698
4699 <section id="rawmidi-interface-op-trigger-in">
4700 <title><function>trigger</function> callback for input
4701 substreams</title>
4702
4703 <informalexample>
4704 <programlisting>
4705<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004706 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004707]]>
4708 </programlisting>
4709 </informalexample>
4710
4711 <para>
4712 This is called with a nonzero <parameter>up</parameter>
4713 parameter to enable receiving data, or with a zero
4714 <parameter>up</parameter> parameter do disable receiving data.
4715 </para>
4716
4717 <para>
4718 The <function>trigger</function> callback must not sleep; the
4719 actual reading of data from the device is usually done in an
4720 interrupt handler.
4721 </para>
4722
4723 <para>
4724 When data reception is enabled, your interrupt handler should
4725 call <function>snd_rawmidi_receive</function> for all received
4726 data:
4727 <informalexample>
4728 <programlisting>
4729<![CDATA[
4730 void snd_mychip_midi_interrupt(...)
4731 {
4732 while (mychip_midi_available()) {
4733 unsigned char data;
4734 data = mychip_midi_read();
4735 snd_rawmidi_receive(substream, &data, 1);
4736 }
4737 }
4738]]>
4739 </programlisting>
4740 </informalexample>
4741 </para>
4742 </section>
4743
4744 <section id="rawmidi-interface-op-drain">
4745 <title><function>drain</function> callback</title>
4746
4747 <informalexample>
4748 <programlisting>
4749<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004750 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004751]]>
4752 </programlisting>
4753 </informalexample>
4754
4755 <para>
4756 This is only used with output substreams. This function should wait
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004757 until all data read from the substream buffer have been transmitted.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004758 This ensures that the device can be closed and the driver unloaded
4759 without losing data.
4760 </para>
4761
4762 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004763 This callback is optional. If you do not set
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004764 <structfield>drain</structfield> in the struct snd_rawmidi_ops
Linus Torvalds1da177e2005-04-16 15:20:36 -07004765 structure, ALSA will simply wait for 50&nbsp;milliseconds
4766 instead.
4767 </para>
4768 </section>
4769 </section>
4770
4771 </chapter>
4772
4773
4774<!-- ****************************************************** -->
4775<!-- Miscellaneous Devices -->
4776<!-- ****************************************************** -->
4777 <chapter id="misc-devices">
4778 <title>Miscellaneous Devices</title>
4779
4780 <section id="misc-devices-opl3">
4781 <title>FM OPL3</title>
4782 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004783 The FM OPL3 is still used in many chips (mainly for backward
Linus Torvalds1da177e2005-04-16 15:20:36 -07004784 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4785 OPL3 API is defined in
4786 <filename>&lt;sound/opl3.h&gt;</filename>.
4787 </para>
4788
4789 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004790 FM registers can be directly accessed through the direct-FM API,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004791 defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4792 ALSA native mode, FM registers are accessed through
Lucas De Marchi25985ed2011-03-30 22:57:33 -03004793 the Hardware-Dependent Device direct-FM extension API, whereas in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004794 OSS compatible mode, FM registers can be accessed with the OSS
4795 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004796 </para>
4797
4798 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004799 To create the OPL3 component, you have two functions to
4800 call. The first one is a constructor for the <type>opl3_t</type>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004801 instance.
4802
4803 <informalexample>
4804 <programlisting>
4805<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004806 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004807 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4808 integrated, &opl3);
4809]]>
4810 </programlisting>
4811 </informalexample>
4812 </para>
4813
4814 <para>
4815 The first argument is the card pointer, the second one is the
4816 left port address, and the third is the right port address. In
4817 most cases, the right port is placed at the left port + 2.
4818 </para>
4819
4820 <para>
4821 The fourth argument is the hardware type.
4822 </para>
4823
4824 <para>
4825 When the left and right ports have been already allocated by
4826 the card driver, pass non-zero to the fifth argument
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004827 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
Linus Torvalds1da177e2005-04-16 15:20:36 -07004828 allocate the specified ports by itself.
4829 </para>
4830
4831 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004832 When the accessing the hardware requires special method
Linus Torvalds1da177e2005-04-16 15:20:36 -07004833 instead of the standard I/O access, you can create opl3 instance
4834 separately with <function>snd_opl3_new()</function>.
4835
4836 <informalexample>
4837 <programlisting>
4838<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004839 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004840 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4841]]>
4842 </programlisting>
4843 </informalexample>
4844 </para>
4845
4846 <para>
4847 Then set <structfield>command</structfield>,
4848 <structfield>private_data</structfield> and
4849 <structfield>private_free</structfield> for the private
4850 access function, the private data and the destructor.
4851 The l_port and r_port are not necessarily set. Only the
4852 command must be set properly. You can retrieve the data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004853 from the opl3-&gt;private_data field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004854 </para>
4855
4856 <para>
4857 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4858 call <function>snd_opl3_init()</function> to initialize the chip to the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004859 proper state. Note that <function>snd_opl3_create()</function> always
Linus Torvalds1da177e2005-04-16 15:20:36 -07004860 calls it internally.
4861 </para>
4862
4863 <para>
4864 If the opl3 instance is created successfully, then create a
4865 hwdep device for this opl3.
4866
4867 <informalexample>
4868 <programlisting>
4869<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004870 struct snd_hwdep *opl3hwdep;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004871 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4872]]>
4873 </programlisting>
4874 </informalexample>
4875 </para>
4876
4877 <para>
4878 The first argument is the <type>opl3_t</type> instance you
4879 created, and the second is the index number, usually 0.
4880 </para>
4881
4882 <para>
4883 The third argument is the index-offset for the sequencer
4884 client assigned to the OPL3 port. When there is an MPU401-UART,
4885 give 1 for here (UART always takes 0).
4886 </para>
4887 </section>
4888
4889 <section id="misc-devices-hardware-dependent">
4890 <title>Hardware-Dependent Devices</title>
4891 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004892 Some chips need user-space access for special
Linus Torvalds1da177e2005-04-16 15:20:36 -07004893 controls or for loading the micro code. In such a case, you can
4894 create a hwdep (hardware-dependent) device. The hwdep API is
4895 defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4896 find examples in opl3 driver or
4897 <filename>isa/sb/sb16_csp.c</filename>.
4898 </para>
4899
4900 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004901 The creation of the <type>hwdep</type> instance is done via
Linus Torvalds1da177e2005-04-16 15:20:36 -07004902 <function>snd_hwdep_new()</function>.
4903
4904 <informalexample>
4905 <programlisting>
4906<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004907 struct snd_hwdep *hw;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004908 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4909]]>
4910 </programlisting>
4911 </informalexample>
4912
4913 where the third argument is the index number.
4914 </para>
4915
4916 <para>
4917 You can then pass any pointer value to the
4918 <parameter>private_data</parameter>.
4919 If you assign a private data, you should define the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004920 destructor, too. The destructor function is set in
4921 the <structfield>private_free</structfield> field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004922
4923 <informalexample>
4924 <programlisting>
4925<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004926 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004927 hw->private_data = p;
4928 hw->private_free = mydata_free;
4929]]>
4930 </programlisting>
4931 </informalexample>
4932
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004933 and the implementation of the destructor would be:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004934
4935 <informalexample>
4936 <programlisting>
4937<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004938 static void mydata_free(struct snd_hwdep *hw)
Linus Torvalds1da177e2005-04-16 15:20:36 -07004939 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004940 struct mydata *p = hw->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004941 kfree(p);
4942 }
4943]]>
4944 </programlisting>
4945 </informalexample>
4946 </para>
4947
4948 <para>
4949 The arbitrary file operations can be defined for this
4950 instance. The file operators are defined in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004951 the <parameter>ops</parameter> table. For example, assume that
Linus Torvalds1da177e2005-04-16 15:20:36 -07004952 this chip needs an ioctl.
4953
4954 <informalexample>
4955 <programlisting>
4956<![CDATA[
4957 hw->ops.open = mydata_open;
4958 hw->ops.ioctl = mydata_ioctl;
4959 hw->ops.release = mydata_release;
4960]]>
4961 </programlisting>
4962 </informalexample>
4963
4964 And implement the callback functions as you like.
4965 </para>
4966 </section>
4967
4968 <section id="misc-devices-IEC958">
4969 <title>IEC958 (S/PDIF)</title>
4970 <para>
4971 Usually the controls for IEC958 devices are implemented via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004972 the control interface. There is a macro to compose a name string for
Linus Torvalds1da177e2005-04-16 15:20:36 -07004973 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4974 defined in <filename>&lt;include/asound.h&gt;</filename>.
4975 </para>
4976
4977 <para>
4978 There are some standard controls for IEC958 status bits. These
4979 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4980 and the size of element is fixed as 4 bytes array
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004981 (value.iec958.status[x]). For the <structfield>info</structfield>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004982 callback, you don't specify
4983 the value field for this type (the count field must be set,
4984 though).
4985 </para>
4986
4987 <para>
4988 <quote>IEC958 Playback Con Mask</quote> is used to return the
4989 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4990 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4991 professional mode. They are read-only controls, and are defined
4992 as MIXER controls (iface =
4993 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4994 </para>
4995
4996 <para>
4997 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4998 defined for getting and setting the current default IEC958
4999 bits. Note that this one is usually defined as a PCM control
5000 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
5001 although in some places it's defined as a MIXER control.
5002 </para>
5003
5004 <para>
5005 In addition, you can define the control switches to
5006 enable/disable or to set the raw bit mode. The implementation
5007 will depend on the chip, but the control should be named as
5008 <quote>IEC958 xxx</quote>, preferably using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005009 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005010 </para>
5011
5012 <para>
5013 You can find several cases, for example,
5014 <filename>pci/emu10k1</filename>,
5015 <filename>pci/ice1712</filename>, or
5016 <filename>pci/cmipci.c</filename>.
5017 </para>
5018 </section>
5019
5020 </chapter>
5021
5022
5023<!-- ****************************************************** -->
5024<!-- Buffer and Memory Management -->
5025<!-- ****************************************************** -->
5026 <chapter id="buffer-and-memory">
5027 <title>Buffer and Memory Management</title>
5028
5029 <section id="buffer-and-memory-buffer-types">
5030 <title>Buffer Types</title>
5031 <para>
5032 ALSA provides several different buffer allocation functions
5033 depending on the bus and the architecture. All these have a
5034 consistent API. The allocation of physically-contiguous pages is
5035 done via
5036 <function>snd_malloc_xxx_pages()</function> function, where xxx
5037 is the bus type.
5038 </para>
5039
5040 <para>
5041 The allocation of pages with fallback is
5042 <function>snd_malloc_xxx_pages_fallback()</function>. This
5043 function tries to allocate the specified pages but if the pages
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005044 are not available, it tries to reduce the page sizes until
Linus Torvalds1da177e2005-04-16 15:20:36 -07005045 enough space is found.
5046 </para>
5047
5048 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005049 The release the pages, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005050 <function>snd_free_xxx_pages()</function> function.
5051 </para>
5052
5053 <para>
5054 Usually, ALSA drivers try to allocate and reserve
5055 a large contiguous physical space
5056 at the time the module is loaded for the later use.
5057 This is called <quote>pre-allocation</quote>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005058 As already written, you can call the following function at
5059 pcm instance construction time (in the case of PCI bus).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005060
5061 <informalexample>
5062 <programlisting>
5063<![CDATA[
5064 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5065 snd_dma_pci_data(pci), size, max);
5066]]>
5067 </programlisting>
5068 </informalexample>
5069
5070 where <parameter>size</parameter> is the byte size to be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005071 pre-allocated and the <parameter>max</parameter> is the maximum
5072 size to be changed via the <filename>prealloc</filename> proc file.
5073 The allocator will try to get an area as large as possible
Linus Torvalds1da177e2005-04-16 15:20:36 -07005074 within the given size.
5075 </para>
5076
5077 <para>
5078 The second argument (type) and the third argument (device pointer)
5079 are dependent on the bus.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005080 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005081 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5082 For the continuous buffer unrelated to the bus can be pre-allocated
5083 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5084 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005085 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
David S. Miller759ee812008-08-27 00:33:26 -07005086 use.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005087 For the PCI scatter-gather buffers, use
5088 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5089 <function>snd_dma_pci_data(pci)</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005090 (see the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005091 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005092 </citetitle></link> section).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005093 </para>
5094
5095 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005096 Once the buffer is pre-allocated, you can use the
5097 allocator in the <structfield>hw_params</structfield> callback:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005098
5099 <informalexample>
5100 <programlisting>
5101<![CDATA[
5102 snd_pcm_lib_malloc_pages(substream, size);
5103]]>
5104 </programlisting>
5105 </informalexample>
5106
5107 Note that you have to pre-allocate to use this function.
5108 </para>
5109 </section>
5110
5111 <section id="buffer-and-memory-external-hardware">
5112 <title>External Hardware Buffers</title>
5113 <para>
5114 Some chips have their own hardware buffers and the DMA
5115 transfer from the host memory is not available. In such a case,
5116 you need to either 1) copy/set the audio data directly to the
5117 external hardware buffer, or 2) make an intermediate buffer and
5118 copy/set the data from it to the external hardware buffer in
5119 interrupts (or in tasklets, preferably).
5120 </para>
5121
5122 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005123 The first case works fine if the external hardware buffer is large
5124 enough. This method doesn't need any extra buffers and thus is
Linus Torvalds1da177e2005-04-16 15:20:36 -07005125 more effective. You need to define the
5126 <structfield>copy</structfield> and
5127 <structfield>silence</structfield> callbacks for
5128 the data transfer. However, there is a drawback: it cannot
5129 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5130 wavetable PCM.
5131 </para>
5132
5133 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005134 The second case allows for mmap on the buffer, although you have
5135 to handle an interrupt or a tasklet to transfer the data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005136 from the intermediate buffer to the hardware buffer. You can find an
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005137 example in the vxpocket driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005138 </para>
5139
5140 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005141 Another case is when the chip uses a PCI memory-map
Linus Torvalds1da177e2005-04-16 15:20:36 -07005142 region for the buffer instead of the host memory. In this case,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005143 mmap is available only on certain architectures like the Intel one.
5144 In non-mmap mode, the data cannot be transferred as in the normal
5145 way. Thus you need to define the <structfield>copy</structfield> and
5146 <structfield>silence</structfield> callbacks as well,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005147 as in the cases above. The examples are found in
5148 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5149 </para>
5150
5151 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005152 The implementation of the <structfield>copy</structfield> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07005153 <structfield>silence</structfield> callbacks depends upon
5154 whether the hardware supports interleaved or non-interleaved
5155 samples. The <structfield>copy</structfield> callback is
5156 defined like below, a bit
5157 differently depending whether the direction is playback or
5158 capture:
5159
5160 <informalexample>
5161 <programlisting>
5162<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005163 static int playback_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005164 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005165 static int capture_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005166 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5167]]>
5168 </programlisting>
5169 </informalexample>
5170 </para>
5171
5172 <para>
5173 In the case of interleaved samples, the second argument
5174 (<parameter>channel</parameter>) is not used. The third argument
5175 (<parameter>pos</parameter>) points the
5176 current position offset in frames.
5177 </para>
5178
5179 <para>
5180 The meaning of the fourth argument is different between
5181 playback and capture. For playback, it holds the source data
5182 pointer, and for capture, it's the destination data pointer.
5183 </para>
5184
5185 <para>
5186 The last argument is the number of frames to be copied.
5187 </para>
5188
5189 <para>
5190 What you have to do in this callback is again different
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005191 between playback and capture directions. In the
5192 playback case, you copy the given amount of data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005193 (<parameter>count</parameter>) at the specified pointer
5194 (<parameter>src</parameter>) to the specified offset
5195 (<parameter>pos</parameter>) on the hardware buffer. When
5196 coded like memcpy-like way, the copy would be like:
5197
5198 <informalexample>
5199 <programlisting>
5200<![CDATA[
5201 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5202 frames_to_bytes(runtime, count));
5203]]>
5204 </programlisting>
5205 </informalexample>
5206 </para>
5207
5208 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005209 For the capture direction, you copy the given amount of
Linus Torvalds1da177e2005-04-16 15:20:36 -07005210 data (<parameter>count</parameter>) at the specified offset
5211 (<parameter>pos</parameter>) on the hardware buffer to the
5212 specified pointer (<parameter>dst</parameter>).
5213
5214 <informalexample>
5215 <programlisting>
5216<![CDATA[
5217 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5218 frames_to_bytes(runtime, count));
5219]]>
5220 </programlisting>
5221 </informalexample>
5222
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005223 Note that both the position and the amount of data are given
Linus Torvalds1da177e2005-04-16 15:20:36 -07005224 in frames.
5225 </para>
5226
5227 <para>
5228 In the case of non-interleaved samples, the implementation
5229 will be a bit more complicated.
5230 </para>
5231
5232 <para>
5233 You need to check the channel argument, and if it's -1, copy
5234 the whole channels. Otherwise, you have to copy only the
5235 specified channel. Please check
5236 <filename>isa/gus/gus_pcm.c</filename> as an example.
5237 </para>
5238
5239 <para>
5240 The <structfield>silence</structfield> callback is also
5241 implemented in a similar way.
5242
5243 <informalexample>
5244 <programlisting>
5245<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005246 static int silence(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005247 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5248]]>
5249 </programlisting>
5250 </informalexample>
5251 </para>
5252
5253 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005254 The meanings of arguments are the same as in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005255 <structfield>copy</structfield>
5256 callback, although there is no <parameter>src/dst</parameter>
5257 argument. In the case of interleaved samples, the channel
5258 argument has no meaning, as well as on
5259 <structfield>copy</structfield> callback.
5260 </para>
5261
5262 <para>
5263 The role of <structfield>silence</structfield> callback is to
5264 set the given amount
5265 (<parameter>count</parameter>) of silence data at the
5266 specified offset (<parameter>pos</parameter>) on the hardware
5267 buffer. Suppose that the data format is signed (that is, the
5268 silent-data is 0), and the implementation using a memset-like
5269 function would be like:
5270
5271 <informalexample>
5272 <programlisting>
5273<![CDATA[
5274 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5275 frames_to_bytes(runtime, count));
5276]]>
5277 </programlisting>
5278 </informalexample>
5279 </para>
5280
5281 <para>
5282 In the case of non-interleaved samples, again, the
5283 implementation becomes a bit more complicated. See, for example,
5284 <filename>isa/gus/gus_pcm.c</filename>.
5285 </para>
5286 </section>
5287
5288 <section id="buffer-and-memory-non-contiguous">
5289 <title>Non-Contiguous Buffers</title>
5290 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005291 If your hardware supports the page table as in emu10k1 or the
5292 buffer descriptors as in via82xx, you can use the scatter-gather
Linus Torvalds1da177e2005-04-16 15:20:36 -07005293 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5294 The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
5295 </para>
5296
5297 <para>
5298 For creating the SG-buffer handler, call
5299 <function>snd_pcm_lib_preallocate_pages()</function> or
5300 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5301 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5302 in the PCM constructor like other PCI pre-allocator.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005303 You need to pass <function>snd_dma_pci_data(pci)</function>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005304 where pci is the struct <structname>pci_dev</structname> pointer
5305 of the chip as well.
Giuliano Pochini44275f12006-01-27 12:02:05 +01005306 The <type>struct snd_sg_buf</type> instance is created as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005307 substream-&gt;dma_private. You can cast
5308 the pointer like:
5309
5310 <informalexample>
5311 <programlisting>
5312<![CDATA[
Giuliano Pochini44275f12006-01-27 12:02:05 +01005313 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005314]]>
5315 </programlisting>
5316 </informalexample>
5317 </para>
5318
5319 <para>
5320 Then call <function>snd_pcm_lib_malloc_pages()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005321 in the <structfield>hw_params</structfield> callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07005322 as well as in the case of normal PCI buffer.
5323 The SG-buffer handler will allocate the non-contiguous kernel
5324 pages of the given size and map them onto the virtually contiguous
5325 memory. The virtual pointer is addressed in runtime-&gt;dma_area.
5326 The physical address (runtime-&gt;dma_addr) is set to zero,
André Goddard Rosaaf901ca2009-11-14 13:09:05 -02005327 because the buffer is physically non-contiguous.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005328 The physical address table is set up in sgbuf-&gt;table.
5329 You can get the physical address at a certain offset via
5330 <function>snd_pcm_sgbuf_get_addr()</function>.
5331 </para>
5332
5333 <para>
5334 When a SG-handler is used, you need to set
5335 <function>snd_pcm_sgbuf_ops_page</function> as
5336 the <structfield>page</structfield> callback.
5337 (See <link linkend="pcm-interface-operators-page-callback">
5338 <citetitle>page callback section</citetitle></link>.)
5339 </para>
5340
5341 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005342 To release the data, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005343 <function>snd_pcm_lib_free_pages()</function> in the
5344 <structfield>hw_free</structfield> callback as usual.
5345 </para>
5346 </section>
5347
5348 <section id="buffer-and-memory-vmalloced">
5349 <title>Vmalloc'ed Buffers</title>
5350 <para>
5351 It's possible to use a buffer allocated via
5352 <function>vmalloc</function>, for example, for an intermediate
5353 buffer. Since the allocated pages are not contiguous, you need
5354 to set the <structfield>page</structfield> callback to obtain
5355 the physical address at every offset.
5356 </para>
5357
5358 <para>
5359 The implementation of <structfield>page</structfield> callback
5360 would be like this:
5361
5362 <informalexample>
5363 <programlisting>
5364<![CDATA[
5365 #include <linux/vmalloc.h>
5366
5367 /* get the physical page pointer on the given offset */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005368 static struct page *mychip_page(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005369 unsigned long offset)
5370 {
5371 void *pageptr = substream->runtime->dma_area + offset;
5372 return vmalloc_to_page(pageptr);
5373 }
5374]]>
5375 </programlisting>
5376 </informalexample>
5377 </para>
5378 </section>
5379
5380 </chapter>
5381
5382
5383<!-- ****************************************************** -->
5384<!-- Proc Interface -->
5385<!-- ****************************************************** -->
5386 <chapter id="proc-interface">
5387 <title>Proc Interface</title>
5388 <para>
5389 ALSA provides an easy interface for procfs. The proc files are
5390 very useful for debugging. I recommend you set up proc files if
5391 you write a driver and want to get a running status or register
5392 dumps. The API is found in
5393 <filename>&lt;sound/info.h&gt;</filename>.
5394 </para>
5395
5396 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005397 To create a proc file, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005398 <function>snd_card_proc_new()</function>.
5399
5400 <informalexample>
5401 <programlisting>
5402<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005403 struct snd_info_entry *entry;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005404 int err = snd_card_proc_new(card, "my-file", &entry);
5405]]>
5406 </programlisting>
5407 </informalexample>
5408
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005409 where the second argument specifies the name of the proc file to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005410 created. The above example will create a file
5411 <filename>my-file</filename> under the card directory,
5412 e.g. <filename>/proc/asound/card0/my-file</filename>.
5413 </para>
5414
5415 <para>
5416 Like other components, the proc entry created via
5417 <function>snd_card_proc_new()</function> will be registered and
5418 released automatically in the card registration and release
5419 functions.
5420 </para>
5421
5422 <para>
5423 When the creation is successful, the function stores a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005424 instance in the pointer given in the third argument.
5425 It is initialized as a text proc file for read only. To use
Linus Torvalds1da177e2005-04-16 15:20:36 -07005426 this proc file as a read-only text file as it is, set the read
5427 callback with a private data via
5428 <function>snd_info_set_text_ops()</function>.
5429
5430 <informalexample>
5431 <programlisting>
5432<![CDATA[
Takashi Iwaibf850202006-04-28 15:13:41 +02005433 snd_info_set_text_ops(entry, chip, my_proc_read);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005434]]>
5435 </programlisting>
5436 </informalexample>
5437
5438 where the second argument (<parameter>chip</parameter>) is the
5439 private data to be used in the callbacks. The third parameter
5440 specifies the read buffer size and the fourth
5441 (<parameter>my_proc_read</parameter>) is the callback function, which
5442 is defined like
5443
5444 <informalexample>
5445 <programlisting>
5446<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005447 static void my_proc_read(struct snd_info_entry *entry,
5448 struct snd_info_buffer *buffer);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005449]]>
5450 </programlisting>
5451 </informalexample>
5452
5453 </para>
5454
5455 <para>
5456 In the read callback, use <function>snd_iprintf()</function> for
5457 output strings, which works just like normal
5458 <function>printf()</function>. For example,
5459
5460 <informalexample>
5461 <programlisting>
5462<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005463 static void my_proc_read(struct snd_info_entry *entry,
5464 struct snd_info_buffer *buffer)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005465 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005466 struct my_chip *chip = entry->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005467
5468 snd_iprintf(buffer, "This is my chip!\n");
5469 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5470 }
5471]]>
5472 </programlisting>
5473 </informalexample>
5474 </para>
5475
5476 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005477 The file permissions can be changed afterwards. As default, it's
5478 set as read only for all users. If you want to add write
5479 permission for the user (root as default), do as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005480
5481 <informalexample>
5482 <programlisting>
5483<![CDATA[
5484 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5485]]>
5486 </programlisting>
5487 </informalexample>
5488
5489 and set the write buffer size and the callback
5490
5491 <informalexample>
5492 <programlisting>
5493<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -07005494 entry->c.text.write = my_proc_write;
5495]]>
5496 </programlisting>
5497 </informalexample>
5498 </para>
5499
5500 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005501 For the write callback, you can use
5502 <function>snd_info_get_line()</function> to get a text line, and
5503 <function>snd_info_get_str()</function> to retrieve a string from
5504 the line. Some examples are found in
5505 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5506 <filename>pcm_oss.c</filename>.
5507 </para>
5508
5509 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005510 For a raw-data proc-file, set the attributes as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005511
5512 <informalexample>
5513 <programlisting>
5514<![CDATA[
5515 static struct snd_info_entry_ops my_file_io_ops = {
5516 .read = my_file_io_read,
5517 };
5518
5519 entry->content = SNDRV_INFO_CONTENT_DATA;
5520 entry->private_data = chip;
5521 entry->c.ops = &my_file_io_ops;
5522 entry->size = 4096;
5523 entry->mode = S_IFREG | S_IRUGO;
5524]]>
5525 </programlisting>
5526 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005527
5528 For the raw data, <structfield>size</structfield> field must be
5529 set properly. This specifies the maximum size of the proc file access.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005530 </para>
5531
5532 <para>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005533 The read/write callbacks of raw mode are more direct than the text mode.
5534 You need to use a low-level I/O functions such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005535 <function>copy_from/to_user()</function> to transfer the
5536 data.
5537
5538 <informalexample>
5539 <programlisting>
5540<![CDATA[
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005541 static ssize_t my_file_io_read(struct snd_info_entry *entry,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005542 void *file_private_data,
5543 struct file *file,
5544 char *buf,
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005545 size_t count,
5546 loff_t pos)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005547 {
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005548 if (copy_to_user(buf, local_data + pos, count))
Linus Torvalds1da177e2005-04-16 15:20:36 -07005549 return -EFAULT;
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005550 return count;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005551 }
5552]]>
5553 </programlisting>
5554 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005555
5556 If the size of the info entry has been set up properly,
5557 <structfield>count</structfield> and <structfield>pos</structfield> are
5558 guaranteed to fit within 0 and the given size.
5559 You don't have to check the range in the callbacks unless any
5560 other condition is required.
5561
Linus Torvalds1da177e2005-04-16 15:20:36 -07005562 </para>
5563
5564 </chapter>
5565
5566
5567<!-- ****************************************************** -->
5568<!-- Power Management -->
5569<!-- ****************************************************** -->
5570 <chapter id="power-management">
5571 <title>Power Management</title>
5572 <para>
Paolo Ornati670e9f32006-10-03 22:57:56 +02005573 If the chip is supposed to work with suspend/resume
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005574 functions, you need to add power-management code to the
5575 driver. The additional code for power-management should be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005576 <function>ifdef</function>'ed with
5577 <constant>CONFIG_PM</constant>.
5578 </para>
5579
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005580 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005581 If the driver <emphasis>fully</emphasis> supports suspend/resume
5582 that is, the device can be
5583 properly resumed to its state when suspend was called,
5584 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5585 in the pcm info field. Usually, this is possible when the
5586 registers of the chip can be safely saved and restored to
5587 RAM. If this is set, the trigger callback is called with
5588 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5589 callback completes.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005590 </para>
5591
5592 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005593 Even if the driver doesn't support PM fully but
5594 partial suspend/resume is still possible, it's still worthy to
5595 implement suspend/resume callbacks. In such a case, applications
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005596 would reset the status by calling
5597 <function>snd_pcm_prepare()</function> and restart the stream
5598 appropriately. Hence, you can define suspend/resume callbacks
5599 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5600 info flag to the PCM.
5601 </para>
5602
5603 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005604 Note that the trigger with SUSPEND can always be called when
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005605 <function>snd_pcm_suspend_all</function> is called,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005606 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005607 The <constant>RESUME</constant> flag affects only the behavior
5608 of <function>snd_pcm_resume()</function>.
5609 (Thus, in theory,
5610 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5611 to be handled in the trigger callback when no
5612 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005613 it's better to keep it for compatibility reasons.)
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005614 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005615 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005616 In the earlier version of ALSA drivers, a common
5617 power-management layer was provided, but it has been removed.
5618 The driver needs to define the suspend/resume hooks according to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005619 the bus the device is connected to. In the case of PCI drivers, the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005620 callbacks look like below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005621
5622 <informalexample>
5623 <programlisting>
5624<![CDATA[
5625 #ifdef CONFIG_PM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005626 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005627 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005628 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005629 return 0;
5630 }
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005631 static int snd_my_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005632 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005633 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005634 return 0;
5635 }
5636 #endif
5637]]>
5638 </programlisting>
5639 </informalexample>
5640 </para>
5641
5642 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005643 The scheme of the real suspend job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005644
5645 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005646 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5647 <listitem><para>Call <function>snd_power_change_state()</function> with
5648 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5649 power status.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005650 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005651 <listitem><para>If AC97 codecs are used, call
Takashi Iwaia7306332006-05-04 11:58:43 +02005652 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005653 <listitem><para>Save the register values if necessary.</para></listitem>
5654 <listitem><para>Stop the hardware if necessary.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005655 <listitem><para>Disable the PCI device by calling
5656 <function>pci_disable_device()</function>. Then, call
5657 <function>pci_save_state()</function> at last.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005658 </orderedlist>
5659 </para>
5660
5661 <para>
5662 A typical code would be like:
5663
5664 <informalexample>
5665 <programlisting>
5666<![CDATA[
Alexey Dobriyan323579882006-01-15 02:12:54 +01005667 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005668 {
5669 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005670 struct snd_card *card = pci_get_drvdata(pci);
5671 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005672 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005673 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005674 /* (3) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005675 snd_pcm_suspend_all(chip->pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005676 /* (4) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005677 snd_ac97_suspend(chip->ac97);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005678 /* (5) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005679 snd_mychip_save_registers(chip);
5680 /* (6) */
5681 snd_mychip_stop_hardware(chip);
5682 /* (7) */
5683 pci_disable_device(pci);
5684 pci_save_state(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005685 return 0;
5686 }
5687]]>
5688 </programlisting>
5689 </informalexample>
5690 </para>
5691
5692 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005693 The scheme of the real resume job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005694
5695 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005696 <listitem><para>Retrieve the card and the chip data.</para></listitem>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005697 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005698 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5699 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005700 <listitem><para>Re-initialize the chip.</para></listitem>
5701 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5702 <listitem><para>Resume the mixer, e.g. calling
5703 <function>snd_ac97_resume()</function>.</para></listitem>
5704 <listitem><para>Restart the hardware (if any).</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005705 <listitem><para>Call <function>snd_power_change_state()</function> with
5706 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005707 </orderedlist>
5708 </para>
5709
5710 <para>
5711 A typical code would be like:
5712
5713 <informalexample>
5714 <programlisting>
5715<![CDATA[
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005716 static int mychip_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005717 {
5718 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005719 struct snd_card *card = pci_get_drvdata(pci);
5720 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005721 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005722 pci_restore_state(pci);
5723 pci_enable_device(pci);
5724 pci_set_master(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005725 /* (3) */
5726 snd_mychip_reinit_chip(chip);
5727 /* (4) */
5728 snd_mychip_restore_registers(chip);
5729 /* (5) */
5730 snd_ac97_resume(chip->ac97);
5731 /* (6) */
5732 snd_mychip_restart_chip(chip);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005733 /* (7) */
5734 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005735 return 0;
5736 }
5737]]>
5738 </programlisting>
5739 </informalexample>
5740 </para>
5741
5742 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005743 As shown in the above, it's better to save registers after
5744 suspending the PCM operations via
5745 <function>snd_pcm_suspend_all()</function> or
5746 <function>snd_pcm_suspend()</function>. It means that the PCM
5747 streams are already stoppped when the register snapshot is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005748 taken. But, remember that you don't have to restart the PCM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005749 stream in the resume callback. It'll be restarted via
5750 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5751 when necessary.
5752 </para>
5753
5754 <para>
5755 OK, we have all callbacks now. Let's set them up. In the
5756 initialization of the card, make sure that you can get the chip
5757 data from the card instance, typically via
5758 <structfield>private_data</structfield> field, in case you
5759 created the chip data individually.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005760
5761 <informalexample>
5762 <programlisting>
5763<![CDATA[
5764 static int __devinit snd_mychip_probe(struct pci_dev *pci,
5765 const struct pci_device_id *pci_id)
5766 {
5767 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005768 struct snd_card *card;
5769 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005770 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005771 ....
Takashi Iwaid4533792008-12-28 16:45:34 +01005772 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005773 ....
5774 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5775 ....
5776 card->private_data = chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005777 ....
5778 }
5779]]>
5780 </programlisting>
5781 </informalexample>
5782
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005783 When you created the chip data with
Takashi Iwaid4533792008-12-28 16:45:34 +01005784 <function>snd_card_create()</function>, it's anyway accessible
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005785 via <structfield>private_data</structfield> field.
5786
5787 <informalexample>
5788 <programlisting>
5789<![CDATA[
5790 static int __devinit snd_mychip_probe(struct pci_dev *pci,
5791 const struct pci_device_id *pci_id)
5792 {
5793 ....
5794 struct snd_card *card;
5795 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005796 int err;
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005797 ....
Takashi Iwaid4533792008-12-28 16:45:34 +01005798 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
5799 sizeof(struct mychip), &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005800 ....
5801 chip = card->private_data;
5802 ....
5803 }
5804]]>
5805 </programlisting>
5806 </informalexample>
5807
Linus Torvalds1da177e2005-04-16 15:20:36 -07005808 </para>
5809
5810 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005811 If you need a space to save the registers, allocate the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005812 buffer for it here, too, since it would be fatal
Linus Torvalds1da177e2005-04-16 15:20:36 -07005813 if you cannot allocate a memory in the suspend phase.
5814 The allocated buffer should be released in the corresponding
5815 destructor.
5816 </para>
5817
5818 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005819 And next, set suspend/resume callbacks to the pci_driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005820
5821 <informalexample>
5822 <programlisting>
5823<![CDATA[
5824 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02005825 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005826 .id_table = snd_my_ids,
5827 .probe = snd_my_probe,
5828 .remove = __devexit_p(snd_my_remove),
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005829 #ifdef CONFIG_PM
5830 .suspend = snd_my_suspend,
5831 .resume = snd_my_resume,
5832 #endif
Linus Torvalds1da177e2005-04-16 15:20:36 -07005833 };
5834]]>
5835 </programlisting>
5836 </informalexample>
5837 </para>
5838
5839 </chapter>
5840
5841
5842<!-- ****************************************************** -->
5843<!-- Module Parameters -->
5844<!-- ****************************************************** -->
5845 <chapter id="module-parameters">
5846 <title>Module Parameters</title>
5847 <para>
5848 There are standard module options for ALSA. At least, each
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005849 module should have the <parameter>index</parameter>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005850 <parameter>id</parameter> and <parameter>enable</parameter>
5851 options.
5852 </para>
5853
5854 <para>
5855 If the module supports multiple cards (usually up to
5856 8 = <constant>SNDRV_CARDS</constant> cards), they should be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005857 arrays. The default initial values are defined already as
5858 constants for easier programming:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005859
5860 <informalexample>
5861 <programlisting>
5862<![CDATA[
5863 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5864 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5865 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5866]]>
5867 </programlisting>
5868 </informalexample>
5869 </para>
5870
5871 <para>
5872 If the module supports only a single card, they could be single
5873 variables, instead. <parameter>enable</parameter> option is not
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005874 always necessary in this case, but it would be better to have a
Linus Torvalds1da177e2005-04-16 15:20:36 -07005875 dummy option for compatibility.
5876 </para>
5877
5878 <para>
5879 The module parameters must be declared with the standard
5880 <function>module_param()()</function>,
5881 <function>module_param_array()()</function> and
5882 <function>MODULE_PARM_DESC()</function> macros.
5883 </para>
5884
5885 <para>
5886 The typical coding would be like below:
5887
5888 <informalexample>
5889 <programlisting>
5890<![CDATA[
5891 #define CARD_NAME "My Chip"
5892
5893 module_param_array(index, int, NULL, 0444);
5894 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5895 module_param_array(id, charp, NULL, 0444);
5896 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5897 module_param_array(enable, bool, NULL, 0444);
5898 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5899]]>
5900 </programlisting>
5901 </informalexample>
5902 </para>
5903
5904 <para>
5905 Also, don't forget to define the module description, classes,
5906 license and devices. Especially, the recent modprobe requires to
5907 define the module license as GPL, etc., otherwise the system is
5908 shown as <quote>tainted</quote>.
5909
5910 <informalexample>
5911 <programlisting>
5912<![CDATA[
5913 MODULE_DESCRIPTION("My Chip");
5914 MODULE_LICENSE("GPL");
5915 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5916]]>
5917 </programlisting>
5918 </informalexample>
5919 </para>
5920
5921 </chapter>
5922
5923
5924<!-- ****************************************************** -->
5925<!-- How To Put Your Driver -->
5926<!-- ****************************************************** -->
5927 <chapter id="how-to-put-your-driver">
5928 <title>How To Put Your Driver Into ALSA Tree</title>
5929 <section>
5930 <title>General</title>
5931 <para>
5932 So far, you've learned how to write the driver codes.
5933 And you might have a question now: how to put my own
5934 driver into the ALSA driver tree?
5935 Here (finally :) the standard procedure is described briefly.
5936 </para>
5937
5938 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005939 Suppose that you create a new PCI driver for the card
Linus Torvalds1da177e2005-04-16 15:20:36 -07005940 <quote>xyz</quote>. The card module name would be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005941 snd-xyz. The new driver is usually put into the alsa-driver
Linus Torvalds1da177e2005-04-16 15:20:36 -07005942 tree, <filename>alsa-driver/pci</filename> directory in
5943 the case of PCI cards.
5944 Then the driver is evaluated, audited and tested
5945 by developers and users. After a certain time, the driver
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005946 will go to the alsa-kernel tree (to the corresponding directory,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005947 such as <filename>alsa-kernel/pci</filename>) and eventually
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005948 will be integrated into the Linux 2.6 tree (the directory would be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005949 <filename>linux/sound/pci</filename>).
5950 </para>
5951
5952 <para>
5953 In the following sections, the driver code is supposed
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005954 to be put into alsa-driver tree. The two cases are covered:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005955 a driver consisting of a single source file and one consisting
5956 of several source files.
5957 </para>
5958 </section>
5959
5960 <section>
5961 <title>Driver with A Single Source File</title>
5962 <para>
5963 <orderedlist>
5964 <listitem>
5965 <para>
5966 Modify alsa-driver/pci/Makefile
5967 </para>
5968
5969 <para>
5970 Suppose you have a file xyz.c. Add the following
5971 two lines
5972 <informalexample>
5973 <programlisting>
5974<![CDATA[
5975 snd-xyz-objs := xyz.o
5976 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5977]]>
5978 </programlisting>
5979 </informalexample>
5980 </para>
5981 </listitem>
5982
5983 <listitem>
5984 <para>
5985 Create the Kconfig entry
5986 </para>
5987
5988 <para>
5989 Add the new entry of Kconfig for your xyz driver.
5990 <informalexample>
5991 <programlisting>
5992<![CDATA[
5993 config SND_XYZ
5994 tristate "Foobar XYZ"
5995 depends on SND
5996 select SND_PCM
5997 help
5998 Say Y here to include support for Foobar XYZ soundcard.
5999
6000 To compile this driver as a module, choose M here: the module
6001 will be called snd-xyz.
6002]]>
6003 </programlisting>
6004 </informalexample>
6005
6006 the line, select SND_PCM, specifies that the driver xyz supports
6007 PCM. In addition to SND_PCM, the following components are
6008 supported for select command:
6009 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
6010 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
6011 Add the select command for each supported component.
6012 </para>
6013
6014 <para>
6015 Note that some selections imply the lowlevel selections.
6016 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
6017 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
6018 You don't need to give the lowlevel selections again.
6019 </para>
6020
6021 <para>
6022 For the details of Kconfig script, refer to the kbuild
6023 documentation.
6024 </para>
6025
6026 </listitem>
6027
6028 <listitem>
6029 <para>
6030 Run cvscompile script to re-generate the configure script and
6031 build the whole stuff again.
6032 </para>
6033 </listitem>
6034 </orderedlist>
6035 </para>
6036 </section>
6037
6038 <section>
6039 <title>Drivers with Several Source Files</title>
6040 <para>
6041 Suppose that the driver snd-xyz have several source files.
6042 They are located in the new subdirectory,
6043 pci/xyz.
6044
6045 <orderedlist>
6046 <listitem>
6047 <para>
6048 Add a new directory (<filename>xyz</filename>) in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006049 <filename>alsa-driver/pci/Makefile</filename> as below
Linus Torvalds1da177e2005-04-16 15:20:36 -07006050
6051 <informalexample>
6052 <programlisting>
6053<![CDATA[
6054 obj-$(CONFIG_SND) += xyz/
6055]]>
6056 </programlisting>
6057 </informalexample>
6058 </para>
6059 </listitem>
6060
6061 <listitem>
6062 <para>
6063 Under the directory <filename>xyz</filename>, create a Makefile
6064
6065 <example>
6066 <title>Sample Makefile for a driver xyz</title>
6067 <programlisting>
6068<![CDATA[
6069 ifndef SND_TOPDIR
6070 SND_TOPDIR=../..
6071 endif
6072
6073 include $(SND_TOPDIR)/toplevel.config
6074 include $(SND_TOPDIR)/Makefile.conf
6075
6076 snd-xyz-objs := xyz.o abc.o def.o
6077
6078 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6079
6080 include $(SND_TOPDIR)/Rules.make
6081]]>
6082 </programlisting>
6083 </example>
6084 </para>
6085 </listitem>
6086
6087 <listitem>
6088 <para>
6089 Create the Kconfig entry
6090 </para>
6091
6092 <para>
6093 This procedure is as same as in the last section.
6094 </para>
6095 </listitem>
6096
6097 <listitem>
6098 <para>
6099 Run cvscompile script to re-generate the configure script and
6100 build the whole stuff again.
6101 </para>
6102 </listitem>
6103 </orderedlist>
6104 </para>
6105 </section>
6106
6107 </chapter>
6108
6109<!-- ****************************************************** -->
6110<!-- Useful Functions -->
6111<!-- ****************************************************** -->
6112 <chapter id="useful-functions">
6113 <title>Useful Functions</title>
6114
6115 <section id="useful-functions-snd-printk">
6116 <title><function>snd_printk()</function> and friends</title>
6117 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006118 ALSA provides a verbose version of the
Linus Torvalds1da177e2005-04-16 15:20:36 -07006119 <function>printk()</function> function. If a kernel config
6120 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6121 function prints the given message together with the file name
6122 and the line of the caller. The <constant>KERN_XXX</constant>
6123 prefix is processed as
6124 well as the original <function>printk()</function> does, so it's
6125 recommended to add this prefix, e.g.
6126
6127 <informalexample>
6128 <programlisting>
6129<![CDATA[
6130 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6131]]>
6132 </programlisting>
6133 </informalexample>
6134 </para>
6135
6136 <para>
6137 There are also <function>printk()</function>'s for
6138 debugging. <function>snd_printd()</function> can be used for
6139 general debugging purposes. If
6140 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6141 compiled, and works just like
6142 <function>snd_printk()</function>. If the ALSA is compiled
6143 without the debugging flag, it's ignored.
6144 </para>
6145
6146 <para>
6147 <function>snd_printdd()</function> is compiled in only when
Takashi Iwai62cf8722008-05-20 12:15:15 +02006148 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6149 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
Linus Torvalds1da177e2005-04-16 15:20:36 -07006150 even if you configure the alsa-driver with
6151 <option>--with-debug=full</option> option. You need to give
6152 explicitly <option>--with-debug=detect</option> option instead.
6153 </para>
6154 </section>
6155
Linus Torvalds1da177e2005-04-16 15:20:36 -07006156 <section id="useful-functions-snd-bug">
6157 <title><function>snd_BUG()</function></title>
6158 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006159 It shows the <computeroutput>BUG?</computeroutput> message and
Takashi Iwai7cc6dff2008-08-08 17:14:55 +02006160 stack trace as well as <function>snd_BUG_ON</function> at the point.
Takashi Iwai7c22f1a2005-10-10 11:46:31 +02006161 It's useful to show that a fatal error happens there.
6162 </para>
6163 <para>
6164 When no debug flag is set, this macro is ignored.
Linus Torvalds1da177e2005-04-16 15:20:36 -07006165 </para>
6166 </section>
Takashi Iwai5ef03462008-08-08 17:06:01 +02006167
6168 <section id="useful-functions-snd-bug-on">
6169 <title><function>snd_BUG_ON()</function></title>
6170 <para>
6171 <function>snd_BUG_ON()</function> macro is similar with
6172 <function>WARN_ON()</function> macro. For example,
6173
6174 <informalexample>
6175 <programlisting>
6176<![CDATA[
6177 snd_BUG_ON(!pointer);
6178]]>
6179 </programlisting>
6180 </informalexample>
6181
6182 or it can be used as the condition,
6183 <informalexample>
6184 <programlisting>
6185<![CDATA[
6186 if (snd_BUG_ON(non_zero_is_bug))
6187 return -EINVAL;
6188]]>
6189 </programlisting>
6190 </informalexample>
6191
6192 </para>
6193
6194 <para>
6195 The macro takes an conditional expression to evaluate.
6196 When <constant>CONFIG_SND_DEBUG</constant>, is set, the
6197 expression is actually evaluated. If it's non-zero, it shows
6198 the warning message such as
6199 <computeroutput>BUG? (xxx)</computeroutput>
6200 normally followed by stack trace. It returns the evaluated
6201 value.
6202 When no <constant>CONFIG_SND_DEBUG</constant> is set, this
6203 macro always returns zero.
6204 </para>
6205
6206 </section>
6207
Linus Torvalds1da177e2005-04-16 15:20:36 -07006208 </chapter>
6209
6210
6211<!-- ****************************************************** -->
6212<!-- Acknowledgments -->
6213<!-- ****************************************************** -->
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01006214 <chapter id="acknowledgments">
Linus Torvalds1da177e2005-04-16 15:20:36 -07006215 <title>Acknowledgments</title>
6216 <para>
6217 I would like to thank Phil Kerr for his help for improvement and
6218 corrections of this document.
6219 </para>
6220 <para>
6221 Kevin Conder reformatted the original plain-text to the
6222 DocBook format.
6223 </para>
6224 <para>
6225 Giuliano Pochini corrected typos and contributed the example codes
6226 in the hardware constraints section.
6227 </para>
6228 </chapter>
Linus Torvalds1da177e2005-04-16 15:20:36 -07006229</book>