blob: 06741e9259850d43eaac5d287da48fa284992255 [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 Iwai090015a2012-12-07 07:52:28 +0100436 static int snd_mychip_create(struct snd_card *card,
437 struct pci_dev *pci,
438 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 */
Takashi Iwai090015a2012-12-07 07:52:28 +0100478 static int snd_mychip_probe(struct pci_dev *pci,
479 const struct pci_device_id *pci_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700480 {
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 */
Takashi Iwai090015a2012-12-07 07:52:28 +0100529 static void snd_mychip_remove(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700530 {
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
Takashi Iwai090015a2012-12-07 07:52:28 +0100545 from the <function>probe</function> callback cannot be used with
546 the <parameter>__init</parameter> prefix
Linus Torvalds1da177e2005-04-16 15:20:36 -0700547 because any PCI device could be a hotplug device.
548 </para>
549
550 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200551 In the <function>probe</function> callback, the following scheme is often used.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700552 </para>
553
554 <section id="basic-flow-constructor-device-index">
555 <title>1) Check and increment the device index.</title>
556 <para>
557 <informalexample>
558 <programlisting>
559<![CDATA[
560 static int dev;
561 ....
562 if (dev >= SNDRV_CARDS)
563 return -ENODEV;
564 if (!enable[dev]) {
565 dev++;
566 return -ENOENT;
567 }
568]]>
569 </programlisting>
570 </informalexample>
571
572 where enable[dev] is the module option.
573 </para>
574
575 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200576 Each time the <function>probe</function> callback is called, check the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700577 availability of the device. If not available, simply increment
578 the device index and returns. dev will be incremented also
579 later (<link
580 linkend="basic-flow-constructor-set-pci"><citetitle>step
581 7</citetitle></link>).
582 </para>
583 </section>
584
585 <section id="basic-flow-constructor-create-card">
586 <title>2) Create a card instance</title>
587 <para>
588 <informalexample>
589 <programlisting>
590<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100591 struct snd_card *card;
Takashi Iwaid4533792008-12-28 16:45:34 +0100592 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700593 ....
Takashi Iwaid4533792008-12-28 16:45:34 +0100594 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700595]]>
596 </programlisting>
597 </informalexample>
598 </para>
599
600 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200601 The details will be explained in the section
Linus Torvalds1da177e2005-04-16 15:20:36 -0700602 <link linkend="card-management-card-instance"><citetitle>
603 Management of Cards and Components</citetitle></link>.
604 </para>
605 </section>
606
607 <section id="basic-flow-constructor-create-main">
608 <title>3) Create a main component</title>
609 <para>
610 In this part, the PCI resources are allocated.
611
612 <informalexample>
613 <programlisting>
614<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100615 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700616 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +0200617 err = snd_mychip_create(card, pci, &chip);
618 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700619 snd_card_free(card);
620 return err;
621 }
622]]>
623 </programlisting>
624 </informalexample>
625
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200626 The details will be explained in the section <link
Linus Torvalds1da177e2005-04-16 15:20:36 -0700627 linkend="pci-resource"><citetitle>PCI Resource
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200628 Management</citetitle></link>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700629 </para>
630 </section>
631
632 <section id="basic-flow-constructor-main-component">
633 <title>4) Set the driver ID and name strings.</title>
634 <para>
635 <informalexample>
636 <programlisting>
637<![CDATA[
638 strcpy(card->driver, "My Chip");
639 strcpy(card->shortname, "My Own Chip 123");
640 sprintf(card->longname, "%s at 0x%lx irq %i",
641 card->shortname, chip->ioport, chip->irq);
642]]>
643 </programlisting>
644 </informalexample>
645
646 The driver field holds the minimal ID string of the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200647 chip. This is used by alsa-lib's configurator, so keep it
Linus Torvalds1da177e2005-04-16 15:20:36 -0700648 simple but unique.
649 Even the same driver can have different driver IDs to
650 distinguish the functionality of each chip type.
651 </para>
652
653 <para>
654 The shortname field is a string shown as more verbose
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200655 name. The longname field contains the information
Linus Torvalds1da177e2005-04-16 15:20:36 -0700656 shown in <filename>/proc/asound/cards</filename>.
657 </para>
658 </section>
659
660 <section id="basic-flow-constructor-create-other">
661 <title>5) Create other components, such as mixer, MIDI, etc.</title>
662 <para>
663 Here you define the basic components such as
664 <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
665 mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
666 MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
667 and other interfaces.
668 Also, if you want a <link linkend="proc-interface"><citetitle>proc
669 file</citetitle></link>, define it here, too.
670 </para>
671 </section>
672
673 <section id="basic-flow-constructor-register-card">
674 <title>6) Register the card instance.</title>
675 <para>
676 <informalexample>
677 <programlisting>
678<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +0200679 err = snd_card_register(card);
680 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700681 snd_card_free(card);
682 return err;
683 }
684]]>
685 </programlisting>
686 </informalexample>
687 </para>
688
689 <para>
690 Will be explained in the section <link
691 linkend="card-management-registration"><citetitle>Management
692 of Cards and Components</citetitle></link>, too.
693 </para>
694 </section>
695
696 <section id="basic-flow-constructor-set-pci">
697 <title>7) Set the PCI driver data and return zero.</title>
698 <para>
699 <informalexample>
700 <programlisting>
701<![CDATA[
702 pci_set_drvdata(pci, card);
703 dev++;
704 return 0;
705]]>
706 </programlisting>
707 </informalexample>
708
709 In the above, the card record is stored. This pointer is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200710 used in the remove callback and power-management
Linus Torvalds1da177e2005-04-16 15:20:36 -0700711 callbacks, too.
712 </para>
713 </section>
714 </section>
715
716 <section id="basic-flow-destructor">
717 <title>Destructor</title>
718 <para>
719 The destructor, remove callback, simply releases the card
720 instance. Then the ALSA middle layer will release all the
721 attached components automatically.
722 </para>
723
724 <para>
725 It would be typically like the following:
726
727 <informalexample>
728 <programlisting>
729<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +0100730 static void snd_mychip_remove(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700731 {
732 snd_card_free(pci_get_drvdata(pci));
733 pci_set_drvdata(pci, NULL);
734 }
735]]>
736 </programlisting>
737 </informalexample>
738
739 The above code assumes that the card pointer is set to the PCI
740 driver data.
741 </para>
742 </section>
743
744 <section id="basic-flow-header-files">
745 <title>Header Files</title>
746 <para>
747 For the above example, at least the following include files
748 are necessary.
749
750 <informalexample>
751 <programlisting>
752<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -0700753 #include <linux/init.h>
754 #include <linux/pci.h>
755 #include <linux/slab.h>
756 #include <sound/core.h>
757 #include <sound/initval.h>
758]]>
759 </programlisting>
760 </informalexample>
761
762 where the last one is necessary only when module options are
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200763 defined in the source file. If the code is split into several
764 files, the files without module options don't need them.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700765 </para>
766
767 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200768 In addition to these headers, you'll need
769 <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
770 handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
771 access. If you use the <function>mdelay()</function> or
Linus Torvalds1da177e2005-04-16 15:20:36 -0700772 <function>udelay()</function> functions, you'll need to include
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200773 <filename>&lt;linux/delay.h&gt;</filename> too.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700774 </para>
775
776 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200777 The ALSA interfaces like the PCM and control APIs are defined in other
778 <filename>&lt;sound/xxx.h&gt;</filename> header files.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700779 They have to be included after
780 <filename>&lt;sound/core.h&gt;</filename>.
781 </para>
782
783 </section>
784 </chapter>
785
786
787<!-- ****************************************************** -->
788<!-- Management of Cards and Components -->
789<!-- ****************************************************** -->
790 <chapter id="card-management">
791 <title>Management of Cards and Components</title>
792
793 <section id="card-management-card-instance">
794 <title>Card Instance</title>
795 <para>
796 For each soundcard, a <quote>card</quote> record must be allocated.
797 </para>
798
799 <para>
800 A card record is the headquarters of the soundcard. It manages
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200801 the whole list of devices (components) on the soundcard, such as
Linus Torvalds1da177e2005-04-16 15:20:36 -0700802 PCM, mixers, MIDI, synthesizer, and so on. Also, the card
803 record holds the ID and the name strings of the card, manages
804 the root of proc files, and controls the power-management states
805 and hotplug disconnections. The component list on the card
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200806 record is used to manage the correct release of resources at
Linus Torvalds1da177e2005-04-16 15:20:36 -0700807 destruction.
808 </para>
809
810 <para>
811 As mentioned above, to create a card instance, call
Takashi Iwaid4533792008-12-28 16:45:34 +0100812 <function>snd_card_create()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700813
814 <informalexample>
815 <programlisting>
816<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100817 struct snd_card *card;
Takashi Iwaid4533792008-12-28 16:45:34 +0100818 int err;
819 err = snd_card_create(index, id, module, extra_size, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700820]]>
821 </programlisting>
822 </informalexample>
823 </para>
824
825 <para>
Takashi Iwaid4533792008-12-28 16:45:34 +0100826 The function takes five arguments, the card-index number, the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700827 id string, the module pointer (usually
828 <constant>THIS_MODULE</constant>),
Takashi Iwaid4533792008-12-28 16:45:34 +0100829 the size of extra-data space, and the pointer to return the
830 card instance. The extra_size argument is used to
Linus Torvalds1da177e2005-04-16 15:20:36 -0700831 allocate card-&gt;private_data for the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200832 chip-specific data. Note that these data
Takashi Iwaid4533792008-12-28 16:45:34 +0100833 are allocated by <function>snd_card_create()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700834 </para>
835 </section>
836
837 <section id="card-management-component">
838 <title>Components</title>
839 <para>
840 After the card is created, you can attach the components
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200841 (devices) to the card instance. In an ALSA driver, a component is
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100842 represented as a struct <structname>snd_device</structname> object.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700843 A component can be a PCM instance, a control interface, a raw
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200844 MIDI interface, etc. Each such instance has one component
Linus Torvalds1da177e2005-04-16 15:20:36 -0700845 entry.
846 </para>
847
848 <para>
849 A component can be created via
850 <function>snd_device_new()</function> function.
851
852 <informalexample>
853 <programlisting>
854<![CDATA[
855 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
856]]>
857 </programlisting>
858 </informalexample>
859 </para>
860
861 <para>
862 This takes the card pointer, the device-level
863 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
864 callback pointers (<parameter>&amp;ops</parameter>). The
865 device-level defines the type of components and the order of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200866 registration and de-registration. For most components, the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700867 device-level is already defined. For a user-defined component,
868 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
869 </para>
870
871 <para>
872 This function itself doesn't allocate the data space. The data
873 must be allocated manually beforehand, and its pointer is passed
Antonio Ospite04044b82013-01-29 12:56:27 +0100874 as the argument. This pointer (<parameter>chip</parameter> in the
875 above example) is used as the identifier for the instance.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700876 </para>
877
878 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200879 Each pre-defined ALSA component such as ac97 and pcm calls
Linus Torvalds1da177e2005-04-16 15:20:36 -0700880 <function>snd_device_new()</function> inside its
881 constructor. The destructor for each component is defined in the
882 callback pointers. Hence, you don't need to take care of
883 calling a destructor for such a component.
884 </para>
885
886 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200887 If you wish to create your own component, you need to
888 set the destructor function to the dev_free callback in
889 the <parameter>ops</parameter>, so that it can be released
890 automatically via <function>snd_card_free()</function>.
891 The next example will show an implementation of chip-specific
892 data.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700893 </para>
894 </section>
895
896 <section id="card-management-chip-specific">
897 <title>Chip-Specific Data</title>
898 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200899 Chip-specific information, e.g. the I/O port address, its
Linus Torvalds1da177e2005-04-16 15:20:36 -0700900 resource pointer, or the irq number, is stored in the
901 chip-specific record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700902
903 <informalexample>
904 <programlisting>
905<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100906 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700907 ....
908 };
909]]>
910 </programlisting>
911 </informalexample>
912 </para>
913
914 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200915 In general, there are two ways of allocating the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700916 </para>
917
918 <section id="card-management-chip-specific-snd-card-new">
Takashi Iwaid4533792008-12-28 16:45:34 +0100919 <title>1. Allocating via <function>snd_card_create()</function>.</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700920 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200921 As mentioned above, you can pass the extra-data-length
Takashi Iwaid4533792008-12-28 16:45:34 +0100922 to the 4th argument of <function>snd_card_create()</function>, i.e.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700923
924 <informalexample>
925 <programlisting>
926<![CDATA[
Takashi Iwaid4533792008-12-28 16:45:34 +0100927 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
928 sizeof(struct mychip), &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700929]]>
930 </programlisting>
931 </informalexample>
932
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200933 struct <structname>mychip</structname> is the type of the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700934 </para>
935
936 <para>
937 In return, the allocated record can be accessed as
938
939 <informalexample>
940 <programlisting>
941<![CDATA[
Takashi Iwai437a5a42006-11-21 12:14:23 +0100942 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700943]]>
944 </programlisting>
945 </informalexample>
946
947 With this method, you don't have to allocate twice.
948 The record is released together with the card instance.
949 </para>
950 </section>
951
952 <section id="card-management-chip-specific-allocate-extra">
953 <title>2. Allocating an extra device.</title>
954
955 <para>
956 After allocating a card instance via
Takashi Iwaid4533792008-12-28 16:45:34 +0100957 <function>snd_card_create()</function> (with
958 <constant>0</constant> on the 4th arg), call
Takashi Iwai561b2202005-09-09 14:22:34 +0200959 <function>kzalloc()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700960
961 <informalexample>
962 <programlisting>
963<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100964 struct snd_card *card;
965 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +0100966 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700967 .....
Takashi Iwai561b2202005-09-09 14:22:34 +0200968 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700969]]>
970 </programlisting>
971 </informalexample>
972 </para>
973
974 <para>
975 The chip record should have the field to hold the card
976 pointer at least,
977
978 <informalexample>
979 <programlisting>
980<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100981 struct mychip {
982 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700983 ....
984 };
985]]>
986 </programlisting>
987 </informalexample>
988 </para>
989
990 <para>
991 Then, set the card pointer in the returned chip instance.
992
993 <informalexample>
994 <programlisting>
995<![CDATA[
996 chip->card = card;
997]]>
998 </programlisting>
999 </informalexample>
1000 </para>
1001
1002 <para>
1003 Next, initialize the fields, and register this chip
1004 record as a low-level device with a specified
1005 <parameter>ops</parameter>,
1006
1007 <informalexample>
1008 <programlisting>
1009<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001010 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001011 .dev_free = snd_mychip_dev_free,
1012 };
1013 ....
1014 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1015]]>
1016 </programlisting>
1017 </informalexample>
1018
1019 <function>snd_mychip_dev_free()</function> is the
1020 device-destructor function, which will call the real
1021 destructor.
1022 </para>
1023
1024 <para>
1025 <informalexample>
1026 <programlisting>
1027<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001028 static int snd_mychip_dev_free(struct snd_device *device)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001029 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001030 return snd_mychip_free(device->device_data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001031 }
1032]]>
1033 </programlisting>
1034 </informalexample>
1035
1036 where <function>snd_mychip_free()</function> is the real destructor.
1037 </para>
1038 </section>
1039 </section>
1040
1041 <section id="card-management-registration">
1042 <title>Registration and Release</title>
1043 <para>
1044 After all components are assigned, register the card instance
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001045 by calling <function>snd_card_register()</function>. Access
1046 to the device files is enabled at this point. That is, before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001047 <function>snd_card_register()</function> is called, the
1048 components are safely inaccessible from external side. If this
1049 call fails, exit the probe function after releasing the card via
1050 <function>snd_card_free()</function>.
1051 </para>
1052
1053 <para>
1054 For releasing the card instance, you can call simply
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001055 <function>snd_card_free()</function>. As mentioned earlier, all
Linus Torvalds1da177e2005-04-16 15:20:36 -07001056 components are released automatically by this call.
1057 </para>
1058
1059 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001060 For a device which allows hotplugging, you can use
Takashi Iwai2b29b132006-06-23 14:38:26 +02001061 <function>snd_card_free_when_closed</function>. This one will
1062 postpone the destruction until all devices are closed.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001063 </para>
1064
1065 </section>
1066
1067 </chapter>
1068
1069
1070<!-- ****************************************************** -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001071<!-- PCI Resource Management -->
Linus Torvalds1da177e2005-04-16 15:20:36 -07001072<!-- ****************************************************** -->
1073 <chapter id="pci-resource">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001074 <title>PCI Resource Management</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001075
1076 <section id="pci-resource-example">
1077 <title>Full Code Example</title>
1078 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001079 In this section, we'll complete the chip-specific constructor,
1080 destructor and PCI entries. Example code is shown first,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001081 below.
1082
1083 <example>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001084 <title>PCI Resource Management Example</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001085 <programlisting>
1086<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001087 struct mychip {
1088 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001089 struct pci_dev *pci;
1090
1091 unsigned long port;
1092 int irq;
1093 };
1094
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001095 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001096 {
1097 /* disable hardware here if any */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001098 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001099
1100 /* release the irq */
1101 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001102 free_irq(chip->irq, chip);
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001103 /* release the I/O ports & memory */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001104 pci_release_regions(chip->pci);
1105 /* disable the PCI entry */
1106 pci_disable_device(chip->pci);
1107 /* release the data */
1108 kfree(chip);
1109 return 0;
1110 }
1111
1112 /* chip-specific constructor */
Takashi Iwai090015a2012-12-07 07:52:28 +01001113 static int snd_mychip_create(struct snd_card *card,
1114 struct pci_dev *pci,
1115 struct mychip **rchip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001116 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001117 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001118 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001119 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001120 .dev_free = snd_mychip_dev_free,
1121 };
1122
1123 *rchip = NULL;
1124
1125 /* initialize the PCI entry */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001126 err = pci_enable_device(pci);
1127 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001128 return err;
1129 /* check PCI availability (28bit DMA) */
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001130 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1131 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001132 printk(KERN_ERR "error to set 28bit mask DMA\n");
1133 pci_disable_device(pci);
1134 return -ENXIO;
1135 }
1136
Takashi Iwai561b2202005-09-09 14:22:34 +02001137 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001138 if (chip == NULL) {
1139 pci_disable_device(pci);
1140 return -ENOMEM;
1141 }
1142
1143 /* initialize the stuff */
1144 chip->card = card;
1145 chip->pci = pci;
1146 chip->irq = -1;
1147
1148 /* (1) PCI resource allocation */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001149 err = pci_request_regions(pci, "My Chip");
1150 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001151 kfree(chip);
1152 pci_disable_device(pci);
1153 return err;
1154 }
1155 chip->port = pci_resource_start(pci, 0);
1156 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001157 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001158 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1159 snd_mychip_free(chip);
1160 return -EBUSY;
1161 }
1162 chip->irq = pci->irq;
1163
1164 /* (2) initialization of the chip hardware */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001165 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001166
Takashi Iwai95a5b082007-07-26 16:50:09 +02001167 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1168 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001169 snd_mychip_free(chip);
1170 return err;
1171 }
1172
1173 snd_card_set_dev(card, &pci->dev);
1174
1175 *rchip = chip;
1176 return 0;
1177 }
1178
1179 /* PCI IDs */
Takashi Iwaif40b6892006-07-05 16:51:05 +02001180 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001181 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1182 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1183 ....
1184 { 0, }
1185 };
1186 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1187
1188 /* pci_driver definition */
1189 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001190 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001191 .id_table = snd_mychip_ids,
1192 .probe = snd_mychip_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01001193 .remove = snd_mychip_remove,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001194 };
1195
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001196 /* module initialization */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001197 static int __init alsa_card_mychip_init(void)
1198 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001199 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001200 }
1201
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001202 /* module clean up */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001203 static void __exit alsa_card_mychip_exit(void)
1204 {
1205 pci_unregister_driver(&driver);
1206 }
1207
1208 module_init(alsa_card_mychip_init)
1209 module_exit(alsa_card_mychip_exit)
1210
1211 EXPORT_NO_SYMBOLS; /* for old kernels only */
1212]]>
1213 </programlisting>
1214 </example>
1215 </para>
1216 </section>
1217
1218 <section id="pci-resource-some-haftas">
1219 <title>Some Hafta's</title>
1220 <para>
1221 The allocation of PCI resources is done in the
1222 <function>probe()</function> function, and usually an extra
1223 <function>xxx_create()</function> function is written for this
Tobias Klauser56b146d2006-04-10 22:54:21 -07001224 purpose.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001225 </para>
1226
1227 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001228 In the case of PCI devices, you first have to call
1229 the <function>pci_enable_device()</function> function before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001230 allocating resources. Also, you need to set the proper PCI DMA
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001231 mask to limit the accessed I/O range. In some cases, you might
Linus Torvalds1da177e2005-04-16 15:20:36 -07001232 need to call <function>pci_set_master()</function> function,
Tobias Klauser56b146d2006-04-10 22:54:21 -07001233 too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001234 </para>
1235
1236 <para>
1237 Suppose the 28bit mask, and the code to be added would be like:
1238
1239 <informalexample>
1240 <programlisting>
1241<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001242 err = pci_enable_device(pci);
1243 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001244 return err;
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001245 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1246 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001247 printk(KERN_ERR "error to set 28bit mask DMA\n");
1248 pci_disable_device(pci);
1249 return -ENXIO;
1250 }
1251
1252]]>
1253 </programlisting>
1254 </informalexample>
1255 </para>
1256 </section>
1257
1258 <section id="pci-resource-resource-allocation">
1259 <title>Resource Allocation</title>
1260 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001261 The allocation of I/O ports and irqs is done via standard kernel
Linus Torvalds1da177e2005-04-16 15:20:36 -07001262 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1263 that. And these resources must be released in the destructor
1264 function (see below). Also, on ALSA 0.9.x, you don't need to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001265 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001266 </para>
1267
1268 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001269 Now assume that the PCI device has an I/O port with 8 bytes
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001270 and an interrupt. Then struct <structname>mychip</structname> will have the
Tobias Klauser56b146d2006-04-10 22:54:21 -07001271 following fields:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001272
1273 <informalexample>
1274 <programlisting>
1275<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001276 struct mychip {
1277 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001278
1279 unsigned long port;
1280 int irq;
1281 };
1282]]>
1283 </programlisting>
1284 </informalexample>
1285 </para>
1286
1287 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001288 For an I/O port (and also a memory region), you need to have
Linus Torvalds1da177e2005-04-16 15:20:36 -07001289 the resource pointer for the standard resource management. For
1290 an irq, you have to keep only the irq number (integer). But you
1291 need to initialize this number as -1 before actual allocation,
1292 since irq 0 is valid. The port address and its resource pointer
1293 can be initialized as null by
Takashi Iwai561b2202005-09-09 14:22:34 +02001294 <function>kzalloc()</function> automatically, so you
Linus Torvalds1da177e2005-04-16 15:20:36 -07001295 don't have to take care of resetting them.
1296 </para>
1297
1298 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001299 The allocation of an I/O port is done like this:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001300
1301 <informalexample>
1302 <programlisting>
1303<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001304 err = pci_request_regions(pci, "My Chip");
1305 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001306 kfree(chip);
1307 pci_disable_device(pci);
1308 return err;
1309 }
1310 chip->port = pci_resource_start(pci, 0);
1311]]>
1312 </programlisting>
1313 </informalexample>
1314 </para>
1315
1316 <para>
1317 <!-- obsolete -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001318 It will reserve the I/O port region of 8 bytes of the given
Linus Torvalds1da177e2005-04-16 15:20:36 -07001319 PCI device. The returned value, chip-&gt;res_port, is allocated
1320 via <function>kmalloc()</function> by
1321 <function>request_region()</function>. The pointer must be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001322 released via <function>kfree()</function>, but there is a
1323 problem with this. This issue will be explained later.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001324 </para>
1325
1326 <para>
1327 The allocation of an interrupt source is done like this:
1328
1329 <informalexample>
1330 <programlisting>
1331<![CDATA[
1332 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001333 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001334 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1335 snd_mychip_free(chip);
1336 return -EBUSY;
1337 }
1338 chip->irq = pci->irq;
1339]]>
1340 </programlisting>
1341 </informalexample>
1342
1343 where <function>snd_mychip_interrupt()</function> is the
1344 interrupt handler defined <link
1345 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1346 Note that chip-&gt;irq should be defined
1347 only when <function>request_irq()</function> succeeded.
1348 </para>
1349
1350 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001351 On the PCI bus, interrupts can be shared. Thus,
1352 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
Linus Torvalds1da177e2005-04-16 15:20:36 -07001353 <function>request_irq()</function>.
1354 </para>
1355
1356 <para>
1357 The last argument of <function>request_irq()</function> is the
1358 data pointer passed to the interrupt handler. Usually, the
1359 chip-specific record is used for that, but you can use what you
1360 like, too.
1361 </para>
1362
1363 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001364 I won't give details about the interrupt handler at this
Linus Torvalds1da177e2005-04-16 15:20:36 -07001365 point, but at least its appearance can be explained now. The
1366 interrupt handler looks usually like the following:
1367
1368 <informalexample>
1369 <programlisting>
1370<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01001371 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001372 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001373 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001374 ....
1375 return IRQ_HANDLED;
1376 }
1377]]>
1378 </programlisting>
1379 </informalexample>
1380 </para>
1381
1382 <para>
1383 Now let's write the corresponding destructor for the resources
1384 above. The role of destructor is simple: disable the hardware
1385 (if already activated) and release the resources. So far, we
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001386 have no hardware part, so the disabling code is not written here.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001387 </para>
1388
1389 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001390 To release the resources, the <quote>check-and-release</quote>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001391 method is a safer way. For the interrupt, do like this:
1392
1393 <informalexample>
1394 <programlisting>
1395<![CDATA[
1396 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001397 free_irq(chip->irq, chip);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001398]]>
1399 </programlisting>
1400 </informalexample>
1401
1402 Since the irq number can start from 0, you should initialize
1403 chip-&gt;irq with a negative value (e.g. -1), so that you can
1404 check the validity of the irq number as above.
1405 </para>
1406
1407 <para>
1408 When you requested I/O ports or memory regions via
1409 <function>pci_request_region()</function> or
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001410 <function>pci_request_regions()</function> like in this example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001411 release the resource(s) using the corresponding function,
1412 <function>pci_release_region()</function> or
1413 <function>pci_release_regions()</function>.
1414
1415 <informalexample>
1416 <programlisting>
1417<![CDATA[
1418 pci_release_regions(chip->pci);
1419]]>
1420 </programlisting>
1421 </informalexample>
1422 </para>
1423
1424 <para>
1425 When you requested manually via <function>request_region()</function>
1426 or <function>request_mem_region</function>, you can release it via
1427 <function>release_resource()</function>. Suppose that you keep
1428 the resource pointer returned from <function>request_region()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001429 in chip-&gt;res_port, the release procedure looks like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001430
1431 <informalexample>
1432 <programlisting>
1433<![CDATA[
Takashi Iwaib1d57762005-10-10 11:56:31 +02001434 release_and_free_resource(chip->res_port);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001435]]>
1436 </programlisting>
1437 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001438 </para>
1439
1440 <para>
1441 Don't forget to call <function>pci_disable_device()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001442 before the end.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001443 </para>
1444
1445 <para>
1446 And finally, release the chip-specific record.
1447
1448 <informalexample>
1449 <programlisting>
1450<![CDATA[
1451 kfree(chip);
1452]]>
1453 </programlisting>
1454 </informalexample>
1455 </para>
1456
1457 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001458 We didn't implement the hardware disabling part in the above.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001459 If you need to do this, please note that the destructor may be
1460 called even before the initialization of the chip is completed.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001461 It would be better to have a flag to skip hardware disabling
Linus Torvalds1da177e2005-04-16 15:20:36 -07001462 if the hardware was not initialized yet.
1463 </para>
1464
1465 <para>
1466 When the chip-data is assigned to the card using
1467 <function>snd_device_new()</function> with
1468 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1469 called at the last. That is, it is assured that all other
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001470 components like PCMs and controls have already been released.
1471 You don't have to stop PCMs, etc. explicitly, but just
1472 call low-level hardware stopping.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001473 </para>
1474
1475 <para>
1476 The management of a memory-mapped region is almost as same as
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001477 the management of an I/O port. You'll need three fields like
Linus Torvalds1da177e2005-04-16 15:20:36 -07001478 the following:
1479
1480 <informalexample>
1481 <programlisting>
1482<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001483 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001484 ....
1485 unsigned long iobase_phys;
1486 void __iomem *iobase_virt;
1487 };
1488]]>
1489 </programlisting>
1490 </informalexample>
1491
1492 and the allocation would be like below:
1493
1494 <informalexample>
1495 <programlisting>
1496<![CDATA[
1497 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1498 kfree(chip);
1499 return err;
1500 }
1501 chip->iobase_phys = pci_resource_start(pci, 0);
1502 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1503 pci_resource_len(pci, 0));
1504]]>
1505 </programlisting>
1506 </informalexample>
1507
1508 and the corresponding destructor would be:
1509
1510 <informalexample>
1511 <programlisting>
1512<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001513 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001514 {
1515 ....
1516 if (chip->iobase_virt)
1517 iounmap(chip->iobase_virt);
1518 ....
1519 pci_release_regions(chip->pci);
1520 ....
1521 }
1522]]>
1523 </programlisting>
1524 </informalexample>
1525 </para>
1526
1527 </section>
1528
1529 <section id="pci-resource-device-struct">
1530 <title>Registration of Device Struct</title>
1531 <para>
1532 At some point, typically after calling <function>snd_device_new()</function>,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001533 you need to register the struct <structname>device</structname> of the chip
Linus Torvalds1da177e2005-04-16 15:20:36 -07001534 you're handling for udev and co. ALSA provides a macro for compatibility with
1535 older kernels. Simply call like the following:
1536 <informalexample>
1537 <programlisting>
1538<![CDATA[
1539 snd_card_set_dev(card, &pci->dev);
1540]]>
1541 </programlisting>
1542 </informalexample>
1543 so that it stores the PCI's device pointer to the card. This will be
1544 referred by ALSA core functions later when the devices are registered.
1545 </para>
1546 <para>
1547 In the case of non-PCI, pass the proper device struct pointer of the BUS
1548 instead. (In the case of legacy ISA without PnP, you don't have to do
1549 anything.)
1550 </para>
1551 </section>
1552
1553 <section id="pci-resource-entries">
1554 <title>PCI Entries</title>
1555 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001556 So far, so good. Let's finish the missing PCI
1557 stuff. At first, we need a
Linus Torvalds1da177e2005-04-16 15:20:36 -07001558 <structname>pci_device_id</structname> table for this
1559 chipset. It's a table of PCI vendor/device ID number, and some
1560 masks.
1561 </para>
1562
1563 <para>
1564 For example,
1565
1566 <informalexample>
1567 <programlisting>
1568<![CDATA[
Takashi Iwaif40b6892006-07-05 16:51:05 +02001569 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001570 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1571 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1572 ....
1573 { 0, }
1574 };
1575 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1576]]>
1577 </programlisting>
1578 </informalexample>
1579 </para>
1580
1581 <para>
1582 The first and second fields of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001583 the <structname>pci_device_id</structname> structure are the vendor and
1584 device IDs. If you have no reason to filter the matching
1585 devices, you can leave the remaining fields as above. The last
1586 field of the <structname>pci_device_id</structname> struct contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07001587 private data for this entry. You can specify any value here, for
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001588 example, to define specific operations for supported device IDs.
1589 Such an example is found in the intel8x0 driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001590 </para>
1591
1592 <para>
1593 The last entry of this list is the terminator. You must
1594 specify this all-zero entry.
1595 </para>
1596
1597 <para>
1598 Then, prepare the <structname>pci_driver</structname> record:
1599
1600 <informalexample>
1601 <programlisting>
1602<![CDATA[
1603 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001604 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001605 .id_table = snd_mychip_ids,
1606 .probe = snd_mychip_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01001607 .remove = snd_mychip_remove,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001608 };
1609]]>
1610 </programlisting>
1611 </informalexample>
1612 </para>
1613
1614 <para>
1615 The <structfield>probe</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001616 <structfield>remove</structfield> functions have already
1617 been defined in the previous sections.
Takashi Iwai090015a2012-12-07 07:52:28 +01001618 The <structfield>name</structfield>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001619 field is the name string of this device. Note that you must not
1620 use a slash <quote>/</quote> in this string.
1621 </para>
1622
1623 <para>
1624 And at last, the module entries:
1625
1626 <informalexample>
1627 <programlisting>
1628<![CDATA[
1629 static int __init alsa_card_mychip_init(void)
1630 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001631 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001632 }
1633
1634 static void __exit alsa_card_mychip_exit(void)
1635 {
1636 pci_unregister_driver(&driver);
1637 }
1638
1639 module_init(alsa_card_mychip_init)
1640 module_exit(alsa_card_mychip_exit)
1641]]>
1642 </programlisting>
1643 </informalexample>
1644 </para>
1645
1646 <para>
1647 Note that these module entries are tagged with
1648 <parameter>__init</parameter> and
Takashi Iwai090015a2012-12-07 07:52:28 +01001649 <parameter>__exit</parameter> prefixes.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001650 </para>
1651
1652 <para>
1653 Oh, one thing was forgotten. If you have no exported symbols,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001654 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 -07001655
1656 <informalexample>
1657 <programlisting>
1658<![CDATA[
1659 EXPORT_NO_SYMBOLS;
1660]]>
1661 </programlisting>
1662 </informalexample>
1663
1664 That's all!
1665 </para>
1666 </section>
1667 </chapter>
1668
1669
1670<!-- ****************************************************** -->
1671<!-- PCM Interface -->
1672<!-- ****************************************************** -->
1673 <chapter id="pcm-interface">
1674 <title>PCM Interface</title>
1675
1676 <section id="pcm-interface-general">
1677 <title>General</title>
1678 <para>
1679 The PCM middle layer of ALSA is quite powerful and it is only
1680 necessary for each driver to implement the low-level functions
1681 to access its hardware.
1682 </para>
1683
1684 <para>
1685 For accessing to the PCM layer, you need to include
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001686 <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001687 <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
1688 if you access to some functions related with hw_param.
1689 </para>
1690
1691 <para>
1692 Each card device can have up to four pcm instances. A pcm
1693 instance corresponds to a pcm device file. The limitation of
1694 number of instances comes only from the available bit size of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001695 the Linux's device numbers. Once when 64bit device number is
1696 used, we'll have more pcm instances available.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001697 </para>
1698
1699 <para>
1700 A pcm instance consists of pcm playback and capture streams,
1701 and each pcm stream consists of one or more pcm substreams. Some
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001702 soundcards support multiple playback functions. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001703 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1704 each open, a free substream is (usually) automatically chosen
1705 and opened. Meanwhile, when only one substream exists and it was
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001706 already opened, the successful open will either block
1707 or error with <constant>EAGAIN</constant> according to the
1708 file open mode. But you don't have to care about such details in your
1709 driver. The PCM middle layer will take care of such work.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001710 </para>
1711 </section>
1712
1713 <section id="pcm-interface-example">
1714 <title>Full Code Example</title>
1715 <para>
1716 The example code below does not include any hardware access
1717 routines but shows only the skeleton, how to build up the PCM
1718 interfaces.
1719
1720 <example>
1721 <title>PCM Example Code</title>
1722 <programlisting>
1723<![CDATA[
1724 #include <sound/pcm.h>
1725 ....
1726
1727 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001728 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001729 .info = (SNDRV_PCM_INFO_MMAP |
1730 SNDRV_PCM_INFO_INTERLEAVED |
1731 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1732 SNDRV_PCM_INFO_MMAP_VALID),
1733 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1734 .rates = SNDRV_PCM_RATE_8000_48000,
1735 .rate_min = 8000,
1736 .rate_max = 48000,
1737 .channels_min = 2,
1738 .channels_max = 2,
1739 .buffer_bytes_max = 32768,
1740 .period_bytes_min = 4096,
1741 .period_bytes_max = 32768,
1742 .periods_min = 1,
1743 .periods_max = 1024,
1744 };
1745
1746 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001747 static struct snd_pcm_hardware snd_mychip_capture_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001748 .info = (SNDRV_PCM_INFO_MMAP |
1749 SNDRV_PCM_INFO_INTERLEAVED |
1750 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1751 SNDRV_PCM_INFO_MMAP_VALID),
1752 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1753 .rates = SNDRV_PCM_RATE_8000_48000,
1754 .rate_min = 8000,
1755 .rate_max = 48000,
1756 .channels_min = 2,
1757 .channels_max = 2,
1758 .buffer_bytes_max = 32768,
1759 .period_bytes_min = 4096,
1760 .period_bytes_max = 32768,
1761 .periods_min = 1,
1762 .periods_max = 1024,
1763 };
1764
1765 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001766 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001767 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001768 struct mychip *chip = snd_pcm_substream_chip(substream);
1769 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001770
1771 runtime->hw = snd_mychip_playback_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001772 /* more hardware-initialization will be done here */
1773 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001774 return 0;
1775 }
1776
1777 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001778 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001779 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001780 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001781 /* the hardware-specific codes will be here */
1782 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001783 return 0;
1784
1785 }
1786
1787 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001788 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001789 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001790 struct mychip *chip = snd_pcm_substream_chip(substream);
1791 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001792
1793 runtime->hw = snd_mychip_capture_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001794 /* more hardware-initialization will be done here */
1795 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001796 return 0;
1797 }
1798
1799 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001800 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001801 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001802 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001803 /* the hardware-specific codes will be here */
1804 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001805 return 0;
1806
1807 }
1808
1809 /* hw_params callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001810 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1811 struct snd_pcm_hw_params *hw_params)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001812 {
1813 return snd_pcm_lib_malloc_pages(substream,
1814 params_buffer_bytes(hw_params));
1815 }
1816
1817 /* hw_free callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001818 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001819 {
1820 return snd_pcm_lib_free_pages(substream);
1821 }
1822
1823 /* prepare callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001824 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001825 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001826 struct mychip *chip = snd_pcm_substream_chip(substream);
1827 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001828
1829 /* set up the hardware with the current configuration
1830 * for example...
1831 */
1832 mychip_set_sample_format(chip, runtime->format);
1833 mychip_set_sample_rate(chip, runtime->rate);
1834 mychip_set_channels(chip, runtime->channels);
Takashi Iwai0b7bed42006-03-02 15:35:55 +01001835 mychip_set_dma_setup(chip, runtime->dma_addr,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001836 chip->buffer_size,
1837 chip->period_size);
1838 return 0;
1839 }
1840
1841 /* trigger callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001842 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001843 int cmd)
1844 {
1845 switch (cmd) {
1846 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001847 /* do something to start the PCM engine */
1848 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001849 break;
1850 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001851 /* do something to stop the PCM engine */
1852 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001853 break;
1854 default:
1855 return -EINVAL;
1856 }
1857 }
1858
1859 /* pointer callback */
1860 static snd_pcm_uframes_t
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001861 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001862 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001863 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001864 unsigned int current_ptr;
1865
1866 /* get the current hardware pointer */
1867 current_ptr = mychip_get_hw_pointer(chip);
1868 return current_ptr;
1869 }
1870
1871 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001872 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001873 .open = snd_mychip_playback_open,
1874 .close = snd_mychip_playback_close,
1875 .ioctl = snd_pcm_lib_ioctl,
1876 .hw_params = snd_mychip_pcm_hw_params,
1877 .hw_free = snd_mychip_pcm_hw_free,
1878 .prepare = snd_mychip_pcm_prepare,
1879 .trigger = snd_mychip_pcm_trigger,
1880 .pointer = snd_mychip_pcm_pointer,
1881 };
1882
1883 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001884 static struct snd_pcm_ops snd_mychip_capture_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001885 .open = snd_mychip_capture_open,
1886 .close = snd_mychip_capture_close,
1887 .ioctl = snd_pcm_lib_ioctl,
1888 .hw_params = snd_mychip_pcm_hw_params,
1889 .hw_free = snd_mychip_pcm_hw_free,
1890 .prepare = snd_mychip_pcm_prepare,
1891 .trigger = snd_mychip_pcm_trigger,
1892 .pointer = snd_mychip_pcm_pointer,
1893 };
1894
1895 /*
1896 * definitions of capture are omitted here...
1897 */
1898
1899 /* create a pcm device */
Takashi Iwai090015a2012-12-07 07:52:28 +01001900 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001901 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001902 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001903 int err;
1904
Takashi Iwai95a5b082007-07-26 16:50:09 +02001905 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1906 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001907 return err;
1908 pcm->private_data = chip;
1909 strcpy(pcm->name, "My Chip");
1910 chip->pcm = pcm;
1911 /* set operators */
1912 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1913 &snd_mychip_playback_ops);
1914 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1915 &snd_mychip_capture_ops);
1916 /* pre-allocation of buffers */
1917 /* NOTE: this may fail */
1918 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1919 snd_dma_pci_data(chip->pci),
1920 64*1024, 64*1024);
1921 return 0;
1922 }
1923]]>
1924 </programlisting>
1925 </example>
1926 </para>
1927 </section>
1928
1929 <section id="pcm-interface-constructor">
1930 <title>Constructor</title>
1931 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001932 A pcm instance is allocated by the <function>snd_pcm_new()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001933 function. It would be better to create a constructor for pcm,
1934 namely,
1935
1936 <informalexample>
1937 <programlisting>
1938<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01001939 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001940 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001941 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001942 int err;
1943
Takashi Iwai95a5b082007-07-26 16:50:09 +02001944 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1945 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001946 return err;
1947 pcm->private_data = chip;
1948 strcpy(pcm->name, "My Chip");
1949 chip->pcm = pcm;
1950 ....
1951 return 0;
1952 }
1953]]>
1954 </programlisting>
1955 </informalexample>
1956 </para>
1957
1958 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001959 The <function>snd_pcm_new()</function> function takes four
Linus Torvalds1da177e2005-04-16 15:20:36 -07001960 arguments. The first argument is the card pointer to which this
1961 pcm is assigned, and the second is the ID string.
1962 </para>
1963
1964 <para>
1965 The third argument (<parameter>index</parameter>, 0 in the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001966 above) is the index of this new pcm. It begins from zero. If
1967 you create more than one pcm instances, specify the
Linus Torvalds1da177e2005-04-16 15:20:36 -07001968 different numbers in this argument. For example,
1969 <parameter>index</parameter> = 1 for the second PCM device.
1970 </para>
1971
1972 <para>
1973 The fourth and fifth arguments are the number of substreams
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001974 for playback and capture, respectively. Here 1 is used for
1975 both arguments. When no playback or capture substreams are available,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001976 pass 0 to the corresponding argument.
1977 </para>
1978
1979 <para>
1980 If a chip supports multiple playbacks or captures, you can
1981 specify more numbers, but they must be handled properly in
1982 open/close, etc. callbacks. When you need to know which
1983 substream you are referring to, then it can be obtained from
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001984 struct <structname>snd_pcm_substream</structname> data passed to each callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07001985 as follows:
1986
1987 <informalexample>
1988 <programlisting>
1989<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001990 struct snd_pcm_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001991 int index = substream->number;
1992]]>
1993 </programlisting>
1994 </informalexample>
1995 </para>
1996
1997 <para>
1998 After the pcm is created, you need to set operators for each
1999 pcm stream.
2000
2001 <informalexample>
2002 <programlisting>
2003<![CDATA[
2004 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
2005 &snd_mychip_playback_ops);
2006 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
2007 &snd_mychip_capture_ops);
2008]]>
2009 </programlisting>
2010 </informalexample>
2011 </para>
2012
2013 <para>
2014 The operators are defined typically like this:
2015
2016 <informalexample>
2017 <programlisting>
2018<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002019 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002020 .open = snd_mychip_pcm_open,
2021 .close = snd_mychip_pcm_close,
2022 .ioctl = snd_pcm_lib_ioctl,
2023 .hw_params = snd_mychip_pcm_hw_params,
2024 .hw_free = snd_mychip_pcm_hw_free,
2025 .prepare = snd_mychip_pcm_prepare,
2026 .trigger = snd_mychip_pcm_trigger,
2027 .pointer = snd_mychip_pcm_pointer,
2028 };
2029]]>
2030 </programlisting>
2031 </informalexample>
2032
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002033 All the callbacks are described in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002034 <link linkend="pcm-interface-operators"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002035 Operators</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002036 </para>
2037
2038 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002039 After setting the operators, you probably will want to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002040 pre-allocate the buffer. For the pre-allocation, simply call
2041 the following:
2042
2043 <informalexample>
2044 <programlisting>
2045<![CDATA[
2046 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2047 snd_dma_pci_data(chip->pci),
2048 64*1024, 64*1024);
2049]]>
2050 </programlisting>
2051 </informalexample>
2052
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002053 It will allocate a buffer up to 64kB as default.
2054 Buffer management details will be described in the later section <link
Linus Torvalds1da177e2005-04-16 15:20:36 -07002055 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2056 Management</citetitle></link>.
2057 </para>
2058
2059 <para>
2060 Additionally, you can set some extra information for this pcm
2061 in pcm-&gt;info_flags.
2062 The available values are defined as
2063 <constant>SNDRV_PCM_INFO_XXX</constant> in
2064 <filename>&lt;sound/asound.h&gt;</filename>, which is used for
2065 the hardware definition (described later). When your soundchip
2066 supports only half-duplex, specify like this:
2067
2068 <informalexample>
2069 <programlisting>
2070<![CDATA[
2071 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2072]]>
2073 </programlisting>
2074 </informalexample>
2075 </para>
2076 </section>
2077
2078 <section id="pcm-interface-destructor">
2079 <title>... And the Destructor?</title>
2080 <para>
2081 The destructor for a pcm instance is not always
2082 necessary. Since the pcm device will be released by the middle
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002083 layer code automatically, you don't have to call the destructor
Linus Torvalds1da177e2005-04-16 15:20:36 -07002084 explicitly.
2085 </para>
2086
2087 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002088 The destructor would be necessary if you created
2089 special records internally and needed to release them. In such a
Linus Torvalds1da177e2005-04-16 15:20:36 -07002090 case, set the destructor function to
2091 pcm-&gt;private_free:
2092
2093 <example>
2094 <title>PCM Instance with a Destructor</title>
2095 <programlisting>
2096<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002097 static void mychip_pcm_free(struct snd_pcm *pcm)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002098 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002099 struct mychip *chip = snd_pcm_chip(pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002100 /* free your own data */
2101 kfree(chip->my_private_pcm_data);
Takashi Iwai95a5b082007-07-26 16:50:09 +02002102 /* do what you like else */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002103 ....
2104 }
2105
Takashi Iwai090015a2012-12-07 07:52:28 +01002106 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002107 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002108 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002109 ....
2110 /* allocate your own data */
2111 chip->my_private_pcm_data = kmalloc(...);
2112 /* set the destructor */
2113 pcm->private_data = chip;
2114 pcm->private_free = mychip_pcm_free;
2115 ....
2116 }
2117]]>
2118 </programlisting>
2119 </example>
2120 </para>
2121 </section>
2122
2123 <section id="pcm-interface-runtime">
2124 <title>Runtime Pointer - The Chest of PCM Information</title>
2125 <para>
2126 When the PCM substream is opened, a PCM runtime instance is
2127 allocated and assigned to the substream. This pointer is
2128 accessible via <constant>substream-&gt;runtime</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002129 This runtime pointer holds most information you need
2130 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2131 pointers, mmap records, spinlocks, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002132 </para>
2133
2134 <para>
2135 The definition of runtime instance is found in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002136 <filename>&lt;sound/pcm.h&gt;</filename>. Here are
2137 the contents of this file:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002138 <informalexample>
2139 <programlisting>
2140<![CDATA[
2141struct _snd_pcm_runtime {
2142 /* -- Status -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002143 struct snd_pcm_substream *trigger_master;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002144 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2145 int overrange;
2146 snd_pcm_uframes_t avail_max;
2147 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2148 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2149
2150 /* -- HW params -- */
2151 snd_pcm_access_t access; /* access mode */
2152 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2153 snd_pcm_subformat_t subformat; /* subformat */
2154 unsigned int rate; /* rate in Hz */
2155 unsigned int channels; /* channels */
2156 snd_pcm_uframes_t period_size; /* period size */
2157 unsigned int periods; /* periods */
2158 snd_pcm_uframes_t buffer_size; /* buffer size */
2159 unsigned int tick_time; /* tick time */
2160 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2161 size_t byte_align;
2162 unsigned int frame_bits;
2163 unsigned int sample_bits;
2164 unsigned int info;
2165 unsigned int rate_num;
2166 unsigned int rate_den;
2167
2168 /* -- SW params -- */
Takashi Iwai07799e72005-10-10 11:49:49 +02002169 struct timespec tstamp_mode; /* mmap timestamp is updated */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002170 unsigned int period_step;
2171 unsigned int sleep_min; /* min ticks to sleep */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002172 snd_pcm_uframes_t start_threshold;
2173 snd_pcm_uframes_t stop_threshold;
2174 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2175 noise is nearest than this */
2176 snd_pcm_uframes_t silence_size; /* Silence filling size */
2177 snd_pcm_uframes_t boundary; /* pointers wrap point */
2178
2179 snd_pcm_uframes_t silenced_start;
2180 snd_pcm_uframes_t silenced_size;
2181
2182 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2183
2184 /* -- mmap -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002185 volatile struct snd_pcm_mmap_status *status;
2186 volatile struct snd_pcm_mmap_control *control;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002187 atomic_t mmap_count;
2188
2189 /* -- locking / scheduling -- */
2190 spinlock_t lock;
2191 wait_queue_head_t sleep;
2192 struct timer_list tick_timer;
2193 struct fasync_struct *fasync;
2194
2195 /* -- private section -- */
2196 void *private_data;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002197 void (*private_free)(struct snd_pcm_runtime *runtime);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002198
2199 /* -- hardware description -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002200 struct snd_pcm_hardware hw;
2201 struct snd_pcm_hw_constraints hw_constraints;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002202
2203 /* -- interrupt callbacks -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002204 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2205 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002206
2207 /* -- timer -- */
2208 unsigned int timer_resolution; /* timer resolution */
2209
2210 /* -- DMA -- */
2211 unsigned char *dma_area; /* DMA area */
2212 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2213 size_t dma_bytes; /* size of DMA area */
2214
2215 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2216
2217#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2218 /* -- OSS things -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002219 struct snd_pcm_oss_runtime oss;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002220#endif
2221};
2222]]>
2223 </programlisting>
2224 </informalexample>
2225 </para>
2226
2227 <para>
2228 For the operators (callbacks) of each sound driver, most of
2229 these records are supposed to be read-only. Only the PCM
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002230 middle-layer changes / updates them. The exceptions are
Linus Torvalds1da177e2005-04-16 15:20:36 -07002231 the hardware description (hw), interrupt callbacks
2232 (transfer_ack_xxx), DMA buffer information, and the private
2233 data. Besides, if you use the standard buffer allocation
2234 method via <function>snd_pcm_lib_malloc_pages()</function>,
2235 you don't need to set the DMA buffer information by yourself.
2236 </para>
2237
2238 <para>
2239 In the sections below, important records are explained.
2240 </para>
2241
2242 <section id="pcm-interface-runtime-hw">
2243 <title>Hardware Description</title>
2244 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002245 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002246 contains the definitions of the fundamental hardware
2247 configuration. Above all, you'll need to define this in
2248 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2249 the open callback</citetitle></link>.
2250 Note that the runtime instance holds the copy of the
2251 descriptor, not the pointer to the existing descriptor. That
2252 is, in the open callback, you can modify the copied descriptor
2253 (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
2254 number of channels is 1 only on some chip models, you can
2255 still use the same hardware descriptor and change the
2256 channels_max later:
2257 <informalexample>
2258 <programlisting>
2259<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002260 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002261 ...
2262 runtime->hw = snd_mychip_playback_hw; /* common definition */
2263 if (chip->model == VERY_OLD_ONE)
2264 runtime->hw.channels_max = 1;
2265]]>
2266 </programlisting>
2267 </informalexample>
2268 </para>
2269
2270 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002271 Typically, you'll have a hardware descriptor as below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002272 <informalexample>
2273 <programlisting>
2274<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002275 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002276 .info = (SNDRV_PCM_INFO_MMAP |
2277 SNDRV_PCM_INFO_INTERLEAVED |
2278 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2279 SNDRV_PCM_INFO_MMAP_VALID),
2280 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2281 .rates = SNDRV_PCM_RATE_8000_48000,
2282 .rate_min = 8000,
2283 .rate_max = 48000,
2284 .channels_min = 2,
2285 .channels_max = 2,
2286 .buffer_bytes_max = 32768,
2287 .period_bytes_min = 4096,
2288 .period_bytes_max = 32768,
2289 .periods_min = 1,
2290 .periods_max = 1024,
2291 };
2292]]>
2293 </programlisting>
2294 </informalexample>
2295 </para>
2296
2297 <para>
2298 <itemizedlist>
2299 <listitem><para>
2300 The <structfield>info</structfield> field contains the type and
2301 capabilities of this pcm. The bit flags are defined in
2302 <filename>&lt;sound/asound.h&gt;</filename> as
2303 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2304 have to specify whether the mmap is supported and which
2305 interleaved format is supported.
Antonio Ospite04044b82013-01-29 12:56:27 +01002306 When the hardware supports mmap, add the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002307 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2308 hardware supports the interleaved or the non-interleaved
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002309 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
Linus Torvalds1da177e2005-04-16 15:20:36 -07002310 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2311 be set, respectively. If both are supported, you can set both,
2312 too.
2313 </para>
2314
2315 <para>
2316 In the above example, <constant>MMAP_VALID</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002317 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
Linus Torvalds1da177e2005-04-16 15:20:36 -07002318 mode. Usually both are set. Of course,
2319 <constant>MMAP_VALID</constant> is set only if the mmap is
2320 really supported.
2321 </para>
2322
2323 <para>
2324 The other possible flags are
2325 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2326 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2327 <constant>PAUSE</constant> bit means that the pcm supports the
2328 <quote>pause</quote> operation, while the
2329 <constant>RESUME</constant> bit means that the pcm supports
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002330 the full <quote>suspend/resume</quote> operation.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002331 If the <constant>PAUSE</constant> flag is set,
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002332 the <structfield>trigger</structfield> callback below
2333 must handle the corresponding (pause push/release) commands.
2334 The suspend/resume trigger commands can be defined even without
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002335 the <constant>RESUME</constant> flag. See <link
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002336 linkend="power-management"><citetitle>
2337 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002338 </para>
2339
2340 <para>
2341 When the PCM substreams can be synchronized (typically,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01002342 synchronized start/stop of a playback and a capture streams),
Linus Torvalds1da177e2005-04-16 15:20:36 -07002343 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2344 too. In this case, you'll need to check the linked-list of
2345 PCM substreams in the trigger callback. This will be
2346 described in the later section.
2347 </para>
2348 </listitem>
2349
2350 <listitem>
2351 <para>
2352 <structfield>formats</structfield> field contains the bit-flags
2353 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2354 If the hardware supports more than one format, give all or'ed
2355 bits. In the example above, the signed 16bit little-endian
2356 format is specified.
2357 </para>
2358 </listitem>
2359
2360 <listitem>
2361 <para>
2362 <structfield>rates</structfield> field contains the bit-flags of
2363 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2364 When the chip supports continuous rates, pass
2365 <constant>CONTINUOUS</constant> bit additionally.
2366 The pre-defined rate bits are provided only for typical
2367 rates. If your chip supports unconventional rates, you need to add
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002368 the <constant>KNOT</constant> bit and set up the hardware
Linus Torvalds1da177e2005-04-16 15:20:36 -07002369 constraint manually (explained later).
2370 </para>
2371 </listitem>
2372
2373 <listitem>
2374 <para>
2375 <structfield>rate_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002376 <structfield>rate_max</structfield> define the minimum and
2377 maximum sample rate. This should correspond somehow to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002378 <structfield>rates</structfield> bits.
2379 </para>
2380 </listitem>
2381
2382 <listitem>
2383 <para>
2384 <structfield>channel_min</structfield> and
2385 <structfield>channel_max</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002386 define, as you might already expected, the minimum and maximum
Linus Torvalds1da177e2005-04-16 15:20:36 -07002387 number of channels.
2388 </para>
2389 </listitem>
2390
2391 <listitem>
2392 <para>
2393 <structfield>buffer_bytes_max</structfield> defines the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002394 maximum buffer size in bytes. There is no
Linus Torvalds1da177e2005-04-16 15:20:36 -07002395 <structfield>buffer_bytes_min</structfield> field, since
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002396 it can be calculated from the minimum period size and the
2397 minimum number of periods.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002398 Meanwhile, <structfield>period_bytes_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002399 define the minimum and maximum size of the period in bytes.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002400 <structfield>periods_max</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002401 <structfield>periods_min</structfield> define the maximum and
2402 minimum number of periods in the buffer.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002403 </para>
2404
2405 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002406 The <quote>period</quote> is a term that corresponds to
2407 a fragment in the OSS world. The period defines the size at
2408 which a PCM interrupt is generated. This size strongly
Linus Torvalds1da177e2005-04-16 15:20:36 -07002409 depends on the hardware.
2410 Generally, the smaller period size will give you more
2411 interrupts, that is, more controls.
2412 In the case of capture, this size defines the input latency.
2413 On the other hand, the whole buffer size defines the
2414 output latency for the playback direction.
2415 </para>
2416 </listitem>
2417
2418 <listitem>
2419 <para>
2420 There is also a field <structfield>fifo_size</structfield>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002421 This specifies the size of the hardware FIFO, but currently it
2422 is neither used in the driver nor in the alsa-lib. So, you
Linus Torvalds1da177e2005-04-16 15:20:36 -07002423 can ignore this field.
2424 </para>
2425 </listitem>
2426 </itemizedlist>
2427 </para>
2428 </section>
2429
2430 <section id="pcm-interface-runtime-config">
2431 <title>PCM Configurations</title>
2432 <para>
2433 Ok, let's go back again to the PCM runtime records.
2434 The most frequently referred records in the runtime instance are
2435 the PCM configurations.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002436 The PCM configurations are stored in the runtime instance
Linus Torvalds1da177e2005-04-16 15:20:36 -07002437 after the application sends <type>hw_params</type> data via
2438 alsa-lib. There are many fields copied from hw_params and
2439 sw_params structs. For example,
2440 <structfield>format</structfield> holds the format type
2441 chosen by the application. This field contains the enum value
2442 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2443 </para>
2444
2445 <para>
2446 One thing to be noted is that the configured buffer and period
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002447 sizes are stored in <quote>frames</quote> in the runtime.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002448 In the ALSA world, 1 frame = channels * samples-size.
2449 For conversion between frames and bytes, you can use the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002450 <function>frames_to_bytes()</function> and
2451 <function>bytes_to_frames()</function> helper functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002452 <informalexample>
2453 <programlisting>
2454<![CDATA[
2455 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2456]]>
2457 </programlisting>
2458 </informalexample>
2459 </para>
2460
2461 <para>
2462 Also, many software parameters (sw_params) are
2463 stored in frames, too. Please check the type of the field.
2464 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2465 integer while <type>snd_pcm_sframes_t</type> is for the frames
2466 as signed integer.
2467 </para>
2468 </section>
2469
2470 <section id="pcm-interface-runtime-dma">
2471 <title>DMA Buffer Information</title>
2472 <para>
2473 The DMA buffer is defined by the following four fields,
2474 <structfield>dma_area</structfield>,
2475 <structfield>dma_addr</structfield>,
2476 <structfield>dma_bytes</structfield> and
2477 <structfield>dma_private</structfield>.
2478 The <structfield>dma_area</structfield> holds the buffer
2479 pointer (the logical address). You can call
2480 <function>memcpy</function> from/to
2481 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2482 holds the physical address of the buffer. This field is
2483 specified only when the buffer is a linear buffer.
2484 <structfield>dma_bytes</structfield> holds the size of buffer
2485 in bytes. <structfield>dma_private</structfield> is used for
2486 the ALSA DMA allocator.
2487 </para>
2488
2489 <para>
2490 If you use a standard ALSA function,
2491 <function>snd_pcm_lib_malloc_pages()</function>, for
2492 allocating the buffer, these fields are set by the ALSA middle
2493 layer, and you should <emphasis>not</emphasis> change them by
2494 yourself. You can read them but not write them.
2495 On the other hand, if you want to allocate the buffer by
2496 yourself, you'll need to manage it in hw_params callback.
2497 At least, <structfield>dma_bytes</structfield> is mandatory.
2498 <structfield>dma_area</structfield> is necessary when the
2499 buffer is mmapped. If your driver doesn't support mmap, this
2500 field is not necessary. <structfield>dma_addr</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002501 is also optional. You can use
Linus Torvalds1da177e2005-04-16 15:20:36 -07002502 <structfield>dma_private</structfield> as you like, too.
2503 </para>
2504 </section>
2505
2506 <section id="pcm-interface-runtime-status">
2507 <title>Running Status</title>
2508 <para>
2509 The running status can be referred via <constant>runtime-&gt;status</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002510 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002511 record. For example, you can get the current DMA hardware
2512 pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2513 </para>
2514
2515 <para>
2516 The DMA application pointer can be referred via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002517 <constant>runtime-&gt;control</constant>, which points to the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002518 struct <structname>snd_pcm_mmap_control</structname> record.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002519 However, accessing directly to this value is not recommended.
2520 </para>
2521 </section>
2522
2523 <section id="pcm-interface-runtime-private">
2524 <title>Private Data</title>
2525 <para>
2526 You can allocate a record for the substream and store it in
2527 <constant>runtime-&gt;private_data</constant>. Usually, this
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002528 is done in
Linus Torvalds1da177e2005-04-16 15:20:36 -07002529 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2530 the open callback</citetitle></link>.
2531 Don't mix this with <constant>pcm-&gt;private_data</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002532 The <constant>pcm-&gt;private_data</constant> usually points to the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002533 chip instance assigned statically at the creation of PCM, while the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002534 <constant>runtime-&gt;private_data</constant> points to a dynamic
2535 data structure created at the PCM open callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002536
2537 <informalexample>
2538 <programlisting>
2539<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002540 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002541 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002542 struct my_pcm_data *data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002543 ....
2544 data = kmalloc(sizeof(*data), GFP_KERNEL);
2545 substream->runtime->private_data = data;
2546 ....
2547 }
2548]]>
2549 </programlisting>
2550 </informalexample>
2551 </para>
2552
2553 <para>
2554 The allocated object must be released in
2555 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2556 the close callback</citetitle></link>.
2557 </para>
2558 </section>
2559
2560 <section id="pcm-interface-runtime-intr">
2561 <title>Interrupt Callbacks</title>
2562 <para>
2563 The field <structfield>transfer_ack_begin</structfield> and
2564 <structfield>transfer_ack_end</structfield> are called at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002565 the beginning and at the end of
Linus Torvalds1da177e2005-04-16 15:20:36 -07002566 <function>snd_pcm_period_elapsed()</function>, respectively.
2567 </para>
2568 </section>
2569
2570 </section>
2571
2572 <section id="pcm-interface-operators">
2573 <title>Operators</title>
2574 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002575 OK, now let me give details about each pcm callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07002576 (<parameter>ops</parameter>). In general, every callback must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002577 return 0 if successful, or a negative error number
2578 such as <constant>-EINVAL</constant>. To choose an appropriate
2579 error number, it is advised to check what value other parts of
2580 the kernel return when the same kind of request fails.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002581 </para>
2582
2583 <para>
2584 The callback function takes at least the argument with
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002585 <structname>snd_pcm_substream</structname> pointer. To retrieve
2586 the chip record from the given substream instance, you can use the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002587 following macro.
2588
2589 <informalexample>
2590 <programlisting>
2591<![CDATA[
2592 int xxx() {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002593 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002594 ....
2595 }
2596]]>
2597 </programlisting>
2598 </informalexample>
2599
2600 The macro reads <constant>substream-&gt;private_data</constant>,
2601 which is a copy of <constant>pcm-&gt;private_data</constant>.
2602 You can override the former if you need to assign different data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002603 records per PCM substream. For example, the cmi8330 driver assigns
Linus Torvalds1da177e2005-04-16 15:20:36 -07002604 different private_data for playback and capture directions,
2605 because it uses two different codecs (SB- and AD-compatible) for
2606 different directions.
2607 </para>
2608
2609 <section id="pcm-interface-operators-open-callback">
2610 <title>open callback</title>
2611 <para>
2612 <informalexample>
2613 <programlisting>
2614<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002615 static int snd_xxx_open(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002616]]>
2617 </programlisting>
2618 </informalexample>
2619
2620 This is called when a pcm substream is opened.
2621 </para>
2622
2623 <para>
2624 At least, here you have to initialize the runtime-&gt;hw
2625 record. Typically, this is done by like this:
2626
2627 <informalexample>
2628 <programlisting>
2629<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002630 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002631 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002632 struct mychip *chip = snd_pcm_substream_chip(substream);
2633 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002634
2635 runtime->hw = snd_mychip_playback_hw;
2636 return 0;
2637 }
2638]]>
2639 </programlisting>
2640 </informalexample>
2641
2642 where <parameter>snd_mychip_playback_hw</parameter> is the
2643 pre-defined hardware description.
2644 </para>
2645
2646 <para>
2647 You can allocate a private data in this callback, as described
2648 in <link linkend="pcm-interface-runtime-private"><citetitle>
2649 Private Data</citetitle></link> section.
2650 </para>
2651
2652 <para>
2653 If the hardware configuration needs more constraints, set the
2654 hardware constraints here, too.
2655 See <link linkend="pcm-interface-constraints"><citetitle>
2656 Constraints</citetitle></link> for more details.
2657 </para>
2658 </section>
2659
2660 <section id="pcm-interface-operators-close-callback">
2661 <title>close callback</title>
2662 <para>
2663 <informalexample>
2664 <programlisting>
2665<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002666 static int snd_xxx_close(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002667]]>
2668 </programlisting>
2669 </informalexample>
2670
2671 Obviously, this is called when a pcm substream is closed.
2672 </para>
2673
2674 <para>
2675 Any private instance for a pcm substream allocated in the
2676 open callback will be released here.
2677
2678 <informalexample>
2679 <programlisting>
2680<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002681 static int snd_xxx_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002682 {
2683 ....
2684 kfree(substream->runtime->private_data);
2685 ....
2686 }
2687]]>
2688 </programlisting>
2689 </informalexample>
2690 </para>
2691 </section>
2692
2693 <section id="pcm-interface-operators-ioctl-callback">
2694 <title>ioctl callback</title>
2695 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002696 This is used for any special call to pcm ioctls. But
Linus Torvalds1da177e2005-04-16 15:20:36 -07002697 usually you can pass a generic ioctl callback,
2698 <function>snd_pcm_lib_ioctl</function>.
2699 </para>
2700 </section>
2701
2702 <section id="pcm-interface-operators-hw-params-callback">
2703 <title>hw_params callback</title>
2704 <para>
2705 <informalexample>
2706 <programlisting>
2707<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002708 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2709 struct snd_pcm_hw_params *hw_params);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002710]]>
2711 </programlisting>
2712 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002713 </para>
2714
2715 <para>
2716 This is called when the hardware parameter
2717 (<structfield>hw_params</structfield>) is set
2718 up by the application,
2719 that is, once when the buffer size, the period size, the
2720 format, etc. are defined for the pcm substream.
2721 </para>
2722
2723 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002724 Many hardware setups should be done in this callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07002725 including the allocation of buffers.
2726 </para>
2727
2728 <para>
2729 Parameters to be initialized are retrieved by
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002730 <function>params_xxx()</function> macros. To allocate
Linus Torvalds1da177e2005-04-16 15:20:36 -07002731 buffer, you can call a helper function,
2732
2733 <informalexample>
2734 <programlisting>
2735<![CDATA[
2736 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2737]]>
2738 </programlisting>
2739 </informalexample>
2740
2741 <function>snd_pcm_lib_malloc_pages()</function> is available
2742 only when the DMA buffers have been pre-allocated.
2743 See the section <link
2744 linkend="buffer-and-memory-buffer-types"><citetitle>
2745 Buffer Types</citetitle></link> for more details.
2746 </para>
2747
2748 <para>
2749 Note that this and <structfield>prepare</structfield> callbacks
2750 may be called multiple times per initialization.
2751 For example, the OSS emulation may
2752 call these callbacks at each change via its ioctl.
2753 </para>
2754
2755 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002756 Thus, you need to be careful not to allocate the same buffers
2757 many times, which will lead to memory leaks! Calling the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002758 helper function above many times is OK. It will release the
2759 previous buffer automatically when it was already allocated.
2760 </para>
2761
2762 <para>
2763 Another note is that this callback is non-atomic
2764 (schedulable). This is important, because the
2765 <structfield>trigger</structfield> callback
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002766 is atomic (non-schedulable). That is, mutexes or any
Linus Torvalds1da177e2005-04-16 15:20:36 -07002767 schedule-related functions are not available in
2768 <structfield>trigger</structfield> callback.
2769 Please see the subsection
2770 <link linkend="pcm-interface-atomicity"><citetitle>
2771 Atomicity</citetitle></link> for details.
2772 </para>
2773 </section>
2774
2775 <section id="pcm-interface-operators-hw-free-callback">
2776 <title>hw_free callback</title>
2777 <para>
2778 <informalexample>
2779 <programlisting>
2780<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002781 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002782]]>
2783 </programlisting>
2784 </informalexample>
2785 </para>
2786
2787 <para>
2788 This is called to release the resources allocated via
2789 <structfield>hw_params</structfield>. For example, releasing the
2790 buffer via
2791 <function>snd_pcm_lib_malloc_pages()</function> is done by
2792 calling the following:
2793
2794 <informalexample>
2795 <programlisting>
2796<![CDATA[
2797 snd_pcm_lib_free_pages(substream);
2798]]>
2799 </programlisting>
2800 </informalexample>
2801 </para>
2802
2803 <para>
2804 This function is always called before the close callback is called.
2805 Also, the callback may be called multiple times, too.
2806 Keep track whether the resource was already released.
2807 </para>
2808 </section>
2809
2810 <section id="pcm-interface-operators-prepare-callback">
2811 <title>prepare callback</title>
2812 <para>
2813 <informalexample>
2814 <programlisting>
2815<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002816 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002817]]>
2818 </programlisting>
2819 </informalexample>
2820 </para>
2821
2822 <para>
2823 This callback is called when the pcm is
2824 <quote>prepared</quote>. You can set the format type, sample
2825 rate, etc. here. The difference from
2826 <structfield>hw_params</structfield> is that the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002827 <structfield>prepare</structfield> callback will be called each
Linus Torvalds1da177e2005-04-16 15:20:36 -07002828 time
2829 <function>snd_pcm_prepare()</function> is called, i.e. when
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002830 recovering after underruns, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002831 </para>
2832
2833 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002834 Note that this callback is now non-atomic.
2835 You can use schedule-related functions safely in this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002836 </para>
2837
2838 <para>
2839 In this and the following callbacks, you can refer to the
2840 values via the runtime record,
2841 substream-&gt;runtime.
2842 For example, to get the current
2843 rate, format or channels, access to
2844 runtime-&gt;rate,
2845 runtime-&gt;format or
2846 runtime-&gt;channels, respectively.
2847 The physical address of the allocated buffer is set to
2848 runtime-&gt;dma_area. The buffer and period sizes are
2849 in runtime-&gt;buffer_size and runtime-&gt;period_size,
2850 respectively.
2851 </para>
2852
2853 <para>
2854 Be careful that this callback will be called many times at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002855 each setup, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002856 </para>
2857 </section>
2858
2859 <section id="pcm-interface-operators-trigger-callback">
2860 <title>trigger callback</title>
2861 <para>
2862 <informalexample>
2863 <programlisting>
2864<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002865 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002866]]>
2867 </programlisting>
2868 </informalexample>
2869
2870 This is called when the pcm is started, stopped or paused.
2871 </para>
2872
2873 <para>
2874 Which action is specified in the second argument,
2875 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2876 <filename>&lt;sound/pcm.h&gt;</filename>. At least,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002877 the <constant>START</constant> and <constant>STOP</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002878 commands must be defined in this callback.
2879
2880 <informalexample>
2881 <programlisting>
2882<![CDATA[
2883 switch (cmd) {
2884 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002885 /* do something to start the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002886 break;
2887 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002888 /* do something to stop the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002889 break;
2890 default:
2891 return -EINVAL;
2892 }
2893]]>
2894 </programlisting>
2895 </informalexample>
2896 </para>
2897
2898 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002899 When the pcm supports the pause operation (given in the info
Antonio Ospited4dab5a2013-01-29 12:56:28 +01002900 field of the hardware table), the <constant>PAUSE_PUSH</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002901 and <constant>PAUSE_RELEASE</constant> commands must be
2902 handled here, too. The former is the command to pause the pcm,
2903 and the latter to restart the pcm again.
2904 </para>
2905
2906 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002907 When the pcm supports the suspend/resume operation,
2908 regardless of full or partial suspend/resume support,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002909 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002910 commands must be handled, too.
2911 These commands are issued when the power-management status is
2912 changed. Obviously, the <constant>SUSPEND</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002913 <constant>RESUME</constant> commands
2914 suspend and resume the pcm substream, and usually, they
2915 are identical to the <constant>STOP</constant> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07002916 <constant>START</constant> commands, respectively.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002917 See the <link linkend="power-management"><citetitle>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002918 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002919 </para>
2920
2921 <para>
2922 As mentioned, this callback is atomic. You cannot call
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002923 functions which may sleep.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002924 The trigger callback should be as minimal as possible,
2925 just really triggering the DMA. The other stuff should be
2926 initialized hw_params and prepare callbacks properly
2927 beforehand.
2928 </para>
2929 </section>
2930
2931 <section id="pcm-interface-operators-pointer-callback">
2932 <title>pointer callback</title>
2933 <para>
2934 <informalexample>
2935 <programlisting>
2936<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002937 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002938]]>
2939 </programlisting>
2940 </informalexample>
2941
2942 This callback is called when the PCM middle layer inquires
2943 the current hardware position on the buffer. The position must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002944 be returned in frames,
2945 ranging from 0 to buffer_size - 1.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002946 </para>
2947
2948 <para>
2949 This is called usually from the buffer-update routine in the
2950 pcm middle layer, which is invoked when
2951 <function>snd_pcm_period_elapsed()</function> is called in the
2952 interrupt routine. Then the pcm middle layer updates the
2953 position and calculates the available space, and wakes up the
2954 sleeping poll threads, etc.
2955 </para>
2956
2957 <para>
2958 This callback is also atomic.
2959 </para>
2960 </section>
2961
2962 <section id="pcm-interface-operators-copy-silence">
2963 <title>copy and silence callbacks</title>
2964 <para>
2965 These callbacks are not mandatory, and can be omitted in
2966 most cases. These callbacks are used when the hardware buffer
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002967 cannot be in the normal memory space. Some chips have their
Linus Torvalds1da177e2005-04-16 15:20:36 -07002968 own buffer on the hardware which is not mappable. In such a
2969 case, you have to transfer the data manually from the memory
2970 buffer to the hardware buffer. Or, if the buffer is
2971 non-contiguous on both physical and virtual memory spaces,
2972 these callbacks must be defined, too.
2973 </para>
2974
2975 <para>
2976 If these two callbacks are defined, copy and set-silence
2977 operations are done by them. The detailed will be described in
2978 the later section <link
2979 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2980 Management</citetitle></link>.
2981 </para>
2982 </section>
2983
2984 <section id="pcm-interface-operators-ack">
2985 <title>ack callback</title>
2986 <para>
2987 This callback is also not mandatory. This callback is called
2988 when the appl_ptr is updated in read or write operations.
2989 Some drivers like emu10k1-fx and cs46xx need to track the
2990 current appl_ptr for the internal buffer, and this callback
2991 is useful only for such a purpose.
2992 </para>
2993 <para>
2994 This callback is atomic.
2995 </para>
2996 </section>
2997
2998 <section id="pcm-interface-operators-page-callback">
2999 <title>page callback</title>
3000
3001 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003002 This callback is optional too. This callback is used
3003 mainly for non-contiguous buffers. The mmap calls this
Linus Torvalds1da177e2005-04-16 15:20:36 -07003004 callback to get the page address. Some examples will be
3005 explained in the later section <link
3006 linkend="buffer-and-memory"><citetitle>Buffer and Memory
3007 Management</citetitle></link>, too.
3008 </para>
3009 </section>
3010 </section>
3011
3012 <section id="pcm-interface-interrupt-handler">
3013 <title>Interrupt Handler</title>
3014 <para>
3015 The rest of pcm stuff is the PCM interrupt handler. The
3016 role of PCM interrupt handler in the sound driver is to update
3017 the buffer position and to tell the PCM middle layer when the
3018 buffer position goes across the prescribed period size. To
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003019 inform this, call the <function>snd_pcm_period_elapsed()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003020 function.
3021 </para>
3022
3023 <para>
3024 There are several types of sound chips to generate the interrupts.
3025 </para>
3026
3027 <section id="pcm-interface-interrupt-handler-boundary">
3028 <title>Interrupts at the period (fragment) boundary</title>
3029 <para>
3030 This is the most frequently found type: the hardware
3031 generates an interrupt at each period boundary.
3032 In this case, you can call
3033 <function>snd_pcm_period_elapsed()</function> at each
3034 interrupt.
3035 </para>
3036
3037 <para>
3038 <function>snd_pcm_period_elapsed()</function> takes the
3039 substream pointer as its argument. Thus, you need to keep the
3040 substream pointer accessible from the chip instance. For
3041 example, define substream field in the chip record to hold the
3042 current running substream pointer, and set the pointer value
3043 at open callback (and reset at close callback).
3044 </para>
3045
3046 <para>
Adrian Bunk04187262006-06-30 18:23:04 +02003047 If you acquire a spinlock in the interrupt handler, and the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003048 lock is used in other pcm callbacks, too, then you have to
3049 release the lock before calling
3050 <function>snd_pcm_period_elapsed()</function>, because
3051 <function>snd_pcm_period_elapsed()</function> calls other pcm
3052 callbacks inside.
3053 </para>
3054
3055 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003056 Typical code would be like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003057
3058 <example>
3059 <title>Interrupt Handler Case #1</title>
3060 <programlisting>
3061<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003062 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003063 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003064 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003065 spin_lock(&chip->lock);
3066 ....
3067 if (pcm_irq_invoked(chip)) {
3068 /* call updater, unlock before it */
3069 spin_unlock(&chip->lock);
3070 snd_pcm_period_elapsed(chip->substream);
3071 spin_lock(&chip->lock);
Takashi Iwai95a5b082007-07-26 16:50:09 +02003072 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003073 }
3074 ....
3075 spin_unlock(&chip->lock);
3076 return IRQ_HANDLED;
3077 }
3078]]>
3079 </programlisting>
3080 </example>
3081 </para>
3082 </section>
3083
3084 <section id="pcm-interface-interrupt-handler-timer">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003085 <title>High frequency timer interrupts</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003086 <para>
Antonio Ospited4dab5a2013-01-29 12:56:28 +01003087 This happens when the hardware doesn't generate interrupts
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003088 at the period boundary but issues timer interrupts at a fixed
Linus Torvalds1da177e2005-04-16 15:20:36 -07003089 timer rate (e.g. es1968 or ymfpci drivers).
3090 In this case, you need to check the current hardware
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003091 position and accumulate the processed sample length at each
3092 interrupt. When the accumulated size exceeds the period
Linus Torvalds1da177e2005-04-16 15:20:36 -07003093 size, call
3094 <function>snd_pcm_period_elapsed()</function> and reset the
3095 accumulator.
3096 </para>
3097
3098 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003099 Typical code would be like the following.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003100
3101 <example>
3102 <title>Interrupt Handler Case #2</title>
3103 <programlisting>
3104<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003105 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003106 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003107 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003108 spin_lock(&chip->lock);
3109 ....
3110 if (pcm_irq_invoked(chip)) {
3111 unsigned int last_ptr, size;
3112 /* get the current hardware pointer (in frames) */
3113 last_ptr = get_hw_ptr(chip);
3114 /* calculate the processed frames since the
3115 * last update
3116 */
3117 if (last_ptr < chip->last_ptr)
3118 size = runtime->buffer_size + last_ptr
3119 - chip->last_ptr;
3120 else
3121 size = last_ptr - chip->last_ptr;
3122 /* remember the last updated point */
3123 chip->last_ptr = last_ptr;
3124 /* accumulate the size */
3125 chip->size += size;
3126 /* over the period boundary? */
3127 if (chip->size >= runtime->period_size) {
3128 /* reset the accumulator */
3129 chip->size %= runtime->period_size;
3130 /* call updater */
3131 spin_unlock(&chip->lock);
3132 snd_pcm_period_elapsed(substream);
3133 spin_lock(&chip->lock);
3134 }
Takashi Iwai95a5b082007-07-26 16:50:09 +02003135 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003136 }
3137 ....
3138 spin_unlock(&chip->lock);
3139 return IRQ_HANDLED;
3140 }
3141]]>
3142 </programlisting>
3143 </example>
3144 </para>
3145 </section>
3146
3147 <section id="pcm-interface-interrupt-handler-both">
3148 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3149 <para>
3150 In both cases, even if more than one period are elapsed, you
3151 don't have to call
3152 <function>snd_pcm_period_elapsed()</function> many times. Call
3153 only once. And the pcm layer will check the current hardware
3154 pointer and update to the latest status.
3155 </para>
3156 </section>
3157 </section>
3158
3159 <section id="pcm-interface-atomicity">
3160 <title>Atomicity</title>
3161 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003162 One of the most important (and thus difficult to debug) problems
3163 in kernel programming are race conditions.
3164 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3165 or semaphores. In general, if a race condition can happen
3166 in an interrupt handler, it has to be managed atomically, and you
3167 have to use a spinlock to protect the critical session. If the
3168 critical section is not in interrupt handler code and
3169 if taking a relatively long time to execute is acceptable, you
3170 should use mutexes or semaphores instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003171 </para>
3172
3173 <para>
3174 As already seen, some pcm callbacks are atomic and some are
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003175 not. For example, the <parameter>hw_params</parameter> callback is
Linus Torvalds1da177e2005-04-16 15:20:36 -07003176 non-atomic, while <parameter>trigger</parameter> callback is
3177 atomic. This means, the latter is called already in a spinlock
3178 held by the PCM middle layer. Please take this atomicity into
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003179 account when you choose a locking scheme in the callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003180 </para>
3181
3182 <para>
3183 In the atomic callbacks, you cannot use functions which may call
3184 <function>schedule</function> or go to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003185 <function>sleep</function>. Semaphores and mutexes can sleep,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003186 and hence they cannot be used inside the atomic callbacks
3187 (e.g. <parameter>trigger</parameter> callback).
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003188 To implement some delay in such a callback, please use
Linus Torvalds1da177e2005-04-16 15:20:36 -07003189 <function>udelay()</function> or <function>mdelay()</function>.
3190 </para>
3191
3192 <para>
3193 All three atomic callbacks (trigger, pointer, and ack) are
3194 called with local interrupts disabled.
3195 </para>
3196
3197 </section>
3198 <section id="pcm-interface-constraints">
3199 <title>Constraints</title>
3200 <para>
3201 If your chip supports unconventional sample rates, or only the
3202 limited samples, you need to set a constraint for the
3203 condition.
3204 </para>
3205
3206 <para>
3207 For example, in order to restrict the sample rates in the some
3208 supported values, use
3209 <function>snd_pcm_hw_constraint_list()</function>.
3210 You need to call this function in the open callback.
3211
3212 <example>
3213 <title>Example of Hardware Constraints</title>
3214 <programlisting>
3215<![CDATA[
3216 static unsigned int rates[] =
3217 {4000, 10000, 22050, 44100};
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003218 static struct snd_pcm_hw_constraint_list constraints_rates = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003219 .count = ARRAY_SIZE(rates),
3220 .list = rates,
3221 .mask = 0,
3222 };
3223
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003224 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003225 {
3226 int err;
3227 ....
3228 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3229 SNDRV_PCM_HW_PARAM_RATE,
3230 &constraints_rates);
3231 if (err < 0)
3232 return err;
3233 ....
3234 }
3235]]>
3236 </programlisting>
3237 </example>
3238 </para>
3239
3240 <para>
3241 There are many different constraints.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003242 Look at <filename>sound/pcm.h</filename> for a complete list.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003243 You can even define your own constraint rules.
3244 For example, let's suppose my_chip can manage a substream of 1 channel
3245 if and only if the format is S16_LE, otherwise it supports any format
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003246 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
Linus Torvalds1da177e2005-04-16 15:20:36 -07003247 other constraint_list). You can build a rule like this:
3248
3249 <example>
3250 <title>Example of Hardware Constraints for Channels</title>
3251 <programlisting>
3252<![CDATA[
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003253 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003254 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003255 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003256 struct snd_interval *c = hw_param_interval(params,
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003257 SNDRV_PCM_HW_PARAM_CHANNELS);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003258 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003259 struct snd_interval ch;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003260
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003261 snd_interval_any(&ch);
3262 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3263 ch.min = ch.max = 1;
3264 ch.integer = 1;
3265 return snd_interval_refine(c, &ch);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003266 }
3267 return 0;
3268 }
3269]]>
3270 </programlisting>
3271 </example>
3272 </para>
3273
3274 <para>
3275 Then you need to call this function to add your rule:
3276
3277 <informalexample>
3278 <programlisting>
3279<![CDATA[
3280 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
Takashi Iwai16c5ab12013-02-05 14:23:53 +01003281 hw_rule_channels_by_format, NULL,
3282 SNDRV_PCM_HW_PARAM_FORMAT, -1);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003283]]>
3284 </programlisting>
3285 </informalexample>
3286 </para>
3287
3288 <para>
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003289 The rule function is called when an application sets the PCM
3290 format, and it refines the number of channels accordingly.
3291 But an application may set the number of channels before
3292 setting the format. Thus you also need to define the inverse rule:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003293
3294 <example>
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003295 <title>Example of Hardware Constraints for Formats</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003296 <programlisting>
3297<![CDATA[
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003298 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003299 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003300 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003301 struct snd_interval *c = hw_param_interval(params,
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003302 SNDRV_PCM_HW_PARAM_CHANNELS);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003303 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003304 struct snd_mask fmt;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003305
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003306 snd_mask_any(&fmt); /* Init the struct */
3307 if (c->min < 2) {
3308 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3309 return snd_mask_refine(f, &fmt);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003310 }
3311 return 0;
3312 }
3313]]>
3314 </programlisting>
3315 </example>
3316 </para>
3317
3318 <para>
3319 ...and in the open callback:
3320 <informalexample>
3321 <programlisting>
3322<![CDATA[
3323 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
Takashi Iwai16c5ab12013-02-05 14:23:53 +01003324 hw_rule_format_by_channels, NULL,
3325 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003326]]>
3327 </programlisting>
3328 </informalexample>
3329 </para>
3330
3331 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003332 I won't give more details here, rather I
Linus Torvalds1da177e2005-04-16 15:20:36 -07003333 would like to say, <quote>Luke, use the source.</quote>
3334 </para>
3335 </section>
3336
3337 </chapter>
3338
3339
3340<!-- ****************************************************** -->
3341<!-- Control Interface -->
3342<!-- ****************************************************** -->
3343 <chapter id="control-interface">
3344 <title>Control Interface</title>
3345
3346 <section id="control-interface-general">
3347 <title>General</title>
3348 <para>
3349 The control interface is used widely for many switches,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003350 sliders, etc. which are accessed from user-space. Its most
3351 important use is the mixer interface. In other words, since ALSA
3352 0.9.x, all the mixer stuff is implemented on the control kernel API.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003353 </para>
3354
3355 <para>
3356 ALSA has a well-defined AC97 control module. If your chip
3357 supports only the AC97 and nothing else, you can skip this
3358 section.
3359 </para>
3360
3361 <para>
3362 The control API is defined in
3363 <filename>&lt;sound/control.h&gt;</filename>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003364 Include this file if you want to add your own controls.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003365 </para>
3366 </section>
3367
3368 <section id="control-interface-definition">
3369 <title>Definition of Controls</title>
3370 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003371 To create a new control, you need to define the
3372 following three
Linus Torvalds1da177e2005-04-16 15:20:36 -07003373 callbacks: <structfield>info</structfield>,
3374 <structfield>get</structfield> and
3375 <structfield>put</structfield>. Then, define a
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003376 struct <structname>snd_kcontrol_new</structname> record, such as:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003377
3378 <example>
3379 <title>Definition of a Control</title>
3380 <programlisting>
3381<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01003382 static struct snd_kcontrol_new my_control = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003383 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3384 .name = "PCM Playback Switch",
3385 .index = 0,
3386 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003387 .private_value = 0xffff,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003388 .info = my_control_info,
3389 .get = my_control_get,
3390 .put = my_control_put
3391 };
3392]]>
3393 </programlisting>
3394 </example>
3395 </para>
3396
3397 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003398 The <structfield>iface</structfield> field specifies the control
3399 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
Clemens Ladisch67ed4162005-07-29 15:32:58 +02003400 is usually <constant>MIXER</constant>.
3401 Use <constant>CARD</constant> for global controls that are not
3402 logically part of the mixer.
3403 If the control is closely associated with some specific device on
3404 the sound card, use <constant>HWDEP</constant>,
3405 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3406 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3407 specify the device number with the
3408 <structfield>device</structfield> and
3409 <structfield>subdevice</structfield> fields.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003410 </para>
3411
3412 <para>
3413 The <structfield>name</structfield> is the name identifier
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003414 string. Since ALSA 0.9.x, the control name is very important,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003415 because its role is classified from its name. There are
3416 pre-defined standard control names. The details are described in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003417 the <link linkend="control-interface-control-names"><citetitle>
3418 Control Names</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003419 </para>
3420
3421 <para>
3422 The <structfield>index</structfield> field holds the index number
3423 of this control. If there are several different controls with
3424 the same name, they can be distinguished by the index
3425 number. This is the case when
3426 several codecs exist on the card. If the index is zero, you can
3427 omit the definition above.
3428 </para>
3429
3430 <para>
3431 The <structfield>access</structfield> field contains the access
3432 type of this control. Give the combination of bit masks,
3433 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003434 The details will be explained in
3435 the <link linkend="control-interface-access-flags"><citetitle>
3436 Access Flags</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003437 </para>
3438
3439 <para>
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003440 The <structfield>private_value</structfield> field contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07003441 an arbitrary long integer value for this record. When using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003442 the generic <structfield>info</structfield>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003443 <structfield>get</structfield> and
3444 <structfield>put</structfield> callbacks, you can pass a value
3445 through this field. If several small numbers are necessary, you can
3446 combine them in bitwise. Or, it's possible to give a pointer
3447 (casted to unsigned long) of some record to this field, too.
3448 </para>
3449
3450 <para>
Clemens Ladischd1761d12007-09-10 08:05:19 +02003451 The <structfield>tlv</structfield> field can be used to provide
3452 metadata about the control; see the
3453 <link linkend="control-interface-tlv">
3454 <citetitle>Metadata</citetitle></link> subsection.
3455 </para>
3456
3457 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003458 The other three are
3459 <link linkend="control-interface-callbacks"><citetitle>
3460 callback functions</citetitle></link>.
3461 </para>
3462 </section>
3463
3464 <section id="control-interface-control-names">
3465 <title>Control Names</title>
3466 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003467 There are some standards to define the control names. A
Linus Torvalds1da177e2005-04-16 15:20:36 -07003468 control is usually defined from the three parts as
3469 <quote>SOURCE DIRECTION FUNCTION</quote>.
3470 </para>
3471
3472 <para>
3473 The first, <constant>SOURCE</constant>, specifies the source
3474 of the control, and is a string such as <quote>Master</quote>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003475 <quote>PCM</quote>, <quote>CD</quote> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07003476 <quote>Line</quote>. There are many pre-defined sources.
3477 </para>
3478
3479 <para>
3480 The second, <constant>DIRECTION</constant>, is one of the
3481 following strings according to the direction of the control:
3482 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3483 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3484 be omitted, meaning both playback and capture directions.
3485 </para>
3486
3487 <para>
3488 The third, <constant>FUNCTION</constant>, is one of the
3489 following strings according to the function of the control:
3490 <quote>Switch</quote>, <quote>Volume</quote> and
3491 <quote>Route</quote>.
3492 </para>
3493
3494 <para>
3495 The example of control names are, thus, <quote>Master Capture
3496 Switch</quote> or <quote>PCM Playback Volume</quote>.
3497 </para>
3498
3499 <para>
3500 There are some exceptions:
3501 </para>
3502
3503 <section id="control-interface-control-names-global">
3504 <title>Global capture and playback</title>
3505 <para>
3506 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3507 and <quote>Capture Volume</quote> are used for the global
3508 capture (input) source, switch and volume. Similarly,
3509 <quote>Playback Switch</quote> and <quote>Playback
3510 Volume</quote> are used for the global output gain switch and
3511 volume.
3512 </para>
3513 </section>
3514
3515 <section id="control-interface-control-names-tone">
3516 <title>Tone-controls</title>
3517 <para>
3518 tone-control switch and volumes are specified like
3519 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3520 Switch</quote>, <quote>Tone Control - Bass</quote>,
3521 <quote>Tone Control - Center</quote>.
3522 </para>
3523 </section>
3524
3525 <section id="control-interface-control-names-3d">
3526 <title>3D controls</title>
3527 <para>
3528 3D-control switches and volumes are specified like <quote>3D
3529 Control - XXX</quote>, e.g. <quote>3D Control -
3530 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3531 Control - Space</quote>.
3532 </para>
3533 </section>
3534
3535 <section id="control-interface-control-names-mic">
3536 <title>Mic boost</title>
3537 <para>
3538 Mic-boost switch is set as <quote>Mic Boost</quote> or
3539 <quote>Mic Boost (6dB)</quote>.
3540 </para>
3541
3542 <para>
3543 More precise information can be found in
3544 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3545 </para>
3546 </section>
3547 </section>
3548
3549 <section id="control-interface-access-flags">
3550 <title>Access Flags</title>
3551
3552 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003553 The access flag is the bitmask which specifies the access type
Linus Torvalds1da177e2005-04-16 15:20:36 -07003554 of the given control. The default access type is
3555 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3556 which means both read and write are allowed to this control.
3557 When the access flag is omitted (i.e. = 0), it is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003558 considered as <constant>READWRITE</constant> access as default.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003559 </para>
3560
3561 <para>
3562 When the control is read-only, pass
3563 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3564 In this case, you don't have to define
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003565 the <structfield>put</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003566 Similarly, when the control is write-only (although it's a rare
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003567 case), you can use the <constant>WRITE</constant> flag instead, and
3568 you don't need the <structfield>get</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003569 </para>
3570
3571 <para>
3572 If the control value changes frequently (e.g. the VU meter),
3573 <constant>VOLATILE</constant> flag should be given. This means
3574 that the control may be changed without
3575 <link linkend="control-interface-change-notification"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003576 notification</citetitle></link>. Applications should poll such
Linus Torvalds1da177e2005-04-16 15:20:36 -07003577 a control constantly.
3578 </para>
3579
3580 <para>
3581 When the control is inactive, set
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003582 the <constant>INACTIVE</constant> flag, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003583 There are <constant>LOCK</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003584 <constant>OWNER</constant> flags to change the write
Linus Torvalds1da177e2005-04-16 15:20:36 -07003585 permissions.
3586 </para>
3587
3588 </section>
3589
3590 <section id="control-interface-callbacks">
3591 <title>Callbacks</title>
3592
3593 <section id="control-interface-callbacks-info">
3594 <title>info callback</title>
3595 <para>
3596 The <structfield>info</structfield> callback is used to get
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003597 detailed information on this control. This must store the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003598 values of the given struct <structname>snd_ctl_elem_info</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003599 object. For example, for a boolean control with a single
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003600 element:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003601
3602 <example>
3603 <title>Example of info callback</title>
3604 <programlisting>
3605<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003606 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003607 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003608 {
3609 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3610 uinfo->count = 1;
3611 uinfo->value.integer.min = 0;
3612 uinfo->value.integer.max = 1;
3613 return 0;
3614 }
3615]]>
3616 </programlisting>
3617 </example>
3618 </para>
3619
3620 <para>
3621 The <structfield>type</structfield> field specifies the type
3622 of the control. There are <constant>BOOLEAN</constant>,
3623 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3624 <constant>BYTES</constant>, <constant>IEC958</constant> and
3625 <constant>INTEGER64</constant>. The
3626 <structfield>count</structfield> field specifies the
3627 number of elements in this control. For example, a stereo
3628 volume would have count = 2. The
3629 <structfield>value</structfield> field is a union, and
3630 the values stored are depending on the type. The boolean and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003631 integer types are identical.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003632 </para>
3633
3634 <para>
3635 The enumerated type is a bit different from others. You'll
3636 need to set the string for the currently given item index.
3637
3638 <informalexample>
3639 <programlisting>
3640<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003641 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003642 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003643 {
3644 static char *texts[4] = {
3645 "First", "Second", "Third", "Fourth"
3646 };
3647 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3648 uinfo->count = 1;
3649 uinfo->value.enumerated.items = 4;
3650 if (uinfo->value.enumerated.item > 3)
3651 uinfo->value.enumerated.item = 3;
3652 strcpy(uinfo->value.enumerated.name,
3653 texts[uinfo->value.enumerated.item]);
3654 return 0;
3655 }
3656]]>
3657 </programlisting>
3658 </informalexample>
3659 </para>
Takashi Iwai95a5b082007-07-26 16:50:09 +02003660
3661 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003662 Some common info callbacks are available for your convenience:
Takashi Iwai95a5b082007-07-26 16:50:09 +02003663 <function>snd_ctl_boolean_mono_info()</function> and
3664 <function>snd_ctl_boolean_stereo_info()</function>.
3665 Obviously, the former is an info callback for a mono channel
3666 boolean item, just like <function>snd_myctl_mono_info</function>
3667 above, and the latter is for a stereo channel boolean item.
3668 </para>
3669
Linus Torvalds1da177e2005-04-16 15:20:36 -07003670 </section>
3671
3672 <section id="control-interface-callbacks-get">
3673 <title>get callback</title>
3674
3675 <para>
3676 This callback is used to read the current value of the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003677 control and to return to user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003678 </para>
3679
3680 <para>
3681 For example,
3682
3683 <example>
3684 <title>Example of get callback</title>
3685 <programlisting>
3686<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003687 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3688 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003689 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003690 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003691 ucontrol->value.integer.value[0] = get_some_value(chip);
3692 return 0;
3693 }
3694]]>
3695 </programlisting>
3696 </example>
3697 </para>
3698
3699 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003700 The <structfield>value</structfield> field depends on
3701 the type of control as well as on the info callback. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003702 the sb driver uses this field to store the register offset,
3703 the bit-shift and the bit-mask. The
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003704 <structfield>private_value</structfield> field is set as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003705 <informalexample>
3706 <programlisting>
3707<![CDATA[
3708 .private_value = reg | (shift << 16) | (mask << 24)
3709]]>
3710 </programlisting>
3711 </informalexample>
3712 and is retrieved in callbacks like
3713 <informalexample>
3714 <programlisting>
3715<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003716 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3717 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003718 {
3719 int reg = kcontrol->private_value & 0xff;
3720 int shift = (kcontrol->private_value >> 16) & 0xff;
3721 int mask = (kcontrol->private_value >> 24) & 0xff;
3722 ....
3723 }
3724]]>
3725 </programlisting>
3726 </informalexample>
3727 </para>
3728
3729 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003730 In the <structfield>get</structfield> callback,
3731 you have to fill all the elements if the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003732 control has more than one elements,
3733 i.e. <structfield>count</structfield> &gt; 1.
3734 In the example above, we filled only one element
3735 (<structfield>value.integer.value[0]</structfield>) since it's
3736 assumed as <structfield>count</structfield> = 1.
3737 </para>
3738 </section>
3739
3740 <section id="control-interface-callbacks-put">
3741 <title>put callback</title>
3742
3743 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003744 This callback is used to write a value from user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003745 </para>
3746
3747 <para>
3748 For example,
3749
3750 <example>
3751 <title>Example of put callback</title>
3752 <programlisting>
3753<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003754 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3755 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003756 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003757 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003758 int changed = 0;
3759 if (chip->current_value !=
3760 ucontrol->value.integer.value[0]) {
3761 change_current_value(chip,
3762 ucontrol->value.integer.value[0]);
3763 changed = 1;
3764 }
3765 return changed;
3766 }
3767]]>
3768 </programlisting>
3769 </example>
3770
3771 As seen above, you have to return 1 if the value is
3772 changed. If the value is not changed, return 0 instead.
3773 If any fatal error happens, return a negative error code as
3774 usual.
3775 </para>
3776
3777 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003778 As in the <structfield>get</structfield> callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003779 when the control has more than one elements,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003780 all elements must be evaluated in this callback, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003781 </para>
3782 </section>
3783
3784 <section id="control-interface-callbacks-all">
3785 <title>Callbacks are not atomic</title>
3786 <para>
3787 All these three callbacks are basically not atomic.
3788 </para>
3789 </section>
3790 </section>
3791
3792 <section id="control-interface-constructor">
3793 <title>Constructor</title>
3794 <para>
3795 When everything is ready, finally we can create a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003796 control. To create a control, there are two functions to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07003797 called, <function>snd_ctl_new1()</function> and
3798 <function>snd_ctl_add()</function>.
3799 </para>
3800
3801 <para>
3802 In the simplest way, you can do like this:
3803
3804 <informalexample>
3805 <programlisting>
3806<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003807 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3808 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003809 return err;
3810]]>
3811 </programlisting>
3812 </informalexample>
3813
3814 where <parameter>my_control</parameter> is the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003815 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
Linus Torvalds1da177e2005-04-16 15:20:36 -07003816 is the object pointer to be passed to
3817 kcontrol-&gt;private_data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003818 which can be referred to in callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003819 </para>
3820
3821 <para>
3822 <function>snd_ctl_new1()</function> allocates a new
Takashi Iwai090015a2012-12-07 07:52:28 +01003823 <structname>snd_kcontrol</structname> instance,
3824 and <function>snd_ctl_add</function> assigns the given
Linus Torvalds1da177e2005-04-16 15:20:36 -07003825 control component to the card.
3826 </para>
3827 </section>
3828
3829 <section id="control-interface-change-notification">
3830 <title>Change Notification</title>
3831 <para>
3832 If you need to change and update a control in the interrupt
3833 routine, you can call <function>snd_ctl_notify()</function>. For
3834 example,
3835
3836 <informalexample>
3837 <programlisting>
3838<![CDATA[
3839 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3840]]>
3841 </programlisting>
3842 </informalexample>
3843
3844 This function takes the card pointer, the event-mask, and the
3845 control id pointer for the notification. The event-mask
3846 specifies the types of notification, for example, in the above
3847 example, the change of control values is notified.
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003848 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003849 to be notified.
3850 You can find some examples in <filename>es1938.c</filename> or
3851 <filename>es1968.c</filename> for hardware volume interrupts.
3852 </para>
3853 </section>
3854
Clemens Ladischd1761d12007-09-10 08:05:19 +02003855 <section id="control-interface-tlv">
3856 <title>Metadata</title>
3857 <para>
3858 To provide information about the dB values of a mixer control, use
3859 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3860 <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3861 containing this information, set the<structfield>tlv.p
3862 </structfield> field to point to this variable, and include the
3863 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3864 <structfield>access</structfield> field; like this:
3865 <informalexample>
3866 <programlisting>
3867<![CDATA[
3868 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3869
Takashi Iwai090015a2012-12-07 07:52:28 +01003870 static struct snd_kcontrol_new my_control = {
Clemens Ladischd1761d12007-09-10 08:05:19 +02003871 ...
3872 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3873 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3874 ...
3875 .tlv.p = db_scale_my_control,
3876 };
3877]]>
3878 </programlisting>
3879 </informalexample>
3880 </para>
3881
3882 <para>
3883 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3884 information about a mixer control where each step in the control's
3885 value changes the dB value by a constant dB amount.
3886 The first parameter is the name of the variable to be defined.
3887 The second parameter is the minimum value, in units of 0.01 dB.
3888 The third parameter is the step size, in units of 0.01 dB.
3889 Set the fourth parameter to 1 if the minimum value actually mutes
3890 the control.
3891 </para>
3892
3893 <para>
3894 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3895 information about a mixer control where the control's value affects
3896 the output linearly.
3897 The first parameter is the name of the variable to be defined.
3898 The second parameter is the minimum value, in units of 0.01 dB.
3899 The third parameter is the maximum value, in units of 0.01 dB.
3900 If the minimum value mutes the control, set the second parameter to
3901 <constant>TLV_DB_GAIN_MUTE</constant>.
3902 </para>
3903 </section>
3904
Linus Torvalds1da177e2005-04-16 15:20:36 -07003905 </chapter>
3906
3907
3908<!-- ****************************************************** -->
3909<!-- API for AC97 Codec -->
3910<!-- ****************************************************** -->
3911 <chapter id="api-ac97">
3912 <title>API for AC97 Codec</title>
3913
3914 <section>
3915 <title>General</title>
3916 <para>
3917 The ALSA AC97 codec layer is a well-defined one, and you don't
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003918 have to write much code to control it. Only low-level control
Linus Torvalds1da177e2005-04-16 15:20:36 -07003919 routines are necessary. The AC97 codec API is defined in
3920 <filename>&lt;sound/ac97_codec.h&gt;</filename>.
3921 </para>
3922 </section>
3923
3924 <section id="api-ac97-example">
3925 <title>Full Code Example</title>
3926 <para>
3927 <example>
3928 <title>Example of AC97 Interface</title>
3929 <programlisting>
3930<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003931 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003932 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003933 struct snd_ac97 *ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003934 ....
3935 };
3936
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003937 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003938 unsigned short reg)
3939 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003940 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003941 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003942 /* read a register value here from the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003943 return the_register_value;
3944 }
3945
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003946 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003947 unsigned short reg, unsigned short val)
3948 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003949 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003950 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003951 /* write the given register value to the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003952 }
3953
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003954 static int snd_mychip_ac97(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003955 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003956 struct snd_ac97_bus *bus;
3957 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003958 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003959 static struct snd_ac97_bus_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003960 .write = snd_mychip_ac97_write,
3961 .read = snd_mychip_ac97_read,
3962 };
3963
Takashi Iwai95a5b082007-07-26 16:50:09 +02003964 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3965 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003966 return err;
3967 memset(&ac97, 0, sizeof(ac97));
3968 ac97.private_data = chip;
3969 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3970 }
3971
3972]]>
3973 </programlisting>
3974 </example>
3975 </para>
3976 </section>
3977
3978 <section id="api-ac97-constructor">
3979 <title>Constructor</title>
3980 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003981 To create an ac97 instance, first call <function>snd_ac97_bus</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003982 with an <type>ac97_bus_ops_t</type> record with callback functions.
3983
3984 <informalexample>
3985 <programlisting>
3986<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003987 struct snd_ac97_bus *bus;
3988 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
3993 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
3994]]>
3995 </programlisting>
3996 </informalexample>
3997
3998 The bus record is shared among all belonging ac97 instances.
3999 </para>
4000
4001 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004002 And then call <function>snd_ac97_mixer()</function> with an
4003 struct <structname>snd_ac97_template</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004004 record together with the bus pointer created above.
4005
4006 <informalexample>
4007 <programlisting>
4008<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004009 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004010 int err;
4011
4012 memset(&ac97, 0, sizeof(ac97));
4013 ac97.private_data = chip;
4014 snd_ac97_mixer(bus, &ac97, &chip->ac97);
4015]]>
4016 </programlisting>
4017 </informalexample>
4018
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004019 where chip-&gt;ac97 is a pointer to a newly created
Linus Torvalds1da177e2005-04-16 15:20:36 -07004020 <type>ac97_t</type> instance.
4021 In this case, the chip pointer is set as the private data, so that
4022 the read/write callback functions can refer to this chip instance.
4023 This instance is not necessarily stored in the chip
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004024 record. If you need to change the register values from the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004025 driver, or need the suspend/resume of ac97 codecs, keep this
4026 pointer to pass to the corresponding functions.
4027 </para>
4028 </section>
4029
4030 <section id="api-ac97-callbacks">
4031 <title>Callbacks</title>
4032 <para>
4033 The standard callbacks are <structfield>read</structfield> and
4034 <structfield>write</structfield>. Obviously they
4035 correspond to the functions for read and write accesses to the
4036 hardware low-level codes.
4037 </para>
4038
4039 <para>
4040 The <structfield>read</structfield> callback returns the
4041 register value specified in the argument.
4042
4043 <informalexample>
4044 <programlisting>
4045<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004046 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004047 unsigned short reg)
4048 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004049 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004050 ....
4051 return the_register_value;
4052 }
4053]]>
4054 </programlisting>
4055 </informalexample>
4056
4057 Here, the chip can be cast from ac97-&gt;private_data.
4058 </para>
4059
4060 <para>
4061 Meanwhile, the <structfield>write</structfield> callback is
4062 used to set the register value.
4063
4064 <informalexample>
4065 <programlisting>
4066<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004067 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004068 unsigned short reg, unsigned short val)
4069]]>
4070 </programlisting>
4071 </informalexample>
4072 </para>
4073
4074 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004075 These callbacks are non-atomic like the control API callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004076 </para>
4077
4078 <para>
4079 There are also other callbacks:
4080 <structfield>reset</structfield>,
4081 <structfield>wait</structfield> and
4082 <structfield>init</structfield>.
4083 </para>
4084
4085 <para>
4086 The <structfield>reset</structfield> callback is used to reset
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004087 the codec. If the chip requires a special kind of reset, you can
Linus Torvalds1da177e2005-04-16 15:20:36 -07004088 define this callback.
4089 </para>
4090
4091 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004092 The <structfield>wait</structfield> callback is used to
4093 add some waiting time in the standard initialization of the codec. If the
4094 chip requires the extra waiting time, define this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004095 </para>
4096
4097 <para>
4098 The <structfield>init</structfield> callback is used for
4099 additional initialization of the codec.
4100 </para>
4101 </section>
4102
4103 <section id="api-ac97-updating-registers">
4104 <title>Updating Registers in The Driver</title>
4105 <para>
4106 If you need to access to the codec from the driver, you can
4107 call the following functions:
4108 <function>snd_ac97_write()</function>,
4109 <function>snd_ac97_read()</function>,
4110 <function>snd_ac97_update()</function> and
4111 <function>snd_ac97_update_bits()</function>.
4112 </para>
4113
4114 <para>
4115 Both <function>snd_ac97_write()</function> and
4116 <function>snd_ac97_update()</function> functions are used to
4117 set a value to the given register
4118 (<constant>AC97_XXX</constant>). The difference between them is
4119 that <function>snd_ac97_update()</function> doesn't write a
4120 value if the given value has been already set, while
4121 <function>snd_ac97_write()</function> always rewrites the
4122 value.
4123
4124 <informalexample>
4125 <programlisting>
4126<![CDATA[
4127 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4128 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4129]]>
4130 </programlisting>
4131 </informalexample>
4132 </para>
4133
4134 <para>
4135 <function>snd_ac97_read()</function> is used to read the value
4136 of the given register. For example,
4137
4138 <informalexample>
4139 <programlisting>
4140<![CDATA[
4141 value = snd_ac97_read(ac97, AC97_MASTER);
4142]]>
4143 </programlisting>
4144 </informalexample>
4145 </para>
4146
4147 <para>
4148 <function>snd_ac97_update_bits()</function> is used to update
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004149 some bits in the given register.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004150
4151 <informalexample>
4152 <programlisting>
4153<![CDATA[
4154 snd_ac97_update_bits(ac97, reg, mask, value);
4155]]>
4156 </programlisting>
4157 </informalexample>
4158 </para>
4159
4160 <para>
4161 Also, there is a function to change the sample rate (of a
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004162 given register such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07004163 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4164 DRA is supported by the codec:
4165 <function>snd_ac97_set_rate()</function>.
4166
4167 <informalexample>
4168 <programlisting>
4169<![CDATA[
4170 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4171]]>
4172 </programlisting>
4173 </informalexample>
4174 </para>
4175
4176 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004177 The following registers are available to set the rate:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004178 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4179 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4180 <constant>AC97_PCM_LR_ADC_RATE</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004181 <constant>AC97_SPDIF</constant>. When
Linus Torvalds1da177e2005-04-16 15:20:36 -07004182 <constant>AC97_SPDIF</constant> is specified, the register is
4183 not really changed but the corresponding IEC958 status bits will
4184 be updated.
4185 </para>
4186 </section>
4187
4188 <section id="api-ac97-clock-adjustment">
4189 <title>Clock Adjustment</title>
4190 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004191 In some chips, the clock of the codec isn't 48000 but using a
Linus Torvalds1da177e2005-04-16 15:20:36 -07004192 PCI clock (to save a quartz!). In this case, change the field
4193 bus-&gt;clock to the corresponding
4194 value. For example, intel8x0
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004195 and es1968 drivers have their own function to read from the clock.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004196 </para>
4197 </section>
4198
4199 <section id="api-ac97-proc-files">
4200 <title>Proc Files</title>
4201 <para>
4202 The ALSA AC97 interface will create a proc file such as
4203 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4204 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4205 see the current status and registers of the codec.
4206 </para>
4207 </section>
4208
4209 <section id="api-ac97-multiple-codecs">
4210 <title>Multiple Codecs</title>
4211 <para>
4212 When there are several codecs on the same card, you need to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004213 call <function>snd_ac97_mixer()</function> multiple times with
Linus Torvalds1da177e2005-04-16 15:20:36 -07004214 ac97.num=1 or greater. The <structfield>num</structfield> field
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004215 specifies the codec number.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004216 </para>
4217
4218 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004219 If you set up multiple codecs, you either need to write
Linus Torvalds1da177e2005-04-16 15:20:36 -07004220 different callbacks for each codec or check
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004221 ac97-&gt;num in the callback routines.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004222 </para>
4223 </section>
4224
4225 </chapter>
4226
4227
4228<!-- ****************************************************** -->
4229<!-- MIDI (MPU401-UART) Interface -->
4230<!-- ****************************************************** -->
4231 <chapter id="midi-interface">
4232 <title>MIDI (MPU401-UART) Interface</title>
4233
4234 <section id="midi-interface-general">
4235 <title>General</title>
4236 <para>
4237 Many soundcards have built-in MIDI (MPU401-UART)
4238 interfaces. When the soundcard supports the standard MPU401-UART
4239 interface, most likely you can use the ALSA MPU401-UART API. The
4240 MPU401-UART API is defined in
4241 <filename>&lt;sound/mpu401.h&gt;</filename>.
4242 </para>
4243
4244 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004245 Some soundchips have a similar but slightly different
Linus Torvalds1da177e2005-04-16 15:20:36 -07004246 implementation of mpu401 stuff. For example, emu10k1 has its own
4247 mpu401 routines.
4248 </para>
4249 </section>
4250
4251 <section id="midi-interface-constructor">
4252 <title>Constructor</title>
4253 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004254 To create a rawmidi object, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004255 <function>snd_mpu401_uart_new()</function>.
4256
4257 <informalexample>
4258 <programlisting>
4259<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004260 struct snd_rawmidi *rmidi;
Takashi Iwai302e4c22006-05-23 13:24:30 +02004261 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
Clemens Ladischdba8b462011-09-13 11:24:41 +02004262 irq, &rmidi);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004263]]>
4264 </programlisting>
4265 </informalexample>
4266 </para>
4267
4268 <para>
4269 The first argument is the card pointer, and the second is the
4270 index of this component. You can create up to 8 rawmidi
4271 devices.
4272 </para>
4273
4274 <para>
4275 The third argument is the type of the hardware,
4276 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4277 you can use <constant>MPU401_HW_MPU401</constant>.
4278 </para>
4279
4280 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004281 The 4th argument is the I/O port address. Many
4282 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4283 might be a part of its own PCI I/O region. It depends on the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004284 chip design.
4285 </para>
4286
4287 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004288 The 5th argument is a bitflag for additional information.
4289 When the I/O port address above is part of the PCI I/O
4290 region, the MPU401 I/O port might have been already allocated
Takashi Iwai302e4c22006-05-23 13:24:30 +02004291 (reserved) by the driver itself. In such a case, pass a bit flag
4292 <constant>MPU401_INFO_INTEGRATED</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004293 and the mpu401-uart layer will allocate the I/O ports by itself.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004294 </para>
4295
Takashi Iwai302e4c22006-05-23 13:24:30 +02004296 <para>
4297 When the controller supports only the input or output MIDI stream,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004298 pass the <constant>MPU401_INFO_INPUT</constant> or
Takashi Iwai302e4c22006-05-23 13:24:30 +02004299 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4300 Then the rawmidi instance is created as a single stream.
4301 </para>
4302
4303 <para>
4304 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4305 the access method to MMIO (via readb and writeb) instead of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004306 iob and outb. In this case, you have to pass the iomapped address
Takashi Iwai302e4c22006-05-23 13:24:30 +02004307 to <function>snd_mpu401_uart_new()</function>.
4308 </para>
4309
4310 <para>
4311 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4312 stream isn't checked in the default interrupt handler. The driver
4313 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004314 by itself to start processing the output stream in the irq handler.
Takashi Iwai302e4c22006-05-23 13:24:30 +02004315 </para>
4316
Clemens Ladischdba8b462011-09-13 11:24:41 +02004317 <para>
4318 If the MPU-401 interface shares its interrupt with the other logical
4319 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4320 (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4321 below</citetitle></link>).
4322 </para>
4323
Linus Torvalds1da177e2005-04-16 15:20:36 -07004324 <para>
4325 Usually, the port address corresponds to the command port and
4326 port + 1 corresponds to the data port. If not, you may change
4327 the <structfield>cport</structfield> field of
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004328 struct <structname>snd_mpu401</structname> manually
4329 afterward. However, <structname>snd_mpu401</structname> pointer is not
Linus Torvalds1da177e2005-04-16 15:20:36 -07004330 returned explicitly by
4331 <function>snd_mpu401_uart_new()</function>. You need to cast
4332 rmidi-&gt;private_data to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004333 <structname>snd_mpu401</structname> explicitly,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004334
4335 <informalexample>
4336 <programlisting>
4337<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004338 struct snd_mpu401 *mpu;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004339 mpu = rmidi->private_data;
4340]]>
4341 </programlisting>
4342 </informalexample>
4343
4344 and reset the cport as you like:
4345
4346 <informalexample>
4347 <programlisting>
4348<![CDATA[
4349 mpu->cport = my_own_control_port;
4350]]>
4351 </programlisting>
4352 </informalexample>
4353 </para>
4354
4355 <para>
Clemens Ladischdba8b462011-09-13 11:24:41 +02004356 The 6th argument specifies the ISA irq number that will be
4357 allocated. If no interrupt is to be allocated (because your
4358 code is already allocating a shared interrupt, or because the
4359 device does not use interrupts), pass -1 instead.
4360 For a MPU-401 device without an interrupt, a polling timer
4361 will be used instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004362 </para>
4363 </section>
4364
4365 <section id="midi-interface-interrupt-handler">
4366 <title>Interrupt Handler</title>
4367 <para>
4368 When the interrupt is allocated in
Clemens Ladischdba8b462011-09-13 11:24:41 +02004369 <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4370 interrupt handler is automatically used, hence you don't have
4371 anything else to do than creating the mpu401 stuff. Otherwise, you
4372 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4373 <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4374 own interrupt handler when it has determined that a UART interrupt
4375 has occurred.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004376 </para>
4377
4378 <para>
4379 In this case, you need to pass the private_data of the
4380 returned rawmidi object from
4381 <function>snd_mpu401_uart_new()</function> as the second
4382 argument of <function>snd_mpu401_uart_interrupt()</function>.
4383
4384 <informalexample>
4385 <programlisting>
4386<![CDATA[
4387 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4388]]>
4389 </programlisting>
4390 </informalexample>
4391 </para>
4392 </section>
4393
4394 </chapter>
4395
4396
4397<!-- ****************************************************** -->
4398<!-- RawMIDI Interface -->
4399<!-- ****************************************************** -->
4400 <chapter id="rawmidi-interface">
4401 <title>RawMIDI Interface</title>
4402
4403 <section id="rawmidi-interface-overview">
4404 <title>Overview</title>
4405
4406 <para>
4407 The raw MIDI interface is used for hardware MIDI ports that can
4408 be accessed as a byte stream. It is not used for synthesizer
4409 chips that do not directly understand MIDI.
4410 </para>
4411
4412 <para>
4413 ALSA handles file and buffer management. All you have to do is
4414 to write some code to move data between the buffer and the
4415 hardware.
4416 </para>
4417
4418 <para>
4419 The rawmidi API is defined in
4420 <filename>&lt;sound/rawmidi.h&gt;</filename>.
4421 </para>
4422 </section>
4423
4424 <section id="rawmidi-interface-constructor">
4425 <title>Constructor</title>
4426
4427 <para>
4428 To create a rawmidi device, call the
4429 <function>snd_rawmidi_new</function> function:
4430 <informalexample>
4431 <programlisting>
4432<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004433 struct snd_rawmidi *rmidi;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004434 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4435 if (err < 0)
4436 return err;
4437 rmidi->private_data = chip;
4438 strcpy(rmidi->name, "My MIDI");
4439 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4440 SNDRV_RAWMIDI_INFO_INPUT |
4441 SNDRV_RAWMIDI_INFO_DUPLEX;
4442]]>
4443 </programlisting>
4444 </informalexample>
4445 </para>
4446
4447 <para>
4448 The first argument is the card pointer, the second argument is
4449 the ID string.
4450 </para>
4451
4452 <para>
4453 The third argument is the index of this component. You can
4454 create up to 8 rawmidi devices.
4455 </para>
4456
4457 <para>
4458 The fourth and fifth arguments are the number of output and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004459 input substreams, respectively, of this device (a substream is
4460 the equivalent of a MIDI port).
Linus Torvalds1da177e2005-04-16 15:20:36 -07004461 </para>
4462
4463 <para>
4464 Set the <structfield>info_flags</structfield> field to specify
4465 the capabilities of the device.
4466 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4467 at least one output port,
4468 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4469 least one input port,
4470 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4471 can handle output and input at the same time.
4472 </para>
4473
4474 <para>
4475 After the rawmidi device is created, you need to set the
4476 operators (callbacks) for each substream. There are helper
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004477 functions to set the operators for all the substreams of a device:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004478 <informalexample>
4479 <programlisting>
4480<![CDATA[
4481 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4482 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4483]]>
4484 </programlisting>
4485 </informalexample>
4486 </para>
4487
4488 <para>
4489 The operators are usually defined like this:
4490 <informalexample>
4491 <programlisting>
4492<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004493 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004494 .open = snd_mymidi_output_open,
4495 .close = snd_mymidi_output_close,
4496 .trigger = snd_mymidi_output_trigger,
4497 };
4498]]>
4499 </programlisting>
4500 </informalexample>
4501 These callbacks are explained in the <link
4502 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4503 section.
4504 </para>
4505
4506 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004507 If there are more than one substream, you should give a
4508 unique name to each of them:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004509 <informalexample>
4510 <programlisting>
4511<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004512 struct snd_rawmidi_substream *substream;
Takashi Iwai95a5b082007-07-26 16:50:09 +02004513 list_for_each_entry(substream,
4514 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4515 list {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004516 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4517 }
4518 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4519]]>
4520 </programlisting>
4521 </informalexample>
4522 </para>
4523 </section>
4524
4525 <section id="rawmidi-interface-callbacks">
4526 <title>Callbacks</title>
4527
4528 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004529 In all the callbacks, the private data that you've set for the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004530 rawmidi device can be accessed as
4531 substream-&gt;rmidi-&gt;private_data.
4532 <!-- <code> isn't available before DocBook 4.3 -->
4533 </para>
4534
4535 <para>
4536 If there is more than one port, your callbacks can determine the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004537 port index from the struct snd_rawmidi_substream data passed to each
Linus Torvalds1da177e2005-04-16 15:20:36 -07004538 callback:
4539 <informalexample>
4540 <programlisting>
4541<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004542 struct snd_rawmidi_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004543 int index = substream->number;
4544]]>
4545 </programlisting>
4546 </informalexample>
4547 </para>
4548
4549 <section id="rawmidi-interface-op-open">
4550 <title><function>open</function> callback</title>
4551
4552 <informalexample>
4553 <programlisting>
4554<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004555 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004556]]>
4557 </programlisting>
4558 </informalexample>
4559
4560 <para>
4561 This is called when a substream is opened.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004562 You can initialize the hardware here, but you shouldn't
4563 start transmitting/receiving data yet.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004564 </para>
4565 </section>
4566
4567 <section id="rawmidi-interface-op-close">
4568 <title><function>close</function> callback</title>
4569
4570 <informalexample>
4571 <programlisting>
4572<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004573 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004574]]>
4575 </programlisting>
4576 </informalexample>
4577
4578 <para>
4579 Guess what.
4580 </para>
4581
4582 <para>
4583 The <function>open</function> and <function>close</function>
4584 callbacks of a rawmidi device are serialized with a mutex,
4585 and can sleep.
4586 </para>
4587 </section>
4588
4589 <section id="rawmidi-interface-op-trigger-out">
4590 <title><function>trigger</function> callback for output
4591 substreams</title>
4592
4593 <informalexample>
4594 <programlisting>
4595<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004596 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004597]]>
4598 </programlisting>
4599 </informalexample>
4600
4601 <para>
4602 This is called with a nonzero <parameter>up</parameter>
4603 parameter when there is some data in the substream buffer that
4604 must be transmitted.
4605 </para>
4606
4607 <para>
4608 To read data from the buffer, call
4609 <function>snd_rawmidi_transmit_peek</function>. It will
4610 return the number of bytes that have been read; this will be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004611 less than the number of bytes requested when there are no more
Linus Torvalds1da177e2005-04-16 15:20:36 -07004612 data in the buffer.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004613 After the data have been transmitted successfully, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004614 <function>snd_rawmidi_transmit_ack</function> to remove the
4615 data from the substream buffer:
4616 <informalexample>
4617 <programlisting>
4618<![CDATA[
4619 unsigned char data;
4620 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004621 if (snd_mychip_try_to_transmit(data))
Linus Torvalds1da177e2005-04-16 15:20:36 -07004622 snd_rawmidi_transmit_ack(substream, 1);
4623 else
4624 break; /* hardware FIFO full */
4625 }
4626]]>
4627 </programlisting>
4628 </informalexample>
4629 </para>
4630
4631 <para>
4632 If you know beforehand that the hardware will accept data, you
4633 can use the <function>snd_rawmidi_transmit</function> function
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004634 which reads some data and removes them from the buffer at once:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004635 <informalexample>
4636 <programlisting>
4637<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004638 while (snd_mychip_transmit_possible()) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004639 unsigned char data;
4640 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4641 break; /* no more data */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004642 snd_mychip_transmit(data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004643 }
4644]]>
4645 </programlisting>
4646 </informalexample>
4647 </para>
4648
4649 <para>
4650 If you know beforehand how many bytes you can accept, you can
4651 use a buffer size greater than one with the
4652 <function>snd_rawmidi_transmit*</function> functions.
4653 </para>
4654
4655 <para>
4656 The <function>trigger</function> callback must not sleep. If
4657 the hardware FIFO is full before the substream buffer has been
4658 emptied, you have to continue transmitting data later, either
4659 in an interrupt handler, or with a timer if the hardware
4660 doesn't have a MIDI transmit interrupt.
4661 </para>
4662
4663 <para>
4664 The <function>trigger</function> callback is called with a
4665 zero <parameter>up</parameter> parameter when the transmission
4666 of data should be aborted.
4667 </para>
4668 </section>
4669
4670 <section id="rawmidi-interface-op-trigger-in">
4671 <title><function>trigger</function> callback for input
4672 substreams</title>
4673
4674 <informalexample>
4675 <programlisting>
4676<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004677 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004678]]>
4679 </programlisting>
4680 </informalexample>
4681
4682 <para>
4683 This is called with a nonzero <parameter>up</parameter>
4684 parameter to enable receiving data, or with a zero
4685 <parameter>up</parameter> parameter do disable receiving data.
4686 </para>
4687
4688 <para>
4689 The <function>trigger</function> callback must not sleep; the
4690 actual reading of data from the device is usually done in an
4691 interrupt handler.
4692 </para>
4693
4694 <para>
4695 When data reception is enabled, your interrupt handler should
4696 call <function>snd_rawmidi_receive</function> for all received
4697 data:
4698 <informalexample>
4699 <programlisting>
4700<![CDATA[
4701 void snd_mychip_midi_interrupt(...)
4702 {
4703 while (mychip_midi_available()) {
4704 unsigned char data;
4705 data = mychip_midi_read();
4706 snd_rawmidi_receive(substream, &data, 1);
4707 }
4708 }
4709]]>
4710 </programlisting>
4711 </informalexample>
4712 </para>
4713 </section>
4714
4715 <section id="rawmidi-interface-op-drain">
4716 <title><function>drain</function> callback</title>
4717
4718 <informalexample>
4719 <programlisting>
4720<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004721 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004722]]>
4723 </programlisting>
4724 </informalexample>
4725
4726 <para>
4727 This is only used with output substreams. This function should wait
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004728 until all data read from the substream buffer have been transmitted.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004729 This ensures that the device can be closed and the driver unloaded
4730 without losing data.
4731 </para>
4732
4733 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004734 This callback is optional. If you do not set
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004735 <structfield>drain</structfield> in the struct snd_rawmidi_ops
Linus Torvalds1da177e2005-04-16 15:20:36 -07004736 structure, ALSA will simply wait for 50&nbsp;milliseconds
4737 instead.
4738 </para>
4739 </section>
4740 </section>
4741
4742 </chapter>
4743
4744
4745<!-- ****************************************************** -->
4746<!-- Miscellaneous Devices -->
4747<!-- ****************************************************** -->
4748 <chapter id="misc-devices">
4749 <title>Miscellaneous Devices</title>
4750
4751 <section id="misc-devices-opl3">
4752 <title>FM OPL3</title>
4753 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004754 The FM OPL3 is still used in many chips (mainly for backward
Linus Torvalds1da177e2005-04-16 15:20:36 -07004755 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4756 OPL3 API is defined in
4757 <filename>&lt;sound/opl3.h&gt;</filename>.
4758 </para>
4759
4760 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004761 FM registers can be directly accessed through the direct-FM API,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004762 defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4763 ALSA native mode, FM registers are accessed through
Lucas De Marchi25985ed2011-03-30 22:57:33 -03004764 the Hardware-Dependent Device direct-FM extension API, whereas in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004765 OSS compatible mode, FM registers can be accessed with the OSS
4766 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004767 </para>
4768
4769 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004770 To create the OPL3 component, you have two functions to
4771 call. The first one is a constructor for the <type>opl3_t</type>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004772 instance.
4773
4774 <informalexample>
4775 <programlisting>
4776<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004777 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004778 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4779 integrated, &opl3);
4780]]>
4781 </programlisting>
4782 </informalexample>
4783 </para>
4784
4785 <para>
4786 The first argument is the card pointer, the second one is the
4787 left port address, and the third is the right port address. In
4788 most cases, the right port is placed at the left port + 2.
4789 </para>
4790
4791 <para>
4792 The fourth argument is the hardware type.
4793 </para>
4794
4795 <para>
4796 When the left and right ports have been already allocated by
4797 the card driver, pass non-zero to the fifth argument
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004798 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
Linus Torvalds1da177e2005-04-16 15:20:36 -07004799 allocate the specified ports by itself.
4800 </para>
4801
4802 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004803 When the accessing the hardware requires special method
Linus Torvalds1da177e2005-04-16 15:20:36 -07004804 instead of the standard I/O access, you can create opl3 instance
4805 separately with <function>snd_opl3_new()</function>.
4806
4807 <informalexample>
4808 <programlisting>
4809<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004810 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004811 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4812]]>
4813 </programlisting>
4814 </informalexample>
4815 </para>
4816
4817 <para>
4818 Then set <structfield>command</structfield>,
4819 <structfield>private_data</structfield> and
4820 <structfield>private_free</structfield> for the private
4821 access function, the private data and the destructor.
4822 The l_port and r_port are not necessarily set. Only the
4823 command must be set properly. You can retrieve the data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004824 from the opl3-&gt;private_data field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004825 </para>
4826
4827 <para>
4828 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4829 call <function>snd_opl3_init()</function> to initialize the chip to the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004830 proper state. Note that <function>snd_opl3_create()</function> always
Linus Torvalds1da177e2005-04-16 15:20:36 -07004831 calls it internally.
4832 </para>
4833
4834 <para>
4835 If the opl3 instance is created successfully, then create a
4836 hwdep device for this opl3.
4837
4838 <informalexample>
4839 <programlisting>
4840<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004841 struct snd_hwdep *opl3hwdep;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004842 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4843]]>
4844 </programlisting>
4845 </informalexample>
4846 </para>
4847
4848 <para>
4849 The first argument is the <type>opl3_t</type> instance you
4850 created, and the second is the index number, usually 0.
4851 </para>
4852
4853 <para>
4854 The third argument is the index-offset for the sequencer
4855 client assigned to the OPL3 port. When there is an MPU401-UART,
4856 give 1 for here (UART always takes 0).
4857 </para>
4858 </section>
4859
4860 <section id="misc-devices-hardware-dependent">
4861 <title>Hardware-Dependent Devices</title>
4862 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004863 Some chips need user-space access for special
Linus Torvalds1da177e2005-04-16 15:20:36 -07004864 controls or for loading the micro code. In such a case, you can
4865 create a hwdep (hardware-dependent) device. The hwdep API is
4866 defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4867 find examples in opl3 driver or
4868 <filename>isa/sb/sb16_csp.c</filename>.
4869 </para>
4870
4871 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004872 The creation of the <type>hwdep</type> instance is done via
Linus Torvalds1da177e2005-04-16 15:20:36 -07004873 <function>snd_hwdep_new()</function>.
4874
4875 <informalexample>
4876 <programlisting>
4877<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004878 struct snd_hwdep *hw;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004879 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4880]]>
4881 </programlisting>
4882 </informalexample>
4883
4884 where the third argument is the index number.
4885 </para>
4886
4887 <para>
4888 You can then pass any pointer value to the
4889 <parameter>private_data</parameter>.
4890 If you assign a private data, you should define the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004891 destructor, too. The destructor function is set in
4892 the <structfield>private_free</structfield> field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004893
4894 <informalexample>
4895 <programlisting>
4896<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004897 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004898 hw->private_data = p;
4899 hw->private_free = mydata_free;
4900]]>
4901 </programlisting>
4902 </informalexample>
4903
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004904 and the implementation of the destructor would be:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004905
4906 <informalexample>
4907 <programlisting>
4908<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004909 static void mydata_free(struct snd_hwdep *hw)
Linus Torvalds1da177e2005-04-16 15:20:36 -07004910 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004911 struct mydata *p = hw->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004912 kfree(p);
4913 }
4914]]>
4915 </programlisting>
4916 </informalexample>
4917 </para>
4918
4919 <para>
4920 The arbitrary file operations can be defined for this
4921 instance. The file operators are defined in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004922 the <parameter>ops</parameter> table. For example, assume that
Linus Torvalds1da177e2005-04-16 15:20:36 -07004923 this chip needs an ioctl.
4924
4925 <informalexample>
4926 <programlisting>
4927<![CDATA[
4928 hw->ops.open = mydata_open;
4929 hw->ops.ioctl = mydata_ioctl;
4930 hw->ops.release = mydata_release;
4931]]>
4932 </programlisting>
4933 </informalexample>
4934
4935 And implement the callback functions as you like.
4936 </para>
4937 </section>
4938
4939 <section id="misc-devices-IEC958">
4940 <title>IEC958 (S/PDIF)</title>
4941 <para>
4942 Usually the controls for IEC958 devices are implemented via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004943 the control interface. There is a macro to compose a name string for
Linus Torvalds1da177e2005-04-16 15:20:36 -07004944 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4945 defined in <filename>&lt;include/asound.h&gt;</filename>.
4946 </para>
4947
4948 <para>
4949 There are some standard controls for IEC958 status bits. These
4950 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4951 and the size of element is fixed as 4 bytes array
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004952 (value.iec958.status[x]). For the <structfield>info</structfield>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004953 callback, you don't specify
4954 the value field for this type (the count field must be set,
4955 though).
4956 </para>
4957
4958 <para>
4959 <quote>IEC958 Playback Con Mask</quote> is used to return the
4960 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4961 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4962 professional mode. They are read-only controls, and are defined
4963 as MIXER controls (iface =
4964 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4965 </para>
4966
4967 <para>
4968 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4969 defined for getting and setting the current default IEC958
4970 bits. Note that this one is usually defined as a PCM control
4971 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4972 although in some places it's defined as a MIXER control.
4973 </para>
4974
4975 <para>
4976 In addition, you can define the control switches to
4977 enable/disable or to set the raw bit mode. The implementation
4978 will depend on the chip, but the control should be named as
4979 <quote>IEC958 xxx</quote>, preferably using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004980 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004981 </para>
4982
4983 <para>
4984 You can find several cases, for example,
4985 <filename>pci/emu10k1</filename>,
4986 <filename>pci/ice1712</filename>, or
4987 <filename>pci/cmipci.c</filename>.
4988 </para>
4989 </section>
4990
4991 </chapter>
4992
4993
4994<!-- ****************************************************** -->
4995<!-- Buffer and Memory Management -->
4996<!-- ****************************************************** -->
4997 <chapter id="buffer-and-memory">
4998 <title>Buffer and Memory Management</title>
4999
5000 <section id="buffer-and-memory-buffer-types">
5001 <title>Buffer Types</title>
5002 <para>
5003 ALSA provides several different buffer allocation functions
5004 depending on the bus and the architecture. All these have a
5005 consistent API. The allocation of physically-contiguous pages is
5006 done via
5007 <function>snd_malloc_xxx_pages()</function> function, where xxx
5008 is the bus type.
5009 </para>
5010
5011 <para>
5012 The allocation of pages with fallback is
5013 <function>snd_malloc_xxx_pages_fallback()</function>. This
5014 function tries to allocate the specified pages but if the pages
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005015 are not available, it tries to reduce the page sizes until
Linus Torvalds1da177e2005-04-16 15:20:36 -07005016 enough space is found.
5017 </para>
5018
5019 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005020 The release the pages, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005021 <function>snd_free_xxx_pages()</function> function.
5022 </para>
5023
5024 <para>
5025 Usually, ALSA drivers try to allocate and reserve
5026 a large contiguous physical space
5027 at the time the module is loaded for the later use.
5028 This is called <quote>pre-allocation</quote>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005029 As already written, you can call the following function at
5030 pcm instance construction time (in the case of PCI bus).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005031
5032 <informalexample>
5033 <programlisting>
5034<![CDATA[
5035 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5036 snd_dma_pci_data(pci), size, max);
5037]]>
5038 </programlisting>
5039 </informalexample>
5040
5041 where <parameter>size</parameter> is the byte size to be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005042 pre-allocated and the <parameter>max</parameter> is the maximum
5043 size to be changed via the <filename>prealloc</filename> proc file.
5044 The allocator will try to get an area as large as possible
Linus Torvalds1da177e2005-04-16 15:20:36 -07005045 within the given size.
5046 </para>
5047
5048 <para>
5049 The second argument (type) and the third argument (device pointer)
5050 are dependent on the bus.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005051 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005052 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5053 For the continuous buffer unrelated to the bus can be pre-allocated
5054 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5055 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005056 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
David S. Miller759ee812008-08-27 00:33:26 -07005057 use.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005058 For the PCI scatter-gather buffers, use
5059 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5060 <function>snd_dma_pci_data(pci)</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005061 (see the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005062 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005063 </citetitle></link> section).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005064 </para>
5065
5066 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005067 Once the buffer is pre-allocated, you can use the
5068 allocator in the <structfield>hw_params</structfield> callback:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005069
5070 <informalexample>
5071 <programlisting>
5072<![CDATA[
5073 snd_pcm_lib_malloc_pages(substream, size);
5074]]>
5075 </programlisting>
5076 </informalexample>
5077
5078 Note that you have to pre-allocate to use this function.
5079 </para>
5080 </section>
5081
5082 <section id="buffer-and-memory-external-hardware">
5083 <title>External Hardware Buffers</title>
5084 <para>
5085 Some chips have their own hardware buffers and the DMA
5086 transfer from the host memory is not available. In such a case,
5087 you need to either 1) copy/set the audio data directly to the
5088 external hardware buffer, or 2) make an intermediate buffer and
5089 copy/set the data from it to the external hardware buffer in
5090 interrupts (or in tasklets, preferably).
5091 </para>
5092
5093 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005094 The first case works fine if the external hardware buffer is large
5095 enough. This method doesn't need any extra buffers and thus is
Linus Torvalds1da177e2005-04-16 15:20:36 -07005096 more effective. You need to define the
5097 <structfield>copy</structfield> and
5098 <structfield>silence</structfield> callbacks for
5099 the data transfer. However, there is a drawback: it cannot
5100 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5101 wavetable PCM.
5102 </para>
5103
5104 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005105 The second case allows for mmap on the buffer, although you have
5106 to handle an interrupt or a tasklet to transfer the data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005107 from the intermediate buffer to the hardware buffer. You can find an
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005108 example in the vxpocket driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005109 </para>
5110
5111 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005112 Another case is when the chip uses a PCI memory-map
Linus Torvalds1da177e2005-04-16 15:20:36 -07005113 region for the buffer instead of the host memory. In this case,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005114 mmap is available only on certain architectures like the Intel one.
5115 In non-mmap mode, the data cannot be transferred as in the normal
5116 way. Thus you need to define the <structfield>copy</structfield> and
5117 <structfield>silence</structfield> callbacks as well,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005118 as in the cases above. The examples are found in
5119 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5120 </para>
5121
5122 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005123 The implementation of the <structfield>copy</structfield> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07005124 <structfield>silence</structfield> callbacks depends upon
5125 whether the hardware supports interleaved or non-interleaved
5126 samples. The <structfield>copy</structfield> callback is
5127 defined like below, a bit
5128 differently depending whether the direction is playback or
5129 capture:
5130
5131 <informalexample>
5132 <programlisting>
5133<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005134 static int playback_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005135 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005136 static int capture_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005137 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5138]]>
5139 </programlisting>
5140 </informalexample>
5141 </para>
5142
5143 <para>
5144 In the case of interleaved samples, the second argument
5145 (<parameter>channel</parameter>) is not used. The third argument
5146 (<parameter>pos</parameter>) points the
5147 current position offset in frames.
5148 </para>
5149
5150 <para>
5151 The meaning of the fourth argument is different between
5152 playback and capture. For playback, it holds the source data
5153 pointer, and for capture, it's the destination data pointer.
5154 </para>
5155
5156 <para>
5157 The last argument is the number of frames to be copied.
5158 </para>
5159
5160 <para>
5161 What you have to do in this callback is again different
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005162 between playback and capture directions. In the
5163 playback case, you copy the given amount of data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005164 (<parameter>count</parameter>) at the specified pointer
5165 (<parameter>src</parameter>) to the specified offset
5166 (<parameter>pos</parameter>) on the hardware buffer. When
5167 coded like memcpy-like way, the copy would be like:
5168
5169 <informalexample>
5170 <programlisting>
5171<![CDATA[
5172 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5173 frames_to_bytes(runtime, count));
5174]]>
5175 </programlisting>
5176 </informalexample>
5177 </para>
5178
5179 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005180 For the capture direction, you copy the given amount of
Linus Torvalds1da177e2005-04-16 15:20:36 -07005181 data (<parameter>count</parameter>) at the specified offset
5182 (<parameter>pos</parameter>) on the hardware buffer to the
5183 specified pointer (<parameter>dst</parameter>).
5184
5185 <informalexample>
5186 <programlisting>
5187<![CDATA[
5188 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5189 frames_to_bytes(runtime, count));
5190]]>
5191 </programlisting>
5192 </informalexample>
5193
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005194 Note that both the position and the amount of data are given
Linus Torvalds1da177e2005-04-16 15:20:36 -07005195 in frames.
5196 </para>
5197
5198 <para>
5199 In the case of non-interleaved samples, the implementation
5200 will be a bit more complicated.
5201 </para>
5202
5203 <para>
5204 You need to check the channel argument, and if it's -1, copy
5205 the whole channels. Otherwise, you have to copy only the
5206 specified channel. Please check
5207 <filename>isa/gus/gus_pcm.c</filename> as an example.
5208 </para>
5209
5210 <para>
5211 The <structfield>silence</structfield> callback is also
5212 implemented in a similar way.
5213
5214 <informalexample>
5215 <programlisting>
5216<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005217 static int silence(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005218 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5219]]>
5220 </programlisting>
5221 </informalexample>
5222 </para>
5223
5224 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005225 The meanings of arguments are the same as in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005226 <structfield>copy</structfield>
5227 callback, although there is no <parameter>src/dst</parameter>
5228 argument. In the case of interleaved samples, the channel
5229 argument has no meaning, as well as on
5230 <structfield>copy</structfield> callback.
5231 </para>
5232
5233 <para>
5234 The role of <structfield>silence</structfield> callback is to
5235 set the given amount
5236 (<parameter>count</parameter>) of silence data at the
5237 specified offset (<parameter>pos</parameter>) on the hardware
5238 buffer. Suppose that the data format is signed (that is, the
5239 silent-data is 0), and the implementation using a memset-like
5240 function would be like:
5241
5242 <informalexample>
5243 <programlisting>
5244<![CDATA[
5245 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5246 frames_to_bytes(runtime, count));
5247]]>
5248 </programlisting>
5249 </informalexample>
5250 </para>
5251
5252 <para>
5253 In the case of non-interleaved samples, again, the
5254 implementation becomes a bit more complicated. See, for example,
5255 <filename>isa/gus/gus_pcm.c</filename>.
5256 </para>
5257 </section>
5258
5259 <section id="buffer-and-memory-non-contiguous">
5260 <title>Non-Contiguous Buffers</title>
5261 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005262 If your hardware supports the page table as in emu10k1 or the
5263 buffer descriptors as in via82xx, you can use the scatter-gather
Linus Torvalds1da177e2005-04-16 15:20:36 -07005264 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5265 The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
5266 </para>
5267
5268 <para>
5269 For creating the SG-buffer handler, call
5270 <function>snd_pcm_lib_preallocate_pages()</function> or
5271 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5272 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5273 in the PCM constructor like other PCI pre-allocator.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005274 You need to pass <function>snd_dma_pci_data(pci)</function>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005275 where pci is the struct <structname>pci_dev</structname> pointer
5276 of the chip as well.
Giuliano Pochini44275f12006-01-27 12:02:05 +01005277 The <type>struct snd_sg_buf</type> instance is created as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005278 substream-&gt;dma_private. You can cast
5279 the pointer like:
5280
5281 <informalexample>
5282 <programlisting>
5283<![CDATA[
Giuliano Pochini44275f12006-01-27 12:02:05 +01005284 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005285]]>
5286 </programlisting>
5287 </informalexample>
5288 </para>
5289
5290 <para>
5291 Then call <function>snd_pcm_lib_malloc_pages()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005292 in the <structfield>hw_params</structfield> callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07005293 as well as in the case of normal PCI buffer.
5294 The SG-buffer handler will allocate the non-contiguous kernel
5295 pages of the given size and map them onto the virtually contiguous
5296 memory. The virtual pointer is addressed in runtime-&gt;dma_area.
5297 The physical address (runtime-&gt;dma_addr) is set to zero,
André Goddard Rosaaf901ca2009-11-14 13:09:05 -02005298 because the buffer is physically non-contiguous.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005299 The physical address table is set up in sgbuf-&gt;table.
5300 You can get the physical address at a certain offset via
5301 <function>snd_pcm_sgbuf_get_addr()</function>.
5302 </para>
5303
5304 <para>
5305 When a SG-handler is used, you need to set
5306 <function>snd_pcm_sgbuf_ops_page</function> as
5307 the <structfield>page</structfield> callback.
5308 (See <link linkend="pcm-interface-operators-page-callback">
5309 <citetitle>page callback section</citetitle></link>.)
5310 </para>
5311
5312 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005313 To release the data, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005314 <function>snd_pcm_lib_free_pages()</function> in the
5315 <structfield>hw_free</structfield> callback as usual.
5316 </para>
5317 </section>
5318
5319 <section id="buffer-and-memory-vmalloced">
5320 <title>Vmalloc'ed Buffers</title>
5321 <para>
5322 It's possible to use a buffer allocated via
5323 <function>vmalloc</function>, for example, for an intermediate
5324 buffer. Since the allocated pages are not contiguous, you need
5325 to set the <structfield>page</structfield> callback to obtain
5326 the physical address at every offset.
5327 </para>
5328
5329 <para>
5330 The implementation of <structfield>page</structfield> callback
5331 would be like this:
5332
5333 <informalexample>
5334 <programlisting>
5335<![CDATA[
5336 #include <linux/vmalloc.h>
5337
5338 /* get the physical page pointer on the given offset */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005339 static struct page *mychip_page(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005340 unsigned long offset)
5341 {
5342 void *pageptr = substream->runtime->dma_area + offset;
5343 return vmalloc_to_page(pageptr);
5344 }
5345]]>
5346 </programlisting>
5347 </informalexample>
5348 </para>
5349 </section>
5350
5351 </chapter>
5352
5353
5354<!-- ****************************************************** -->
5355<!-- Proc Interface -->
5356<!-- ****************************************************** -->
5357 <chapter id="proc-interface">
5358 <title>Proc Interface</title>
5359 <para>
5360 ALSA provides an easy interface for procfs. The proc files are
5361 very useful for debugging. I recommend you set up proc files if
5362 you write a driver and want to get a running status or register
5363 dumps. The API is found in
5364 <filename>&lt;sound/info.h&gt;</filename>.
5365 </para>
5366
5367 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005368 To create a proc file, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005369 <function>snd_card_proc_new()</function>.
5370
5371 <informalexample>
5372 <programlisting>
5373<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005374 struct snd_info_entry *entry;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005375 int err = snd_card_proc_new(card, "my-file", &entry);
5376]]>
5377 </programlisting>
5378 </informalexample>
5379
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005380 where the second argument specifies the name of the proc file to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005381 created. The above example will create a file
5382 <filename>my-file</filename> under the card directory,
5383 e.g. <filename>/proc/asound/card0/my-file</filename>.
5384 </para>
5385
5386 <para>
5387 Like other components, the proc entry created via
5388 <function>snd_card_proc_new()</function> will be registered and
5389 released automatically in the card registration and release
5390 functions.
5391 </para>
5392
5393 <para>
5394 When the creation is successful, the function stores a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005395 instance in the pointer given in the third argument.
5396 It is initialized as a text proc file for read only. To use
Linus Torvalds1da177e2005-04-16 15:20:36 -07005397 this proc file as a read-only text file as it is, set the read
5398 callback with a private data via
5399 <function>snd_info_set_text_ops()</function>.
5400
5401 <informalexample>
5402 <programlisting>
5403<![CDATA[
Takashi Iwaibf850202006-04-28 15:13:41 +02005404 snd_info_set_text_ops(entry, chip, my_proc_read);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005405]]>
5406 </programlisting>
5407 </informalexample>
5408
5409 where the second argument (<parameter>chip</parameter>) is the
5410 private data to be used in the callbacks. The third parameter
5411 specifies the read buffer size and the fourth
5412 (<parameter>my_proc_read</parameter>) is the callback function, which
5413 is defined like
5414
5415 <informalexample>
5416 <programlisting>
5417<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005418 static void my_proc_read(struct snd_info_entry *entry,
5419 struct snd_info_buffer *buffer);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005420]]>
5421 </programlisting>
5422 </informalexample>
5423
5424 </para>
5425
5426 <para>
5427 In the read callback, use <function>snd_iprintf()</function> for
5428 output strings, which works just like normal
5429 <function>printf()</function>. For example,
5430
5431 <informalexample>
5432 <programlisting>
5433<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005434 static void my_proc_read(struct snd_info_entry *entry,
5435 struct snd_info_buffer *buffer)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005436 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005437 struct my_chip *chip = entry->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005438
5439 snd_iprintf(buffer, "This is my chip!\n");
5440 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5441 }
5442]]>
5443 </programlisting>
5444 </informalexample>
5445 </para>
5446
5447 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005448 The file permissions can be changed afterwards. As default, it's
5449 set as read only for all users. If you want to add write
5450 permission for the user (root as default), do as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005451
5452 <informalexample>
5453 <programlisting>
5454<![CDATA[
5455 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5456]]>
5457 </programlisting>
5458 </informalexample>
5459
5460 and set the write buffer size and the callback
5461
5462 <informalexample>
5463 <programlisting>
5464<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -07005465 entry->c.text.write = my_proc_write;
5466]]>
5467 </programlisting>
5468 </informalexample>
5469 </para>
5470
5471 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005472 For the write callback, you can use
5473 <function>snd_info_get_line()</function> to get a text line, and
5474 <function>snd_info_get_str()</function> to retrieve a string from
5475 the line. Some examples are found in
5476 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5477 <filename>pcm_oss.c</filename>.
5478 </para>
5479
5480 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005481 For a raw-data proc-file, set the attributes as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005482
5483 <informalexample>
5484 <programlisting>
5485<![CDATA[
5486 static struct snd_info_entry_ops my_file_io_ops = {
5487 .read = my_file_io_read,
5488 };
5489
5490 entry->content = SNDRV_INFO_CONTENT_DATA;
5491 entry->private_data = chip;
5492 entry->c.ops = &my_file_io_ops;
5493 entry->size = 4096;
5494 entry->mode = S_IFREG | S_IRUGO;
5495]]>
5496 </programlisting>
5497 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005498
5499 For the raw data, <structfield>size</structfield> field must be
5500 set properly. This specifies the maximum size of the proc file access.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005501 </para>
5502
5503 <para>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005504 The read/write callbacks of raw mode are more direct than the text mode.
5505 You need to use a low-level I/O functions such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005506 <function>copy_from/to_user()</function> to transfer the
5507 data.
5508
5509 <informalexample>
5510 <programlisting>
5511<![CDATA[
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005512 static ssize_t my_file_io_read(struct snd_info_entry *entry,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005513 void *file_private_data,
5514 struct file *file,
5515 char *buf,
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005516 size_t count,
5517 loff_t pos)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005518 {
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005519 if (copy_to_user(buf, local_data + pos, count))
Linus Torvalds1da177e2005-04-16 15:20:36 -07005520 return -EFAULT;
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005521 return count;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005522 }
5523]]>
5524 </programlisting>
5525 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005526
5527 If the size of the info entry has been set up properly,
5528 <structfield>count</structfield> and <structfield>pos</structfield> are
5529 guaranteed to fit within 0 and the given size.
5530 You don't have to check the range in the callbacks unless any
5531 other condition is required.
5532
Linus Torvalds1da177e2005-04-16 15:20:36 -07005533 </para>
5534
5535 </chapter>
5536
5537
5538<!-- ****************************************************** -->
5539<!-- Power Management -->
5540<!-- ****************************************************** -->
5541 <chapter id="power-management">
5542 <title>Power Management</title>
5543 <para>
Paolo Ornati670e9f32006-10-03 22:57:56 +02005544 If the chip is supposed to work with suspend/resume
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005545 functions, you need to add power-management code to the
5546 driver. The additional code for power-management should be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005547 <function>ifdef</function>'ed with
5548 <constant>CONFIG_PM</constant>.
5549 </para>
5550
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005551 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005552 If the driver <emphasis>fully</emphasis> supports suspend/resume
5553 that is, the device can be
5554 properly resumed to its state when suspend was called,
5555 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5556 in the pcm info field. Usually, this is possible when the
5557 registers of the chip can be safely saved and restored to
5558 RAM. If this is set, the trigger callback is called with
5559 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5560 callback completes.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005561 </para>
5562
5563 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005564 Even if the driver doesn't support PM fully but
5565 partial suspend/resume is still possible, it's still worthy to
5566 implement suspend/resume callbacks. In such a case, applications
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005567 would reset the status by calling
5568 <function>snd_pcm_prepare()</function> and restart the stream
5569 appropriately. Hence, you can define suspend/resume callbacks
5570 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5571 info flag to the PCM.
5572 </para>
5573
5574 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005575 Note that the trigger with SUSPEND can always be called when
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005576 <function>snd_pcm_suspend_all</function> is called,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005577 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005578 The <constant>RESUME</constant> flag affects only the behavior
5579 of <function>snd_pcm_resume()</function>.
5580 (Thus, in theory,
5581 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5582 to be handled in the trigger callback when no
5583 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005584 it's better to keep it for compatibility reasons.)
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005585 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005586 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005587 In the earlier version of ALSA drivers, a common
5588 power-management layer was provided, but it has been removed.
5589 The driver needs to define the suspend/resume hooks according to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005590 the bus the device is connected to. In the case of PCI drivers, the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005591 callbacks look like below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005592
5593 <informalexample>
5594 <programlisting>
5595<![CDATA[
5596 #ifdef CONFIG_PM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005597 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005598 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005599 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005600 return 0;
5601 }
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005602 static int snd_my_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005603 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005604 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005605 return 0;
5606 }
5607 #endif
5608]]>
5609 </programlisting>
5610 </informalexample>
5611 </para>
5612
5613 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005614 The scheme of the real suspend job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005615
5616 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005617 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5618 <listitem><para>Call <function>snd_power_change_state()</function> with
5619 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5620 power status.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005621 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005622 <listitem><para>If AC97 codecs are used, call
Takashi Iwaia7306332006-05-04 11:58:43 +02005623 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005624 <listitem><para>Save the register values if necessary.</para></listitem>
5625 <listitem><para>Stop the hardware if necessary.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005626 <listitem><para>Disable the PCI device by calling
5627 <function>pci_disable_device()</function>. Then, call
5628 <function>pci_save_state()</function> at last.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005629 </orderedlist>
5630 </para>
5631
5632 <para>
5633 A typical code would be like:
5634
5635 <informalexample>
5636 <programlisting>
5637<![CDATA[
Alexey Dobriyan323579882006-01-15 02:12:54 +01005638 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005639 {
5640 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005641 struct snd_card *card = pci_get_drvdata(pci);
5642 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005643 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005644 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005645 /* (3) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005646 snd_pcm_suspend_all(chip->pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005647 /* (4) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005648 snd_ac97_suspend(chip->ac97);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005649 /* (5) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005650 snd_mychip_save_registers(chip);
5651 /* (6) */
5652 snd_mychip_stop_hardware(chip);
5653 /* (7) */
5654 pci_disable_device(pci);
5655 pci_save_state(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005656 return 0;
5657 }
5658]]>
5659 </programlisting>
5660 </informalexample>
5661 </para>
5662
5663 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005664 The scheme of the real resume job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005665
5666 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005667 <listitem><para>Retrieve the card and the chip data.</para></listitem>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005668 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005669 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5670 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005671 <listitem><para>Re-initialize the chip.</para></listitem>
5672 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5673 <listitem><para>Resume the mixer, e.g. calling
5674 <function>snd_ac97_resume()</function>.</para></listitem>
5675 <listitem><para>Restart the hardware (if any).</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005676 <listitem><para>Call <function>snd_power_change_state()</function> with
5677 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005678 </orderedlist>
5679 </para>
5680
5681 <para>
5682 A typical code would be like:
5683
5684 <informalexample>
5685 <programlisting>
5686<![CDATA[
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005687 static int mychip_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005688 {
5689 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005690 struct snd_card *card = pci_get_drvdata(pci);
5691 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005692 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005693 pci_restore_state(pci);
5694 pci_enable_device(pci);
5695 pci_set_master(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005696 /* (3) */
5697 snd_mychip_reinit_chip(chip);
5698 /* (4) */
5699 snd_mychip_restore_registers(chip);
5700 /* (5) */
5701 snd_ac97_resume(chip->ac97);
5702 /* (6) */
5703 snd_mychip_restart_chip(chip);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005704 /* (7) */
5705 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005706 return 0;
5707 }
5708]]>
5709 </programlisting>
5710 </informalexample>
5711 </para>
5712
5713 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005714 As shown in the above, it's better to save registers after
5715 suspending the PCM operations via
5716 <function>snd_pcm_suspend_all()</function> or
5717 <function>snd_pcm_suspend()</function>. It means that the PCM
5718 streams are already stoppped when the register snapshot is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005719 taken. But, remember that you don't have to restart the PCM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005720 stream in the resume callback. It'll be restarted via
5721 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5722 when necessary.
5723 </para>
5724
5725 <para>
5726 OK, we have all callbacks now. Let's set them up. In the
5727 initialization of the card, make sure that you can get the chip
5728 data from the card instance, typically via
5729 <structfield>private_data</structfield> field, in case you
5730 created the chip data individually.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005731
5732 <informalexample>
5733 <programlisting>
5734<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01005735 static int snd_mychip_probe(struct pci_dev *pci,
5736 const struct pci_device_id *pci_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005737 {
5738 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005739 struct snd_card *card;
5740 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005741 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005742 ....
Takashi Iwaid4533792008-12-28 16:45:34 +01005743 err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005744 ....
5745 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5746 ....
5747 card->private_data = chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005748 ....
5749 }
5750]]>
5751 </programlisting>
5752 </informalexample>
5753
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005754 When you created the chip data with
Takashi Iwaid4533792008-12-28 16:45:34 +01005755 <function>snd_card_create()</function>, it's anyway accessible
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005756 via <structfield>private_data</structfield> field.
5757
5758 <informalexample>
5759 <programlisting>
5760<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01005761 static int snd_mychip_probe(struct pci_dev *pci,
5762 const struct pci_device_id *pci_id)
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005763 {
5764 ....
5765 struct snd_card *card;
5766 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005767 int err;
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005768 ....
Takashi Iwaid4533792008-12-28 16:45:34 +01005769 err = snd_card_create(index[dev], id[dev], THIS_MODULE,
5770 sizeof(struct mychip), &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005771 ....
5772 chip = card->private_data;
5773 ....
5774 }
5775]]>
5776 </programlisting>
5777 </informalexample>
5778
Linus Torvalds1da177e2005-04-16 15:20:36 -07005779 </para>
5780
5781 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005782 If you need a space to save the registers, allocate the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005783 buffer for it here, too, since it would be fatal
Linus Torvalds1da177e2005-04-16 15:20:36 -07005784 if you cannot allocate a memory in the suspend phase.
5785 The allocated buffer should be released in the corresponding
5786 destructor.
5787 </para>
5788
5789 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005790 And next, set suspend/resume callbacks to the pci_driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005791
5792 <informalexample>
5793 <programlisting>
5794<![CDATA[
5795 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02005796 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005797 .id_table = snd_my_ids,
5798 .probe = snd_my_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01005799 .remove = snd_my_remove,
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005800 #ifdef CONFIG_PM
5801 .suspend = snd_my_suspend,
5802 .resume = snd_my_resume,
5803 #endif
Linus Torvalds1da177e2005-04-16 15:20:36 -07005804 };
5805]]>
5806 </programlisting>
5807 </informalexample>
5808 </para>
5809
5810 </chapter>
5811
5812
5813<!-- ****************************************************** -->
5814<!-- Module Parameters -->
5815<!-- ****************************************************** -->
5816 <chapter id="module-parameters">
5817 <title>Module Parameters</title>
5818 <para>
5819 There are standard module options for ALSA. At least, each
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005820 module should have the <parameter>index</parameter>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005821 <parameter>id</parameter> and <parameter>enable</parameter>
5822 options.
5823 </para>
5824
5825 <para>
5826 If the module supports multiple cards (usually up to
5827 8 = <constant>SNDRV_CARDS</constant> cards), they should be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005828 arrays. The default initial values are defined already as
5829 constants for easier programming:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005830
5831 <informalexample>
5832 <programlisting>
5833<![CDATA[
5834 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5835 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5836 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5837]]>
5838 </programlisting>
5839 </informalexample>
5840 </para>
5841
5842 <para>
5843 If the module supports only a single card, they could be single
5844 variables, instead. <parameter>enable</parameter> option is not
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005845 always necessary in this case, but it would be better to have a
Linus Torvalds1da177e2005-04-16 15:20:36 -07005846 dummy option for compatibility.
5847 </para>
5848
5849 <para>
5850 The module parameters must be declared with the standard
5851 <function>module_param()()</function>,
5852 <function>module_param_array()()</function> and
5853 <function>MODULE_PARM_DESC()</function> macros.
5854 </para>
5855
5856 <para>
5857 The typical coding would be like below:
5858
5859 <informalexample>
5860 <programlisting>
5861<![CDATA[
5862 #define CARD_NAME "My Chip"
5863
5864 module_param_array(index, int, NULL, 0444);
5865 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5866 module_param_array(id, charp, NULL, 0444);
5867 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5868 module_param_array(enable, bool, NULL, 0444);
5869 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5870]]>
5871 </programlisting>
5872 </informalexample>
5873 </para>
5874
5875 <para>
5876 Also, don't forget to define the module description, classes,
5877 license and devices. Especially, the recent modprobe requires to
5878 define the module license as GPL, etc., otherwise the system is
5879 shown as <quote>tainted</quote>.
5880
5881 <informalexample>
5882 <programlisting>
5883<![CDATA[
5884 MODULE_DESCRIPTION("My Chip");
5885 MODULE_LICENSE("GPL");
5886 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5887]]>
5888 </programlisting>
5889 </informalexample>
5890 </para>
5891
5892 </chapter>
5893
5894
5895<!-- ****************************************************** -->
5896<!-- How To Put Your Driver -->
5897<!-- ****************************************************** -->
5898 <chapter id="how-to-put-your-driver">
5899 <title>How To Put Your Driver Into ALSA Tree</title>
5900 <section>
5901 <title>General</title>
5902 <para>
5903 So far, you've learned how to write the driver codes.
5904 And you might have a question now: how to put my own
5905 driver into the ALSA driver tree?
5906 Here (finally :) the standard procedure is described briefly.
5907 </para>
5908
5909 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005910 Suppose that you create a new PCI driver for the card
Linus Torvalds1da177e2005-04-16 15:20:36 -07005911 <quote>xyz</quote>. The card module name would be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005912 snd-xyz. The new driver is usually put into the alsa-driver
Linus Torvalds1da177e2005-04-16 15:20:36 -07005913 tree, <filename>alsa-driver/pci</filename> directory in
5914 the case of PCI cards.
5915 Then the driver is evaluated, audited and tested
5916 by developers and users. After a certain time, the driver
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005917 will go to the alsa-kernel tree (to the corresponding directory,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005918 such as <filename>alsa-kernel/pci</filename>) and eventually
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005919 will be integrated into the Linux 2.6 tree (the directory would be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005920 <filename>linux/sound/pci</filename>).
5921 </para>
5922
5923 <para>
5924 In the following sections, the driver code is supposed
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005925 to be put into alsa-driver tree. The two cases are covered:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005926 a driver consisting of a single source file and one consisting
5927 of several source files.
5928 </para>
5929 </section>
5930
5931 <section>
5932 <title>Driver with A Single Source File</title>
5933 <para>
5934 <orderedlist>
5935 <listitem>
5936 <para>
5937 Modify alsa-driver/pci/Makefile
5938 </para>
5939
5940 <para>
5941 Suppose you have a file xyz.c. Add the following
5942 two lines
5943 <informalexample>
5944 <programlisting>
5945<![CDATA[
5946 snd-xyz-objs := xyz.o
5947 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5948]]>
5949 </programlisting>
5950 </informalexample>
5951 </para>
5952 </listitem>
5953
5954 <listitem>
5955 <para>
5956 Create the Kconfig entry
5957 </para>
5958
5959 <para>
5960 Add the new entry of Kconfig for your xyz driver.
5961 <informalexample>
5962 <programlisting>
5963<![CDATA[
5964 config SND_XYZ
5965 tristate "Foobar XYZ"
5966 depends on SND
5967 select SND_PCM
5968 help
5969 Say Y here to include support for Foobar XYZ soundcard.
5970
5971 To compile this driver as a module, choose M here: the module
5972 will be called snd-xyz.
5973]]>
5974 </programlisting>
5975 </informalexample>
5976
5977 the line, select SND_PCM, specifies that the driver xyz supports
5978 PCM. In addition to SND_PCM, the following components are
5979 supported for select command:
5980 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5981 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5982 Add the select command for each supported component.
5983 </para>
5984
5985 <para>
5986 Note that some selections imply the lowlevel selections.
5987 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5988 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5989 You don't need to give the lowlevel selections again.
5990 </para>
5991
5992 <para>
5993 For the details of Kconfig script, refer to the kbuild
5994 documentation.
5995 </para>
5996
5997 </listitem>
5998
5999 <listitem>
6000 <para>
6001 Run cvscompile script to re-generate the configure script and
6002 build the whole stuff again.
6003 </para>
6004 </listitem>
6005 </orderedlist>
6006 </para>
6007 </section>
6008
6009 <section>
6010 <title>Drivers with Several Source Files</title>
6011 <para>
6012 Suppose that the driver snd-xyz have several source files.
6013 They are located in the new subdirectory,
6014 pci/xyz.
6015
6016 <orderedlist>
6017 <listitem>
6018 <para>
6019 Add a new directory (<filename>xyz</filename>) in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006020 <filename>alsa-driver/pci/Makefile</filename> as below
Linus Torvalds1da177e2005-04-16 15:20:36 -07006021
6022 <informalexample>
6023 <programlisting>
6024<![CDATA[
6025 obj-$(CONFIG_SND) += xyz/
6026]]>
6027 </programlisting>
6028 </informalexample>
6029 </para>
6030 </listitem>
6031
6032 <listitem>
6033 <para>
6034 Under the directory <filename>xyz</filename>, create a Makefile
6035
6036 <example>
6037 <title>Sample Makefile for a driver xyz</title>
6038 <programlisting>
6039<![CDATA[
6040 ifndef SND_TOPDIR
6041 SND_TOPDIR=../..
6042 endif
6043
6044 include $(SND_TOPDIR)/toplevel.config
6045 include $(SND_TOPDIR)/Makefile.conf
6046
6047 snd-xyz-objs := xyz.o abc.o def.o
6048
6049 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6050
6051 include $(SND_TOPDIR)/Rules.make
6052]]>
6053 </programlisting>
6054 </example>
6055 </para>
6056 </listitem>
6057
6058 <listitem>
6059 <para>
6060 Create the Kconfig entry
6061 </para>
6062
6063 <para>
6064 This procedure is as same as in the last section.
6065 </para>
6066 </listitem>
6067
6068 <listitem>
6069 <para>
6070 Run cvscompile script to re-generate the configure script and
6071 build the whole stuff again.
6072 </para>
6073 </listitem>
6074 </orderedlist>
6075 </para>
6076 </section>
6077
6078 </chapter>
6079
6080<!-- ****************************************************** -->
6081<!-- Useful Functions -->
6082<!-- ****************************************************** -->
6083 <chapter id="useful-functions">
6084 <title>Useful Functions</title>
6085
6086 <section id="useful-functions-snd-printk">
6087 <title><function>snd_printk()</function> and friends</title>
6088 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006089 ALSA provides a verbose version of the
Linus Torvalds1da177e2005-04-16 15:20:36 -07006090 <function>printk()</function> function. If a kernel config
6091 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6092 function prints the given message together with the file name
6093 and the line of the caller. The <constant>KERN_XXX</constant>
6094 prefix is processed as
6095 well as the original <function>printk()</function> does, so it's
6096 recommended to add this prefix, e.g.
6097
6098 <informalexample>
6099 <programlisting>
6100<![CDATA[
6101 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6102]]>
6103 </programlisting>
6104 </informalexample>
6105 </para>
6106
6107 <para>
6108 There are also <function>printk()</function>'s for
6109 debugging. <function>snd_printd()</function> can be used for
6110 general debugging purposes. If
6111 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6112 compiled, and works just like
6113 <function>snd_printk()</function>. If the ALSA is compiled
6114 without the debugging flag, it's ignored.
6115 </para>
6116
6117 <para>
6118 <function>snd_printdd()</function> is compiled in only when
Takashi Iwai62cf8722008-05-20 12:15:15 +02006119 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6120 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
Linus Torvalds1da177e2005-04-16 15:20:36 -07006121 even if you configure the alsa-driver with
6122 <option>--with-debug=full</option> option. You need to give
6123 explicitly <option>--with-debug=detect</option> option instead.
6124 </para>
6125 </section>
6126
Linus Torvalds1da177e2005-04-16 15:20:36 -07006127 <section id="useful-functions-snd-bug">
6128 <title><function>snd_BUG()</function></title>
6129 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006130 It shows the <computeroutput>BUG?</computeroutput> message and
Takashi Iwai7cc6dff2008-08-08 17:14:55 +02006131 stack trace as well as <function>snd_BUG_ON</function> at the point.
Takashi Iwai7c22f1a2005-10-10 11:46:31 +02006132 It's useful to show that a fatal error happens there.
6133 </para>
6134 <para>
6135 When no debug flag is set, this macro is ignored.
Linus Torvalds1da177e2005-04-16 15:20:36 -07006136 </para>
6137 </section>
Takashi Iwai5ef03462008-08-08 17:06:01 +02006138
6139 <section id="useful-functions-snd-bug-on">
6140 <title><function>snd_BUG_ON()</function></title>
6141 <para>
6142 <function>snd_BUG_ON()</function> macro is similar with
6143 <function>WARN_ON()</function> macro. For example,
6144
6145 <informalexample>
6146 <programlisting>
6147<![CDATA[
6148 snd_BUG_ON(!pointer);
6149]]>
6150 </programlisting>
6151 </informalexample>
6152
6153 or it can be used as the condition,
6154 <informalexample>
6155 <programlisting>
6156<![CDATA[
6157 if (snd_BUG_ON(non_zero_is_bug))
6158 return -EINVAL;
6159]]>
6160 </programlisting>
6161 </informalexample>
6162
6163 </para>
6164
6165 <para>
6166 The macro takes an conditional expression to evaluate.
Christine Spangd5702162013-03-04 17:02:59 -05006167 When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
6168 expression is non-zero, it shows the warning message such as
Takashi Iwai5ef03462008-08-08 17:06:01 +02006169 <computeroutput>BUG? (xxx)</computeroutput>
Christine Spangd5702162013-03-04 17:02:59 -05006170 normally followed by stack trace.
6171
6172 In both cases it returns the evaluated value.
Takashi Iwai5ef03462008-08-08 17:06:01 +02006173 </para>
6174
6175 </section>
6176
Linus Torvalds1da177e2005-04-16 15:20:36 -07006177 </chapter>
6178
6179
6180<!-- ****************************************************** -->
6181<!-- Acknowledgments -->
6182<!-- ****************************************************** -->
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01006183 <chapter id="acknowledgments">
Linus Torvalds1da177e2005-04-16 15:20:36 -07006184 <title>Acknowledgments</title>
6185 <para>
6186 I would like to thank Phil Kerr for his help for improvement and
6187 corrections of this document.
6188 </para>
6189 <para>
6190 Kevin Conder reformatted the original plain-text to the
6191 DocBook format.
6192 </para>
6193 <para>
6194 Giuliano Pochini corrected typos and contributed the example codes
6195 in the hardware constraints section.
6196 </para>
6197 </chapter>
Linus Torvalds1da177e2005-04-16 15:20:36 -07006198</book>