blob: 6f639d9530b51b69394a83c1d29e9ee2a42bce32 [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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700471 *rchip = chip;
472 return 0;
473 }
474
475 /* constructor -- see "Constructor" sub-section */
Takashi Iwai090015a2012-12-07 07:52:28 +0100476 static int snd_mychip_probe(struct pci_dev *pci,
477 const struct pci_device_id *pci_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700478 {
479 static int dev;
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100480 struct snd_card *card;
481 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700482 int err;
483
484 /* (1) */
485 if (dev >= SNDRV_CARDS)
486 return -ENODEV;
487 if (!enable[dev]) {
488 dev++;
489 return -ENOENT;
490 }
491
492 /* (2) */
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100493 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
494 0, &card);
Takashi Iwaid4533792008-12-28 16:45:34 +0100495 if (err < 0)
496 return err;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700497
498 /* (3) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200499 err = snd_mychip_create(card, pci, &chip);
500 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700501 snd_card_free(card);
502 return err;
503 }
504
505 /* (4) */
506 strcpy(card->driver, "My Chip");
507 strcpy(card->shortname, "My Own Chip 123");
508 sprintf(card->longname, "%s at 0x%lx irq %i",
509 card->shortname, chip->ioport, chip->irq);
510
511 /* (5) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200512 .... /* implemented later */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700513
514 /* (6) */
Takashi Iwai95a5b082007-07-26 16:50:09 +0200515 err = snd_card_register(card);
516 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700517 snd_card_free(card);
518 return err;
519 }
520
521 /* (7) */
522 pci_set_drvdata(pci, card);
523 dev++;
524 return 0;
525 }
526
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200527 /* destructor -- see the "Destructor" sub-section */
Takashi Iwai090015a2012-12-07 07:52:28 +0100528 static void snd_mychip_remove(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700529 {
530 snd_card_free(pci_get_drvdata(pci));
531 pci_set_drvdata(pci, NULL);
532 }
533]]>
534 </programlisting>
535 </example>
536 </para>
537 </section>
538
539 <section id="basic-flow-constructor">
540 <title>Constructor</title>
541 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200542 The real constructor of PCI drivers is the <function>probe</function> callback.
543 The <function>probe</function> callback and other component-constructors which are called
Takashi Iwai090015a2012-12-07 07:52:28 +0100544 from the <function>probe</function> callback cannot be used with
545 the <parameter>__init</parameter> prefix
Linus Torvalds1da177e2005-04-16 15:20:36 -0700546 because any PCI device could be a hotplug device.
547 </para>
548
549 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200550 In the <function>probe</function> callback, the following scheme is often used.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700551 </para>
552
553 <section id="basic-flow-constructor-device-index">
554 <title>1) Check and increment the device index.</title>
555 <para>
556 <informalexample>
557 <programlisting>
558<![CDATA[
559 static int dev;
560 ....
561 if (dev >= SNDRV_CARDS)
562 return -ENODEV;
563 if (!enable[dev]) {
564 dev++;
565 return -ENOENT;
566 }
567]]>
568 </programlisting>
569 </informalexample>
570
571 where enable[dev] is the module option.
572 </para>
573
574 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200575 Each time the <function>probe</function> callback is called, check the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700576 availability of the device. If not available, simply increment
577 the device index and returns. dev will be incremented also
578 later (<link
579 linkend="basic-flow-constructor-set-pci"><citetitle>step
580 7</citetitle></link>).
581 </para>
582 </section>
583
584 <section id="basic-flow-constructor-create-card">
585 <title>2) Create a card instance</title>
586 <para>
587 <informalexample>
588 <programlisting>
589<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100590 struct snd_card *card;
Takashi Iwaid4533792008-12-28 16:45:34 +0100591 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700592 ....
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100593 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
594 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 Iwai393aa9c2014-01-29 12:51:12 +0100812 <function>snd_card_new()</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;
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100819 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700820]]>
821 </programlisting>
822 </informalexample>
823 </para>
824
825 <para>
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100826 The function takes six arguments: the parent device pointer,
827 the card-index number, the id string, the module pointer (usually
Linus Torvalds1da177e2005-04-16 15:20:36 -0700828 <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 Iwai393aa9c2014-01-29 12:51:12 +0100833 are allocated by <function>snd_card_new()</function>.
834 </para>
835
836 <para>
837 The first argument, the pointer of struct
838 <structname>device</structname>, specifies the parent device.
839 For PCI devices, typically &amp;pci-&gt; is passed there.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700840 </para>
841 </section>
842
843 <section id="card-management-component">
844 <title>Components</title>
845 <para>
846 After the card is created, you can attach the components
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200847 (devices) to the card instance. In an ALSA driver, a component is
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100848 represented as a struct <structname>snd_device</structname> object.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700849 A component can be a PCM instance, a control interface, a raw
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200850 MIDI interface, etc. Each such instance has one component
Linus Torvalds1da177e2005-04-16 15:20:36 -0700851 entry.
852 </para>
853
854 <para>
855 A component can be created via
856 <function>snd_device_new()</function> function.
857
858 <informalexample>
859 <programlisting>
860<![CDATA[
861 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
862]]>
863 </programlisting>
864 </informalexample>
865 </para>
866
867 <para>
868 This takes the card pointer, the device-level
869 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
870 callback pointers (<parameter>&amp;ops</parameter>). The
871 device-level defines the type of components and the order of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200872 registration and de-registration. For most components, the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700873 device-level is already defined. For a user-defined component,
874 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
875 </para>
876
877 <para>
878 This function itself doesn't allocate the data space. The data
879 must be allocated manually beforehand, and its pointer is passed
Antonio Ospite04044b82013-01-29 12:56:27 +0100880 as the argument. This pointer (<parameter>chip</parameter> in the
881 above example) is used as the identifier for the instance.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700882 </para>
883
884 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200885 Each pre-defined ALSA component such as ac97 and pcm calls
Linus Torvalds1da177e2005-04-16 15:20:36 -0700886 <function>snd_device_new()</function> inside its
887 constructor. The destructor for each component is defined in the
888 callback pointers. Hence, you don't need to take care of
889 calling a destructor for such a component.
890 </para>
891
892 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200893 If you wish to create your own component, you need to
894 set the destructor function to the dev_free callback in
895 the <parameter>ops</parameter>, so that it can be released
896 automatically via <function>snd_card_free()</function>.
897 The next example will show an implementation of chip-specific
898 data.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700899 </para>
900 </section>
901
902 <section id="card-management-chip-specific">
903 <title>Chip-Specific Data</title>
904 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200905 Chip-specific information, e.g. the I/O port address, its
Linus Torvalds1da177e2005-04-16 15:20:36 -0700906 resource pointer, or the irq number, is stored in the
907 chip-specific record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700908
909 <informalexample>
910 <programlisting>
911<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100912 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700913 ....
914 };
915]]>
916 </programlisting>
917 </informalexample>
918 </para>
919
920 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200921 In general, there are two ways of allocating the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700922 </para>
923
924 <section id="card-management-chip-specific-snd-card-new">
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100925 <title>1. Allocating via <function>snd_card_new()</function>.</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700926 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200927 As mentioned above, you can pass the extra-data-length
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100928 to the 5th argument of <function>snd_card_new()</function>, i.e.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700929
930 <informalexample>
931 <programlisting>
932<![CDATA[
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100933 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
934 sizeof(struct mychip), &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700935]]>
936 </programlisting>
937 </informalexample>
938
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +0200939 struct <structname>mychip</structname> is the type of the chip record.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700940 </para>
941
942 <para>
943 In return, the allocated record can be accessed as
944
945 <informalexample>
946 <programlisting>
947<![CDATA[
Takashi Iwai437a5a42006-11-21 12:14:23 +0100948 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700949]]>
950 </programlisting>
951 </informalexample>
952
953 With this method, you don't have to allocate twice.
954 The record is released together with the card instance.
955 </para>
956 </section>
957
958 <section id="card-management-chip-specific-allocate-extra">
959 <title>2. Allocating an extra device.</title>
960
961 <para>
962 After allocating a card instance via
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100963 <function>snd_card_new()</function> (with
Takashi Iwaid4533792008-12-28 16:45:34 +0100964 <constant>0</constant> on the 4th arg), call
Takashi Iwai561b2202005-09-09 14:22:34 +0200965 <function>kzalloc()</function>.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700966
967 <informalexample>
968 <programlisting>
969<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100970 struct snd_card *card;
971 struct mychip *chip;
Takashi Iwai393aa9c2014-01-29 12:51:12 +0100972 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
973 0, &card);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700974 .....
Takashi Iwai561b2202005-09-09 14:22:34 +0200975 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700976]]>
977 </programlisting>
978 </informalexample>
979 </para>
980
981 <para>
982 The chip record should have the field to hold the card
983 pointer at least,
984
985 <informalexample>
986 <programlisting>
987<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100988 struct mychip {
989 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700990 ....
991 };
992]]>
993 </programlisting>
994 </informalexample>
995 </para>
996
997 <para>
998 Then, set the card pointer in the returned chip instance.
999
1000 <informalexample>
1001 <programlisting>
1002<![CDATA[
1003 chip->card = card;
1004]]>
1005 </programlisting>
1006 </informalexample>
1007 </para>
1008
1009 <para>
1010 Next, initialize the fields, and register this chip
1011 record as a low-level device with a specified
1012 <parameter>ops</parameter>,
1013
1014 <informalexample>
1015 <programlisting>
1016<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001017 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001018 .dev_free = snd_mychip_dev_free,
1019 };
1020 ....
1021 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1022]]>
1023 </programlisting>
1024 </informalexample>
1025
1026 <function>snd_mychip_dev_free()</function> is the
1027 device-destructor function, which will call the real
1028 destructor.
1029 </para>
1030
1031 <para>
1032 <informalexample>
1033 <programlisting>
1034<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001035 static int snd_mychip_dev_free(struct snd_device *device)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001036 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001037 return snd_mychip_free(device->device_data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001038 }
1039]]>
1040 </programlisting>
1041 </informalexample>
1042
1043 where <function>snd_mychip_free()</function> is the real destructor.
1044 </para>
1045 </section>
1046 </section>
1047
1048 <section id="card-management-registration">
1049 <title>Registration and Release</title>
1050 <para>
1051 After all components are assigned, register the card instance
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001052 by calling <function>snd_card_register()</function>. Access
1053 to the device files is enabled at this point. That is, before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001054 <function>snd_card_register()</function> is called, the
1055 components are safely inaccessible from external side. If this
1056 call fails, exit the probe function after releasing the card via
1057 <function>snd_card_free()</function>.
1058 </para>
1059
1060 <para>
1061 For releasing the card instance, you can call simply
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001062 <function>snd_card_free()</function>. As mentioned earlier, all
Linus Torvalds1da177e2005-04-16 15:20:36 -07001063 components are released automatically by this call.
1064 </para>
1065
1066 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001067 For a device which allows hotplugging, you can use
Takashi Iwai2b29b132006-06-23 14:38:26 +02001068 <function>snd_card_free_when_closed</function>. This one will
1069 postpone the destruction until all devices are closed.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001070 </para>
1071
1072 </section>
1073
1074 </chapter>
1075
1076
1077<!-- ****************************************************** -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001078<!-- PCI Resource Management -->
Linus Torvalds1da177e2005-04-16 15:20:36 -07001079<!-- ****************************************************** -->
1080 <chapter id="pci-resource">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001081 <title>PCI Resource Management</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001082
1083 <section id="pci-resource-example">
1084 <title>Full Code Example</title>
1085 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001086 In this section, we'll complete the chip-specific constructor,
1087 destructor and PCI entries. Example code is shown first,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001088 below.
1089
1090 <example>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001091 <title>PCI Resource Management Example</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001092 <programlisting>
1093<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001094 struct mychip {
1095 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001096 struct pci_dev *pci;
1097
1098 unsigned long port;
1099 int irq;
1100 };
1101
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001102 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001103 {
1104 /* disable hardware here if any */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001105 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001106
1107 /* release the irq */
1108 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001109 free_irq(chip->irq, chip);
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001110 /* release the I/O ports & memory */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001111 pci_release_regions(chip->pci);
1112 /* disable the PCI entry */
1113 pci_disable_device(chip->pci);
1114 /* release the data */
1115 kfree(chip);
1116 return 0;
1117 }
1118
1119 /* chip-specific constructor */
Takashi Iwai090015a2012-12-07 07:52:28 +01001120 static int snd_mychip_create(struct snd_card *card,
1121 struct pci_dev *pci,
1122 struct mychip **rchip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001123 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001124 struct mychip *chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001125 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001126 static struct snd_device_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001127 .dev_free = snd_mychip_dev_free,
1128 };
1129
1130 *rchip = NULL;
1131
1132 /* initialize the PCI entry */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001133 err = pci_enable_device(pci);
1134 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001135 return err;
1136 /* check PCI availability (28bit DMA) */
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001137 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1138 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001139 printk(KERN_ERR "error to set 28bit mask DMA\n");
1140 pci_disable_device(pci);
1141 return -ENXIO;
1142 }
1143
Takashi Iwai561b2202005-09-09 14:22:34 +02001144 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001145 if (chip == NULL) {
1146 pci_disable_device(pci);
1147 return -ENOMEM;
1148 }
1149
1150 /* initialize the stuff */
1151 chip->card = card;
1152 chip->pci = pci;
1153 chip->irq = -1;
1154
1155 /* (1) PCI resource allocation */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001156 err = pci_request_regions(pci, "My Chip");
1157 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001158 kfree(chip);
1159 pci_disable_device(pci);
1160 return err;
1161 }
1162 chip->port = pci_resource_start(pci, 0);
1163 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001164 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001165 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1166 snd_mychip_free(chip);
1167 return -EBUSY;
1168 }
1169 chip->irq = pci->irq;
1170
1171 /* (2) initialization of the chip hardware */
Takashi Iwai95a5b082007-07-26 16:50:09 +02001172 .... /* (not implemented in this document) */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001173
Takashi Iwai95a5b082007-07-26 16:50:09 +02001174 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1175 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001176 snd_mychip_free(chip);
1177 return err;
1178 }
1179
Linus Torvalds1da177e2005-04-16 15:20:36 -07001180 *rchip = chip;
1181 return 0;
1182 }
1183
1184 /* PCI IDs */
Takashi Iwaif40b6892006-07-05 16:51:05 +02001185 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001186 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1187 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1188 ....
1189 { 0, }
1190 };
1191 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1192
1193 /* pci_driver definition */
1194 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001195 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001196 .id_table = snd_mychip_ids,
1197 .probe = snd_mychip_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01001198 .remove = snd_mychip_remove,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001199 };
1200
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001201 /* module initialization */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001202 static int __init alsa_card_mychip_init(void)
1203 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001204 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001205 }
1206
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001207 /* module clean up */
Linus Torvalds1da177e2005-04-16 15:20:36 -07001208 static void __exit alsa_card_mychip_exit(void)
1209 {
1210 pci_unregister_driver(&driver);
1211 }
1212
1213 module_init(alsa_card_mychip_init)
1214 module_exit(alsa_card_mychip_exit)
1215
1216 EXPORT_NO_SYMBOLS; /* for old kernels only */
1217]]>
1218 </programlisting>
1219 </example>
1220 </para>
1221 </section>
1222
1223 <section id="pci-resource-some-haftas">
1224 <title>Some Hafta's</title>
1225 <para>
1226 The allocation of PCI resources is done in the
1227 <function>probe()</function> function, and usually an extra
1228 <function>xxx_create()</function> function is written for this
Tobias Klauser56b146d2006-04-10 22:54:21 -07001229 purpose.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001230 </para>
1231
1232 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001233 In the case of PCI devices, you first have to call
1234 the <function>pci_enable_device()</function> function before
Linus Torvalds1da177e2005-04-16 15:20:36 -07001235 allocating resources. Also, you need to set the proper PCI DMA
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001236 mask to limit the accessed I/O range. In some cases, you might
Linus Torvalds1da177e2005-04-16 15:20:36 -07001237 need to call <function>pci_set_master()</function> function,
Tobias Klauser56b146d2006-04-10 22:54:21 -07001238 too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001239 </para>
1240
1241 <para>
1242 Suppose the 28bit mask, and the code to be added would be like:
1243
1244 <informalexample>
1245 <programlisting>
1246<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001247 err = pci_enable_device(pci);
1248 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001249 return err;
Yang Hongyang2c5510d2009-04-06 19:01:19 -07001250 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1251 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001252 printk(KERN_ERR "error to set 28bit mask DMA\n");
1253 pci_disable_device(pci);
1254 return -ENXIO;
1255 }
1256
1257]]>
1258 </programlisting>
1259 </informalexample>
1260 </para>
1261 </section>
1262
1263 <section id="pci-resource-resource-allocation">
1264 <title>Resource Allocation</title>
1265 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001266 The allocation of I/O ports and irqs is done via standard kernel
Linus Torvalds1da177e2005-04-16 15:20:36 -07001267 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1268 that. And these resources must be released in the destructor
1269 function (see below). Also, on ALSA 0.9.x, you don't need to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001270 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001271 </para>
1272
1273 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001274 Now assume that the PCI device has an I/O port with 8 bytes
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001275 and an interrupt. Then struct <structname>mychip</structname> will have the
Tobias Klauser56b146d2006-04-10 22:54:21 -07001276 following fields:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001277
1278 <informalexample>
1279 <programlisting>
1280<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001281 struct mychip {
1282 struct snd_card *card;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001283
1284 unsigned long port;
1285 int irq;
1286 };
1287]]>
1288 </programlisting>
1289 </informalexample>
1290 </para>
1291
1292 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001293 For an I/O port (and also a memory region), you need to have
Linus Torvalds1da177e2005-04-16 15:20:36 -07001294 the resource pointer for the standard resource management. For
1295 an irq, you have to keep only the irq number (integer). But you
1296 need to initialize this number as -1 before actual allocation,
1297 since irq 0 is valid. The port address and its resource pointer
1298 can be initialized as null by
Takashi Iwai561b2202005-09-09 14:22:34 +02001299 <function>kzalloc()</function> automatically, so you
Linus Torvalds1da177e2005-04-16 15:20:36 -07001300 don't have to take care of resetting them.
1301 </para>
1302
1303 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001304 The allocation of an I/O port is done like this:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001305
1306 <informalexample>
1307 <programlisting>
1308<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02001309 err = pci_request_regions(pci, "My Chip");
1310 if (err < 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001311 kfree(chip);
1312 pci_disable_device(pci);
1313 return err;
1314 }
1315 chip->port = pci_resource_start(pci, 0);
1316]]>
1317 </programlisting>
1318 </informalexample>
1319 </para>
1320
1321 <para>
1322 <!-- obsolete -->
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001323 It will reserve the I/O port region of 8 bytes of the given
Linus Torvalds1da177e2005-04-16 15:20:36 -07001324 PCI device. The returned value, chip-&gt;res_port, is allocated
1325 via <function>kmalloc()</function> by
1326 <function>request_region()</function>. The pointer must be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001327 released via <function>kfree()</function>, but there is a
1328 problem with this. This issue will be explained later.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001329 </para>
1330
1331 <para>
1332 The allocation of an interrupt source is done like this:
1333
1334 <informalexample>
1335 <programlisting>
1336<![CDATA[
1337 if (request_irq(pci->irq, snd_mychip_interrupt,
Takashi Iwaice1fd362011-06-14 08:54:14 +02001338 IRQF_SHARED, KBUILD_MODNAME, chip)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001339 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1340 snd_mychip_free(chip);
1341 return -EBUSY;
1342 }
1343 chip->irq = pci->irq;
1344]]>
1345 </programlisting>
1346 </informalexample>
1347
1348 where <function>snd_mychip_interrupt()</function> is the
1349 interrupt handler defined <link
1350 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1351 Note that chip-&gt;irq should be defined
1352 only when <function>request_irq()</function> succeeded.
1353 </para>
1354
1355 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001356 On the PCI bus, interrupts can be shared. Thus,
1357 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
Linus Torvalds1da177e2005-04-16 15:20:36 -07001358 <function>request_irq()</function>.
1359 </para>
1360
1361 <para>
1362 The last argument of <function>request_irq()</function> is the
1363 data pointer passed to the interrupt handler. Usually, the
1364 chip-specific record is used for that, but you can use what you
1365 like, too.
1366 </para>
1367
1368 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001369 I won't give details about the interrupt handler at this
Linus Torvalds1da177e2005-04-16 15:20:36 -07001370 point, but at least its appearance can be explained now. The
1371 interrupt handler looks usually like the following:
1372
1373 <informalexample>
1374 <programlisting>
1375<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01001376 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001377 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001378 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001379 ....
1380 return IRQ_HANDLED;
1381 }
1382]]>
1383 </programlisting>
1384 </informalexample>
1385 </para>
1386
1387 <para>
1388 Now let's write the corresponding destructor for the resources
1389 above. The role of destructor is simple: disable the hardware
1390 (if already activated) and release the resources. So far, we
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001391 have no hardware part, so the disabling code is not written here.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001392 </para>
1393
1394 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001395 To release the resources, the <quote>check-and-release</quote>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001396 method is a safer way. For the interrupt, do like this:
1397
1398 <informalexample>
1399 <programlisting>
1400<![CDATA[
1401 if (chip->irq >= 0)
Takashi Iwai437a5a42006-11-21 12:14:23 +01001402 free_irq(chip->irq, chip);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001403]]>
1404 </programlisting>
1405 </informalexample>
1406
1407 Since the irq number can start from 0, you should initialize
1408 chip-&gt;irq with a negative value (e.g. -1), so that you can
1409 check the validity of the irq number as above.
1410 </para>
1411
1412 <para>
1413 When you requested I/O ports or memory regions via
1414 <function>pci_request_region()</function> or
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001415 <function>pci_request_regions()</function> like in this example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001416 release the resource(s) using the corresponding function,
1417 <function>pci_release_region()</function> or
1418 <function>pci_release_regions()</function>.
1419
1420 <informalexample>
1421 <programlisting>
1422<![CDATA[
1423 pci_release_regions(chip->pci);
1424]]>
1425 </programlisting>
1426 </informalexample>
1427 </para>
1428
1429 <para>
1430 When you requested manually via <function>request_region()</function>
1431 or <function>request_mem_region</function>, you can release it via
1432 <function>release_resource()</function>. Suppose that you keep
1433 the resource pointer returned from <function>request_region()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001434 in chip-&gt;res_port, the release procedure looks like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001435
1436 <informalexample>
1437 <programlisting>
1438<![CDATA[
Takashi Iwaib1d57762005-10-10 11:56:31 +02001439 release_and_free_resource(chip->res_port);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001440]]>
1441 </programlisting>
1442 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001443 </para>
1444
1445 <para>
1446 Don't forget to call <function>pci_disable_device()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001447 before the end.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001448 </para>
1449
1450 <para>
1451 And finally, release the chip-specific record.
1452
1453 <informalexample>
1454 <programlisting>
1455<![CDATA[
1456 kfree(chip);
1457]]>
1458 </programlisting>
1459 </informalexample>
1460 </para>
1461
1462 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001463 We didn't implement the hardware disabling part in the above.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001464 If you need to do this, please note that the destructor may be
1465 called even before the initialization of the chip is completed.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001466 It would be better to have a flag to skip hardware disabling
Linus Torvalds1da177e2005-04-16 15:20:36 -07001467 if the hardware was not initialized yet.
1468 </para>
1469
1470 <para>
1471 When the chip-data is assigned to the card using
1472 <function>snd_device_new()</function> with
1473 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1474 called at the last. That is, it is assured that all other
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001475 components like PCMs and controls have already been released.
1476 You don't have to stop PCMs, etc. explicitly, but just
1477 call low-level hardware stopping.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001478 </para>
1479
1480 <para>
1481 The management of a memory-mapped region is almost as same as
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001482 the management of an I/O port. You'll need three fields like
Linus Torvalds1da177e2005-04-16 15:20:36 -07001483 the following:
1484
1485 <informalexample>
1486 <programlisting>
1487<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001488 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001489 ....
1490 unsigned long iobase_phys;
1491 void __iomem *iobase_virt;
1492 };
1493]]>
1494 </programlisting>
1495 </informalexample>
1496
1497 and the allocation would be like below:
1498
1499 <informalexample>
1500 <programlisting>
1501<![CDATA[
1502 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1503 kfree(chip);
1504 return err;
1505 }
1506 chip->iobase_phys = pci_resource_start(pci, 0);
1507 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1508 pci_resource_len(pci, 0));
1509]]>
1510 </programlisting>
1511 </informalexample>
1512
1513 and the corresponding destructor would be:
1514
1515 <informalexample>
1516 <programlisting>
1517<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001518 static int snd_mychip_free(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001519 {
1520 ....
1521 if (chip->iobase_virt)
1522 iounmap(chip->iobase_virt);
1523 ....
1524 pci_release_regions(chip->pci);
1525 ....
1526 }
1527]]>
1528 </programlisting>
1529 </informalexample>
1530 </para>
1531
1532 </section>
1533
Linus Torvalds1da177e2005-04-16 15:20:36 -07001534 <section id="pci-resource-entries">
1535 <title>PCI Entries</title>
1536 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001537 So far, so good. Let's finish the missing PCI
1538 stuff. At first, we need a
Linus Torvalds1da177e2005-04-16 15:20:36 -07001539 <structname>pci_device_id</structname> table for this
1540 chipset. It's a table of PCI vendor/device ID number, and some
1541 masks.
1542 </para>
1543
1544 <para>
1545 For example,
1546
1547 <informalexample>
1548 <programlisting>
1549<![CDATA[
Takashi Iwaif40b6892006-07-05 16:51:05 +02001550 static struct pci_device_id snd_mychip_ids[] = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001551 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1552 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1553 ....
1554 { 0, }
1555 };
1556 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1557]]>
1558 </programlisting>
1559 </informalexample>
1560 </para>
1561
1562 <para>
1563 The first and second fields of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001564 the <structname>pci_device_id</structname> structure are the vendor and
1565 device IDs. If you have no reason to filter the matching
1566 devices, you can leave the remaining fields as above. The last
1567 field of the <structname>pci_device_id</structname> struct contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07001568 private data for this entry. You can specify any value here, for
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001569 example, to define specific operations for supported device IDs.
1570 Such an example is found in the intel8x0 driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001571 </para>
1572
1573 <para>
1574 The last entry of this list is the terminator. You must
1575 specify this all-zero entry.
1576 </para>
1577
1578 <para>
1579 Then, prepare the <structname>pci_driver</structname> record:
1580
1581 <informalexample>
1582 <programlisting>
1583<![CDATA[
1584 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02001585 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001586 .id_table = snd_mychip_ids,
1587 .probe = snd_mychip_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01001588 .remove = snd_mychip_remove,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001589 };
1590]]>
1591 </programlisting>
1592 </informalexample>
1593 </para>
1594
1595 <para>
1596 The <structfield>probe</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001597 <structfield>remove</structfield> functions have already
1598 been defined in the previous sections.
Takashi Iwai090015a2012-12-07 07:52:28 +01001599 The <structfield>name</structfield>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001600 field is the name string of this device. Note that you must not
1601 use a slash <quote>/</quote> in this string.
1602 </para>
1603
1604 <para>
1605 And at last, the module entries:
1606
1607 <informalexample>
1608 <programlisting>
1609<![CDATA[
1610 static int __init alsa_card_mychip_init(void)
1611 {
Takashi Iwai01d25d42005-04-11 16:58:24 +02001612 return pci_register_driver(&driver);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001613 }
1614
1615 static void __exit alsa_card_mychip_exit(void)
1616 {
1617 pci_unregister_driver(&driver);
1618 }
1619
1620 module_init(alsa_card_mychip_init)
1621 module_exit(alsa_card_mychip_exit)
1622]]>
1623 </programlisting>
1624 </informalexample>
1625 </para>
1626
1627 <para>
1628 Note that these module entries are tagged with
1629 <parameter>__init</parameter> and
Takashi Iwai090015a2012-12-07 07:52:28 +01001630 <parameter>__exit</parameter> prefixes.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001631 </para>
1632
1633 <para>
1634 Oh, one thing was forgotten. If you have no exported symbols,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001635 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 -07001636
1637 <informalexample>
1638 <programlisting>
1639<![CDATA[
1640 EXPORT_NO_SYMBOLS;
1641]]>
1642 </programlisting>
1643 </informalexample>
1644
1645 That's all!
1646 </para>
1647 </section>
1648 </chapter>
1649
1650
1651<!-- ****************************************************** -->
1652<!-- PCM Interface -->
1653<!-- ****************************************************** -->
1654 <chapter id="pcm-interface">
1655 <title>PCM Interface</title>
1656
1657 <section id="pcm-interface-general">
1658 <title>General</title>
1659 <para>
1660 The PCM middle layer of ALSA is quite powerful and it is only
1661 necessary for each driver to implement the low-level functions
1662 to access its hardware.
1663 </para>
1664
1665 <para>
1666 For accessing to the PCM layer, you need to include
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001667 <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001668 <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
1669 if you access to some functions related with hw_param.
1670 </para>
1671
1672 <para>
1673 Each card device can have up to four pcm instances. A pcm
1674 instance corresponds to a pcm device file. The limitation of
1675 number of instances comes only from the available bit size of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001676 the Linux's device numbers. Once when 64bit device number is
1677 used, we'll have more pcm instances available.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001678 </para>
1679
1680 <para>
1681 A pcm instance consists of pcm playback and capture streams,
1682 and each pcm stream consists of one or more pcm substreams. Some
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001683 soundcards support multiple playback functions. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001684 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1685 each open, a free substream is (usually) automatically chosen
1686 and opened. Meanwhile, when only one substream exists and it was
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001687 already opened, the successful open will either block
1688 or error with <constant>EAGAIN</constant> according to the
1689 file open mode. But you don't have to care about such details in your
1690 driver. The PCM middle layer will take care of such work.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001691 </para>
1692 </section>
1693
1694 <section id="pcm-interface-example">
1695 <title>Full Code Example</title>
1696 <para>
1697 The example code below does not include any hardware access
1698 routines but shows only the skeleton, how to build up the PCM
1699 interfaces.
1700
1701 <example>
1702 <title>PCM Example Code</title>
1703 <programlisting>
1704<![CDATA[
1705 #include <sound/pcm.h>
1706 ....
1707
1708 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001709 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001710 .info = (SNDRV_PCM_INFO_MMAP |
1711 SNDRV_PCM_INFO_INTERLEAVED |
1712 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1713 SNDRV_PCM_INFO_MMAP_VALID),
1714 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1715 .rates = SNDRV_PCM_RATE_8000_48000,
1716 .rate_min = 8000,
1717 .rate_max = 48000,
1718 .channels_min = 2,
1719 .channels_max = 2,
1720 .buffer_bytes_max = 32768,
1721 .period_bytes_min = 4096,
1722 .period_bytes_max = 32768,
1723 .periods_min = 1,
1724 .periods_max = 1024,
1725 };
1726
1727 /* hardware definition */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001728 static struct snd_pcm_hardware snd_mychip_capture_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 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001747 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001748 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001749 struct mychip *chip = snd_pcm_substream_chip(substream);
1750 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001751
1752 runtime->hw = snd_mychip_playback_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001753 /* more hardware-initialization will be done here */
1754 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001755 return 0;
1756 }
1757
1758 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001759 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001760 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001761 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001762 /* the hardware-specific codes will be here */
1763 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001764 return 0;
1765
1766 }
1767
1768 /* open callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001769 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001770 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001771 struct mychip *chip = snd_pcm_substream_chip(substream);
1772 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001773
1774 runtime->hw = snd_mychip_capture_hw;
Takashi Iwai95a5b082007-07-26 16:50:09 +02001775 /* more hardware-initialization will be done here */
1776 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001777 return 0;
1778 }
1779
1780 /* close callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001781 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001782 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001783 struct mychip *chip = snd_pcm_substream_chip(substream);
Takashi Iwai95a5b082007-07-26 16:50:09 +02001784 /* the hardware-specific codes will be here */
1785 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001786 return 0;
1787
1788 }
1789
1790 /* hw_params callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001791 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1792 struct snd_pcm_hw_params *hw_params)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001793 {
1794 return snd_pcm_lib_malloc_pages(substream,
1795 params_buffer_bytes(hw_params));
1796 }
1797
1798 /* hw_free callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001799 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001800 {
1801 return snd_pcm_lib_free_pages(substream);
1802 }
1803
1804 /* prepare callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001805 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001806 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001807 struct mychip *chip = snd_pcm_substream_chip(substream);
1808 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001809
1810 /* set up the hardware with the current configuration
1811 * for example...
1812 */
1813 mychip_set_sample_format(chip, runtime->format);
1814 mychip_set_sample_rate(chip, runtime->rate);
1815 mychip_set_channels(chip, runtime->channels);
Takashi Iwai0b7bed42006-03-02 15:35:55 +01001816 mychip_set_dma_setup(chip, runtime->dma_addr,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001817 chip->buffer_size,
1818 chip->period_size);
1819 return 0;
1820 }
1821
1822 /* trigger callback */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001823 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001824 int cmd)
1825 {
1826 switch (cmd) {
1827 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001828 /* do something to start the PCM engine */
1829 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001830 break;
1831 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02001832 /* do something to stop the PCM engine */
1833 ....
Linus Torvalds1da177e2005-04-16 15:20:36 -07001834 break;
1835 default:
1836 return -EINVAL;
1837 }
1838 }
1839
1840 /* pointer callback */
1841 static snd_pcm_uframes_t
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001842 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001843 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001844 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001845 unsigned int current_ptr;
1846
1847 /* get the current hardware pointer */
1848 current_ptr = mychip_get_hw_pointer(chip);
1849 return current_ptr;
1850 }
1851
1852 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001853 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001854 .open = snd_mychip_playback_open,
1855 .close = snd_mychip_playback_close,
1856 .ioctl = snd_pcm_lib_ioctl,
1857 .hw_params = snd_mychip_pcm_hw_params,
1858 .hw_free = snd_mychip_pcm_hw_free,
1859 .prepare = snd_mychip_pcm_prepare,
1860 .trigger = snd_mychip_pcm_trigger,
1861 .pointer = snd_mychip_pcm_pointer,
1862 };
1863
1864 /* operators */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001865 static struct snd_pcm_ops snd_mychip_capture_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001866 .open = snd_mychip_capture_open,
1867 .close = snd_mychip_capture_close,
1868 .ioctl = snd_pcm_lib_ioctl,
1869 .hw_params = snd_mychip_pcm_hw_params,
1870 .hw_free = snd_mychip_pcm_hw_free,
1871 .prepare = snd_mychip_pcm_prepare,
1872 .trigger = snd_mychip_pcm_trigger,
1873 .pointer = snd_mychip_pcm_pointer,
1874 };
1875
1876 /*
1877 * definitions of capture are omitted here...
1878 */
1879
1880 /* create a pcm device */
Takashi Iwai090015a2012-12-07 07:52:28 +01001881 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001882 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001883 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001884 int err;
1885
Takashi Iwai95a5b082007-07-26 16:50:09 +02001886 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1887 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001888 return err;
1889 pcm->private_data = chip;
1890 strcpy(pcm->name, "My Chip");
1891 chip->pcm = pcm;
1892 /* set operators */
1893 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1894 &snd_mychip_playback_ops);
1895 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1896 &snd_mychip_capture_ops);
1897 /* pre-allocation of buffers */
1898 /* NOTE: this may fail */
1899 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1900 snd_dma_pci_data(chip->pci),
1901 64*1024, 64*1024);
1902 return 0;
1903 }
1904]]>
1905 </programlisting>
1906 </example>
1907 </para>
1908 </section>
1909
1910 <section id="pcm-interface-constructor">
1911 <title>Constructor</title>
1912 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001913 A pcm instance is allocated by the <function>snd_pcm_new()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07001914 function. It would be better to create a constructor for pcm,
1915 namely,
1916
1917 <informalexample>
1918 <programlisting>
1919<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01001920 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001921 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001922 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001923 int err;
1924
Takashi Iwai95a5b082007-07-26 16:50:09 +02001925 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1926 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001927 return err;
1928 pcm->private_data = chip;
1929 strcpy(pcm->name, "My Chip");
1930 chip->pcm = pcm;
1931 ....
1932 return 0;
1933 }
1934]]>
1935 </programlisting>
1936 </informalexample>
1937 </para>
1938
1939 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001940 The <function>snd_pcm_new()</function> function takes four
Linus Torvalds1da177e2005-04-16 15:20:36 -07001941 arguments. The first argument is the card pointer to which this
1942 pcm is assigned, and the second is the ID string.
1943 </para>
1944
1945 <para>
1946 The third argument (<parameter>index</parameter>, 0 in the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001947 above) is the index of this new pcm. It begins from zero. If
1948 you create more than one pcm instances, specify the
Linus Torvalds1da177e2005-04-16 15:20:36 -07001949 different numbers in this argument. For example,
1950 <parameter>index</parameter> = 1 for the second PCM device.
1951 </para>
1952
1953 <para>
1954 The fourth and fifth arguments are the number of substreams
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02001955 for playback and capture, respectively. Here 1 is used for
1956 both arguments. When no playback or capture substreams are available,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001957 pass 0 to the corresponding argument.
1958 </para>
1959
1960 <para>
1961 If a chip supports multiple playbacks or captures, you can
1962 specify more numbers, but they must be handled properly in
1963 open/close, etc. callbacks. When you need to know which
1964 substream you are referring to, then it can be obtained from
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001965 struct <structname>snd_pcm_substream</structname> data passed to each callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07001966 as follows:
1967
1968 <informalexample>
1969 <programlisting>
1970<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01001971 struct snd_pcm_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001972 int index = substream->number;
1973]]>
1974 </programlisting>
1975 </informalexample>
1976 </para>
1977
1978 <para>
1979 After the pcm is created, you need to set operators for each
1980 pcm stream.
1981
1982 <informalexample>
1983 <programlisting>
1984<![CDATA[
1985 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1986 &snd_mychip_playback_ops);
1987 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1988 &snd_mychip_capture_ops);
1989]]>
1990 </programlisting>
1991 </informalexample>
1992 </para>
1993
1994 <para>
1995 The operators are defined typically like this:
1996
1997 <informalexample>
1998 <programlisting>
1999<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002000 static struct snd_pcm_ops snd_mychip_playback_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002001 .open = snd_mychip_pcm_open,
2002 .close = snd_mychip_pcm_close,
2003 .ioctl = snd_pcm_lib_ioctl,
2004 .hw_params = snd_mychip_pcm_hw_params,
2005 .hw_free = snd_mychip_pcm_hw_free,
2006 .prepare = snd_mychip_pcm_prepare,
2007 .trigger = snd_mychip_pcm_trigger,
2008 .pointer = snd_mychip_pcm_pointer,
2009 };
2010]]>
2011 </programlisting>
2012 </informalexample>
2013
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002014 All the callbacks are described in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002015 <link linkend="pcm-interface-operators"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002016 Operators</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002017 </para>
2018
2019 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002020 After setting the operators, you probably will want to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002021 pre-allocate the buffer. For the pre-allocation, simply call
2022 the following:
2023
2024 <informalexample>
2025 <programlisting>
2026<![CDATA[
2027 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2028 snd_dma_pci_data(chip->pci),
2029 64*1024, 64*1024);
2030]]>
2031 </programlisting>
2032 </informalexample>
2033
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002034 It will allocate a buffer up to 64kB as default.
2035 Buffer management details will be described in the later section <link
Linus Torvalds1da177e2005-04-16 15:20:36 -07002036 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2037 Management</citetitle></link>.
2038 </para>
2039
2040 <para>
2041 Additionally, you can set some extra information for this pcm
2042 in pcm-&gt;info_flags.
2043 The available values are defined as
2044 <constant>SNDRV_PCM_INFO_XXX</constant> in
2045 <filename>&lt;sound/asound.h&gt;</filename>, which is used for
2046 the hardware definition (described later). When your soundchip
2047 supports only half-duplex, specify like this:
2048
2049 <informalexample>
2050 <programlisting>
2051<![CDATA[
2052 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2053]]>
2054 </programlisting>
2055 </informalexample>
2056 </para>
2057 </section>
2058
2059 <section id="pcm-interface-destructor">
2060 <title>... And the Destructor?</title>
2061 <para>
2062 The destructor for a pcm instance is not always
2063 necessary. Since the pcm device will be released by the middle
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002064 layer code automatically, you don't have to call the destructor
Linus Torvalds1da177e2005-04-16 15:20:36 -07002065 explicitly.
2066 </para>
2067
2068 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002069 The destructor would be necessary if you created
2070 special records internally and needed to release them. In such a
Linus Torvalds1da177e2005-04-16 15:20:36 -07002071 case, set the destructor function to
2072 pcm-&gt;private_free:
2073
2074 <example>
2075 <title>PCM Instance with a Destructor</title>
2076 <programlisting>
2077<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002078 static void mychip_pcm_free(struct snd_pcm *pcm)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002079 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002080 struct mychip *chip = snd_pcm_chip(pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002081 /* free your own data */
2082 kfree(chip->my_private_pcm_data);
Takashi Iwai95a5b082007-07-26 16:50:09 +02002083 /* do what you like else */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002084 ....
2085 }
2086
Takashi Iwai090015a2012-12-07 07:52:28 +01002087 static int snd_mychip_new_pcm(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002088 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002089 struct snd_pcm *pcm;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002090 ....
2091 /* allocate your own data */
2092 chip->my_private_pcm_data = kmalloc(...);
2093 /* set the destructor */
2094 pcm->private_data = chip;
2095 pcm->private_free = mychip_pcm_free;
2096 ....
2097 }
2098]]>
2099 </programlisting>
2100 </example>
2101 </para>
2102 </section>
2103
2104 <section id="pcm-interface-runtime">
2105 <title>Runtime Pointer - The Chest of PCM Information</title>
2106 <para>
2107 When the PCM substream is opened, a PCM runtime instance is
2108 allocated and assigned to the substream. This pointer is
2109 accessible via <constant>substream-&gt;runtime</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002110 This runtime pointer holds most information you need
2111 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2112 pointers, mmap records, spinlocks, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002113 </para>
2114
2115 <para>
2116 The definition of runtime instance is found in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002117 <filename>&lt;sound/pcm.h&gt;</filename>. Here are
2118 the contents of this file:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002119 <informalexample>
2120 <programlisting>
2121<![CDATA[
2122struct _snd_pcm_runtime {
2123 /* -- Status -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002124 struct snd_pcm_substream *trigger_master;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002125 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2126 int overrange;
2127 snd_pcm_uframes_t avail_max;
2128 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2129 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2130
2131 /* -- HW params -- */
2132 snd_pcm_access_t access; /* access mode */
2133 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2134 snd_pcm_subformat_t subformat; /* subformat */
2135 unsigned int rate; /* rate in Hz */
2136 unsigned int channels; /* channels */
2137 snd_pcm_uframes_t period_size; /* period size */
2138 unsigned int periods; /* periods */
2139 snd_pcm_uframes_t buffer_size; /* buffer size */
2140 unsigned int tick_time; /* tick time */
2141 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2142 size_t byte_align;
2143 unsigned int frame_bits;
2144 unsigned int sample_bits;
2145 unsigned int info;
2146 unsigned int rate_num;
2147 unsigned int rate_den;
2148
2149 /* -- SW params -- */
Takashi Iwai07799e72005-10-10 11:49:49 +02002150 struct timespec tstamp_mode; /* mmap timestamp is updated */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002151 unsigned int period_step;
2152 unsigned int sleep_min; /* min ticks to sleep */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002153 snd_pcm_uframes_t start_threshold;
2154 snd_pcm_uframes_t stop_threshold;
2155 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2156 noise is nearest than this */
2157 snd_pcm_uframes_t silence_size; /* Silence filling size */
2158 snd_pcm_uframes_t boundary; /* pointers wrap point */
2159
2160 snd_pcm_uframes_t silenced_start;
2161 snd_pcm_uframes_t silenced_size;
2162
2163 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2164
2165 /* -- mmap -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002166 volatile struct snd_pcm_mmap_status *status;
2167 volatile struct snd_pcm_mmap_control *control;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002168 atomic_t mmap_count;
2169
2170 /* -- locking / scheduling -- */
2171 spinlock_t lock;
2172 wait_queue_head_t sleep;
2173 struct timer_list tick_timer;
2174 struct fasync_struct *fasync;
2175
2176 /* -- private section -- */
2177 void *private_data;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002178 void (*private_free)(struct snd_pcm_runtime *runtime);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002179
2180 /* -- hardware description -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002181 struct snd_pcm_hardware hw;
2182 struct snd_pcm_hw_constraints hw_constraints;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002183
2184 /* -- interrupt callbacks -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002185 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2186 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002187
2188 /* -- timer -- */
2189 unsigned int timer_resolution; /* timer resolution */
2190
2191 /* -- DMA -- */
2192 unsigned char *dma_area; /* DMA area */
2193 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2194 size_t dma_bytes; /* size of DMA area */
2195
2196 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2197
2198#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2199 /* -- OSS things -- */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002200 struct snd_pcm_oss_runtime oss;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002201#endif
2202};
2203]]>
2204 </programlisting>
2205 </informalexample>
2206 </para>
2207
2208 <para>
2209 For the operators (callbacks) of each sound driver, most of
2210 these records are supposed to be read-only. Only the PCM
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002211 middle-layer changes / updates them. The exceptions are
Linus Torvalds1da177e2005-04-16 15:20:36 -07002212 the hardware description (hw), interrupt callbacks
2213 (transfer_ack_xxx), DMA buffer information, and the private
2214 data. Besides, if you use the standard buffer allocation
2215 method via <function>snd_pcm_lib_malloc_pages()</function>,
2216 you don't need to set the DMA buffer information by yourself.
2217 </para>
2218
2219 <para>
2220 In the sections below, important records are explained.
2221 </para>
2222
2223 <section id="pcm-interface-runtime-hw">
2224 <title>Hardware Description</title>
2225 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002226 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002227 contains the definitions of the fundamental hardware
2228 configuration. Above all, you'll need to define this in
2229 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2230 the open callback</citetitle></link>.
2231 Note that the runtime instance holds the copy of the
2232 descriptor, not the pointer to the existing descriptor. That
2233 is, in the open callback, you can modify the copied descriptor
2234 (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
2235 number of channels is 1 only on some chip models, you can
2236 still use the same hardware descriptor and change the
2237 channels_max later:
2238 <informalexample>
2239 <programlisting>
2240<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002241 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002242 ...
2243 runtime->hw = snd_mychip_playback_hw; /* common definition */
2244 if (chip->model == VERY_OLD_ONE)
2245 runtime->hw.channels_max = 1;
2246]]>
2247 </programlisting>
2248 </informalexample>
2249 </para>
2250
2251 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002252 Typically, you'll have a hardware descriptor as below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07002253 <informalexample>
2254 <programlisting>
2255<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002256 static struct snd_pcm_hardware snd_mychip_playback_hw = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002257 .info = (SNDRV_PCM_INFO_MMAP |
2258 SNDRV_PCM_INFO_INTERLEAVED |
2259 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2260 SNDRV_PCM_INFO_MMAP_VALID),
2261 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2262 .rates = SNDRV_PCM_RATE_8000_48000,
2263 .rate_min = 8000,
2264 .rate_max = 48000,
2265 .channels_min = 2,
2266 .channels_max = 2,
2267 .buffer_bytes_max = 32768,
2268 .period_bytes_min = 4096,
2269 .period_bytes_max = 32768,
2270 .periods_min = 1,
2271 .periods_max = 1024,
2272 };
2273]]>
2274 </programlisting>
2275 </informalexample>
2276 </para>
2277
2278 <para>
2279 <itemizedlist>
2280 <listitem><para>
2281 The <structfield>info</structfield> field contains the type and
2282 capabilities of this pcm. The bit flags are defined in
2283 <filename>&lt;sound/asound.h&gt;</filename> as
2284 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2285 have to specify whether the mmap is supported and which
2286 interleaved format is supported.
Antonio Ospite04044b82013-01-29 12:56:27 +01002287 When the hardware supports mmap, add the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002288 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2289 hardware supports the interleaved or the non-interleaved
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002290 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
Linus Torvalds1da177e2005-04-16 15:20:36 -07002291 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2292 be set, respectively. If both are supported, you can set both,
2293 too.
2294 </para>
2295
2296 <para>
2297 In the above example, <constant>MMAP_VALID</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002298 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
Linus Torvalds1da177e2005-04-16 15:20:36 -07002299 mode. Usually both are set. Of course,
2300 <constant>MMAP_VALID</constant> is set only if the mmap is
2301 really supported.
2302 </para>
2303
2304 <para>
2305 The other possible flags are
2306 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2307 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2308 <constant>PAUSE</constant> bit means that the pcm supports the
2309 <quote>pause</quote> operation, while the
2310 <constant>RESUME</constant> bit means that the pcm supports
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002311 the full <quote>suspend/resume</quote> operation.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002312 If the <constant>PAUSE</constant> flag is set,
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002313 the <structfield>trigger</structfield> callback below
2314 must handle the corresponding (pause push/release) commands.
2315 The suspend/resume trigger commands can be defined even without
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002316 the <constant>RESUME</constant> flag. See <link
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002317 linkend="power-management"><citetitle>
2318 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002319 </para>
2320
2321 <para>
2322 When the PCM substreams can be synchronized (typically,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01002323 synchronized start/stop of a playback and a capture streams),
Linus Torvalds1da177e2005-04-16 15:20:36 -07002324 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2325 too. In this case, you'll need to check the linked-list of
2326 PCM substreams in the trigger callback. This will be
2327 described in the later section.
2328 </para>
2329 </listitem>
2330
2331 <listitem>
2332 <para>
2333 <structfield>formats</structfield> field contains the bit-flags
2334 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2335 If the hardware supports more than one format, give all or'ed
2336 bits. In the example above, the signed 16bit little-endian
2337 format is specified.
2338 </para>
2339 </listitem>
2340
2341 <listitem>
2342 <para>
2343 <structfield>rates</structfield> field contains the bit-flags of
2344 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2345 When the chip supports continuous rates, pass
2346 <constant>CONTINUOUS</constant> bit additionally.
2347 The pre-defined rate bits are provided only for typical
2348 rates. If your chip supports unconventional rates, you need to add
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002349 the <constant>KNOT</constant> bit and set up the hardware
Linus Torvalds1da177e2005-04-16 15:20:36 -07002350 constraint manually (explained later).
2351 </para>
2352 </listitem>
2353
2354 <listitem>
2355 <para>
2356 <structfield>rate_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002357 <structfield>rate_max</structfield> define the minimum and
2358 maximum sample rate. This should correspond somehow to
Linus Torvalds1da177e2005-04-16 15:20:36 -07002359 <structfield>rates</structfield> bits.
2360 </para>
2361 </listitem>
2362
2363 <listitem>
2364 <para>
2365 <structfield>channel_min</structfield> and
2366 <structfield>channel_max</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002367 define, as you might already expected, the minimum and maximum
Linus Torvalds1da177e2005-04-16 15:20:36 -07002368 number of channels.
2369 </para>
2370 </listitem>
2371
2372 <listitem>
2373 <para>
2374 <structfield>buffer_bytes_max</structfield> defines the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002375 maximum buffer size in bytes. There is no
Linus Torvalds1da177e2005-04-16 15:20:36 -07002376 <structfield>buffer_bytes_min</structfield> field, since
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002377 it can be calculated from the minimum period size and the
2378 minimum number of periods.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002379 Meanwhile, <structfield>period_bytes_min</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002380 define the minimum and maximum size of the period in bytes.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002381 <structfield>periods_max</structfield> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002382 <structfield>periods_min</structfield> define the maximum and
2383 minimum number of periods in the buffer.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002384 </para>
2385
2386 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002387 The <quote>period</quote> is a term that corresponds to
2388 a fragment in the OSS world. The period defines the size at
2389 which a PCM interrupt is generated. This size strongly
Linus Torvalds1da177e2005-04-16 15:20:36 -07002390 depends on the hardware.
2391 Generally, the smaller period size will give you more
2392 interrupts, that is, more controls.
2393 In the case of capture, this size defines the input latency.
2394 On the other hand, the whole buffer size defines the
2395 output latency for the playback direction.
2396 </para>
2397 </listitem>
2398
2399 <listitem>
2400 <para>
2401 There is also a field <structfield>fifo_size</structfield>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002402 This specifies the size of the hardware FIFO, but currently it
2403 is neither used in the driver nor in the alsa-lib. So, you
Linus Torvalds1da177e2005-04-16 15:20:36 -07002404 can ignore this field.
2405 </para>
2406 </listitem>
2407 </itemizedlist>
2408 </para>
2409 </section>
2410
2411 <section id="pcm-interface-runtime-config">
2412 <title>PCM Configurations</title>
2413 <para>
2414 Ok, let's go back again to the PCM runtime records.
2415 The most frequently referred records in the runtime instance are
2416 the PCM configurations.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002417 The PCM configurations are stored in the runtime instance
Linus Torvalds1da177e2005-04-16 15:20:36 -07002418 after the application sends <type>hw_params</type> data via
2419 alsa-lib. There are many fields copied from hw_params and
2420 sw_params structs. For example,
2421 <structfield>format</structfield> holds the format type
2422 chosen by the application. This field contains the enum value
2423 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2424 </para>
2425
2426 <para>
2427 One thing to be noted is that the configured buffer and period
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002428 sizes are stored in <quote>frames</quote> in the runtime.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002429 In the ALSA world, 1 frame = channels * samples-size.
2430 For conversion between frames and bytes, you can use the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002431 <function>frames_to_bytes()</function> and
2432 <function>bytes_to_frames()</function> helper functions.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002433 <informalexample>
2434 <programlisting>
2435<![CDATA[
2436 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2437]]>
2438 </programlisting>
2439 </informalexample>
2440 </para>
2441
2442 <para>
2443 Also, many software parameters (sw_params) are
2444 stored in frames, too. Please check the type of the field.
2445 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2446 integer while <type>snd_pcm_sframes_t</type> is for the frames
2447 as signed integer.
2448 </para>
2449 </section>
2450
2451 <section id="pcm-interface-runtime-dma">
2452 <title>DMA Buffer Information</title>
2453 <para>
2454 The DMA buffer is defined by the following four fields,
2455 <structfield>dma_area</structfield>,
2456 <structfield>dma_addr</structfield>,
2457 <structfield>dma_bytes</structfield> and
2458 <structfield>dma_private</structfield>.
2459 The <structfield>dma_area</structfield> holds the buffer
2460 pointer (the logical address). You can call
2461 <function>memcpy</function> from/to
2462 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2463 holds the physical address of the buffer. This field is
2464 specified only when the buffer is a linear buffer.
2465 <structfield>dma_bytes</structfield> holds the size of buffer
2466 in bytes. <structfield>dma_private</structfield> is used for
2467 the ALSA DMA allocator.
2468 </para>
2469
2470 <para>
2471 If you use a standard ALSA function,
2472 <function>snd_pcm_lib_malloc_pages()</function>, for
2473 allocating the buffer, these fields are set by the ALSA middle
2474 layer, and you should <emphasis>not</emphasis> change them by
2475 yourself. You can read them but not write them.
2476 On the other hand, if you want to allocate the buffer by
2477 yourself, you'll need to manage it in hw_params callback.
2478 At least, <structfield>dma_bytes</structfield> is mandatory.
2479 <structfield>dma_area</structfield> is necessary when the
2480 buffer is mmapped. If your driver doesn't support mmap, this
2481 field is not necessary. <structfield>dma_addr</structfield>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002482 is also optional. You can use
Linus Torvalds1da177e2005-04-16 15:20:36 -07002483 <structfield>dma_private</structfield> as you like, too.
2484 </para>
2485 </section>
2486
2487 <section id="pcm-interface-runtime-status">
2488 <title>Running Status</title>
2489 <para>
2490 The running status can be referred via <constant>runtime-&gt;status</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002491 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002492 record. For example, you can get the current DMA hardware
2493 pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2494 </para>
2495
2496 <para>
2497 The DMA application pointer can be referred via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002498 <constant>runtime-&gt;control</constant>, which points to the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002499 struct <structname>snd_pcm_mmap_control</structname> record.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002500 However, accessing directly to this value is not recommended.
2501 </para>
2502 </section>
2503
2504 <section id="pcm-interface-runtime-private">
2505 <title>Private Data</title>
2506 <para>
2507 You can allocate a record for the substream and store it in
2508 <constant>runtime-&gt;private_data</constant>. Usually, this
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002509 is done in
Linus Torvalds1da177e2005-04-16 15:20:36 -07002510 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2511 the open callback</citetitle></link>.
2512 Don't mix this with <constant>pcm-&gt;private_data</constant>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002513 The <constant>pcm-&gt;private_data</constant> usually points to the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002514 chip instance assigned statically at the creation of PCM, while the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002515 <constant>runtime-&gt;private_data</constant> points to a dynamic
2516 data structure created at the PCM open callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002517
2518 <informalexample>
2519 <programlisting>
2520<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002521 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002522 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002523 struct my_pcm_data *data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002524 ....
2525 data = kmalloc(sizeof(*data), GFP_KERNEL);
2526 substream->runtime->private_data = data;
2527 ....
2528 }
2529]]>
2530 </programlisting>
2531 </informalexample>
2532 </para>
2533
2534 <para>
2535 The allocated object must be released in
2536 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2537 the close callback</citetitle></link>.
2538 </para>
2539 </section>
2540
2541 <section id="pcm-interface-runtime-intr">
2542 <title>Interrupt Callbacks</title>
2543 <para>
2544 The field <structfield>transfer_ack_begin</structfield> and
2545 <structfield>transfer_ack_end</structfield> are called at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002546 the beginning and at the end of
Linus Torvalds1da177e2005-04-16 15:20:36 -07002547 <function>snd_pcm_period_elapsed()</function>, respectively.
2548 </para>
2549 </section>
2550
2551 </section>
2552
2553 <section id="pcm-interface-operators">
2554 <title>Operators</title>
2555 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002556 OK, now let me give details about each pcm callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07002557 (<parameter>ops</parameter>). In general, every callback must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002558 return 0 if successful, or a negative error number
2559 such as <constant>-EINVAL</constant>. To choose an appropriate
2560 error number, it is advised to check what value other parts of
2561 the kernel return when the same kind of request fails.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002562 </para>
2563
2564 <para>
2565 The callback function takes at least the argument with
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002566 <structname>snd_pcm_substream</structname> pointer. To retrieve
2567 the chip record from the given substream instance, you can use the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002568 following macro.
2569
2570 <informalexample>
2571 <programlisting>
2572<![CDATA[
2573 int xxx() {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002574 struct mychip *chip = snd_pcm_substream_chip(substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002575 ....
2576 }
2577]]>
2578 </programlisting>
2579 </informalexample>
2580
2581 The macro reads <constant>substream-&gt;private_data</constant>,
2582 which is a copy of <constant>pcm-&gt;private_data</constant>.
2583 You can override the former if you need to assign different data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002584 records per PCM substream. For example, the cmi8330 driver assigns
Linus Torvalds1da177e2005-04-16 15:20:36 -07002585 different private_data for playback and capture directions,
2586 because it uses two different codecs (SB- and AD-compatible) for
2587 different directions.
2588 </para>
2589
2590 <section id="pcm-interface-operators-open-callback">
2591 <title>open callback</title>
2592 <para>
2593 <informalexample>
2594 <programlisting>
2595<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002596 static int snd_xxx_open(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002597]]>
2598 </programlisting>
2599 </informalexample>
2600
2601 This is called when a pcm substream is opened.
2602 </para>
2603
2604 <para>
2605 At least, here you have to initialize the runtime-&gt;hw
2606 record. Typically, this is done by like this:
2607
2608 <informalexample>
2609 <programlisting>
2610<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002611 static int snd_xxx_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002612 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002613 struct mychip *chip = snd_pcm_substream_chip(substream);
2614 struct snd_pcm_runtime *runtime = substream->runtime;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002615
2616 runtime->hw = snd_mychip_playback_hw;
2617 return 0;
2618 }
2619]]>
2620 </programlisting>
2621 </informalexample>
2622
2623 where <parameter>snd_mychip_playback_hw</parameter> is the
2624 pre-defined hardware description.
2625 </para>
2626
2627 <para>
2628 You can allocate a private data in this callback, as described
2629 in <link linkend="pcm-interface-runtime-private"><citetitle>
2630 Private Data</citetitle></link> section.
2631 </para>
2632
2633 <para>
2634 If the hardware configuration needs more constraints, set the
2635 hardware constraints here, too.
2636 See <link linkend="pcm-interface-constraints"><citetitle>
2637 Constraints</citetitle></link> for more details.
2638 </para>
2639 </section>
2640
2641 <section id="pcm-interface-operators-close-callback">
2642 <title>close callback</title>
2643 <para>
2644 <informalexample>
2645 <programlisting>
2646<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002647 static int snd_xxx_close(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002648]]>
2649 </programlisting>
2650 </informalexample>
2651
2652 Obviously, this is called when a pcm substream is closed.
2653 </para>
2654
2655 <para>
2656 Any private instance for a pcm substream allocated in the
2657 open callback will be released here.
2658
2659 <informalexample>
2660 <programlisting>
2661<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002662 static int snd_xxx_close(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002663 {
2664 ....
2665 kfree(substream->runtime->private_data);
2666 ....
2667 }
2668]]>
2669 </programlisting>
2670 </informalexample>
2671 </para>
2672 </section>
2673
2674 <section id="pcm-interface-operators-ioctl-callback">
2675 <title>ioctl callback</title>
2676 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002677 This is used for any special call to pcm ioctls. But
Linus Torvalds1da177e2005-04-16 15:20:36 -07002678 usually you can pass a generic ioctl callback,
2679 <function>snd_pcm_lib_ioctl</function>.
2680 </para>
2681 </section>
2682
2683 <section id="pcm-interface-operators-hw-params-callback">
2684 <title>hw_params callback</title>
2685 <para>
2686 <informalexample>
2687 <programlisting>
2688<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002689 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2690 struct snd_pcm_hw_params *hw_params);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002691]]>
2692 </programlisting>
2693 </informalexample>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002694 </para>
2695
2696 <para>
2697 This is called when the hardware parameter
2698 (<structfield>hw_params</structfield>) is set
2699 up by the application,
2700 that is, once when the buffer size, the period size, the
2701 format, etc. are defined for the pcm substream.
2702 </para>
2703
2704 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002705 Many hardware setups should be done in this callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07002706 including the allocation of buffers.
2707 </para>
2708
2709 <para>
2710 Parameters to be initialized are retrieved by
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002711 <function>params_xxx()</function> macros. To allocate
Linus Torvalds1da177e2005-04-16 15:20:36 -07002712 buffer, you can call a helper function,
2713
2714 <informalexample>
2715 <programlisting>
2716<![CDATA[
2717 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2718]]>
2719 </programlisting>
2720 </informalexample>
2721
2722 <function>snd_pcm_lib_malloc_pages()</function> is available
2723 only when the DMA buffers have been pre-allocated.
2724 See the section <link
2725 linkend="buffer-and-memory-buffer-types"><citetitle>
2726 Buffer Types</citetitle></link> for more details.
2727 </para>
2728
2729 <para>
2730 Note that this and <structfield>prepare</structfield> callbacks
2731 may be called multiple times per initialization.
2732 For example, the OSS emulation may
2733 call these callbacks at each change via its ioctl.
2734 </para>
2735
2736 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002737 Thus, you need to be careful not to allocate the same buffers
2738 many times, which will lead to memory leaks! Calling the
Linus Torvalds1da177e2005-04-16 15:20:36 -07002739 helper function above many times is OK. It will release the
2740 previous buffer automatically when it was already allocated.
2741 </para>
2742
2743 <para>
2744 Another note is that this callback is non-atomic
2745 (schedulable). This is important, because the
2746 <structfield>trigger</structfield> callback
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002747 is atomic (non-schedulable). That is, mutexes or any
Linus Torvalds1da177e2005-04-16 15:20:36 -07002748 schedule-related functions are not available in
2749 <structfield>trigger</structfield> callback.
2750 Please see the subsection
2751 <link linkend="pcm-interface-atomicity"><citetitle>
2752 Atomicity</citetitle></link> for details.
2753 </para>
2754 </section>
2755
2756 <section id="pcm-interface-operators-hw-free-callback">
2757 <title>hw_free callback</title>
2758 <para>
2759 <informalexample>
2760 <programlisting>
2761<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002762 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002763]]>
2764 </programlisting>
2765 </informalexample>
2766 </para>
2767
2768 <para>
2769 This is called to release the resources allocated via
2770 <structfield>hw_params</structfield>. For example, releasing the
2771 buffer via
2772 <function>snd_pcm_lib_malloc_pages()</function> is done by
2773 calling the following:
2774
2775 <informalexample>
2776 <programlisting>
2777<![CDATA[
2778 snd_pcm_lib_free_pages(substream);
2779]]>
2780 </programlisting>
2781 </informalexample>
2782 </para>
2783
2784 <para>
2785 This function is always called before the close callback is called.
2786 Also, the callback may be called multiple times, too.
2787 Keep track whether the resource was already released.
2788 </para>
2789 </section>
2790
2791 <section id="pcm-interface-operators-prepare-callback">
2792 <title>prepare callback</title>
2793 <para>
2794 <informalexample>
2795 <programlisting>
2796<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002797 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002798]]>
2799 </programlisting>
2800 </informalexample>
2801 </para>
2802
2803 <para>
2804 This callback is called when the pcm is
2805 <quote>prepared</quote>. You can set the format type, sample
2806 rate, etc. here. The difference from
2807 <structfield>hw_params</structfield> is that the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002808 <structfield>prepare</structfield> callback will be called each
Linus Torvalds1da177e2005-04-16 15:20:36 -07002809 time
2810 <function>snd_pcm_prepare()</function> is called, i.e. when
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002811 recovering after underruns, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002812 </para>
2813
2814 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002815 Note that this callback is now non-atomic.
2816 You can use schedule-related functions safely in this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002817 </para>
2818
2819 <para>
2820 In this and the following callbacks, you can refer to the
2821 values via the runtime record,
2822 substream-&gt;runtime.
2823 For example, to get the current
2824 rate, format or channels, access to
2825 runtime-&gt;rate,
2826 runtime-&gt;format or
2827 runtime-&gt;channels, respectively.
2828 The physical address of the allocated buffer is set to
2829 runtime-&gt;dma_area. The buffer and period sizes are
2830 in runtime-&gt;buffer_size and runtime-&gt;period_size,
2831 respectively.
2832 </para>
2833
2834 <para>
2835 Be careful that this callback will be called many times at
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002836 each setup, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002837 </para>
2838 </section>
2839
2840 <section id="pcm-interface-operators-trigger-callback">
2841 <title>trigger callback</title>
2842 <para>
2843 <informalexample>
2844 <programlisting>
2845<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002846 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002847]]>
2848 </programlisting>
2849 </informalexample>
2850
2851 This is called when the pcm is started, stopped or paused.
2852 </para>
2853
2854 <para>
2855 Which action is specified in the second argument,
2856 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2857 <filename>&lt;sound/pcm.h&gt;</filename>. At least,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002858 the <constant>START</constant> and <constant>STOP</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002859 commands must be defined in this callback.
2860
2861 <informalexample>
2862 <programlisting>
2863<![CDATA[
2864 switch (cmd) {
2865 case SNDRV_PCM_TRIGGER_START:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002866 /* do something to start the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002867 break;
2868 case SNDRV_PCM_TRIGGER_STOP:
Takashi Iwai95a5b082007-07-26 16:50:09 +02002869 /* do something to stop the PCM engine */
Linus Torvalds1da177e2005-04-16 15:20:36 -07002870 break;
2871 default:
2872 return -EINVAL;
2873 }
2874]]>
2875 </programlisting>
2876 </informalexample>
2877 </para>
2878
2879 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002880 When the pcm supports the pause operation (given in the info
Antonio Ospited4dab5a2013-01-29 12:56:28 +01002881 field of the hardware table), the <constant>PAUSE_PUSH</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002882 and <constant>PAUSE_RELEASE</constant> commands must be
2883 handled here, too. The former is the command to pause the pcm,
2884 and the latter to restart the pcm again.
2885 </para>
2886
2887 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002888 When the pcm supports the suspend/resume operation,
2889 regardless of full or partial suspend/resume support,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002890 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002891 commands must be handled, too.
2892 These commands are issued when the power-management status is
2893 changed. Obviously, the <constant>SUSPEND</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002894 <constant>RESUME</constant> commands
2895 suspend and resume the pcm substream, and usually, they
2896 are identical to the <constant>STOP</constant> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07002897 <constant>START</constant> commands, respectively.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002898 See the <link linkend="power-management"><citetitle>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01002899 Power Management</citetitle></link> section for details.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002900 </para>
2901
2902 <para>
2903 As mentioned, this callback is atomic. You cannot call
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002904 functions which may sleep.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002905 The trigger callback should be as minimal as possible,
2906 just really triggering the DMA. The other stuff should be
2907 initialized hw_params and prepare callbacks properly
2908 beforehand.
2909 </para>
2910 </section>
2911
2912 <section id="pcm-interface-operators-pointer-callback">
2913 <title>pointer callback</title>
2914 <para>
2915 <informalexample>
2916 <programlisting>
2917<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01002918 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002919]]>
2920 </programlisting>
2921 </informalexample>
2922
2923 This callback is called when the PCM middle layer inquires
2924 the current hardware position on the buffer. The position must
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002925 be returned in frames,
2926 ranging from 0 to buffer_size - 1.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002927 </para>
2928
2929 <para>
2930 This is called usually from the buffer-update routine in the
2931 pcm middle layer, which is invoked when
2932 <function>snd_pcm_period_elapsed()</function> is called in the
2933 interrupt routine. Then the pcm middle layer updates the
2934 position and calculates the available space, and wakes up the
2935 sleeping poll threads, etc.
2936 </para>
2937
2938 <para>
2939 This callback is also atomic.
2940 </para>
2941 </section>
2942
2943 <section id="pcm-interface-operators-copy-silence">
2944 <title>copy and silence callbacks</title>
2945 <para>
2946 These callbacks are not mandatory, and can be omitted in
2947 most cases. These callbacks are used when the hardware buffer
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002948 cannot be in the normal memory space. Some chips have their
Linus Torvalds1da177e2005-04-16 15:20:36 -07002949 own buffer on the hardware which is not mappable. In such a
2950 case, you have to transfer the data manually from the memory
2951 buffer to the hardware buffer. Or, if the buffer is
2952 non-contiguous on both physical and virtual memory spaces,
2953 these callbacks must be defined, too.
2954 </para>
2955
2956 <para>
2957 If these two callbacks are defined, copy and set-silence
2958 operations are done by them. The detailed will be described in
2959 the later section <link
2960 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2961 Management</citetitle></link>.
2962 </para>
2963 </section>
2964
2965 <section id="pcm-interface-operators-ack">
2966 <title>ack callback</title>
2967 <para>
2968 This callback is also not mandatory. This callback is called
2969 when the appl_ptr is updated in read or write operations.
2970 Some drivers like emu10k1-fx and cs46xx need to track the
2971 current appl_ptr for the internal buffer, and this callback
2972 is useful only for such a purpose.
2973 </para>
2974 <para>
2975 This callback is atomic.
2976 </para>
2977 </section>
2978
2979 <section id="pcm-interface-operators-page-callback">
2980 <title>page callback</title>
2981
2982 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02002983 This callback is optional too. This callback is used
2984 mainly for non-contiguous buffers. The mmap calls this
Linus Torvalds1da177e2005-04-16 15:20:36 -07002985 callback to get the page address. Some examples will be
2986 explained in the later section <link
2987 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2988 Management</citetitle></link>, too.
2989 </para>
2990 </section>
2991 </section>
2992
2993 <section id="pcm-interface-interrupt-handler">
2994 <title>Interrupt Handler</title>
2995 <para>
2996 The rest of pcm stuff is the PCM interrupt handler. The
2997 role of PCM interrupt handler in the sound driver is to update
2998 the buffer position and to tell the PCM middle layer when the
2999 buffer position goes across the prescribed period size. To
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003000 inform this, call the <function>snd_pcm_period_elapsed()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003001 function.
3002 </para>
3003
3004 <para>
3005 There are several types of sound chips to generate the interrupts.
3006 </para>
3007
3008 <section id="pcm-interface-interrupt-handler-boundary">
3009 <title>Interrupts at the period (fragment) boundary</title>
3010 <para>
3011 This is the most frequently found type: the hardware
3012 generates an interrupt at each period boundary.
3013 In this case, you can call
3014 <function>snd_pcm_period_elapsed()</function> at each
3015 interrupt.
3016 </para>
3017
3018 <para>
3019 <function>snd_pcm_period_elapsed()</function> takes the
3020 substream pointer as its argument. Thus, you need to keep the
3021 substream pointer accessible from the chip instance. For
3022 example, define substream field in the chip record to hold the
3023 current running substream pointer, and set the pointer value
3024 at open callback (and reset at close callback).
3025 </para>
3026
3027 <para>
Adrian Bunk04187262006-06-30 18:23:04 +02003028 If you acquire a spinlock in the interrupt handler, and the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003029 lock is used in other pcm callbacks, too, then you have to
3030 release the lock before calling
3031 <function>snd_pcm_period_elapsed()</function>, because
3032 <function>snd_pcm_period_elapsed()</function> calls other pcm
3033 callbacks inside.
3034 </para>
3035
3036 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003037 Typical code would be like:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003038
3039 <example>
3040 <title>Interrupt Handler Case #1</title>
3041 <programlisting>
3042<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003043 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003044 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003045 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003046 spin_lock(&chip->lock);
3047 ....
3048 if (pcm_irq_invoked(chip)) {
3049 /* call updater, unlock before it */
3050 spin_unlock(&chip->lock);
3051 snd_pcm_period_elapsed(chip->substream);
3052 spin_lock(&chip->lock);
Takashi Iwai95a5b082007-07-26 16:50:09 +02003053 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003054 }
3055 ....
3056 spin_unlock(&chip->lock);
3057 return IRQ_HANDLED;
3058 }
3059]]>
3060 </programlisting>
3061 </example>
3062 </para>
3063 </section>
3064
3065 <section id="pcm-interface-interrupt-handler-timer">
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003066 <title>High frequency timer interrupts</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003067 <para>
Antonio Ospited4dab5a2013-01-29 12:56:28 +01003068 This happens when the hardware doesn't generate interrupts
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003069 at the period boundary but issues timer interrupts at a fixed
Linus Torvalds1da177e2005-04-16 15:20:36 -07003070 timer rate (e.g. es1968 or ymfpci drivers).
3071 In this case, you need to check the current hardware
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003072 position and accumulate the processed sample length at each
3073 interrupt. When the accumulated size exceeds the period
Linus Torvalds1da177e2005-04-16 15:20:36 -07003074 size, call
3075 <function>snd_pcm_period_elapsed()</function> and reset the
3076 accumulator.
3077 </para>
3078
3079 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003080 Typical code would be like the following.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003081
3082 <example>
3083 <title>Interrupt Handler Case #2</title>
3084 <programlisting>
3085<![CDATA[
Takashi Iwaiad4d1de2007-01-16 17:46:35 +01003086 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003087 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003088 struct mychip *chip = dev_id;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003089 spin_lock(&chip->lock);
3090 ....
3091 if (pcm_irq_invoked(chip)) {
3092 unsigned int last_ptr, size;
3093 /* get the current hardware pointer (in frames) */
3094 last_ptr = get_hw_ptr(chip);
3095 /* calculate the processed frames since the
3096 * last update
3097 */
3098 if (last_ptr < chip->last_ptr)
3099 size = runtime->buffer_size + last_ptr
3100 - chip->last_ptr;
3101 else
3102 size = last_ptr - chip->last_ptr;
3103 /* remember the last updated point */
3104 chip->last_ptr = last_ptr;
3105 /* accumulate the size */
3106 chip->size += size;
3107 /* over the period boundary? */
3108 if (chip->size >= runtime->period_size) {
3109 /* reset the accumulator */
3110 chip->size %= runtime->period_size;
3111 /* call updater */
3112 spin_unlock(&chip->lock);
3113 snd_pcm_period_elapsed(substream);
3114 spin_lock(&chip->lock);
3115 }
Takashi Iwai95a5b082007-07-26 16:50:09 +02003116 /* acknowledge the interrupt if necessary */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003117 }
3118 ....
3119 spin_unlock(&chip->lock);
3120 return IRQ_HANDLED;
3121 }
3122]]>
3123 </programlisting>
3124 </example>
3125 </para>
3126 </section>
3127
3128 <section id="pcm-interface-interrupt-handler-both">
3129 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3130 <para>
3131 In both cases, even if more than one period are elapsed, you
3132 don't have to call
3133 <function>snd_pcm_period_elapsed()</function> many times. Call
3134 only once. And the pcm layer will check the current hardware
3135 pointer and update to the latest status.
3136 </para>
3137 </section>
3138 </section>
3139
3140 <section id="pcm-interface-atomicity">
3141 <title>Atomicity</title>
3142 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003143 One of the most important (and thus difficult to debug) problems
3144 in kernel programming are race conditions.
3145 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3146 or semaphores. In general, if a race condition can happen
3147 in an interrupt handler, it has to be managed atomically, and you
3148 have to use a spinlock to protect the critical session. If the
3149 critical section is not in interrupt handler code and
3150 if taking a relatively long time to execute is acceptable, you
3151 should use mutexes or semaphores instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003152 </para>
3153
3154 <para>
3155 As already seen, some pcm callbacks are atomic and some are
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003156 not. For example, the <parameter>hw_params</parameter> callback is
Linus Torvalds1da177e2005-04-16 15:20:36 -07003157 non-atomic, while <parameter>trigger</parameter> callback is
3158 atomic. This means, the latter is called already in a spinlock
3159 held by the PCM middle layer. Please take this atomicity into
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003160 account when you choose a locking scheme in the callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003161 </para>
3162
3163 <para>
3164 In the atomic callbacks, you cannot use functions which may call
3165 <function>schedule</function> or go to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003166 <function>sleep</function>. Semaphores and mutexes can sleep,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003167 and hence they cannot be used inside the atomic callbacks
3168 (e.g. <parameter>trigger</parameter> callback).
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003169 To implement some delay in such a callback, please use
Linus Torvalds1da177e2005-04-16 15:20:36 -07003170 <function>udelay()</function> or <function>mdelay()</function>.
3171 </para>
3172
3173 <para>
3174 All three atomic callbacks (trigger, pointer, and ack) are
3175 called with local interrupts disabled.
3176 </para>
3177
3178 </section>
3179 <section id="pcm-interface-constraints">
3180 <title>Constraints</title>
3181 <para>
3182 If your chip supports unconventional sample rates, or only the
3183 limited samples, you need to set a constraint for the
3184 condition.
3185 </para>
3186
3187 <para>
3188 For example, in order to restrict the sample rates in the some
3189 supported values, use
3190 <function>snd_pcm_hw_constraint_list()</function>.
3191 You need to call this function in the open callback.
3192
3193 <example>
3194 <title>Example of Hardware Constraints</title>
3195 <programlisting>
3196<![CDATA[
3197 static unsigned int rates[] =
3198 {4000, 10000, 22050, 44100};
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003199 static struct snd_pcm_hw_constraint_list constraints_rates = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003200 .count = ARRAY_SIZE(rates),
3201 .list = rates,
3202 .mask = 0,
3203 };
3204
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003205 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003206 {
3207 int err;
3208 ....
3209 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3210 SNDRV_PCM_HW_PARAM_RATE,
3211 &constraints_rates);
3212 if (err < 0)
3213 return err;
3214 ....
3215 }
3216]]>
3217 </programlisting>
3218 </example>
3219 </para>
3220
3221 <para>
3222 There are many different constraints.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003223 Look at <filename>sound/pcm.h</filename> for a complete list.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003224 You can even define your own constraint rules.
3225 For example, let's suppose my_chip can manage a substream of 1 channel
3226 if and only if the format is S16_LE, otherwise it supports any format
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003227 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
Linus Torvalds1da177e2005-04-16 15:20:36 -07003228 other constraint_list). You can build a rule like this:
3229
3230 <example>
3231 <title>Example of Hardware Constraints for Channels</title>
3232 <programlisting>
3233<![CDATA[
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003234 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003235 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003236 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003237 struct snd_interval *c = hw_param_interval(params,
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003238 SNDRV_PCM_HW_PARAM_CHANNELS);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003239 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003240 struct snd_interval ch;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003241
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003242 snd_interval_any(&ch);
3243 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3244 ch.min = ch.max = 1;
3245 ch.integer = 1;
3246 return snd_interval_refine(c, &ch);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003247 }
3248 return 0;
3249 }
3250]]>
3251 </programlisting>
3252 </example>
3253 </para>
3254
3255 <para>
3256 Then you need to call this function to add your rule:
3257
3258 <informalexample>
3259 <programlisting>
3260<![CDATA[
3261 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
Takashi Iwai16c5ab12013-02-05 14:23:53 +01003262 hw_rule_channels_by_format, NULL,
3263 SNDRV_PCM_HW_PARAM_FORMAT, -1);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003264]]>
3265 </programlisting>
3266 </informalexample>
3267 </para>
3268
3269 <para>
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003270 The rule function is called when an application sets the PCM
3271 format, and it refines the number of channels accordingly.
3272 But an application may set the number of channels before
3273 setting the format. Thus you also need to define the inverse rule:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003274
3275 <example>
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003276 <title>Example of Hardware Constraints for Formats</title>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003277 <programlisting>
3278<![CDATA[
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003279 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003280 struct snd_pcm_hw_rule *rule)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003281 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003282 struct snd_interval *c = hw_param_interval(params,
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003283 SNDRV_PCM_HW_PARAM_CHANNELS);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003284 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003285 struct snd_mask fmt;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003286
Takashi Iwaia690a2a2013-02-05 12:24:22 +01003287 snd_mask_any(&fmt); /* Init the struct */
3288 if (c->min < 2) {
3289 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3290 return snd_mask_refine(f, &fmt);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003291 }
3292 return 0;
3293 }
3294]]>
3295 </programlisting>
3296 </example>
3297 </para>
3298
3299 <para>
3300 ...and in the open callback:
3301 <informalexample>
3302 <programlisting>
3303<![CDATA[
3304 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
Takashi Iwai16c5ab12013-02-05 14:23:53 +01003305 hw_rule_format_by_channels, NULL,
3306 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003307]]>
3308 </programlisting>
3309 </informalexample>
3310 </para>
3311
3312 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003313 I won't give more details here, rather I
Linus Torvalds1da177e2005-04-16 15:20:36 -07003314 would like to say, <quote>Luke, use the source.</quote>
3315 </para>
3316 </section>
3317
3318 </chapter>
3319
3320
3321<!-- ****************************************************** -->
3322<!-- Control Interface -->
3323<!-- ****************************************************** -->
3324 <chapter id="control-interface">
3325 <title>Control Interface</title>
3326
3327 <section id="control-interface-general">
3328 <title>General</title>
3329 <para>
3330 The control interface is used widely for many switches,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003331 sliders, etc. which are accessed from user-space. Its most
3332 important use is the mixer interface. In other words, since ALSA
3333 0.9.x, all the mixer stuff is implemented on the control kernel API.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003334 </para>
3335
3336 <para>
3337 ALSA has a well-defined AC97 control module. If your chip
3338 supports only the AC97 and nothing else, you can skip this
3339 section.
3340 </para>
3341
3342 <para>
3343 The control API is defined in
3344 <filename>&lt;sound/control.h&gt;</filename>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003345 Include this file if you want to add your own controls.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003346 </para>
3347 </section>
3348
3349 <section id="control-interface-definition">
3350 <title>Definition of Controls</title>
3351 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003352 To create a new control, you need to define the
3353 following three
Linus Torvalds1da177e2005-04-16 15:20:36 -07003354 callbacks: <structfield>info</structfield>,
3355 <structfield>get</structfield> and
3356 <structfield>put</structfield>. Then, define a
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003357 struct <structname>snd_kcontrol_new</structname> record, such as:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003358
3359 <example>
3360 <title>Definition of a Control</title>
3361 <programlisting>
3362<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01003363 static struct snd_kcontrol_new my_control = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003364 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3365 .name = "PCM Playback Switch",
3366 .index = 0,
3367 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003368 .private_value = 0xffff,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003369 .info = my_control_info,
3370 .get = my_control_get,
3371 .put = my_control_put
3372 };
3373]]>
3374 </programlisting>
3375 </example>
3376 </para>
3377
3378 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003379 The <structfield>iface</structfield> field specifies the control
3380 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
Clemens Ladisch67ed4162005-07-29 15:32:58 +02003381 is usually <constant>MIXER</constant>.
3382 Use <constant>CARD</constant> for global controls that are not
3383 logically part of the mixer.
3384 If the control is closely associated with some specific device on
3385 the sound card, use <constant>HWDEP</constant>,
3386 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3387 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3388 specify the device number with the
3389 <structfield>device</structfield> and
3390 <structfield>subdevice</structfield> fields.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003391 </para>
3392
3393 <para>
3394 The <structfield>name</structfield> is the name identifier
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003395 string. Since ALSA 0.9.x, the control name is very important,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003396 because its role is classified from its name. There are
3397 pre-defined standard control names. The details are described in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003398 the <link linkend="control-interface-control-names"><citetitle>
3399 Control Names</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003400 </para>
3401
3402 <para>
3403 The <structfield>index</structfield> field holds the index number
3404 of this control. If there are several different controls with
3405 the same name, they can be distinguished by the index
3406 number. This is the case when
3407 several codecs exist on the card. If the index is zero, you can
3408 omit the definition above.
3409 </para>
3410
3411 <para>
3412 The <structfield>access</structfield> field contains the access
3413 type of this control. Give the combination of bit masks,
3414 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003415 The details will be explained in
3416 the <link linkend="control-interface-access-flags"><citetitle>
3417 Access Flags</citetitle></link> subsection.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003418 </para>
3419
3420 <para>
Takashi Iwai0b7bed42006-03-02 15:35:55 +01003421 The <structfield>private_value</structfield> field contains
Linus Torvalds1da177e2005-04-16 15:20:36 -07003422 an arbitrary long integer value for this record. When using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003423 the generic <structfield>info</structfield>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003424 <structfield>get</structfield> and
3425 <structfield>put</structfield> callbacks, you can pass a value
3426 through this field. If several small numbers are necessary, you can
3427 combine them in bitwise. Or, it's possible to give a pointer
3428 (casted to unsigned long) of some record to this field, too.
3429 </para>
3430
3431 <para>
Clemens Ladischd1761d12007-09-10 08:05:19 +02003432 The <structfield>tlv</structfield> field can be used to provide
3433 metadata about the control; see the
3434 <link linkend="control-interface-tlv">
3435 <citetitle>Metadata</citetitle></link> subsection.
3436 </para>
3437
3438 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003439 The other three are
3440 <link linkend="control-interface-callbacks"><citetitle>
3441 callback functions</citetitle></link>.
3442 </para>
3443 </section>
3444
3445 <section id="control-interface-control-names">
3446 <title>Control Names</title>
3447 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003448 There are some standards to define the control names. A
Linus Torvalds1da177e2005-04-16 15:20:36 -07003449 control is usually defined from the three parts as
3450 <quote>SOURCE DIRECTION FUNCTION</quote>.
3451 </para>
3452
3453 <para>
3454 The first, <constant>SOURCE</constant>, specifies the source
3455 of the control, and is a string such as <quote>Master</quote>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003456 <quote>PCM</quote>, <quote>CD</quote> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07003457 <quote>Line</quote>. There are many pre-defined sources.
3458 </para>
3459
3460 <para>
3461 The second, <constant>DIRECTION</constant>, is one of the
3462 following strings according to the direction of the control:
3463 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3464 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3465 be omitted, meaning both playback and capture directions.
3466 </para>
3467
3468 <para>
3469 The third, <constant>FUNCTION</constant>, is one of the
3470 following strings according to the function of the control:
3471 <quote>Switch</quote>, <quote>Volume</quote> and
3472 <quote>Route</quote>.
3473 </para>
3474
3475 <para>
3476 The example of control names are, thus, <quote>Master Capture
3477 Switch</quote> or <quote>PCM Playback Volume</quote>.
3478 </para>
3479
3480 <para>
3481 There are some exceptions:
3482 </para>
3483
3484 <section id="control-interface-control-names-global">
3485 <title>Global capture and playback</title>
3486 <para>
3487 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3488 and <quote>Capture Volume</quote> are used for the global
3489 capture (input) source, switch and volume. Similarly,
3490 <quote>Playback Switch</quote> and <quote>Playback
3491 Volume</quote> are used for the global output gain switch and
3492 volume.
3493 </para>
3494 </section>
3495
3496 <section id="control-interface-control-names-tone">
3497 <title>Tone-controls</title>
3498 <para>
3499 tone-control switch and volumes are specified like
3500 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3501 Switch</quote>, <quote>Tone Control - Bass</quote>,
3502 <quote>Tone Control - Center</quote>.
3503 </para>
3504 </section>
3505
3506 <section id="control-interface-control-names-3d">
3507 <title>3D controls</title>
3508 <para>
3509 3D-control switches and volumes are specified like <quote>3D
3510 Control - XXX</quote>, e.g. <quote>3D Control -
3511 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3512 Control - Space</quote>.
3513 </para>
3514 </section>
3515
3516 <section id="control-interface-control-names-mic">
3517 <title>Mic boost</title>
3518 <para>
3519 Mic-boost switch is set as <quote>Mic Boost</quote> or
3520 <quote>Mic Boost (6dB)</quote>.
3521 </para>
3522
3523 <para>
3524 More precise information can be found in
3525 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3526 </para>
3527 </section>
3528 </section>
3529
3530 <section id="control-interface-access-flags">
3531 <title>Access Flags</title>
3532
3533 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003534 The access flag is the bitmask which specifies the access type
Linus Torvalds1da177e2005-04-16 15:20:36 -07003535 of the given control. The default access type is
3536 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3537 which means both read and write are allowed to this control.
3538 When the access flag is omitted (i.e. = 0), it is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003539 considered as <constant>READWRITE</constant> access as default.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003540 </para>
3541
3542 <para>
3543 When the control is read-only, pass
3544 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3545 In this case, you don't have to define
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003546 the <structfield>put</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003547 Similarly, when the control is write-only (although it's a rare
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003548 case), you can use the <constant>WRITE</constant> flag instead, and
3549 you don't need the <structfield>get</structfield> callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003550 </para>
3551
3552 <para>
3553 If the control value changes frequently (e.g. the VU meter),
3554 <constant>VOLATILE</constant> flag should be given. This means
3555 that the control may be changed without
3556 <link linkend="control-interface-change-notification"><citetitle>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003557 notification</citetitle></link>. Applications should poll such
Linus Torvalds1da177e2005-04-16 15:20:36 -07003558 a control constantly.
3559 </para>
3560
3561 <para>
3562 When the control is inactive, set
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003563 the <constant>INACTIVE</constant> flag, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003564 There are <constant>LOCK</constant> and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003565 <constant>OWNER</constant> flags to change the write
Linus Torvalds1da177e2005-04-16 15:20:36 -07003566 permissions.
3567 </para>
3568
3569 </section>
3570
3571 <section id="control-interface-callbacks">
3572 <title>Callbacks</title>
3573
3574 <section id="control-interface-callbacks-info">
3575 <title>info callback</title>
3576 <para>
3577 The <structfield>info</structfield> callback is used to get
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003578 detailed information on this control. This must store the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003579 values of the given struct <structname>snd_ctl_elem_info</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003580 object. For example, for a boolean control with a single
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003581 element:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003582
3583 <example>
3584 <title>Example of info callback</title>
3585 <programlisting>
3586<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003587 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003588 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003589 {
3590 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3591 uinfo->count = 1;
3592 uinfo->value.integer.min = 0;
3593 uinfo->value.integer.max = 1;
3594 return 0;
3595 }
3596]]>
3597 </programlisting>
3598 </example>
3599 </para>
3600
3601 <para>
3602 The <structfield>type</structfield> field specifies the type
3603 of the control. There are <constant>BOOLEAN</constant>,
3604 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3605 <constant>BYTES</constant>, <constant>IEC958</constant> and
3606 <constant>INTEGER64</constant>. The
3607 <structfield>count</structfield> field specifies the
3608 number of elements in this control. For example, a stereo
3609 volume would have count = 2. The
3610 <structfield>value</structfield> field is a union, and
3611 the values stored are depending on the type. The boolean and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003612 integer types are identical.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003613 </para>
3614
3615 <para>
3616 The enumerated type is a bit different from others. You'll
3617 need to set the string for the currently given item index.
3618
3619 <informalexample>
3620 <programlisting>
3621<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003622 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003623 struct snd_ctl_elem_info *uinfo)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003624 {
3625 static char *texts[4] = {
3626 "First", "Second", "Third", "Fourth"
3627 };
3628 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3629 uinfo->count = 1;
3630 uinfo->value.enumerated.items = 4;
3631 if (uinfo->value.enumerated.item > 3)
3632 uinfo->value.enumerated.item = 3;
3633 strcpy(uinfo->value.enumerated.name,
3634 texts[uinfo->value.enumerated.item]);
3635 return 0;
3636 }
3637]]>
3638 </programlisting>
3639 </informalexample>
3640 </para>
Takashi Iwai95a5b082007-07-26 16:50:09 +02003641
3642 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003643 Some common info callbacks are available for your convenience:
Takashi Iwai95a5b082007-07-26 16:50:09 +02003644 <function>snd_ctl_boolean_mono_info()</function> and
3645 <function>snd_ctl_boolean_stereo_info()</function>.
3646 Obviously, the former is an info callback for a mono channel
3647 boolean item, just like <function>snd_myctl_mono_info</function>
3648 above, and the latter is for a stereo channel boolean item.
3649 </para>
3650
Linus Torvalds1da177e2005-04-16 15:20:36 -07003651 </section>
3652
3653 <section id="control-interface-callbacks-get">
3654 <title>get callback</title>
3655
3656 <para>
3657 This callback is used to read the current value of the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003658 control and to return to user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003659 </para>
3660
3661 <para>
3662 For example,
3663
3664 <example>
3665 <title>Example of get callback</title>
3666 <programlisting>
3667<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003668 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3669 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003670 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003671 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003672 ucontrol->value.integer.value[0] = get_some_value(chip);
3673 return 0;
3674 }
3675]]>
3676 </programlisting>
3677 </example>
3678 </para>
3679
3680 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003681 The <structfield>value</structfield> field depends on
3682 the type of control as well as on the info callback. For example,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003683 the sb driver uses this field to store the register offset,
3684 the bit-shift and the bit-mask. The
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003685 <structfield>private_value</structfield> field is set as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07003686 <informalexample>
3687 <programlisting>
3688<![CDATA[
3689 .private_value = reg | (shift << 16) | (mask << 24)
3690]]>
3691 </programlisting>
3692 </informalexample>
3693 and is retrieved in callbacks like
3694 <informalexample>
3695 <programlisting>
3696<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003697 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3698 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003699 {
3700 int reg = kcontrol->private_value & 0xff;
3701 int shift = (kcontrol->private_value >> 16) & 0xff;
3702 int mask = (kcontrol->private_value >> 24) & 0xff;
3703 ....
3704 }
3705]]>
3706 </programlisting>
3707 </informalexample>
3708 </para>
3709
3710 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003711 In the <structfield>get</structfield> callback,
3712 you have to fill all the elements if the
Linus Torvalds1da177e2005-04-16 15:20:36 -07003713 control has more than one elements,
3714 i.e. <structfield>count</structfield> &gt; 1.
3715 In the example above, we filled only one element
3716 (<structfield>value.integer.value[0]</structfield>) since it's
3717 assumed as <structfield>count</structfield> = 1.
3718 </para>
3719 </section>
3720
3721 <section id="control-interface-callbacks-put">
3722 <title>put callback</title>
3723
3724 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003725 This callback is used to write a value from user-space.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003726 </para>
3727
3728 <para>
3729 For example,
3730
3731 <example>
3732 <title>Example of put callback</title>
3733 <programlisting>
3734<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003735 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3736 struct snd_ctl_elem_value *ucontrol)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003737 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003738 struct mychip *chip = snd_kcontrol_chip(kcontrol);
Linus Torvalds1da177e2005-04-16 15:20:36 -07003739 int changed = 0;
3740 if (chip->current_value !=
3741 ucontrol->value.integer.value[0]) {
3742 change_current_value(chip,
3743 ucontrol->value.integer.value[0]);
3744 changed = 1;
3745 }
3746 return changed;
3747 }
3748]]>
3749 </programlisting>
3750 </example>
3751
3752 As seen above, you have to return 1 if the value is
3753 changed. If the value is not changed, return 0 instead.
3754 If any fatal error happens, return a negative error code as
3755 usual.
3756 </para>
3757
3758 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003759 As in the <structfield>get</structfield> callback,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003760 when the control has more than one elements,
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01003761 all elements must be evaluated in this callback, too.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003762 </para>
3763 </section>
3764
3765 <section id="control-interface-callbacks-all">
3766 <title>Callbacks are not atomic</title>
3767 <para>
3768 All these three callbacks are basically not atomic.
3769 </para>
3770 </section>
3771 </section>
3772
3773 <section id="control-interface-constructor">
3774 <title>Constructor</title>
3775 <para>
3776 When everything is ready, finally we can create a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003777 control. To create a control, there are two functions to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07003778 called, <function>snd_ctl_new1()</function> and
3779 <function>snd_ctl_add()</function>.
3780 </para>
3781
3782 <para>
3783 In the simplest way, you can do like this:
3784
3785 <informalexample>
3786 <programlisting>
3787<![CDATA[
Takashi Iwai95a5b082007-07-26 16:50:09 +02003788 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3789 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003790 return err;
3791]]>
3792 </programlisting>
3793 </informalexample>
3794
3795 where <parameter>my_control</parameter> is the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003796 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
Linus Torvalds1da177e2005-04-16 15:20:36 -07003797 is the object pointer to be passed to
3798 kcontrol-&gt;private_data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003799 which can be referred to in callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07003800 </para>
3801
3802 <para>
3803 <function>snd_ctl_new1()</function> allocates a new
Takashi Iwai090015a2012-12-07 07:52:28 +01003804 <structname>snd_kcontrol</structname> instance,
3805 and <function>snd_ctl_add</function> assigns the given
Linus Torvalds1da177e2005-04-16 15:20:36 -07003806 control component to the card.
3807 </para>
3808 </section>
3809
3810 <section id="control-interface-change-notification">
3811 <title>Change Notification</title>
3812 <para>
3813 If you need to change and update a control in the interrupt
3814 routine, you can call <function>snd_ctl_notify()</function>. For
3815 example,
3816
3817 <informalexample>
3818 <programlisting>
3819<![CDATA[
3820 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3821]]>
3822 </programlisting>
3823 </informalexample>
3824
3825 This function takes the card pointer, the event-mask, and the
3826 control id pointer for the notification. The event-mask
3827 specifies the types of notification, for example, in the above
3828 example, the change of control values is notified.
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003829 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003830 to be notified.
3831 You can find some examples in <filename>es1938.c</filename> or
3832 <filename>es1968.c</filename> for hardware volume interrupts.
3833 </para>
3834 </section>
3835
Clemens Ladischd1761d12007-09-10 08:05:19 +02003836 <section id="control-interface-tlv">
3837 <title>Metadata</title>
3838 <para>
3839 To provide information about the dB values of a mixer control, use
3840 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3841 <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3842 containing this information, set the<structfield>tlv.p
3843 </structfield> field to point to this variable, and include the
3844 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3845 <structfield>access</structfield> field; like this:
3846 <informalexample>
3847 <programlisting>
3848<![CDATA[
3849 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3850
Takashi Iwai090015a2012-12-07 07:52:28 +01003851 static struct snd_kcontrol_new my_control = {
Clemens Ladischd1761d12007-09-10 08:05:19 +02003852 ...
3853 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3854 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3855 ...
3856 .tlv.p = db_scale_my_control,
3857 };
3858]]>
3859 </programlisting>
3860 </informalexample>
3861 </para>
3862
3863 <para>
3864 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3865 information about a mixer control where each step in the control's
3866 value changes the dB value by a constant dB amount.
3867 The first parameter is the name of the variable to be defined.
3868 The second parameter is the minimum value, in units of 0.01 dB.
3869 The third parameter is the step size, in units of 0.01 dB.
3870 Set the fourth parameter to 1 if the minimum value actually mutes
3871 the control.
3872 </para>
3873
3874 <para>
3875 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3876 information about a mixer control where the control's value affects
3877 the output linearly.
3878 The first parameter is the name of the variable to be defined.
3879 The second parameter is the minimum value, in units of 0.01 dB.
3880 The third parameter is the maximum value, in units of 0.01 dB.
3881 If the minimum value mutes the control, set the second parameter to
3882 <constant>TLV_DB_GAIN_MUTE</constant>.
3883 </para>
3884 </section>
3885
Linus Torvalds1da177e2005-04-16 15:20:36 -07003886 </chapter>
3887
3888
3889<!-- ****************************************************** -->
3890<!-- API for AC97 Codec -->
3891<!-- ****************************************************** -->
3892 <chapter id="api-ac97">
3893 <title>API for AC97 Codec</title>
3894
3895 <section>
3896 <title>General</title>
3897 <para>
3898 The ALSA AC97 codec layer is a well-defined one, and you don't
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003899 have to write much code to control it. Only low-level control
Linus Torvalds1da177e2005-04-16 15:20:36 -07003900 routines are necessary. The AC97 codec API is defined in
3901 <filename>&lt;sound/ac97_codec.h&gt;</filename>.
3902 </para>
3903 </section>
3904
3905 <section id="api-ac97-example">
3906 <title>Full Code Example</title>
3907 <para>
3908 <example>
3909 <title>Example of AC97 Interface</title>
3910 <programlisting>
3911<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003912 struct mychip {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003913 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003914 struct snd_ac97 *ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003915 ....
3916 };
3917
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003918 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003919 unsigned short reg)
3920 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003921 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003922 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003923 /* read a register value here from the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003924 return the_register_value;
3925 }
3926
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003927 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07003928 unsigned short reg, unsigned short val)
3929 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003930 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003931 ....
Takashi Iwai95a5b082007-07-26 16:50:09 +02003932 /* write the given register value to the codec */
Linus Torvalds1da177e2005-04-16 15:20:36 -07003933 }
3934
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003935 static int snd_mychip_ac97(struct mychip *chip)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003936 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003937 struct snd_ac97_bus *bus;
3938 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003939 int err;
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003940 static struct snd_ac97_bus_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003941 .write = snd_mychip_ac97_write,
3942 .read = snd_mychip_ac97_read,
3943 };
3944
Takashi Iwai95a5b082007-07-26 16:50:09 +02003945 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3946 if (err < 0)
Linus Torvalds1da177e2005-04-16 15:20:36 -07003947 return err;
3948 memset(&ac97, 0, sizeof(ac97));
3949 ac97.private_data = chip;
3950 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3951 }
3952
3953]]>
3954 </programlisting>
3955 </example>
3956 </para>
3957 </section>
3958
3959 <section id="api-ac97-constructor">
3960 <title>Constructor</title>
3961 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02003962 To create an ac97 instance, first call <function>snd_ac97_bus</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003963 with an <type>ac97_bus_ops_t</type> record with callback functions.
3964
3965 <informalexample>
3966 <programlisting>
3967<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003968 struct snd_ac97_bus *bus;
3969 static struct snd_ac97_bus_ops ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07003970 .write = snd_mychip_ac97_write,
3971 .read = snd_mychip_ac97_read,
3972 };
3973
3974 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
3975]]>
3976 </programlisting>
3977 </informalexample>
3978
3979 The bus record is shared among all belonging ac97 instances.
3980 </para>
3981
3982 <para>
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003983 And then call <function>snd_ac97_mixer()</function> with an
3984 struct <structname>snd_ac97_template</structname>
Linus Torvalds1da177e2005-04-16 15:20:36 -07003985 record together with the bus pointer created above.
3986
3987 <informalexample>
3988 <programlisting>
3989<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01003990 struct snd_ac97_template ac97;
Linus Torvalds1da177e2005-04-16 15:20:36 -07003991 int err;
3992
3993 memset(&ac97, 0, sizeof(ac97));
3994 ac97.private_data = chip;
3995 snd_ac97_mixer(bus, &ac97, &chip->ac97);
3996]]>
3997 </programlisting>
3998 </informalexample>
3999
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004000 where chip-&gt;ac97 is a pointer to a newly created
Linus Torvalds1da177e2005-04-16 15:20:36 -07004001 <type>ac97_t</type> instance.
4002 In this case, the chip pointer is set as the private data, so that
4003 the read/write callback functions can refer to this chip instance.
4004 This instance is not necessarily stored in the chip
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004005 record. If you need to change the register values from the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004006 driver, or need the suspend/resume of ac97 codecs, keep this
4007 pointer to pass to the corresponding functions.
4008 </para>
4009 </section>
4010
4011 <section id="api-ac97-callbacks">
4012 <title>Callbacks</title>
4013 <para>
4014 The standard callbacks are <structfield>read</structfield> and
4015 <structfield>write</structfield>. Obviously they
4016 correspond to the functions for read and write accesses to the
4017 hardware low-level codes.
4018 </para>
4019
4020 <para>
4021 The <structfield>read</structfield> callback returns the
4022 register value specified in the argument.
4023
4024 <informalexample>
4025 <programlisting>
4026<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004027 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004028 unsigned short reg)
4029 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004030 struct mychip *chip = ac97->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004031 ....
4032 return the_register_value;
4033 }
4034]]>
4035 </programlisting>
4036 </informalexample>
4037
4038 Here, the chip can be cast from ac97-&gt;private_data.
4039 </para>
4040
4041 <para>
4042 Meanwhile, the <structfield>write</structfield> callback is
4043 used to set the register value.
4044
4045 <informalexample>
4046 <programlisting>
4047<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004048 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004049 unsigned short reg, unsigned short val)
4050]]>
4051 </programlisting>
4052 </informalexample>
4053 </para>
4054
4055 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004056 These callbacks are non-atomic like the control API callbacks.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004057 </para>
4058
4059 <para>
4060 There are also other callbacks:
4061 <structfield>reset</structfield>,
4062 <structfield>wait</structfield> and
4063 <structfield>init</structfield>.
4064 </para>
4065
4066 <para>
4067 The <structfield>reset</structfield> callback is used to reset
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004068 the codec. If the chip requires a special kind of reset, you can
Linus Torvalds1da177e2005-04-16 15:20:36 -07004069 define this callback.
4070 </para>
4071
4072 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004073 The <structfield>wait</structfield> callback is used to
4074 add some waiting time in the standard initialization of the codec. If the
4075 chip requires the extra waiting time, define this callback.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004076 </para>
4077
4078 <para>
4079 The <structfield>init</structfield> callback is used for
4080 additional initialization of the codec.
4081 </para>
4082 </section>
4083
4084 <section id="api-ac97-updating-registers">
4085 <title>Updating Registers in The Driver</title>
4086 <para>
4087 If you need to access to the codec from the driver, you can
4088 call the following functions:
4089 <function>snd_ac97_write()</function>,
4090 <function>snd_ac97_read()</function>,
4091 <function>snd_ac97_update()</function> and
4092 <function>snd_ac97_update_bits()</function>.
4093 </para>
4094
4095 <para>
4096 Both <function>snd_ac97_write()</function> and
4097 <function>snd_ac97_update()</function> functions are used to
4098 set a value to the given register
4099 (<constant>AC97_XXX</constant>). The difference between them is
4100 that <function>snd_ac97_update()</function> doesn't write a
4101 value if the given value has been already set, while
4102 <function>snd_ac97_write()</function> always rewrites the
4103 value.
4104
4105 <informalexample>
4106 <programlisting>
4107<![CDATA[
4108 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4109 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4110]]>
4111 </programlisting>
4112 </informalexample>
4113 </para>
4114
4115 <para>
4116 <function>snd_ac97_read()</function> is used to read the value
4117 of the given register. For example,
4118
4119 <informalexample>
4120 <programlisting>
4121<![CDATA[
4122 value = snd_ac97_read(ac97, AC97_MASTER);
4123]]>
4124 </programlisting>
4125 </informalexample>
4126 </para>
4127
4128 <para>
4129 <function>snd_ac97_update_bits()</function> is used to update
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004130 some bits in the given register.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004131
4132 <informalexample>
4133 <programlisting>
4134<![CDATA[
4135 snd_ac97_update_bits(ac97, reg, mask, value);
4136]]>
4137 </programlisting>
4138 </informalexample>
4139 </para>
4140
4141 <para>
4142 Also, there is a function to change the sample rate (of a
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004143 given register such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07004144 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4145 DRA is supported by the codec:
4146 <function>snd_ac97_set_rate()</function>.
4147
4148 <informalexample>
4149 <programlisting>
4150<![CDATA[
4151 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4152]]>
4153 </programlisting>
4154 </informalexample>
4155 </para>
4156
4157 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004158 The following registers are available to set the rate:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004159 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4160 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4161 <constant>AC97_PCM_LR_ADC_RATE</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004162 <constant>AC97_SPDIF</constant>. When
Linus Torvalds1da177e2005-04-16 15:20:36 -07004163 <constant>AC97_SPDIF</constant> is specified, the register is
4164 not really changed but the corresponding IEC958 status bits will
4165 be updated.
4166 </para>
4167 </section>
4168
4169 <section id="api-ac97-clock-adjustment">
4170 <title>Clock Adjustment</title>
4171 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004172 In some chips, the clock of the codec isn't 48000 but using a
Linus Torvalds1da177e2005-04-16 15:20:36 -07004173 PCI clock (to save a quartz!). In this case, change the field
4174 bus-&gt;clock to the corresponding
4175 value. For example, intel8x0
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004176 and es1968 drivers have their own function to read from the clock.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004177 </para>
4178 </section>
4179
4180 <section id="api-ac97-proc-files">
4181 <title>Proc Files</title>
4182 <para>
4183 The ALSA AC97 interface will create a proc file such as
4184 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4185 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4186 see the current status and registers of the codec.
4187 </para>
4188 </section>
4189
4190 <section id="api-ac97-multiple-codecs">
4191 <title>Multiple Codecs</title>
4192 <para>
4193 When there are several codecs on the same card, you need to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004194 call <function>snd_ac97_mixer()</function> multiple times with
Linus Torvalds1da177e2005-04-16 15:20:36 -07004195 ac97.num=1 or greater. The <structfield>num</structfield> field
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004196 specifies the codec number.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004197 </para>
4198
4199 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004200 If you set up multiple codecs, you either need to write
Linus Torvalds1da177e2005-04-16 15:20:36 -07004201 different callbacks for each codec or check
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004202 ac97-&gt;num in the callback routines.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004203 </para>
4204 </section>
4205
4206 </chapter>
4207
4208
4209<!-- ****************************************************** -->
4210<!-- MIDI (MPU401-UART) Interface -->
4211<!-- ****************************************************** -->
4212 <chapter id="midi-interface">
4213 <title>MIDI (MPU401-UART) Interface</title>
4214
4215 <section id="midi-interface-general">
4216 <title>General</title>
4217 <para>
4218 Many soundcards have built-in MIDI (MPU401-UART)
4219 interfaces. When the soundcard supports the standard MPU401-UART
4220 interface, most likely you can use the ALSA MPU401-UART API. The
4221 MPU401-UART API is defined in
4222 <filename>&lt;sound/mpu401.h&gt;</filename>.
4223 </para>
4224
4225 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004226 Some soundchips have a similar but slightly different
Linus Torvalds1da177e2005-04-16 15:20:36 -07004227 implementation of mpu401 stuff. For example, emu10k1 has its own
4228 mpu401 routines.
4229 </para>
4230 </section>
4231
4232 <section id="midi-interface-constructor">
4233 <title>Constructor</title>
4234 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004235 To create a rawmidi object, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004236 <function>snd_mpu401_uart_new()</function>.
4237
4238 <informalexample>
4239 <programlisting>
4240<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004241 struct snd_rawmidi *rmidi;
Takashi Iwai302e4c22006-05-23 13:24:30 +02004242 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
Clemens Ladischdba8b462011-09-13 11:24:41 +02004243 irq, &rmidi);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004244]]>
4245 </programlisting>
4246 </informalexample>
4247 </para>
4248
4249 <para>
4250 The first argument is the card pointer, and the second is the
4251 index of this component. You can create up to 8 rawmidi
4252 devices.
4253 </para>
4254
4255 <para>
4256 The third argument is the type of the hardware,
4257 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4258 you can use <constant>MPU401_HW_MPU401</constant>.
4259 </para>
4260
4261 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004262 The 4th argument is the I/O port address. Many
4263 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4264 might be a part of its own PCI I/O region. It depends on the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004265 chip design.
4266 </para>
4267
4268 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004269 The 5th argument is a bitflag for additional information.
4270 When the I/O port address above is part of the PCI I/O
4271 region, the MPU401 I/O port might have been already allocated
Takashi Iwai302e4c22006-05-23 13:24:30 +02004272 (reserved) by the driver itself. In such a case, pass a bit flag
4273 <constant>MPU401_INFO_INTEGRATED</constant>,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004274 and the mpu401-uart layer will allocate the I/O ports by itself.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004275 </para>
4276
Takashi Iwai302e4c22006-05-23 13:24:30 +02004277 <para>
4278 When the controller supports only the input or output MIDI stream,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004279 pass the <constant>MPU401_INFO_INPUT</constant> or
Takashi Iwai302e4c22006-05-23 13:24:30 +02004280 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4281 Then the rawmidi instance is created as a single stream.
4282 </para>
4283
4284 <para>
4285 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4286 the access method to MMIO (via readb and writeb) instead of
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004287 iob and outb. In this case, you have to pass the iomapped address
Takashi Iwai302e4c22006-05-23 13:24:30 +02004288 to <function>snd_mpu401_uart_new()</function>.
4289 </para>
4290
4291 <para>
4292 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4293 stream isn't checked in the default interrupt handler. The driver
4294 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004295 by itself to start processing the output stream in the irq handler.
Takashi Iwai302e4c22006-05-23 13:24:30 +02004296 </para>
4297
Clemens Ladischdba8b462011-09-13 11:24:41 +02004298 <para>
4299 If the MPU-401 interface shares its interrupt with the other logical
4300 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4301 (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4302 below</citetitle></link>).
4303 </para>
4304
Linus Torvalds1da177e2005-04-16 15:20:36 -07004305 <para>
4306 Usually, the port address corresponds to the command port and
4307 port + 1 corresponds to the data port. If not, you may change
4308 the <structfield>cport</structfield> field of
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004309 struct <structname>snd_mpu401</structname> manually
4310 afterward. However, <structname>snd_mpu401</structname> pointer is not
Linus Torvalds1da177e2005-04-16 15:20:36 -07004311 returned explicitly by
4312 <function>snd_mpu401_uart_new()</function>. You need to cast
4313 rmidi-&gt;private_data to
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004314 <structname>snd_mpu401</structname> explicitly,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004315
4316 <informalexample>
4317 <programlisting>
4318<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004319 struct snd_mpu401 *mpu;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004320 mpu = rmidi->private_data;
4321]]>
4322 </programlisting>
4323 </informalexample>
4324
4325 and reset the cport as you like:
4326
4327 <informalexample>
4328 <programlisting>
4329<![CDATA[
4330 mpu->cport = my_own_control_port;
4331]]>
4332 </programlisting>
4333 </informalexample>
4334 </para>
4335
4336 <para>
Clemens Ladischdba8b462011-09-13 11:24:41 +02004337 The 6th argument specifies the ISA irq number that will be
4338 allocated. If no interrupt is to be allocated (because your
4339 code is already allocating a shared interrupt, or because the
4340 device does not use interrupts), pass -1 instead.
4341 For a MPU-401 device without an interrupt, a polling timer
4342 will be used instead.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004343 </para>
4344 </section>
4345
4346 <section id="midi-interface-interrupt-handler">
4347 <title>Interrupt Handler</title>
4348 <para>
4349 When the interrupt is allocated in
Clemens Ladischdba8b462011-09-13 11:24:41 +02004350 <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4351 interrupt handler is automatically used, hence you don't have
4352 anything else to do than creating the mpu401 stuff. Otherwise, you
4353 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4354 <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4355 own interrupt handler when it has determined that a UART interrupt
4356 has occurred.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004357 </para>
4358
4359 <para>
4360 In this case, you need to pass the private_data of the
4361 returned rawmidi object from
4362 <function>snd_mpu401_uart_new()</function> as the second
4363 argument of <function>snd_mpu401_uart_interrupt()</function>.
4364
4365 <informalexample>
4366 <programlisting>
4367<![CDATA[
4368 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4369]]>
4370 </programlisting>
4371 </informalexample>
4372 </para>
4373 </section>
4374
4375 </chapter>
4376
4377
4378<!-- ****************************************************** -->
4379<!-- RawMIDI Interface -->
4380<!-- ****************************************************** -->
4381 <chapter id="rawmidi-interface">
4382 <title>RawMIDI Interface</title>
4383
4384 <section id="rawmidi-interface-overview">
4385 <title>Overview</title>
4386
4387 <para>
4388 The raw MIDI interface is used for hardware MIDI ports that can
4389 be accessed as a byte stream. It is not used for synthesizer
4390 chips that do not directly understand MIDI.
4391 </para>
4392
4393 <para>
4394 ALSA handles file and buffer management. All you have to do is
4395 to write some code to move data between the buffer and the
4396 hardware.
4397 </para>
4398
4399 <para>
4400 The rawmidi API is defined in
4401 <filename>&lt;sound/rawmidi.h&gt;</filename>.
4402 </para>
4403 </section>
4404
4405 <section id="rawmidi-interface-constructor">
4406 <title>Constructor</title>
4407
4408 <para>
4409 To create a rawmidi device, call the
4410 <function>snd_rawmidi_new</function> function:
4411 <informalexample>
4412 <programlisting>
4413<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004414 struct snd_rawmidi *rmidi;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004415 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4416 if (err < 0)
4417 return err;
4418 rmidi->private_data = chip;
4419 strcpy(rmidi->name, "My MIDI");
4420 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4421 SNDRV_RAWMIDI_INFO_INPUT |
4422 SNDRV_RAWMIDI_INFO_DUPLEX;
4423]]>
4424 </programlisting>
4425 </informalexample>
4426 </para>
4427
4428 <para>
4429 The first argument is the card pointer, the second argument is
4430 the ID string.
4431 </para>
4432
4433 <para>
4434 The third argument is the index of this component. You can
4435 create up to 8 rawmidi devices.
4436 </para>
4437
4438 <para>
4439 The fourth and fifth arguments are the number of output and
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004440 input substreams, respectively, of this device (a substream is
4441 the equivalent of a MIDI port).
Linus Torvalds1da177e2005-04-16 15:20:36 -07004442 </para>
4443
4444 <para>
4445 Set the <structfield>info_flags</structfield> field to specify
4446 the capabilities of the device.
4447 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4448 at least one output port,
4449 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4450 least one input port,
4451 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4452 can handle output and input at the same time.
4453 </para>
4454
4455 <para>
4456 After the rawmidi device is created, you need to set the
4457 operators (callbacks) for each substream. There are helper
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004458 functions to set the operators for all the substreams of a device:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004459 <informalexample>
4460 <programlisting>
4461<![CDATA[
4462 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4463 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4464]]>
4465 </programlisting>
4466 </informalexample>
4467 </para>
4468
4469 <para>
4470 The operators are usually defined like this:
4471 <informalexample>
4472 <programlisting>
4473<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004474 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004475 .open = snd_mymidi_output_open,
4476 .close = snd_mymidi_output_close,
4477 .trigger = snd_mymidi_output_trigger,
4478 };
4479]]>
4480 </programlisting>
4481 </informalexample>
4482 These callbacks are explained in the <link
4483 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4484 section.
4485 </para>
4486
4487 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004488 If there are more than one substream, you should give a
4489 unique name to each of them:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004490 <informalexample>
4491 <programlisting>
4492<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004493 struct snd_rawmidi_substream *substream;
Takashi Iwai95a5b082007-07-26 16:50:09 +02004494 list_for_each_entry(substream,
4495 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4496 list {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004497 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4498 }
4499 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4500]]>
4501 </programlisting>
4502 </informalexample>
4503 </para>
4504 </section>
4505
4506 <section id="rawmidi-interface-callbacks">
4507 <title>Callbacks</title>
4508
4509 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004510 In all the callbacks, the private data that you've set for the
Linus Torvalds1da177e2005-04-16 15:20:36 -07004511 rawmidi device can be accessed as
4512 substream-&gt;rmidi-&gt;private_data.
4513 <!-- <code> isn't available before DocBook 4.3 -->
4514 </para>
4515
4516 <para>
4517 If there is more than one port, your callbacks can determine the
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004518 port index from the struct snd_rawmidi_substream data passed to each
Linus Torvalds1da177e2005-04-16 15:20:36 -07004519 callback:
4520 <informalexample>
4521 <programlisting>
4522<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004523 struct snd_rawmidi_substream *substream;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004524 int index = substream->number;
4525]]>
4526 </programlisting>
4527 </informalexample>
4528 </para>
4529
4530 <section id="rawmidi-interface-op-open">
4531 <title><function>open</function> callback</title>
4532
4533 <informalexample>
4534 <programlisting>
4535<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004536 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004537]]>
4538 </programlisting>
4539 </informalexample>
4540
4541 <para>
4542 This is called when a substream is opened.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004543 You can initialize the hardware here, but you shouldn't
4544 start transmitting/receiving data yet.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004545 </para>
4546 </section>
4547
4548 <section id="rawmidi-interface-op-close">
4549 <title><function>close</function> callback</title>
4550
4551 <informalexample>
4552 <programlisting>
4553<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004554 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004555]]>
4556 </programlisting>
4557 </informalexample>
4558
4559 <para>
4560 Guess what.
4561 </para>
4562
4563 <para>
4564 The <function>open</function> and <function>close</function>
4565 callbacks of a rawmidi device are serialized with a mutex,
4566 and can sleep.
4567 </para>
4568 </section>
4569
4570 <section id="rawmidi-interface-op-trigger-out">
4571 <title><function>trigger</function> callback for output
4572 substreams</title>
4573
4574 <informalexample>
4575 <programlisting>
4576<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004577 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004578]]>
4579 </programlisting>
4580 </informalexample>
4581
4582 <para>
4583 This is called with a nonzero <parameter>up</parameter>
4584 parameter when there is some data in the substream buffer that
4585 must be transmitted.
4586 </para>
4587
4588 <para>
4589 To read data from the buffer, call
4590 <function>snd_rawmidi_transmit_peek</function>. It will
4591 return the number of bytes that have been read; this will be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004592 less than the number of bytes requested when there are no more
Linus Torvalds1da177e2005-04-16 15:20:36 -07004593 data in the buffer.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004594 After the data have been transmitted successfully, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07004595 <function>snd_rawmidi_transmit_ack</function> to remove the
4596 data from the substream buffer:
4597 <informalexample>
4598 <programlisting>
4599<![CDATA[
4600 unsigned char data;
4601 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004602 if (snd_mychip_try_to_transmit(data))
Linus Torvalds1da177e2005-04-16 15:20:36 -07004603 snd_rawmidi_transmit_ack(substream, 1);
4604 else
4605 break; /* hardware FIFO full */
4606 }
4607]]>
4608 </programlisting>
4609 </informalexample>
4610 </para>
4611
4612 <para>
4613 If you know beforehand that the hardware will accept data, you
4614 can use the <function>snd_rawmidi_transmit</function> function
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004615 which reads some data and removes them from the buffer at once:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004616 <informalexample>
4617 <programlisting>
4618<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004619 while (snd_mychip_transmit_possible()) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07004620 unsigned char data;
4621 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4622 break; /* no more data */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004623 snd_mychip_transmit(data);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004624 }
4625]]>
4626 </programlisting>
4627 </informalexample>
4628 </para>
4629
4630 <para>
4631 If you know beforehand how many bytes you can accept, you can
4632 use a buffer size greater than one with the
4633 <function>snd_rawmidi_transmit*</function> functions.
4634 </para>
4635
4636 <para>
4637 The <function>trigger</function> callback must not sleep. If
4638 the hardware FIFO is full before the substream buffer has been
4639 emptied, you have to continue transmitting data later, either
4640 in an interrupt handler, or with a timer if the hardware
4641 doesn't have a MIDI transmit interrupt.
4642 </para>
4643
4644 <para>
4645 The <function>trigger</function> callback is called with a
4646 zero <parameter>up</parameter> parameter when the transmission
4647 of data should be aborted.
4648 </para>
4649 </section>
4650
4651 <section id="rawmidi-interface-op-trigger-in">
4652 <title><function>trigger</function> callback for input
4653 substreams</title>
4654
4655 <informalexample>
4656 <programlisting>
4657<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004658 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004659]]>
4660 </programlisting>
4661 </informalexample>
4662
4663 <para>
4664 This is called with a nonzero <parameter>up</parameter>
4665 parameter to enable receiving data, or with a zero
4666 <parameter>up</parameter> parameter do disable receiving data.
4667 </para>
4668
4669 <para>
4670 The <function>trigger</function> callback must not sleep; the
4671 actual reading of data from the device is usually done in an
4672 interrupt handler.
4673 </para>
4674
4675 <para>
4676 When data reception is enabled, your interrupt handler should
4677 call <function>snd_rawmidi_receive</function> for all received
4678 data:
4679 <informalexample>
4680 <programlisting>
4681<![CDATA[
4682 void snd_mychip_midi_interrupt(...)
4683 {
4684 while (mychip_midi_available()) {
4685 unsigned char data;
4686 data = mychip_midi_read();
4687 snd_rawmidi_receive(substream, &data, 1);
4688 }
4689 }
4690]]>
4691 </programlisting>
4692 </informalexample>
4693 </para>
4694 </section>
4695
4696 <section id="rawmidi-interface-op-drain">
4697 <title><function>drain</function> callback</title>
4698
4699 <informalexample>
4700 <programlisting>
4701<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004702 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004703]]>
4704 </programlisting>
4705 </informalexample>
4706
4707 <para>
4708 This is only used with output substreams. This function should wait
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004709 until all data read from the substream buffer have been transmitted.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004710 This ensures that the device can be closed and the driver unloaded
4711 without losing data.
4712 </para>
4713
4714 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004715 This callback is optional. If you do not set
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004716 <structfield>drain</structfield> in the struct snd_rawmidi_ops
Linus Torvalds1da177e2005-04-16 15:20:36 -07004717 structure, ALSA will simply wait for 50&nbsp;milliseconds
4718 instead.
4719 </para>
4720 </section>
4721 </section>
4722
4723 </chapter>
4724
4725
4726<!-- ****************************************************** -->
4727<!-- Miscellaneous Devices -->
4728<!-- ****************************************************** -->
4729 <chapter id="misc-devices">
4730 <title>Miscellaneous Devices</title>
4731
4732 <section id="misc-devices-opl3">
4733 <title>FM OPL3</title>
4734 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004735 The FM OPL3 is still used in many chips (mainly for backward
Linus Torvalds1da177e2005-04-16 15:20:36 -07004736 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4737 OPL3 API is defined in
4738 <filename>&lt;sound/opl3.h&gt;</filename>.
4739 </para>
4740
4741 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004742 FM registers can be directly accessed through the direct-FM API,
Linus Torvalds1da177e2005-04-16 15:20:36 -07004743 defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4744 ALSA native mode, FM registers are accessed through
Lucas De Marchi25985ed2011-03-30 22:57:33 -03004745 the Hardware-Dependent Device direct-FM extension API, whereas in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004746 OSS compatible mode, FM registers can be accessed with the OSS
4747 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004748 </para>
4749
4750 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004751 To create the OPL3 component, you have two functions to
4752 call. The first one is a constructor for the <type>opl3_t</type>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004753 instance.
4754
4755 <informalexample>
4756 <programlisting>
4757<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004758 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004759 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4760 integrated, &opl3);
4761]]>
4762 </programlisting>
4763 </informalexample>
4764 </para>
4765
4766 <para>
4767 The first argument is the card pointer, the second one is the
4768 left port address, and the third is the right port address. In
4769 most cases, the right port is placed at the left port + 2.
4770 </para>
4771
4772 <para>
4773 The fourth argument is the hardware type.
4774 </para>
4775
4776 <para>
4777 When the left and right ports have been already allocated by
4778 the card driver, pass non-zero to the fifth argument
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004779 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
Linus Torvalds1da177e2005-04-16 15:20:36 -07004780 allocate the specified ports by itself.
4781 </para>
4782
4783 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004784 When the accessing the hardware requires special method
Linus Torvalds1da177e2005-04-16 15:20:36 -07004785 instead of the standard I/O access, you can create opl3 instance
4786 separately with <function>snd_opl3_new()</function>.
4787
4788 <informalexample>
4789 <programlisting>
4790<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004791 struct snd_opl3 *opl3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004792 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4793]]>
4794 </programlisting>
4795 </informalexample>
4796 </para>
4797
4798 <para>
4799 Then set <structfield>command</structfield>,
4800 <structfield>private_data</structfield> and
4801 <structfield>private_free</structfield> for the private
4802 access function, the private data and the destructor.
4803 The l_port and r_port are not necessarily set. Only the
4804 command must be set properly. You can retrieve the data
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004805 from the opl3-&gt;private_data field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004806 </para>
4807
4808 <para>
4809 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4810 call <function>snd_opl3_init()</function> to initialize the chip to the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004811 proper state. Note that <function>snd_opl3_create()</function> always
Linus Torvalds1da177e2005-04-16 15:20:36 -07004812 calls it internally.
4813 </para>
4814
4815 <para>
4816 If the opl3 instance is created successfully, then create a
4817 hwdep device for this opl3.
4818
4819 <informalexample>
4820 <programlisting>
4821<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004822 struct snd_hwdep *opl3hwdep;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004823 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4824]]>
4825 </programlisting>
4826 </informalexample>
4827 </para>
4828
4829 <para>
4830 The first argument is the <type>opl3_t</type> instance you
4831 created, and the second is the index number, usually 0.
4832 </para>
4833
4834 <para>
4835 The third argument is the index-offset for the sequencer
4836 client assigned to the OPL3 port. When there is an MPU401-UART,
4837 give 1 for here (UART always takes 0).
4838 </para>
4839 </section>
4840
4841 <section id="misc-devices-hardware-dependent">
4842 <title>Hardware-Dependent Devices</title>
4843 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004844 Some chips need user-space access for special
Linus Torvalds1da177e2005-04-16 15:20:36 -07004845 controls or for loading the micro code. In such a case, you can
4846 create a hwdep (hardware-dependent) device. The hwdep API is
4847 defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4848 find examples in opl3 driver or
4849 <filename>isa/sb/sb16_csp.c</filename>.
4850 </para>
4851
4852 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004853 The creation of the <type>hwdep</type> instance is done via
Linus Torvalds1da177e2005-04-16 15:20:36 -07004854 <function>snd_hwdep_new()</function>.
4855
4856 <informalexample>
4857 <programlisting>
4858<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004859 struct snd_hwdep *hw;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004860 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4861]]>
4862 </programlisting>
4863 </informalexample>
4864
4865 where the third argument is the index number.
4866 </para>
4867
4868 <para>
4869 You can then pass any pointer value to the
4870 <parameter>private_data</parameter>.
4871 If you assign a private data, you should define the
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004872 destructor, too. The destructor function is set in
4873 the <structfield>private_free</structfield> field.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004874
4875 <informalexample>
4876 <programlisting>
4877<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004878 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
Linus Torvalds1da177e2005-04-16 15:20:36 -07004879 hw->private_data = p;
4880 hw->private_free = mydata_free;
4881]]>
4882 </programlisting>
4883 </informalexample>
4884
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004885 and the implementation of the destructor would be:
Linus Torvalds1da177e2005-04-16 15:20:36 -07004886
4887 <informalexample>
4888 <programlisting>
4889<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004890 static void mydata_free(struct snd_hwdep *hw)
Linus Torvalds1da177e2005-04-16 15:20:36 -07004891 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01004892 struct mydata *p = hw->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07004893 kfree(p);
4894 }
4895]]>
4896 </programlisting>
4897 </informalexample>
4898 </para>
4899
4900 <para>
4901 The arbitrary file operations can be defined for this
4902 instance. The file operators are defined in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004903 the <parameter>ops</parameter> table. For example, assume that
Linus Torvalds1da177e2005-04-16 15:20:36 -07004904 this chip needs an ioctl.
4905
4906 <informalexample>
4907 <programlisting>
4908<![CDATA[
4909 hw->ops.open = mydata_open;
4910 hw->ops.ioctl = mydata_ioctl;
4911 hw->ops.release = mydata_release;
4912]]>
4913 </programlisting>
4914 </informalexample>
4915
4916 And implement the callback functions as you like.
4917 </para>
4918 </section>
4919
4920 <section id="misc-devices-IEC958">
4921 <title>IEC958 (S/PDIF)</title>
4922 <para>
4923 Usually the controls for IEC958 devices are implemented via
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004924 the control interface. There is a macro to compose a name string for
Linus Torvalds1da177e2005-04-16 15:20:36 -07004925 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4926 defined in <filename>&lt;include/asound.h&gt;</filename>.
4927 </para>
4928
4929 <para>
4930 There are some standard controls for IEC958 status bits. These
4931 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4932 and the size of element is fixed as 4 bytes array
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004933 (value.iec958.status[x]). For the <structfield>info</structfield>
Linus Torvalds1da177e2005-04-16 15:20:36 -07004934 callback, you don't specify
4935 the value field for this type (the count field must be set,
4936 though).
4937 </para>
4938
4939 <para>
4940 <quote>IEC958 Playback Con Mask</quote> is used to return the
4941 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4942 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4943 professional mode. They are read-only controls, and are defined
4944 as MIXER controls (iface =
4945 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4946 </para>
4947
4948 <para>
4949 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4950 defined for getting and setting the current default IEC958
4951 bits. Note that this one is usually defined as a PCM control
4952 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4953 although in some places it's defined as a MIXER control.
4954 </para>
4955
4956 <para>
4957 In addition, you can define the control switches to
4958 enable/disable or to set the raw bit mode. The implementation
4959 will depend on the chip, but the control should be named as
4960 <quote>IEC958 xxx</quote>, preferably using
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004961 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004962 </para>
4963
4964 <para>
4965 You can find several cases, for example,
4966 <filename>pci/emu10k1</filename>,
4967 <filename>pci/ice1712</filename>, or
4968 <filename>pci/cmipci.c</filename>.
4969 </para>
4970 </section>
4971
4972 </chapter>
4973
4974
4975<!-- ****************************************************** -->
4976<!-- Buffer and Memory Management -->
4977<!-- ****************************************************** -->
4978 <chapter id="buffer-and-memory">
4979 <title>Buffer and Memory Management</title>
4980
4981 <section id="buffer-and-memory-buffer-types">
4982 <title>Buffer Types</title>
4983 <para>
4984 ALSA provides several different buffer allocation functions
4985 depending on the bus and the architecture. All these have a
4986 consistent API. The allocation of physically-contiguous pages is
4987 done via
4988 <function>snd_malloc_xxx_pages()</function> function, where xxx
4989 is the bus type.
4990 </para>
4991
4992 <para>
4993 The allocation of pages with fallback is
4994 <function>snd_malloc_xxx_pages_fallback()</function>. This
4995 function tries to allocate the specified pages but if the pages
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02004996 are not available, it tries to reduce the page sizes until
Linus Torvalds1da177e2005-04-16 15:20:36 -07004997 enough space is found.
4998 </para>
4999
5000 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005001 The release the pages, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005002 <function>snd_free_xxx_pages()</function> function.
5003 </para>
5004
5005 <para>
5006 Usually, ALSA drivers try to allocate and reserve
5007 a large contiguous physical space
5008 at the time the module is loaded for the later use.
5009 This is called <quote>pre-allocation</quote>.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005010 As already written, you can call the following function at
5011 pcm instance construction time (in the case of PCI bus).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005012
5013 <informalexample>
5014 <programlisting>
5015<![CDATA[
5016 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5017 snd_dma_pci_data(pci), size, max);
5018]]>
5019 </programlisting>
5020 </informalexample>
5021
5022 where <parameter>size</parameter> is the byte size to be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005023 pre-allocated and the <parameter>max</parameter> is the maximum
5024 size to be changed via the <filename>prealloc</filename> proc file.
5025 The allocator will try to get an area as large as possible
Linus Torvalds1da177e2005-04-16 15:20:36 -07005026 within the given size.
5027 </para>
5028
5029 <para>
5030 The second argument (type) and the third argument (device pointer)
5031 are dependent on the bus.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005032 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005033 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5034 For the continuous buffer unrelated to the bus can be pre-allocated
5035 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5036 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005037 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
David S. Miller759ee812008-08-27 00:33:26 -07005038 use.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005039 For the PCI scatter-gather buffers, use
5040 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5041 <function>snd_dma_pci_data(pci)</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005042 (see the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005043 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005044 </citetitle></link> section).
Linus Torvalds1da177e2005-04-16 15:20:36 -07005045 </para>
5046
5047 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005048 Once the buffer is pre-allocated, you can use the
5049 allocator in the <structfield>hw_params</structfield> callback:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005050
5051 <informalexample>
5052 <programlisting>
5053<![CDATA[
5054 snd_pcm_lib_malloc_pages(substream, size);
5055]]>
5056 </programlisting>
5057 </informalexample>
5058
5059 Note that you have to pre-allocate to use this function.
5060 </para>
5061 </section>
5062
5063 <section id="buffer-and-memory-external-hardware">
5064 <title>External Hardware Buffers</title>
5065 <para>
5066 Some chips have their own hardware buffers and the DMA
5067 transfer from the host memory is not available. In such a case,
5068 you need to either 1) copy/set the audio data directly to the
5069 external hardware buffer, or 2) make an intermediate buffer and
5070 copy/set the data from it to the external hardware buffer in
5071 interrupts (or in tasklets, preferably).
5072 </para>
5073
5074 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005075 The first case works fine if the external hardware buffer is large
5076 enough. This method doesn't need any extra buffers and thus is
Linus Torvalds1da177e2005-04-16 15:20:36 -07005077 more effective. You need to define the
5078 <structfield>copy</structfield> and
5079 <structfield>silence</structfield> callbacks for
5080 the data transfer. However, there is a drawback: it cannot
5081 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5082 wavetable PCM.
5083 </para>
5084
5085 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005086 The second case allows for mmap on the buffer, although you have
5087 to handle an interrupt or a tasklet to transfer the data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005088 from the intermediate buffer to the hardware buffer. You can find an
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005089 example in the vxpocket driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005090 </para>
5091
5092 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005093 Another case is when the chip uses a PCI memory-map
Linus Torvalds1da177e2005-04-16 15:20:36 -07005094 region for the buffer instead of the host memory. In this case,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005095 mmap is available only on certain architectures like the Intel one.
5096 In non-mmap mode, the data cannot be transferred as in the normal
5097 way. Thus you need to define the <structfield>copy</structfield> and
5098 <structfield>silence</structfield> callbacks as well,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005099 as in the cases above. The examples are found in
5100 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5101 </para>
5102
5103 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005104 The implementation of the <structfield>copy</structfield> and
Linus Torvalds1da177e2005-04-16 15:20:36 -07005105 <structfield>silence</structfield> callbacks depends upon
5106 whether the hardware supports interleaved or non-interleaved
5107 samples. The <structfield>copy</structfield> callback is
5108 defined like below, a bit
5109 differently depending whether the direction is playback or
5110 capture:
5111
5112 <informalexample>
5113 <programlisting>
5114<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005115 static int playback_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005116 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005117 static int capture_copy(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005118 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5119]]>
5120 </programlisting>
5121 </informalexample>
5122 </para>
5123
5124 <para>
5125 In the case of interleaved samples, the second argument
5126 (<parameter>channel</parameter>) is not used. The third argument
5127 (<parameter>pos</parameter>) points the
5128 current position offset in frames.
5129 </para>
5130
5131 <para>
5132 The meaning of the fourth argument is different between
5133 playback and capture. For playback, it holds the source data
5134 pointer, and for capture, it's the destination data pointer.
5135 </para>
5136
5137 <para>
5138 The last argument is the number of frames to be copied.
5139 </para>
5140
5141 <para>
5142 What you have to do in this callback is again different
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005143 between playback and capture directions. In the
5144 playback case, you copy the given amount of data
Linus Torvalds1da177e2005-04-16 15:20:36 -07005145 (<parameter>count</parameter>) at the specified pointer
5146 (<parameter>src</parameter>) to the specified offset
5147 (<parameter>pos</parameter>) on the hardware buffer. When
5148 coded like memcpy-like way, the copy would be like:
5149
5150 <informalexample>
5151 <programlisting>
5152<![CDATA[
5153 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5154 frames_to_bytes(runtime, count));
5155]]>
5156 </programlisting>
5157 </informalexample>
5158 </para>
5159
5160 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005161 For the capture direction, you copy the given amount of
Linus Torvalds1da177e2005-04-16 15:20:36 -07005162 data (<parameter>count</parameter>) at the specified offset
5163 (<parameter>pos</parameter>) on the hardware buffer to the
5164 specified pointer (<parameter>dst</parameter>).
5165
5166 <informalexample>
5167 <programlisting>
5168<![CDATA[
5169 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5170 frames_to_bytes(runtime, count));
5171]]>
5172 </programlisting>
5173 </informalexample>
5174
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005175 Note that both the position and the amount of data are given
Linus Torvalds1da177e2005-04-16 15:20:36 -07005176 in frames.
5177 </para>
5178
5179 <para>
5180 In the case of non-interleaved samples, the implementation
5181 will be a bit more complicated.
5182 </para>
5183
5184 <para>
5185 You need to check the channel argument, and if it's -1, copy
5186 the whole channels. Otherwise, you have to copy only the
5187 specified channel. Please check
5188 <filename>isa/gus/gus_pcm.c</filename> as an example.
5189 </para>
5190
5191 <para>
5192 The <structfield>silence</structfield> callback is also
5193 implemented in a similar way.
5194
5195 <informalexample>
5196 <programlisting>
5197<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005198 static int silence(struct snd_pcm_substream *substream, int channel,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005199 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5200]]>
5201 </programlisting>
5202 </informalexample>
5203 </para>
5204
5205 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005206 The meanings of arguments are the same as in the
Linus Torvalds1da177e2005-04-16 15:20:36 -07005207 <structfield>copy</structfield>
5208 callback, although there is no <parameter>src/dst</parameter>
5209 argument. In the case of interleaved samples, the channel
5210 argument has no meaning, as well as on
5211 <structfield>copy</structfield> callback.
5212 </para>
5213
5214 <para>
5215 The role of <structfield>silence</structfield> callback is to
5216 set the given amount
5217 (<parameter>count</parameter>) of silence data at the
5218 specified offset (<parameter>pos</parameter>) on the hardware
5219 buffer. Suppose that the data format is signed (that is, the
5220 silent-data is 0), and the implementation using a memset-like
5221 function would be like:
5222
5223 <informalexample>
5224 <programlisting>
5225<![CDATA[
5226 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5227 frames_to_bytes(runtime, count));
5228]]>
5229 </programlisting>
5230 </informalexample>
5231 </para>
5232
5233 <para>
5234 In the case of non-interleaved samples, again, the
5235 implementation becomes a bit more complicated. See, for example,
5236 <filename>isa/gus/gus_pcm.c</filename>.
5237 </para>
5238 </section>
5239
5240 <section id="buffer-and-memory-non-contiguous">
5241 <title>Non-Contiguous Buffers</title>
5242 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005243 If your hardware supports the page table as in emu10k1 or the
5244 buffer descriptors as in via82xx, you can use the scatter-gather
Linus Torvalds1da177e2005-04-16 15:20:36 -07005245 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5246 The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
5247 </para>
5248
5249 <para>
5250 For creating the SG-buffer handler, call
5251 <function>snd_pcm_lib_preallocate_pages()</function> or
5252 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5253 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5254 in the PCM constructor like other PCI pre-allocator.
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005255 You need to pass <function>snd_dma_pci_data(pci)</function>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005256 where pci is the struct <structname>pci_dev</structname> pointer
5257 of the chip as well.
Giuliano Pochini44275f12006-01-27 12:02:05 +01005258 The <type>struct snd_sg_buf</type> instance is created as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005259 substream-&gt;dma_private. You can cast
5260 the pointer like:
5261
5262 <informalexample>
5263 <programlisting>
5264<![CDATA[
Giuliano Pochini44275f12006-01-27 12:02:05 +01005265 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005266]]>
5267 </programlisting>
5268 </informalexample>
5269 </para>
5270
5271 <para>
5272 Then call <function>snd_pcm_lib_malloc_pages()</function>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005273 in the <structfield>hw_params</structfield> callback
Linus Torvalds1da177e2005-04-16 15:20:36 -07005274 as well as in the case of normal PCI buffer.
5275 The SG-buffer handler will allocate the non-contiguous kernel
5276 pages of the given size and map them onto the virtually contiguous
5277 memory. The virtual pointer is addressed in runtime-&gt;dma_area.
5278 The physical address (runtime-&gt;dma_addr) is set to zero,
André Goddard Rosaaf901ca2009-11-14 13:09:05 -02005279 because the buffer is physically non-contiguous.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005280 The physical address table is set up in sgbuf-&gt;table.
5281 You can get the physical address at a certain offset via
5282 <function>snd_pcm_sgbuf_get_addr()</function>.
5283 </para>
5284
5285 <para>
5286 When a SG-handler is used, you need to set
5287 <function>snd_pcm_sgbuf_ops_page</function> as
5288 the <structfield>page</structfield> callback.
5289 (See <link linkend="pcm-interface-operators-page-callback">
5290 <citetitle>page callback section</citetitle></link>.)
5291 </para>
5292
5293 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005294 To release the data, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005295 <function>snd_pcm_lib_free_pages()</function> in the
5296 <structfield>hw_free</structfield> callback as usual.
5297 </para>
5298 </section>
5299
5300 <section id="buffer-and-memory-vmalloced">
5301 <title>Vmalloc'ed Buffers</title>
5302 <para>
5303 It's possible to use a buffer allocated via
5304 <function>vmalloc</function>, for example, for an intermediate
5305 buffer. Since the allocated pages are not contiguous, you need
5306 to set the <structfield>page</structfield> callback to obtain
5307 the physical address at every offset.
5308 </para>
5309
5310 <para>
5311 The implementation of <structfield>page</structfield> callback
5312 would be like this:
5313
5314 <informalexample>
5315 <programlisting>
5316<![CDATA[
5317 #include <linux/vmalloc.h>
5318
5319 /* get the physical page pointer on the given offset */
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005320 static struct page *mychip_page(struct snd_pcm_substream *substream,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005321 unsigned long offset)
5322 {
5323 void *pageptr = substream->runtime->dma_area + offset;
5324 return vmalloc_to_page(pageptr);
5325 }
5326]]>
5327 </programlisting>
5328 </informalexample>
5329 </para>
5330 </section>
5331
5332 </chapter>
5333
5334
5335<!-- ****************************************************** -->
5336<!-- Proc Interface -->
5337<!-- ****************************************************** -->
5338 <chapter id="proc-interface">
5339 <title>Proc Interface</title>
5340 <para>
5341 ALSA provides an easy interface for procfs. The proc files are
5342 very useful for debugging. I recommend you set up proc files if
5343 you write a driver and want to get a running status or register
5344 dumps. The API is found in
5345 <filename>&lt;sound/info.h&gt;</filename>.
5346 </para>
5347
5348 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005349 To create a proc file, call
Linus Torvalds1da177e2005-04-16 15:20:36 -07005350 <function>snd_card_proc_new()</function>.
5351
5352 <informalexample>
5353 <programlisting>
5354<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005355 struct snd_info_entry *entry;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005356 int err = snd_card_proc_new(card, "my-file", &entry);
5357]]>
5358 </programlisting>
5359 </informalexample>
5360
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005361 where the second argument specifies the name of the proc file to be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005362 created. The above example will create a file
5363 <filename>my-file</filename> under the card directory,
5364 e.g. <filename>/proc/asound/card0/my-file</filename>.
5365 </para>
5366
5367 <para>
5368 Like other components, the proc entry created via
5369 <function>snd_card_proc_new()</function> will be registered and
5370 released automatically in the card registration and release
5371 functions.
5372 </para>
5373
5374 <para>
5375 When the creation is successful, the function stores a new
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005376 instance in the pointer given in the third argument.
5377 It is initialized as a text proc file for read only. To use
Linus Torvalds1da177e2005-04-16 15:20:36 -07005378 this proc file as a read-only text file as it is, set the read
5379 callback with a private data via
5380 <function>snd_info_set_text_ops()</function>.
5381
5382 <informalexample>
5383 <programlisting>
5384<![CDATA[
Takashi Iwaibf850202006-04-28 15:13:41 +02005385 snd_info_set_text_ops(entry, chip, my_proc_read);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005386]]>
5387 </programlisting>
5388 </informalexample>
5389
5390 where the second argument (<parameter>chip</parameter>) is the
5391 private data to be used in the callbacks. The third parameter
5392 specifies the read buffer size and the fourth
5393 (<parameter>my_proc_read</parameter>) is the callback function, which
5394 is defined like
5395
5396 <informalexample>
5397 <programlisting>
5398<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005399 static void my_proc_read(struct snd_info_entry *entry,
5400 struct snd_info_buffer *buffer);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005401]]>
5402 </programlisting>
5403 </informalexample>
5404
5405 </para>
5406
5407 <para>
5408 In the read callback, use <function>snd_iprintf()</function> for
5409 output strings, which works just like normal
5410 <function>printf()</function>. For example,
5411
5412 <informalexample>
5413 <programlisting>
5414<![CDATA[
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005415 static void my_proc_read(struct snd_info_entry *entry,
5416 struct snd_info_buffer *buffer)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005417 {
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005418 struct my_chip *chip = entry->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005419
5420 snd_iprintf(buffer, "This is my chip!\n");
5421 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5422 }
5423]]>
5424 </programlisting>
5425 </informalexample>
5426 </para>
5427
5428 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005429 The file permissions can be changed afterwards. As default, it's
5430 set as read only for all users. If you want to add write
5431 permission for the user (root as default), do as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005432
5433 <informalexample>
5434 <programlisting>
5435<![CDATA[
5436 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5437]]>
5438 </programlisting>
5439 </informalexample>
5440
5441 and set the write buffer size and the callback
5442
5443 <informalexample>
5444 <programlisting>
5445<![CDATA[
Linus Torvalds1da177e2005-04-16 15:20:36 -07005446 entry->c.text.write = my_proc_write;
5447]]>
5448 </programlisting>
5449 </informalexample>
5450 </para>
5451
5452 <para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005453 For the write callback, you can use
5454 <function>snd_info_get_line()</function> to get a text line, and
5455 <function>snd_info_get_str()</function> to retrieve a string from
5456 the line. Some examples are found in
5457 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5458 <filename>pcm_oss.c</filename>.
5459 </para>
5460
5461 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005462 For a raw-data proc-file, set the attributes as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005463
5464 <informalexample>
5465 <programlisting>
5466<![CDATA[
5467 static struct snd_info_entry_ops my_file_io_ops = {
5468 .read = my_file_io_read,
5469 };
5470
5471 entry->content = SNDRV_INFO_CONTENT_DATA;
5472 entry->private_data = chip;
5473 entry->c.ops = &my_file_io_ops;
5474 entry->size = 4096;
5475 entry->mode = S_IFREG | S_IRUGO;
5476]]>
5477 </programlisting>
5478 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005479
5480 For the raw data, <structfield>size</structfield> field must be
5481 set properly. This specifies the maximum size of the proc file access.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005482 </para>
5483
5484 <para>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005485 The read/write callbacks of raw mode are more direct than the text mode.
5486 You need to use a low-level I/O functions such as
Linus Torvalds1da177e2005-04-16 15:20:36 -07005487 <function>copy_from/to_user()</function> to transfer the
5488 data.
5489
5490 <informalexample>
5491 <programlisting>
5492<![CDATA[
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005493 static ssize_t my_file_io_read(struct snd_info_entry *entry,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005494 void *file_private_data,
5495 struct file *file,
5496 char *buf,
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005497 size_t count,
5498 loff_t pos)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005499 {
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005500 if (copy_to_user(buf, local_data + pos, count))
Linus Torvalds1da177e2005-04-16 15:20:36 -07005501 return -EFAULT;
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005502 return count;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005503 }
5504]]>
5505 </programlisting>
5506 </informalexample>
Takashi Iwaic56a3b12010-04-13 12:55:09 +02005507
5508 If the size of the info entry has been set up properly,
5509 <structfield>count</structfield> and <structfield>pos</structfield> are
5510 guaranteed to fit within 0 and the given size.
5511 You don't have to check the range in the callbacks unless any
5512 other condition is required.
5513
Linus Torvalds1da177e2005-04-16 15:20:36 -07005514 </para>
5515
5516 </chapter>
5517
5518
5519<!-- ****************************************************** -->
5520<!-- Power Management -->
5521<!-- ****************************************************** -->
5522 <chapter id="power-management">
5523 <title>Power Management</title>
5524 <para>
Paolo Ornati670e9f32006-10-03 22:57:56 +02005525 If the chip is supposed to work with suspend/resume
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005526 functions, you need to add power-management code to the
5527 driver. The additional code for power-management should be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005528 <function>ifdef</function>'ed with
5529 <constant>CONFIG_PM</constant>.
5530 </para>
5531
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005532 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005533 If the driver <emphasis>fully</emphasis> supports suspend/resume
5534 that is, the device can be
5535 properly resumed to its state when suspend was called,
5536 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5537 in the pcm info field. Usually, this is possible when the
5538 registers of the chip can be safely saved and restored to
5539 RAM. If this is set, the trigger callback is called with
5540 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5541 callback completes.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005542 </para>
5543
5544 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005545 Even if the driver doesn't support PM fully but
5546 partial suspend/resume is still possible, it's still worthy to
5547 implement suspend/resume callbacks. In such a case, applications
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005548 would reset the status by calling
5549 <function>snd_pcm_prepare()</function> and restart the stream
5550 appropriately. Hence, you can define suspend/resume callbacks
5551 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5552 info flag to the PCM.
5553 </para>
5554
5555 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005556 Note that the trigger with SUSPEND can always be called when
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005557 <function>snd_pcm_suspend_all</function> is called,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005558 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005559 The <constant>RESUME</constant> flag affects only the behavior
5560 of <function>snd_pcm_resume()</function>.
5561 (Thus, in theory,
5562 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5563 to be handled in the trigger callback when no
5564 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005565 it's better to keep it for compatibility reasons.)
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005566 </para>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005567 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005568 In the earlier version of ALSA drivers, a common
5569 power-management layer was provided, but it has been removed.
5570 The driver needs to define the suspend/resume hooks according to
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005571 the bus the device is connected to. In the case of PCI drivers, the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005572 callbacks look like below:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005573
5574 <informalexample>
5575 <programlisting>
5576<![CDATA[
5577 #ifdef CONFIG_PM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005578 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005579 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005580 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005581 return 0;
5582 }
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005583 static int snd_my_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005584 {
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01005585 .... /* do things for suspend */
Linus Torvalds1da177e2005-04-16 15:20:36 -07005586 return 0;
5587 }
5588 #endif
5589]]>
5590 </programlisting>
5591 </informalexample>
5592 </para>
5593
5594 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005595 The scheme of the real suspend job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005596
5597 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005598 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5599 <listitem><para>Call <function>snd_power_change_state()</function> with
5600 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5601 power status.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005602 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005603 <listitem><para>If AC97 codecs are used, call
Takashi Iwaia7306332006-05-04 11:58:43 +02005604 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005605 <listitem><para>Save the register values if necessary.</para></listitem>
5606 <listitem><para>Stop the hardware if necessary.</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005607 <listitem><para>Disable the PCI device by calling
5608 <function>pci_disable_device()</function>. Then, call
5609 <function>pci_save_state()</function> at last.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005610 </orderedlist>
5611 </para>
5612
5613 <para>
5614 A typical code would be like:
5615
5616 <informalexample>
5617 <programlisting>
5618<![CDATA[
Alexey Dobriyan323579882006-01-15 02:12:54 +01005619 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005620 {
5621 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005622 struct snd_card *card = pci_get_drvdata(pci);
5623 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005624 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005625 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005626 /* (3) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005627 snd_pcm_suspend_all(chip->pcm);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005628 /* (4) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005629 snd_ac97_suspend(chip->ac97);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005630 /* (5) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005631 snd_mychip_save_registers(chip);
5632 /* (6) */
5633 snd_mychip_stop_hardware(chip);
5634 /* (7) */
5635 pci_disable_device(pci);
5636 pci_save_state(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005637 return 0;
5638 }
5639]]>
5640 </programlisting>
5641 </informalexample>
5642 </para>
5643
5644 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005645 The scheme of the real resume job is as follows.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005646
5647 <orderedlist>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005648 <listitem><para>Retrieve the card and the chip data.</para></listitem>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005649 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005650 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5651 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005652 <listitem><para>Re-initialize the chip.</para></listitem>
5653 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5654 <listitem><para>Resume the mixer, e.g. calling
5655 <function>snd_ac97_resume()</function>.</para></listitem>
5656 <listitem><para>Restart the hardware (if any).</para></listitem>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005657 <listitem><para>Call <function>snd_power_change_state()</function> with
5658 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005659 </orderedlist>
5660 </para>
5661
5662 <para>
5663 A typical code would be like:
5664
5665 <informalexample>
5666 <programlisting>
5667<![CDATA[
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005668 static int mychip_resume(struct pci_dev *pci)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005669 {
5670 /* (1) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005671 struct snd_card *card = pci_get_drvdata(pci);
5672 struct mychip *chip = card->private_data;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005673 /* (2) */
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005674 pci_restore_state(pci);
5675 pci_enable_device(pci);
5676 pci_set_master(pci);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005677 /* (3) */
5678 snd_mychip_reinit_chip(chip);
5679 /* (4) */
5680 snd_mychip_restore_registers(chip);
5681 /* (5) */
5682 snd_ac97_resume(chip->ac97);
5683 /* (6) */
5684 snd_mychip_restart_chip(chip);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005685 /* (7) */
5686 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
Linus Torvalds1da177e2005-04-16 15:20:36 -07005687 return 0;
5688 }
5689]]>
5690 </programlisting>
5691 </informalexample>
5692 </para>
5693
5694 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005695 As shown in the above, it's better to save registers after
5696 suspending the PCM operations via
5697 <function>snd_pcm_suspend_all()</function> or
5698 <function>snd_pcm_suspend()</function>. It means that the PCM
Masanari Iida0ba4f6e2014-07-12 09:55:28 -07005699 streams are already stopped when the register snapshot is
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005700 taken. But, remember that you don't have to restart the PCM
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005701 stream in the resume callback. It'll be restarted via
5702 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5703 when necessary.
5704 </para>
5705
5706 <para>
5707 OK, we have all callbacks now. Let's set them up. In the
5708 initialization of the card, make sure that you can get the chip
5709 data from the card instance, typically via
5710 <structfield>private_data</structfield> field, in case you
5711 created the chip data individually.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005712
5713 <informalexample>
5714 <programlisting>
5715<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01005716 static int snd_mychip_probe(struct pci_dev *pci,
5717 const struct pci_device_id *pci_id)
Linus Torvalds1da177e2005-04-16 15:20:36 -07005718 {
5719 ....
Takashi Iwai446ab5f2005-11-17 15:12:54 +01005720 struct snd_card *card;
5721 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005722 int err;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005723 ....
Takashi Iwai393aa9c2014-01-29 12:51:12 +01005724 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5725 0, &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005726 ....
5727 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5728 ....
5729 card->private_data = chip;
Linus Torvalds1da177e2005-04-16 15:20:36 -07005730 ....
5731 }
5732]]>
5733 </programlisting>
5734 </informalexample>
5735
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005736 When you created the chip data with
Takashi Iwai393aa9c2014-01-29 12:51:12 +01005737 <function>snd_card_new()</function>, it's anyway accessible
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005738 via <structfield>private_data</structfield> field.
5739
5740 <informalexample>
5741 <programlisting>
5742<![CDATA[
Takashi Iwai090015a2012-12-07 07:52:28 +01005743 static int snd_mychip_probe(struct pci_dev *pci,
5744 const struct pci_device_id *pci_id)
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005745 {
5746 ....
5747 struct snd_card *card;
5748 struct mychip *chip;
Takashi Iwaid4533792008-12-28 16:45:34 +01005749 int err;
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005750 ....
Takashi Iwai393aa9c2014-01-29 12:51:12 +01005751 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5752 sizeof(struct mychip), &card);
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005753 ....
5754 chip = card->private_data;
5755 ....
5756 }
5757]]>
5758 </programlisting>
5759 </informalexample>
5760
Linus Torvalds1da177e2005-04-16 15:20:36 -07005761 </para>
5762
5763 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005764 If you need a space to save the registers, allocate the
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005765 buffer for it here, too, since it would be fatal
Linus Torvalds1da177e2005-04-16 15:20:36 -07005766 if you cannot allocate a memory in the suspend phase.
5767 The allocated buffer should be released in the corresponding
5768 destructor.
5769 </para>
5770
5771 <para>
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005772 And next, set suspend/resume callbacks to the pci_driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -07005773
5774 <informalexample>
5775 <programlisting>
5776<![CDATA[
5777 static struct pci_driver driver = {
Takashi Iwaice1fd362011-06-14 08:54:14 +02005778 .name = KBUILD_MODNAME,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005779 .id_table = snd_my_ids,
5780 .probe = snd_my_probe,
Takashi Iwai090015a2012-12-07 07:52:28 +01005781 .remove = snd_my_remove,
Takashi Iwai5fe76e42005-11-17 17:26:09 +01005782 #ifdef CONFIG_PM
5783 .suspend = snd_my_suspend,
5784 .resume = snd_my_resume,
5785 #endif
Linus Torvalds1da177e2005-04-16 15:20:36 -07005786 };
5787]]>
5788 </programlisting>
5789 </informalexample>
5790 </para>
5791
5792 </chapter>
5793
5794
5795<!-- ****************************************************** -->
5796<!-- Module Parameters -->
5797<!-- ****************************************************** -->
5798 <chapter id="module-parameters">
5799 <title>Module Parameters</title>
5800 <para>
5801 There are standard module options for ALSA. At least, each
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005802 module should have the <parameter>index</parameter>,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005803 <parameter>id</parameter> and <parameter>enable</parameter>
5804 options.
5805 </para>
5806
5807 <para>
5808 If the module supports multiple cards (usually up to
5809 8 = <constant>SNDRV_CARDS</constant> cards), they should be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005810 arrays. The default initial values are defined already as
5811 constants for easier programming:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005812
5813 <informalexample>
5814 <programlisting>
5815<![CDATA[
5816 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5817 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5818 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5819]]>
5820 </programlisting>
5821 </informalexample>
5822 </para>
5823
5824 <para>
5825 If the module supports only a single card, they could be single
5826 variables, instead. <parameter>enable</parameter> option is not
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005827 always necessary in this case, but it would be better to have a
Linus Torvalds1da177e2005-04-16 15:20:36 -07005828 dummy option for compatibility.
5829 </para>
5830
5831 <para>
5832 The module parameters must be declared with the standard
5833 <function>module_param()()</function>,
5834 <function>module_param_array()()</function> and
5835 <function>MODULE_PARM_DESC()</function> macros.
5836 </para>
5837
5838 <para>
5839 The typical coding would be like below:
5840
5841 <informalexample>
5842 <programlisting>
5843<![CDATA[
5844 #define CARD_NAME "My Chip"
5845
5846 module_param_array(index, int, NULL, 0444);
5847 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5848 module_param_array(id, charp, NULL, 0444);
5849 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5850 module_param_array(enable, bool, NULL, 0444);
5851 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5852]]>
5853 </programlisting>
5854 </informalexample>
5855 </para>
5856
5857 <para>
5858 Also, don't forget to define the module description, classes,
5859 license and devices. Especially, the recent modprobe requires to
5860 define the module license as GPL, etc., otherwise the system is
5861 shown as <quote>tainted</quote>.
5862
5863 <informalexample>
5864 <programlisting>
5865<![CDATA[
5866 MODULE_DESCRIPTION("My Chip");
5867 MODULE_LICENSE("GPL");
5868 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5869]]>
5870 </programlisting>
5871 </informalexample>
5872 </para>
5873
5874 </chapter>
5875
5876
5877<!-- ****************************************************** -->
5878<!-- How To Put Your Driver -->
5879<!-- ****************************************************** -->
5880 <chapter id="how-to-put-your-driver">
5881 <title>How To Put Your Driver Into ALSA Tree</title>
5882 <section>
5883 <title>General</title>
5884 <para>
5885 So far, you've learned how to write the driver codes.
5886 And you might have a question now: how to put my own
5887 driver into the ALSA driver tree?
5888 Here (finally :) the standard procedure is described briefly.
5889 </para>
5890
5891 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005892 Suppose that you create a new PCI driver for the card
Linus Torvalds1da177e2005-04-16 15:20:36 -07005893 <quote>xyz</quote>. The card module name would be
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005894 snd-xyz. The new driver is usually put into the alsa-driver
Linus Torvalds1da177e2005-04-16 15:20:36 -07005895 tree, <filename>alsa-driver/pci</filename> directory in
5896 the case of PCI cards.
5897 Then the driver is evaluated, audited and tested
5898 by developers and users. After a certain time, the driver
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005899 will go to the alsa-kernel tree (to the corresponding directory,
Linus Torvalds1da177e2005-04-16 15:20:36 -07005900 such as <filename>alsa-kernel/pci</filename>) and eventually
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005901 will be integrated into the Linux 2.6 tree (the directory would be
Linus Torvalds1da177e2005-04-16 15:20:36 -07005902 <filename>linux/sound/pci</filename>).
5903 </para>
5904
5905 <para>
5906 In the following sections, the driver code is supposed
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02005907 to be put into alsa-driver tree. The two cases are covered:
Linus Torvalds1da177e2005-04-16 15:20:36 -07005908 a driver consisting of a single source file and one consisting
5909 of several source files.
5910 </para>
5911 </section>
5912
5913 <section>
5914 <title>Driver with A Single Source File</title>
5915 <para>
5916 <orderedlist>
5917 <listitem>
5918 <para>
5919 Modify alsa-driver/pci/Makefile
5920 </para>
5921
5922 <para>
5923 Suppose you have a file xyz.c. Add the following
5924 two lines
5925 <informalexample>
5926 <programlisting>
5927<![CDATA[
5928 snd-xyz-objs := xyz.o
5929 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5930]]>
5931 </programlisting>
5932 </informalexample>
5933 </para>
5934 </listitem>
5935
5936 <listitem>
5937 <para>
5938 Create the Kconfig entry
5939 </para>
5940
5941 <para>
5942 Add the new entry of Kconfig for your xyz driver.
5943 <informalexample>
5944 <programlisting>
5945<![CDATA[
5946 config SND_XYZ
5947 tristate "Foobar XYZ"
5948 depends on SND
5949 select SND_PCM
5950 help
5951 Say Y here to include support for Foobar XYZ soundcard.
5952
5953 To compile this driver as a module, choose M here: the module
5954 will be called snd-xyz.
5955]]>
5956 </programlisting>
5957 </informalexample>
5958
5959 the line, select SND_PCM, specifies that the driver xyz supports
5960 PCM. In addition to SND_PCM, the following components are
5961 supported for select command:
5962 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5963 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5964 Add the select command for each supported component.
5965 </para>
5966
5967 <para>
5968 Note that some selections imply the lowlevel selections.
5969 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5970 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5971 You don't need to give the lowlevel selections again.
5972 </para>
5973
5974 <para>
5975 For the details of Kconfig script, refer to the kbuild
5976 documentation.
5977 </para>
5978
5979 </listitem>
5980
5981 <listitem>
5982 <para>
5983 Run cvscompile script to re-generate the configure script and
5984 build the whole stuff again.
5985 </para>
5986 </listitem>
5987 </orderedlist>
5988 </para>
5989 </section>
5990
5991 <section>
5992 <title>Drivers with Several Source Files</title>
5993 <para>
5994 Suppose that the driver snd-xyz have several source files.
5995 They are located in the new subdirectory,
5996 pci/xyz.
5997
5998 <orderedlist>
5999 <listitem>
6000 <para>
6001 Add a new directory (<filename>xyz</filename>) in
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006002 <filename>alsa-driver/pci/Makefile</filename> as below
Linus Torvalds1da177e2005-04-16 15:20:36 -07006003
6004 <informalexample>
6005 <programlisting>
6006<![CDATA[
6007 obj-$(CONFIG_SND) += xyz/
6008]]>
6009 </programlisting>
6010 </informalexample>
6011 </para>
6012 </listitem>
6013
6014 <listitem>
6015 <para>
6016 Under the directory <filename>xyz</filename>, create a Makefile
6017
6018 <example>
6019 <title>Sample Makefile for a driver xyz</title>
6020 <programlisting>
6021<![CDATA[
6022 ifndef SND_TOPDIR
6023 SND_TOPDIR=../..
6024 endif
6025
6026 include $(SND_TOPDIR)/toplevel.config
6027 include $(SND_TOPDIR)/Makefile.conf
6028
6029 snd-xyz-objs := xyz.o abc.o def.o
6030
6031 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6032
6033 include $(SND_TOPDIR)/Rules.make
6034]]>
6035 </programlisting>
6036 </example>
6037 </para>
6038 </listitem>
6039
6040 <listitem>
6041 <para>
6042 Create the Kconfig entry
6043 </para>
6044
6045 <para>
6046 This procedure is as same as in the last section.
6047 </para>
6048 </listitem>
6049
6050 <listitem>
6051 <para>
6052 Run cvscompile script to re-generate the configure script and
6053 build the whole stuff again.
6054 </para>
6055 </listitem>
6056 </orderedlist>
6057 </para>
6058 </section>
6059
6060 </chapter>
6061
6062<!-- ****************************************************** -->
6063<!-- Useful Functions -->
6064<!-- ****************************************************** -->
6065 <chapter id="useful-functions">
6066 <title>Useful Functions</title>
6067
6068 <section id="useful-functions-snd-printk">
6069 <title><function>snd_printk()</function> and friends</title>
6070 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006071 ALSA provides a verbose version of the
Linus Torvalds1da177e2005-04-16 15:20:36 -07006072 <function>printk()</function> function. If a kernel config
6073 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6074 function prints the given message together with the file name
6075 and the line of the caller. The <constant>KERN_XXX</constant>
6076 prefix is processed as
6077 well as the original <function>printk()</function> does, so it's
6078 recommended to add this prefix, e.g.
6079
6080 <informalexample>
6081 <programlisting>
6082<![CDATA[
6083 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6084]]>
6085 </programlisting>
6086 </informalexample>
6087 </para>
6088
6089 <para>
6090 There are also <function>printk()</function>'s for
6091 debugging. <function>snd_printd()</function> can be used for
6092 general debugging purposes. If
6093 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6094 compiled, and works just like
6095 <function>snd_printk()</function>. If the ALSA is compiled
6096 without the debugging flag, it's ignored.
6097 </para>
6098
6099 <para>
6100 <function>snd_printdd()</function> is compiled in only when
Takashi Iwai62cf8722008-05-20 12:15:15 +02006101 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6102 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
Linus Torvalds1da177e2005-04-16 15:20:36 -07006103 even if you configure the alsa-driver with
6104 <option>--with-debug=full</option> option. You need to give
6105 explicitly <option>--with-debug=detect</option> option instead.
6106 </para>
6107 </section>
6108
Linus Torvalds1da177e2005-04-16 15:20:36 -07006109 <section id="useful-functions-snd-bug">
6110 <title><function>snd_BUG()</function></title>
6111 <para>
Michael Opdenacker3f03f7c2007-10-24 10:59:44 +02006112 It shows the <computeroutput>BUG?</computeroutput> message and
Takashi Iwai7cc6dff2008-08-08 17:14:55 +02006113 stack trace as well as <function>snd_BUG_ON</function> at the point.
Takashi Iwai7c22f1a2005-10-10 11:46:31 +02006114 It's useful to show that a fatal error happens there.
6115 </para>
6116 <para>
6117 When no debug flag is set, this macro is ignored.
Linus Torvalds1da177e2005-04-16 15:20:36 -07006118 </para>
6119 </section>
Takashi Iwai5ef03462008-08-08 17:06:01 +02006120
6121 <section id="useful-functions-snd-bug-on">
6122 <title><function>snd_BUG_ON()</function></title>
6123 <para>
6124 <function>snd_BUG_ON()</function> macro is similar with
6125 <function>WARN_ON()</function> macro. For example,
6126
6127 <informalexample>
6128 <programlisting>
6129<![CDATA[
6130 snd_BUG_ON(!pointer);
6131]]>
6132 </programlisting>
6133 </informalexample>
6134
6135 or it can be used as the condition,
6136 <informalexample>
6137 <programlisting>
6138<![CDATA[
6139 if (snd_BUG_ON(non_zero_is_bug))
6140 return -EINVAL;
6141]]>
6142 </programlisting>
6143 </informalexample>
6144
6145 </para>
6146
6147 <para>
6148 The macro takes an conditional expression to evaluate.
Christine Spangd5702162013-03-04 17:02:59 -05006149 When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
6150 expression is non-zero, it shows the warning message such as
Takashi Iwai5ef03462008-08-08 17:06:01 +02006151 <computeroutput>BUG? (xxx)</computeroutput>
Christine Spangd5702162013-03-04 17:02:59 -05006152 normally followed by stack trace.
6153
6154 In both cases it returns the evaluated value.
Takashi Iwai5ef03462008-08-08 17:06:01 +02006155 </para>
6156
6157 </section>
6158
Linus Torvalds1da177e2005-04-16 15:20:36 -07006159 </chapter>
6160
6161
6162<!-- ****************************************************** -->
6163<!-- Acknowledgments -->
6164<!-- ****************************************************** -->
Nicolas Kaiser5bda9fa2007-01-22 14:54:33 +01006165 <chapter id="acknowledgments">
Linus Torvalds1da177e2005-04-16 15:20:36 -07006166 <title>Acknowledgments</title>
6167 <para>
6168 I would like to thank Phil Kerr for his help for improvement and
6169 corrections of this document.
6170 </para>
6171 <para>
6172 Kevin Conder reformatted the original plain-text to the
6173 DocBook format.
6174 </para>
6175 <para>
6176 Giuliano Pochini corrected typos and contributed the example codes
6177 in the hardware constraints section.
6178 </para>
6179 </chapter>
Linus Torvalds1da177e2005-04-16 15:20:36 -07006180</book>