1 ====================== 1 ======================
2 Writing an ALSA Driver 2 Writing an ALSA Driver
3 ====================== 3 ======================
4 4
5 :Author: Takashi Iwai <tiwai@suse.de> 5 :Author: Takashi Iwai <tiwai@suse.de>
>> 6 :Date: Oct 15, 2007
>> 7 :Edition: 0.3.7
6 8
7 Preface 9 Preface
8 ======= 10 =======
9 11
10 This document describes how to write an `ALSA 12 This document describes how to write an `ALSA (Advanced Linux Sound
11 Architecture) <http://www.alsa-project.org/>`_ 13 Architecture) <http://www.alsa-project.org/>`__ driver. The document
12 focuses mainly on PCI soundcards. In the case 14 focuses mainly on PCI soundcards. In the case of other device types, the
13 API might be different, too. However, at least 15 API might be different, too. However, at least the ALSA kernel API is
14 consistent, and therefore it would be still a 16 consistent, and therefore it would be still a bit help for writing them.
15 17
16 This document targets people who already have 18 This document targets people who already have enough C language skills
17 and have basic linux kernel programming knowle 19 and have basic linux kernel programming knowledge. This document doesn't
18 explain the general topic of linux kernel codi 20 explain the general topic of linux kernel coding and doesn't cover
19 low-level driver implementation details. It on 21 low-level driver implementation details. It only describes the standard
20 way to write a PCI sound driver on ALSA. 22 way to write a PCI sound driver on ALSA.
21 23
>> 24 If you are already familiar with the older ALSA ver.0.5.x API, you can
>> 25 check the drivers such as ``sound/pci/es1938.c`` or
>> 26 ``sound/pci/maestro3.c`` which have also almost the same code-base in
>> 27 the ALSA 0.5.x tree, so you can compare the differences.
>> 28
>> 29 This document is still a draft version. Any feedback and corrections,
>> 30 please!!
>> 31
22 File Tree Structure 32 File Tree Structure
23 =================== 33 ===================
24 34
25 General 35 General
26 ------- 36 -------
27 37
28 The file tree structure of ALSA driver is depi !! 38 The ALSA drivers are provided in two ways.
>> 39
>> 40 One is the trees provided as a tarball or via cvs from the ALSA's ftp
>> 41 site, and another is the 2.6 (or later) Linux kernel tree. To
>> 42 synchronize both, the ALSA driver tree is split into two different
>> 43 trees: alsa-kernel and alsa-driver. The former contains purely the
>> 44 source code for the Linux 2.6 (or later) tree. This tree is designed
>> 45 only for compilation on 2.6 or later environment. The latter,
>> 46 alsa-driver, contains many subtle files for compiling ALSA drivers
>> 47 outside of the Linux kernel tree, wrapper functions for older 2.2 and
>> 48 2.4 kernels, to adapt the latest kernel API, and additional drivers
>> 49 which are still in development or in tests. The drivers in alsa-driver
>> 50 tree will be moved to alsa-kernel (and eventually to the 2.6 kernel
>> 51 tree) when they are finished and confirmed to work fine.
>> 52
>> 53 The file tree structure of ALSA driver is depicted below. Both
>> 54 alsa-kernel and alsa-driver have almost the same file structure, except
>> 55 for “core” directory. It's named as “acore” in alsa-driver tree.
>> 56
>> 57 ::
29 58
30 sound 59 sound
31 /core 60 /core
32 /oss 61 /oss
33 /seq 62 /seq
34 /oss 63 /oss
>> 64 /instr
>> 65 /ioctl32
35 /include 66 /include
36 /drivers 67 /drivers
37 /mpu401 68 /mpu401
38 /opl3 69 /opl3
39 /i2c 70 /i2c
>> 71 /l3
40 /synth 72 /synth
41 /emux 73 /emux
42 /pci 74 /pci
43 /(cards) 75 /(cards)
44 /isa 76 /isa
45 /(cards) 77 /(cards)
46 /arm 78 /arm
47 /ppc 79 /ppc
48 /sparc 80 /sparc
49 /usb 81 /usb
50 /pcmcia /(cards) 82 /pcmcia /(cards)
51 /soc <<
52 /oss 83 /oss
53 84
54 85
55 core directory 86 core directory
56 -------------- 87 --------------
57 88
58 This directory contains the middle layer which 89 This directory contains the middle layer which is the heart of ALSA
59 drivers. In this directory, the native ALSA mo 90 drivers. In this directory, the native ALSA modules are stored. The
60 sub-directories contain different modules and 91 sub-directories contain different modules and are dependent upon the
61 kernel config. 92 kernel config.
62 93
63 core/oss 94 core/oss
64 ~~~~~~~~ 95 ~~~~~~~~
65 96
66 The code for OSS PCM and mixer emulation modul !! 97 The codes for PCM and mixer OSS emulation modules are stored in this
67 directory. The OSS rawmidi emulation is includ !! 98 directory. The rawmidi OSS emulation is included in the ALSA rawmidi
68 code since it's quite small. The sequencer cod 99 code since it's quite small. The sequencer code is stored in
69 ``core/seq/oss`` directory (see `below <core/s !! 100 ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
>> 101
>> 102 core/ioctl32
>> 103 ~~~~~~~~~~~~
>> 104
>> 105 This directory contains the 32bit-ioctl wrappers for 64bit architectures
>> 106 such like x86-64, ppc64 and sparc64. For 32bit and alpha architectures,
>> 107 these are not compiled.
70 108
71 core/seq 109 core/seq
72 ~~~~~~~~ 110 ~~~~~~~~
73 111
74 This directory and its sub-directories are for 112 This directory and its sub-directories are for the ALSA sequencer. This
75 directory contains the sequencer core and prim 113 directory contains the sequencer core and primary sequencer modules such
76 as snd-seq-midi, snd-seq-virmidi, etc. They ar !! 114 like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
77 ``CONFIG_SND_SEQUENCER`` is set in the kernel 115 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
78 116
79 core/seq/oss 117 core/seq/oss
80 ~~~~~~~~~~~~ 118 ~~~~~~~~~~~~
81 119
82 This contains the OSS sequencer emulation code !! 120 This contains the OSS sequencer emulation codes.
>> 121
>> 122 core/seq/instr
>> 123 ~~~~~~~~~~~~~~
>> 124
>> 125 This directory contains the modules for the sequencer instrument layer.
83 126
84 include directory 127 include directory
85 ----------------- 128 -----------------
86 129
87 This is the place for the public header files 130 This is the place for the public header files of ALSA drivers, which are
88 to be exported to user-space, or included by s !! 131 to be exported to user-space, or included by several files at different
89 directories. Basically, the private header fil 132 directories. Basically, the private header files should not be placed in
90 this directory, but you may still find files t 133 this directory, but you may still find files there, due to historical
91 reasons :) 134 reasons :)
92 135
93 drivers directory 136 drivers directory
94 ----------------- 137 -----------------
95 138
96 This directory contains code shared among diff 139 This directory contains code shared among different drivers on different
97 architectures. They are hence supposed not to 140 architectures. They are hence supposed not to be architecture-specific.
98 For example, the dummy PCM driver and the seri !! 141 For example, the dummy pcm driver and the serial MIDI driver are found
99 in this directory. In the sub-directories, the 142 in this directory. In the sub-directories, there is code for components
100 which are independent from bus and cpu archite 143 which are independent from bus and cpu architectures.
101 144
102 drivers/mpu401 145 drivers/mpu401
103 ~~~~~~~~~~~~~~ 146 ~~~~~~~~~~~~~~
104 147
105 The MPU401 and MPU401-UART modules are stored 148 The MPU401 and MPU401-UART modules are stored here.
106 149
107 drivers/opl3 and opl4 150 drivers/opl3 and opl4
108 ~~~~~~~~~~~~~~~~~~~~~ 151 ~~~~~~~~~~~~~~~~~~~~~
109 152
110 The OPL3 and OPL4 FM-synth stuff is found here 153 The OPL3 and OPL4 FM-synth stuff is found here.
111 154
112 i2c directory 155 i2c directory
113 ------------- 156 -------------
114 157
115 This contains the ALSA i2c components. 158 This contains the ALSA i2c components.
116 159
117 Although there is a standard i2c layer on Linu 160 Although there is a standard i2c layer on Linux, ALSA has its own i2c
118 code for some cards, because the soundcard nee 161 code for some cards, because the soundcard needs only a simple operation
119 and the standard i2c API is too complicated fo 162 and the standard i2c API is too complicated for such a purpose.
120 163
>> 164 i2c/l3
>> 165 ~~~~~~
>> 166
>> 167 This is a sub-directory for ARM L3 i2c.
>> 168
121 synth directory 169 synth directory
122 --------------- 170 ---------------
123 171
124 This contains the synth middle-level modules. 172 This contains the synth middle-level modules.
125 173
126 So far, there is only Emu8000/Emu10k1 synth dr 174 So far, there is only Emu8000/Emu10k1 synth driver under the
127 ``synth/emux`` sub-directory. 175 ``synth/emux`` sub-directory.
128 176
129 pci directory 177 pci directory
130 ------------- 178 -------------
131 179
132 This directory and its sub-directories hold th 180 This directory and its sub-directories hold the top-level card modules
133 for PCI soundcards and the code specific to th 181 for PCI soundcards and the code specific to the PCI BUS.
134 182
135 The drivers compiled from a single file are st 183 The drivers compiled from a single file are stored directly in the pci
136 directory, while the drivers with several sour 184 directory, while the drivers with several source files are stored on
137 their own sub-directory (e.g. emu10k1, ice1712 185 their own sub-directory (e.g. emu10k1, ice1712).
138 186
139 isa directory 187 isa directory
140 ------------- 188 -------------
141 189
142 This directory and its sub-directories hold th 190 This directory and its sub-directories hold the top-level card modules
143 for ISA soundcards. 191 for ISA soundcards.
144 192
145 arm, ppc, and sparc directories 193 arm, ppc, and sparc directories
146 ------------------------------- 194 -------------------------------
147 195
148 They are used for top-level card modules which 196 They are used for top-level card modules which are specific to one of
149 these architectures. 197 these architectures.
150 198
151 usb directory 199 usb directory
152 ------------- 200 -------------
153 201
154 This directory contains the USB-audio driver. !! 202 This directory contains the USB-audio driver. In the latest version, the
155 The USB MIDI driver is integrated in the usb-a !! 203 USB MIDI driver is integrated in the usb-audio driver.
156 204
157 pcmcia directory 205 pcmcia directory
158 ---------------- 206 ----------------
159 207
160 The PCMCIA, especially PCCard drivers will go 208 The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
161 be in the pci directory, because their API is 209 be in the pci directory, because their API is identical to that of
162 standard PCI cards. 210 standard PCI cards.
163 211
164 soc directory <<
165 ------------- <<
166 <<
167 This directory contains the codes for ASoC (AL <<
168 layer including ASoC core, codec and machine d <<
169 <<
170 oss directory 212 oss directory
171 ------------- 213 -------------
172 214
173 This contains OSS/Lite code. !! 215 The OSS/Lite source files are stored here in Linux 2.6 (or later) tree.
174 At the time of writing, all code has been remo !! 216 In the ALSA driver tarball, this directory is empty, of course :)
175 on m68k. <<
176 <<
177 217
178 Basic Flow for PCI Drivers 218 Basic Flow for PCI Drivers
179 ========================== 219 ==========================
180 220
181 Outline 221 Outline
182 ------- 222 -------
183 223
184 The minimum flow for PCI soundcards is as foll 224 The minimum flow for PCI soundcards is as follows:
185 225
186 - define the PCI ID table (see the section `P 226 - define the PCI ID table (see the section `PCI Entries`_).
187 227
188 - create ``probe`` callback. 228 - create ``probe`` callback.
189 229
190 - create ``remove`` callback. 230 - create ``remove`` callback.
191 231
192 - create a struct pci_driver structure !! 232 - create a :c:type:`struct pci_driver <pci_driver>` structure
193 containing the three pointers above. 233 containing the three pointers above.
194 234
195 - create an ``init`` function just calling th 235 - create an ``init`` function just calling the
196 :c:func:`pci_register_driver()` to register 236 :c:func:`pci_register_driver()` to register the pci_driver
197 table defined above. 237 table defined above.
198 238
199 - create an ``exit`` function to call the 239 - create an ``exit`` function to call the
200 :c:func:`pci_unregister_driver()` function. 240 :c:func:`pci_unregister_driver()` function.
201 241
202 Full Code Example 242 Full Code Example
203 ----------------- 243 -----------------
204 244
205 The code example is shown below. Some parts ar 245 The code example is shown below. Some parts are kept unimplemented at
206 this moment but will be filled in the next sec 246 this moment but will be filled in the next sections. The numbers in the
207 comment lines of the :c:func:`snd_mychip_probe 247 comment lines of the :c:func:`snd_mychip_probe()` function refer
208 to details explained in the following section. 248 to details explained in the following section.
209 249
210 :: 250 ::
211 251
212 #include <linux/init.h> 252 #include <linux/init.h>
213 #include <linux/pci.h> 253 #include <linux/pci.h>
214 #include <linux/slab.h> 254 #include <linux/slab.h>
215 #include <sound/core.h> 255 #include <sound/core.h>
216 #include <sound/initval.h> 256 #include <sound/initval.h>
217 257
218 /* module parameters (see "Module Parame 258 /* module parameters (see "Module Parameters") */
219 /* SNDRV_CARDS: maximum number of cards 259 /* SNDRV_CARDS: maximum number of cards supported by this module */
220 static int index[SNDRV_CARDS] = SNDRV_DE 260 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
221 static char *id[SNDRV_CARDS] = SNDRV_DEF 261 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
222 static bool enable[SNDRV_CARDS] = SNDRV_ 262 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
223 263
224 /* definition of the chip-specific recor 264 /* definition of the chip-specific record */
225 struct mychip { 265 struct mychip {
226 struct snd_card *card; 266 struct snd_card *card;
227 /* the rest of the implementatio 267 /* the rest of the implementation will be in section
228 * "PCI Resource Management" 268 * "PCI Resource Management"
229 */ 269 */
230 }; 270 };
231 271
232 /* chip-specific destructor 272 /* chip-specific destructor
233 * (see "PCI Resource Management") 273 * (see "PCI Resource Management")
234 */ 274 */
235 static int snd_mychip_free(struct mychip 275 static int snd_mychip_free(struct mychip *chip)
236 { 276 {
237 .... /* will be implemented late 277 .... /* will be implemented later... */
238 } 278 }
239 279
240 /* component-destructor 280 /* component-destructor
241 * (see "Management of Cards and Compone 281 * (see "Management of Cards and Components")
242 */ 282 */
243 static int snd_mychip_dev_free(struct sn 283 static int snd_mychip_dev_free(struct snd_device *device)
244 { 284 {
245 return snd_mychip_free(device->d 285 return snd_mychip_free(device->device_data);
246 } 286 }
247 287
248 /* chip-specific constructor 288 /* chip-specific constructor
249 * (see "Management of Cards and Compone 289 * (see "Management of Cards and Components")
250 */ 290 */
251 static int snd_mychip_create(struct snd_ 291 static int snd_mychip_create(struct snd_card *card,
252 struct pci_ 292 struct pci_dev *pci,
253 struct mych 293 struct mychip **rchip)
254 { 294 {
255 struct mychip *chip; 295 struct mychip *chip;
256 int err; 296 int err;
257 static const struct snd_device_o !! 297 static struct snd_device_ops ops = {
258 .dev_free = snd_mychip_de 298 .dev_free = snd_mychip_dev_free,
259 }; 299 };
260 300
261 *rchip = NULL; 301 *rchip = NULL;
262 302
263 /* check PCI availability here 303 /* check PCI availability here
264 * (see "PCI Resource Management 304 * (see "PCI Resource Management")
265 */ 305 */
266 .... 306 ....
267 307
268 /* allocate a chip-specific data 308 /* allocate a chip-specific data with zero filled */
269 chip = kzalloc(sizeof(*chip), GF 309 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
270 if (chip == NULL) 310 if (chip == NULL)
271 return -ENOMEM; 311 return -ENOMEM;
272 312
273 chip->card = card; 313 chip->card = card;
274 314
275 /* rest of initialization here; 315 /* rest of initialization here; will be implemented
276 * later, see "PCI Resource Mana 316 * later, see "PCI Resource Management"
277 */ 317 */
278 .... 318 ....
279 319
280 err = snd_device_new(card, SNDRV 320 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
281 if (err < 0) { 321 if (err < 0) {
282 snd_mychip_free(chip); 322 snd_mychip_free(chip);
283 return err; 323 return err;
284 } 324 }
285 325
286 *rchip = chip; 326 *rchip = chip;
287 return 0; 327 return 0;
288 } 328 }
289 329
290 /* constructor -- see "Driver Constructo 330 /* constructor -- see "Driver Constructor" sub-section */
291 static int snd_mychip_probe(struct pci_d 331 static int snd_mychip_probe(struct pci_dev *pci,
292 const struct 332 const struct pci_device_id *pci_id)
293 { 333 {
294 static int dev; 334 static int dev;
295 struct snd_card *card; 335 struct snd_card *card;
296 struct mychip *chip; 336 struct mychip *chip;
297 int err; 337 int err;
298 338
299 /* (1) */ 339 /* (1) */
300 if (dev >= SNDRV_CARDS) 340 if (dev >= SNDRV_CARDS)
301 return -ENODEV; 341 return -ENODEV;
302 if (!enable[dev]) { 342 if (!enable[dev]) {
303 dev++; 343 dev++;
304 return -ENOENT; 344 return -ENOENT;
305 } 345 }
306 346
307 /* (2) */ 347 /* (2) */
308 err = snd_card_new(&pci->dev, in 348 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
309 0, &card); 349 0, &card);
310 if (err < 0) 350 if (err < 0)
311 return err; 351 return err;
312 352
313 /* (3) */ 353 /* (3) */
314 err = snd_mychip_create(card, pc 354 err = snd_mychip_create(card, pci, &chip);
315 if (err < 0) !! 355 if (err < 0) {
316 goto error; !! 356 snd_card_free(card);
>> 357 return err;
>> 358 }
317 359
318 /* (4) */ 360 /* (4) */
319 strcpy(card->driver, "My Chip"); 361 strcpy(card->driver, "My Chip");
320 strcpy(card->shortname, "My Own 362 strcpy(card->shortname, "My Own Chip 123");
321 sprintf(card->longname, "%s at 0 363 sprintf(card->longname, "%s at 0x%lx irq %i",
322 card->shortname, chip->p !! 364 card->shortname, chip->ioport, chip->irq);
323 365
324 /* (5) */ 366 /* (5) */
325 .... /* implemented later */ 367 .... /* implemented later */
326 368
327 /* (6) */ 369 /* (6) */
328 err = snd_card_register(card); 370 err = snd_card_register(card);
329 if (err < 0) !! 371 if (err < 0) {
330 goto error; !! 372 snd_card_free(card);
>> 373 return err;
>> 374 }
331 375
332 /* (7) */ 376 /* (7) */
333 pci_set_drvdata(pci, card); 377 pci_set_drvdata(pci, card);
334 dev++; 378 dev++;
335 return 0; 379 return 0;
336 <<
337 error: <<
338 snd_card_free(card); <<
339 return err; <<
340 } 380 }
341 381
342 /* destructor -- see the "Destructor" su 382 /* destructor -- see the "Destructor" sub-section */
343 static void snd_mychip_remove(struct pci 383 static void snd_mychip_remove(struct pci_dev *pci)
344 { 384 {
345 snd_card_free(pci_get_drvdata(pc 385 snd_card_free(pci_get_drvdata(pci));
>> 386 pci_set_drvdata(pci, NULL);
346 } 387 }
347 388
348 389
349 390
350 Driver Constructor 391 Driver Constructor
351 ------------------ 392 ------------------
352 393
353 The real constructor of PCI drivers is the ``p 394 The real constructor of PCI drivers is the ``probe`` callback. The
354 ``probe`` callback and other component-constru 395 ``probe`` callback and other component-constructors which are called
355 from the ``probe`` callback cannot be used wit 396 from the ``probe`` callback cannot be used with the ``__init`` prefix
356 because any PCI device could be a hotplug devi 397 because any PCI device could be a hotplug device.
357 398
358 In the ``probe`` callback, the following schem 399 In the ``probe`` callback, the following scheme is often used.
359 400
360 1) Check and increment the device index. 401 1) Check and increment the device index.
361 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362 403
363 :: 404 ::
364 405
365 static int dev; 406 static int dev;
366 .... 407 ....
367 if (dev >= SNDRV_CARDS) 408 if (dev >= SNDRV_CARDS)
368 return -ENODEV; 409 return -ENODEV;
369 if (!enable[dev]) { 410 if (!enable[dev]) {
370 dev++; 411 dev++;
371 return -ENOENT; 412 return -ENOENT;
372 } 413 }
373 414
374 415
375 where ``enable[dev]`` is the module option. 416 where ``enable[dev]`` is the module option.
376 417
377 Each time the ``probe`` callback is called, ch 418 Each time the ``probe`` callback is called, check the availability of
378 the device. If not available, simply increment 419 the device. If not available, simply increment the device index and
379 return. dev will be incremented also later (`s !! 420 returns. dev will be incremented also later (`step 7
380 <7) Set the PCI driver data and return zero._> !! 421 <#set-the-pci-driver-data-and-return-zero>`__).
381 422
382 2) Create a card instance 423 2) Create a card instance
383 ~~~~~~~~~~~~~~~~~~~~~~~~~ 424 ~~~~~~~~~~~~~~~~~~~~~~~~~
384 425
385 :: 426 ::
386 427
387 struct snd_card *card; 428 struct snd_card *card;
388 int err; 429 int err;
389 .... 430 ....
390 err = snd_card_new(&pci->dev, index[dev], id 431 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
391 0, &card); 432 0, &card);
392 433
393 434
394 The details will be explained in the section ` 435 The details will be explained in the section `Management of Cards and
395 Components`_. 436 Components`_.
396 437
397 3) Create a main component 438 3) Create a main component
398 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 439 ~~~~~~~~~~~~~~~~~~~~~~~~~~
399 440
400 In this part, the PCI resources are allocated: !! 441 In this part, the PCI resources are allocated.
>> 442
>> 443 ::
401 444
402 struct mychip *chip; 445 struct mychip *chip;
403 .... 446 ....
404 err = snd_mychip_create(card, pci, &chip); 447 err = snd_mychip_create(card, pci, &chip);
405 if (err < 0) !! 448 if (err < 0) {
406 goto error; <<
407 <<
408 The details will be explained in the section ` <<
409 Management`_. <<
410 <<
411 When something goes wrong, the probe function <<
412 error. In this example, we have a single erro <<
413 at the end of the function:: <<
414 <<
415 error: <<
416 snd_card_free(card); 449 snd_card_free(card);
417 return err; 450 return err;
>> 451 }
418 452
419 Since each component can be properly freed, th !! 453 The details will be explained in the section `PCI Resource
420 :c:func:`snd_card_free()` call should suffice !! 454 Management`_.
421 <<
422 455
423 4) Set the driver ID and name strings. 456 4) Set the driver ID and name strings.
424 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 457 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
425 458
426 :: 459 ::
427 460
428 strcpy(card->driver, "My Chip"); 461 strcpy(card->driver, "My Chip");
429 strcpy(card->shortname, "My Own Chip 123"); 462 strcpy(card->shortname, "My Own Chip 123");
430 sprintf(card->longname, "%s at 0x%lx irq %i" 463 sprintf(card->longname, "%s at 0x%lx irq %i",
431 card->shortname, chip->port, chip->i !! 464 card->shortname, chip->ioport, chip->irq);
432 465
433 The driver field holds the minimal ID string o 466 The driver field holds the minimal ID string of the chip. This is used
434 by alsa-lib's configurator, so keep it simple 467 by alsa-lib's configurator, so keep it simple but unique. Even the
435 same driver can have different driver IDs to d 468 same driver can have different driver IDs to distinguish the
436 functionality of each chip type. 469 functionality of each chip type.
437 470
438 The shortname field is a string shown as more 471 The shortname field is a string shown as more verbose name. The longname
439 field contains the information shown in ``/pro 472 field contains the information shown in ``/proc/asound/cards``.
440 473
441 5) Create other components, such as mixer, MID 474 5) Create other components, such as mixer, MIDI, etc.
442 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
443 476
444 Here you define the basic components such as ` !! 477 Here you define the basic components such as `PCM <#PCM-Interface>`__,
445 mixer (e.g. `AC97 <API for AC97 Codec_>`__), M !! 478 mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
446 `MPU-401 <MIDI (MPU401-UART) Interface_>`__), !! 479 `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
447 Also, if you want a `proc file <Proc Interface !! 480 Also, if you want a `proc file <#Proc-Interface>`__, define it here,
448 too. 481 too.
449 482
450 6) Register the card instance. 483 6) Register the card instance.
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452 485
453 :: 486 ::
454 487
455 err = snd_card_register(card); 488 err = snd_card_register(card);
456 if (err < 0) !! 489 if (err < 0) {
457 goto error; !! 490 snd_card_free(card);
>> 491 return err;
>> 492 }
458 493
459 Will be explained in the section `Management o 494 Will be explained in the section `Management of Cards and
460 Components`_, too. 495 Components`_, too.
461 496
462 7) Set the PCI driver data and return zero. 497 7) Set the PCI driver data and return zero.
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464 499
465 :: 500 ::
466 501
467 pci_set_drvdata(pci, card); 502 pci_set_drvdata(pci, card);
468 dev++; 503 dev++;
469 return 0; 504 return 0;
470 505
471 In the above, the card record is stored. This 506 In the above, the card record is stored. This pointer is used in the
472 remove callback and power-management callbacks 507 remove callback and power-management callbacks, too.
473 508
474 Destructor 509 Destructor
475 ---------- 510 ----------
476 511
477 The destructor, the remove callback, simply re !! 512 The destructor, remove callback, simply releases the card instance. Then
478 Then the ALSA middle layer will release all th !! 513 the ALSA middle layer will release all the attached components
479 automatically. 514 automatically.
480 515
481 It would be typically just calling :c:func:`sn !! 516 It would be typically like the following:
>> 517
>> 518 ::
482 519
483 static void snd_mychip_remove(struct pci_dev 520 static void snd_mychip_remove(struct pci_dev *pci)
484 { 521 {
485 snd_card_free(pci_get_drvdata(pci)); 522 snd_card_free(pci_get_drvdata(pci));
>> 523 pci_set_drvdata(pci, NULL);
486 } 524 }
487 525
488 526
489 The above code assumes that the card pointer i 527 The above code assumes that the card pointer is set to the PCI driver
490 data. 528 data.
491 529
492 Header Files 530 Header Files
493 ------------ 531 ------------
494 532
495 For the above example, at least the following 533 For the above example, at least the following include files are
496 necessary:: !! 534 necessary.
>> 535
>> 536 ::
497 537
498 #include <linux/init.h> 538 #include <linux/init.h>
499 #include <linux/pci.h> 539 #include <linux/pci.h>
500 #include <linux/slab.h> 540 #include <linux/slab.h>
501 #include <sound/core.h> 541 #include <sound/core.h>
502 #include <sound/initval.h> 542 #include <sound/initval.h>
503 543
504 where the last one is necessary only when modu 544 where the last one is necessary only when module options are defined
505 in the source file. If the code is split into 545 in the source file. If the code is split into several files, the files
506 without module options don't need them. 546 without module options don't need them.
507 547
508 In addition to these headers, you'll need ``<l 548 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
509 interrupt handling, and ``<linux/io.h>`` for I !! 549 interrupt handling, and ``<asm/io.h>`` for I/O access. If you use the
510 :c:func:`mdelay()` or :c:func:`udelay()` funct 550 :c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
511 to include ``<linux/delay.h>`` too. 551 to include ``<linux/delay.h>`` too.
512 552
513 The ALSA interfaces like the PCM and control A 553 The ALSA interfaces like the PCM and control APIs are defined in other
514 ``<sound/xxx.h>`` header files. They have to b 554 ``<sound/xxx.h>`` header files. They have to be included after
515 ``<sound/core.h>``. 555 ``<sound/core.h>``.
516 556
517 Management of Cards and Components 557 Management of Cards and Components
518 ================================== 558 ==================================
519 559
520 Card Instance 560 Card Instance
521 ------------- 561 -------------
522 562
523 For each soundcard, a “card” record must b 563 For each soundcard, a “card” record must be allocated.
524 564
525 A card record is the headquarters of the sound 565 A card record is the headquarters of the soundcard. It manages the whole
526 list of devices (components) on the soundcard, 566 list of devices (components) on the soundcard, such as PCM, mixers,
527 MIDI, synthesizer, and so on. Also, the card r 567 MIDI, synthesizer, and so on. Also, the card record holds the ID and the
528 name strings of the card, manages the root of 568 name strings of the card, manages the root of proc files, and controls
529 the power-management states and hotplug discon 569 the power-management states and hotplug disconnections. The component
530 list on the card record is used to manage the 570 list on the card record is used to manage the correct release of
531 resources at destruction. 571 resources at destruction.
532 572
533 As mentioned above, to create a card instance, 573 As mentioned above, to create a card instance, call
534 :c:func:`snd_card_new()`:: !! 574 :c:func:`snd_card_new()`.
>> 575
>> 576 ::
535 577
536 struct snd_card *card; 578 struct snd_card *card;
537 int err; 579 int err;
538 err = snd_card_new(&pci->dev, index, id, mod 580 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
539 581
540 582
541 The function takes six arguments: the parent d 583 The function takes six arguments: the parent device pointer, the
542 card-index number, the id string, the module p 584 card-index number, the id string, the module pointer (usually
543 ``THIS_MODULE``), the size of extra-data space 585 ``THIS_MODULE``), the size of extra-data space, and the pointer to
544 return the card instance. The extra_size argum 586 return the card instance. The extra_size argument is used to allocate
545 card->private_data for the chip-specific data. 587 card->private_data for the chip-specific data. Note that these data are
546 allocated by :c:func:`snd_card_new()`. 588 allocated by :c:func:`snd_card_new()`.
547 589
548 The first argument, the pointer of struct devi !! 590 The first argument, the pointer of struct :c:type:`struct device
549 device. For PCI devices, typically ``&pci->`` !! 591 <device>`, specifies the parent device. For PCI devices, typically
>> 592 ``&pci->`` is passed there.
550 593
551 Components 594 Components
552 ---------- 595 ----------
553 596
554 After the card is created, you can attach the 597 After the card is created, you can attach the components (devices) to
555 the card instance. In an ALSA driver, a compon 598 the card instance. In an ALSA driver, a component is represented as a
556 struct snd_device object. A component !! 599 :c:type:`struct snd_device <snd_device>` object. A component
557 can be a PCM instance, a control interface, a 600 can be a PCM instance, a control interface, a raw MIDI interface, etc.
558 Each such instance has one component entry. 601 Each such instance has one component entry.
559 602
560 A component can be created via the :c:func:`sn !! 603 A component can be created via :c:func:`snd_device_new()`
561 function:: !! 604 function.
>> 605
>> 606 ::
562 607
563 snd_device_new(card, SNDRV_DEV_XXX, chip, &o 608 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
564 609
565 This takes the card pointer, the device-level 610 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
566 data pointer, and the callback pointers (``&op 611 data pointer, and the callback pointers (``&ops``). The device-level
567 defines the type of components and the order o 612 defines the type of components and the order of registration and
568 de-registration. For most components, the devi 613 de-registration. For most components, the device-level is already
569 defined. For a user-defined component, you can 614 defined. For a user-defined component, you can use
570 ``SNDRV_DEV_LOWLEVEL``. 615 ``SNDRV_DEV_LOWLEVEL``.
571 616
572 This function itself doesn't allocate the data 617 This function itself doesn't allocate the data space. The data must be
573 allocated manually beforehand, and its pointer 618 allocated manually beforehand, and its pointer is passed as the
574 argument. This pointer (``chip`` in the above 619 argument. This pointer (``chip`` in the above example) is used as the
575 identifier for the instance. 620 identifier for the instance.
576 621
577 Each pre-defined ALSA component such as AC97 a !! 622 Each pre-defined ALSA component such as ac97 and pcm calls
578 :c:func:`snd_device_new()` inside its construc 623 :c:func:`snd_device_new()` inside its constructor. The destructor
579 for each component is defined in the callback 624 for each component is defined in the callback pointers. Hence, you don't
580 need to take care of calling a destructor for 625 need to take care of calling a destructor for such a component.
581 626
582 If you wish to create your own component, you 627 If you wish to create your own component, you need to set the destructor
583 function to the dev_free callback in the ``ops 628 function to the dev_free callback in the ``ops``, so that it can be
584 released automatically via :c:func:`snd_card_f 629 released automatically via :c:func:`snd_card_free()`. The next
585 example will show an implementation of chip-sp 630 example will show an implementation of chip-specific data.
586 631
587 Chip-Specific Data 632 Chip-Specific Data
588 ------------------ 633 ------------------
589 634
590 Chip-specific information, e.g. the I/O port a 635 Chip-specific information, e.g. the I/O port address, its resource
591 pointer, or the irq number, is stored in the c !! 636 pointer, or the irq number, is stored in the chip-specific record.
>> 637
>> 638 ::
592 639
593 struct mychip { 640 struct mychip {
594 .... 641 ....
595 }; 642 };
596 643
597 644
598 In general, there are two ways of allocating t 645 In general, there are two ways of allocating the chip record.
599 646
600 1. Allocating via :c:func:`snd_card_new()`. 647 1. Allocating via :c:func:`snd_card_new()`.
601 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 648 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602 649
603 As mentioned above, you can pass the extra-dat 650 As mentioned above, you can pass the extra-data-length to the 5th
604 argument of :c:func:`snd_card_new()`, e.g.:: !! 651 argument of :c:func:`snd_card_new()`, i.e.
>> 652
>> 653 ::
605 654
606 err = snd_card_new(&pci->dev, index[dev], id 655 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
607 sizeof(struct mychip), &c 656 sizeof(struct mychip), &card);
608 657
609 struct mychip is the type of the chip record. !! 658 :c:type:`struct mychip <mychip>` is the type of the chip record.
610 659
611 In return, the allocated record can be accesse 660 In return, the allocated record can be accessed as
612 661
613 :: 662 ::
614 663
615 struct mychip *chip = card->private_data; 664 struct mychip *chip = card->private_data;
616 665
617 With this method, you don't have to allocate t 666 With this method, you don't have to allocate twice. The record is
618 released together with the card instance. 667 released together with the card instance.
619 668
620 2. Allocating an extra device. 669 2. Allocating an extra device.
621 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 670 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622 671
623 After allocating a card instance via :c:func:` 672 After allocating a card instance via :c:func:`snd_card_new()`
624 (with ``0`` on the 4th arg), call :c:func:`kza !! 673 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
>> 674
>> 675 ::
625 676
626 struct snd_card *card; 677 struct snd_card *card;
627 struct mychip *chip; 678 struct mychip *chip;
628 err = snd_card_new(&pci->dev, index[dev], id 679 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
629 0, &card); 680 0, &card);
630 ..... 681 .....
631 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 682 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
632 683
633 The chip record should have the field to hold 684 The chip record should have the field to hold the card pointer at least,
634 685
635 :: 686 ::
636 687
637 struct mychip { 688 struct mychip {
638 struct snd_card *card; 689 struct snd_card *card;
639 .... 690 ....
640 }; 691 };
641 692
642 693
643 Then, set the card pointer in the returned chi !! 694 Then, set the card pointer in the returned chip instance.
>> 695
>> 696 ::
644 697
645 chip->card = card; 698 chip->card = card;
646 699
647 Next, initialize the fields, and register this 700 Next, initialize the fields, and register this chip record as a
648 low-level device with a specified ``ops``:: !! 701 low-level device with a specified ``ops``,
649 702
650 static const struct snd_device_ops ops = { !! 703 ::
>> 704
>> 705 static struct snd_device_ops ops = {
651 .dev_free = snd_mychip_dev_fr 706 .dev_free = snd_mychip_dev_free,
652 }; 707 };
653 .... 708 ....
654 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chi 709 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
655 710
656 :c:func:`snd_mychip_dev_free()` is the device- 711 :c:func:`snd_mychip_dev_free()` is the device-destructor
657 function, which will call the real destructor: !! 712 function, which will call the real destructor.
>> 713
>> 714 ::
658 715
659 static int snd_mychip_dev_free(struct snd_de 716 static int snd_mychip_dev_free(struct snd_device *device)
660 { 717 {
661 return snd_mychip_free(device->devic 718 return snd_mychip_free(device->device_data);
662 } 719 }
663 720
664 where :c:func:`snd_mychip_free()` is the real 721 where :c:func:`snd_mychip_free()` is the real destructor.
665 722
666 The demerit of this method is the obviously la <<
667 The merit is, however, that you can trigger yo <<
668 registering and disconnecting the card via a s <<
669 About registering and disconnecting the card, <<
670 below. <<
671 <<
672 <<
673 Registration and Release 723 Registration and Release
674 ------------------------ 724 ------------------------
675 725
676 After all components are assigned, register th 726 After all components are assigned, register the card instance by calling
677 :c:func:`snd_card_register()`. Access to the d 727 :c:func:`snd_card_register()`. Access to the device files is
678 enabled at this point. That is, before 728 enabled at this point. That is, before
679 :c:func:`snd_card_register()` is called, the c 729 :c:func:`snd_card_register()` is called, the components are safely
680 inaccessible from external side. If this call 730 inaccessible from external side. If this call fails, exit the probe
681 function after releasing the card via :c:func: 731 function after releasing the card via :c:func:`snd_card_free()`.
682 732
683 For releasing the card instance, you can call 733 For releasing the card instance, you can call simply
684 :c:func:`snd_card_free()`. As mentioned earlie 734 :c:func:`snd_card_free()`. As mentioned earlier, all components
685 are released automatically by this call. 735 are released automatically by this call.
686 736
687 For a device which allows hotplugging, you can 737 For a device which allows hotplugging, you can use
688 :c:func:`snd_card_free_when_closed()`. This on 738 :c:func:`snd_card_free_when_closed()`. This one will postpone
689 the destruction until all devices are closed. 739 the destruction until all devices are closed.
690 740
691 PCI Resource Management 741 PCI Resource Management
692 ======================= 742 =======================
693 743
694 Full Code Example 744 Full Code Example
695 ----------------- 745 -----------------
696 746
697 In this section, we'll complete the chip-speci 747 In this section, we'll complete the chip-specific constructor,
698 destructor and PCI entries. Example code is sh !! 748 destructor and PCI entries. Example code is shown first, below.
>> 749
>> 750 ::
699 751
700 struct mychip { 752 struct mychip {
701 struct snd_card *card; 753 struct snd_card *card;
702 struct pci_dev *pci; 754 struct pci_dev *pci;
703 755
704 unsigned long port; 756 unsigned long port;
705 int irq; 757 int irq;
706 }; 758 };
707 759
708 static int snd_mychip_free(struct mychip 760 static int snd_mychip_free(struct mychip *chip)
709 { 761 {
710 /* disable hardware here if any 762 /* disable hardware here if any */
711 .... /* (not implemented in this 763 .... /* (not implemented in this document) */
712 764
713 /* release the irq */ 765 /* release the irq */
714 if (chip->irq >= 0) 766 if (chip->irq >= 0)
715 free_irq(chip->irq, chip 767 free_irq(chip->irq, chip);
716 /* release the I/O ports & memor 768 /* release the I/O ports & memory */
717 pci_release_regions(chip->pci); 769 pci_release_regions(chip->pci);
718 /* disable the PCI entry */ 770 /* disable the PCI entry */
719 pci_disable_device(chip->pci); 771 pci_disable_device(chip->pci);
720 /* release the data */ 772 /* release the data */
721 kfree(chip); 773 kfree(chip);
722 return 0; 774 return 0;
723 } 775 }
724 776
725 /* chip-specific constructor */ 777 /* chip-specific constructor */
726 static int snd_mychip_create(struct snd_ 778 static int snd_mychip_create(struct snd_card *card,
727 struct pci_ 779 struct pci_dev *pci,
728 struct mych 780 struct mychip **rchip)
729 { 781 {
730 struct mychip *chip; 782 struct mychip *chip;
731 int err; 783 int err;
732 static const struct snd_device_o !! 784 static struct snd_device_ops ops = {
733 .dev_free = snd_mychip_de 785 .dev_free = snd_mychip_dev_free,
734 }; 786 };
735 787
736 *rchip = NULL; 788 *rchip = NULL;
737 789
738 /* initialize the PCI entry */ 790 /* initialize the PCI entry */
739 err = pci_enable_device(pci); 791 err = pci_enable_device(pci);
740 if (err < 0) 792 if (err < 0)
741 return err; 793 return err;
742 /* check PCI availability (28bit 794 /* check PCI availability (28bit DMA) */
743 if (pci_set_dma_mask(pci, DMA_BI 795 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
744 pci_set_consistent_dma_mask( 796 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
745 printk(KERN_ERR "error t 797 printk(KERN_ERR "error to set 28bit mask DMA\n");
746 pci_disable_device(pci); 798 pci_disable_device(pci);
747 return -ENXIO; 799 return -ENXIO;
748 } 800 }
749 801
750 chip = kzalloc(sizeof(*chip), GF 802 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
751 if (chip == NULL) { 803 if (chip == NULL) {
752 pci_disable_device(pci); 804 pci_disable_device(pci);
753 return -ENOMEM; 805 return -ENOMEM;
754 } 806 }
755 807
756 /* initialize the stuff */ 808 /* initialize the stuff */
757 chip->card = card; 809 chip->card = card;
758 chip->pci = pci; 810 chip->pci = pci;
759 chip->irq = -1; 811 chip->irq = -1;
760 812
761 /* (1) PCI resource allocation * 813 /* (1) PCI resource allocation */
762 err = pci_request_regions(pci, " 814 err = pci_request_regions(pci, "My Chip");
763 if (err < 0) { 815 if (err < 0) {
764 kfree(chip); 816 kfree(chip);
765 pci_disable_device(pci); 817 pci_disable_device(pci);
766 return err; 818 return err;
767 } 819 }
768 chip->port = pci_resource_start( 820 chip->port = pci_resource_start(pci, 0);
769 if (request_irq(pci->irq, snd_my 821 if (request_irq(pci->irq, snd_mychip_interrupt,
770 IRQF_SHARED, KBU 822 IRQF_SHARED, KBUILD_MODNAME, chip)) {
771 printk(KERN_ERR "cannot 823 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
772 snd_mychip_free(chip); 824 snd_mychip_free(chip);
773 return -EBUSY; 825 return -EBUSY;
774 } 826 }
775 chip->irq = pci->irq; 827 chip->irq = pci->irq;
776 card->sync_irq = chip->irq; <<
777 828
778 /* (2) initialization of the chi 829 /* (2) initialization of the chip hardware */
779 .... /* (not implemented in th 830 .... /* (not implemented in this document) */
780 831
781 err = snd_device_new(card, SNDRV 832 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
782 if (err < 0) { 833 if (err < 0) {
783 snd_mychip_free(chip); 834 snd_mychip_free(chip);
784 return err; 835 return err;
785 } 836 }
786 837
787 *rchip = chip; 838 *rchip = chip;
788 return 0; 839 return 0;
789 } 840 }
790 841
791 /* PCI IDs */ 842 /* PCI IDs */
792 static struct pci_device_id snd_mychip_i 843 static struct pci_device_id snd_mychip_ids[] = {
793 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ 844 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
794 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 845 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
795 .... 846 ....
796 { 0, } 847 { 0, }
797 }; 848 };
798 MODULE_DEVICE_TABLE(pci, snd_mychip_ids) 849 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
799 850
800 /* pci_driver definition */ 851 /* pci_driver definition */
801 static struct pci_driver driver = { 852 static struct pci_driver driver = {
802 .name = KBUILD_MODNAME, 853 .name = KBUILD_MODNAME,
803 .id_table = snd_mychip_ids, 854 .id_table = snd_mychip_ids,
804 .probe = snd_mychip_probe, 855 .probe = snd_mychip_probe,
805 .remove = snd_mychip_remove, 856 .remove = snd_mychip_remove,
806 }; 857 };
807 858
808 /* module initialization */ 859 /* module initialization */
809 static int __init alsa_card_mychip_init( 860 static int __init alsa_card_mychip_init(void)
810 { 861 {
811 return pci_register_driver(&driv 862 return pci_register_driver(&driver);
812 } 863 }
813 864
814 /* module clean up */ 865 /* module clean up */
815 static void __exit alsa_card_mychip_exit 866 static void __exit alsa_card_mychip_exit(void)
816 { 867 {
817 pci_unregister_driver(&driver); 868 pci_unregister_driver(&driver);
818 } 869 }
819 870
820 module_init(alsa_card_mychip_init) 871 module_init(alsa_card_mychip_init)
821 module_exit(alsa_card_mychip_exit) 872 module_exit(alsa_card_mychip_exit)
822 873
823 EXPORT_NO_SYMBOLS; /* for old kernels on 874 EXPORT_NO_SYMBOLS; /* for old kernels only */
824 875
825 Some Hafta's 876 Some Hafta's
826 ------------ 877 ------------
827 878
828 The allocation of PCI resources is done in the 879 The allocation of PCI resources is done in the ``probe`` function, and
829 usually an extra :c:func:`xxx_create()` functi 880 usually an extra :c:func:`xxx_create()` function is written for this
830 purpose. 881 purpose.
831 882
832 In the case of PCI devices, you first have to 883 In the case of PCI devices, you first have to call the
833 :c:func:`pci_enable_device()` function before 884 :c:func:`pci_enable_device()` function before allocating
834 resources. Also, you need to set the proper PC 885 resources. Also, you need to set the proper PCI DMA mask to limit the
835 accessed I/O range. In some cases, you might n 886 accessed I/O range. In some cases, you might need to call
836 :c:func:`pci_set_master()` function, too. 887 :c:func:`pci_set_master()` function, too.
837 888
838 Suppose a 28bit mask, the code to be added wou !! 889 Suppose the 28bit mask, and the code to be added would be like:
>> 890
>> 891 ::
839 892
840 err = pci_enable_device(pci); 893 err = pci_enable_device(pci);
841 if (err < 0) 894 if (err < 0)
842 return err; 895 return err;
843 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) 896 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
844 pci_set_consistent_dma_mask(pci, DMA_BIT 897 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
845 printk(KERN_ERR "error to set 28bit 898 printk(KERN_ERR "error to set 28bit mask DMA\n");
846 pci_disable_device(pci); 899 pci_disable_device(pci);
847 return -ENXIO; 900 return -ENXIO;
848 } 901 }
849 902
850 903
851 Resource Allocation 904 Resource Allocation
852 ------------------- 905 -------------------
853 906
854 The allocation of I/O ports and irqs is done v 907 The allocation of I/O ports and irqs is done via standard kernel
855 functions. These resources must be released i !! 908 functions. Unlike ALSA ver.0.5.x., there are no helpers for that. And
856 function (see below). !! 909 these resources must be released in the destructor function (see below).
>> 910 Also, on ALSA 0.9.x, you don't need to allocate (pseudo-)DMA for PCI
>> 911 like in ALSA 0.5.x.
857 912
858 Now assume that the PCI device has an I/O port 913 Now assume that the PCI device has an I/O port with 8 bytes and an
859 interrupt. Then struct mychip will have the !! 914 interrupt. Then :c:type:`struct mychip <mychip>` will have the
860 following fields:: !! 915 following fields:
>> 916
>> 917 ::
861 918
862 struct mychip { 919 struct mychip {
863 struct snd_card *card; 920 struct snd_card *card;
864 921
865 unsigned long port; 922 unsigned long port;
866 int irq; 923 int irq;
867 }; 924 };
868 925
869 926
870 For an I/O port (and also a memory region), yo 927 For an I/O port (and also a memory region), you need to have the
871 resource pointer for the standard resource man 928 resource pointer for the standard resource management. For an irq, you
872 have to keep only the irq number (integer). Bu 929 have to keep only the irq number (integer). But you need to initialize
873 this number to -1 before actual allocation, si !! 930 this number as -1 before actual allocation, since irq 0 is valid. The
874 port address and its resource pointer can be i 931 port address and its resource pointer can be initialized as null by
875 :c:func:`kzalloc()` automatically, so you don' 932 :c:func:`kzalloc()` automatically, so you don't have to take care of
876 resetting them. 933 resetting them.
877 934
878 The allocation of an I/O port is done like thi !! 935 The allocation of an I/O port is done like this:
>> 936
>> 937 ::
879 938
880 err = pci_request_regions(pci, "My Chip"); 939 err = pci_request_regions(pci, "My Chip");
881 if (err < 0) { 940 if (err < 0) {
882 kfree(chip); 941 kfree(chip);
883 pci_disable_device(pci); 942 pci_disable_device(pci);
884 return err; 943 return err;
885 } 944 }
886 chip->port = pci_resource_start(pci, 0); 945 chip->port = pci_resource_start(pci, 0);
887 946
888 It will reserve the I/O port region of 8 bytes 947 It will reserve the I/O port region of 8 bytes of the given PCI device.
889 The returned value, ``chip->res_port``, is all 948 The returned value, ``chip->res_port``, is allocated via
890 :c:func:`kmalloc()` by :c:func:`request_region 949 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
891 must be released via :c:func:`kfree()`, but th 950 must be released via :c:func:`kfree()`, but there is a problem with
892 this. This issue will be explained later. 951 this. This issue will be explained later.
893 952
894 The allocation of an interrupt source is done !! 953 The allocation of an interrupt source is done like this:
>> 954
>> 955 ::
895 956
896 if (request_irq(pci->irq, snd_mychip_interru 957 if (request_irq(pci->irq, snd_mychip_interrupt,
897 IRQF_SHARED, KBUILD_MODNAME, 958 IRQF_SHARED, KBUILD_MODNAME, chip)) {
898 printk(KERN_ERR "cannot grab irq %d\ 959 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
899 snd_mychip_free(chip); 960 snd_mychip_free(chip);
900 return -EBUSY; 961 return -EBUSY;
901 } 962 }
902 chip->irq = pci->irq; 963 chip->irq = pci->irq;
903 964
904 where :c:func:`snd_mychip_interrupt()` is the 965 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
905 defined `later <PCM Interrupt Handler_>`__. No !! 966 defined `later <#pcm-interface-interrupt-handler>`__. Note that
906 ``chip->irq`` should be defined only when :c:f 967 ``chip->irq`` should be defined only when :c:func:`request_irq()`
907 succeeded. 968 succeeded.
908 969
909 On the PCI bus, interrupts can be shared. Thus 970 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
910 as the interrupt flag of :c:func:`request_irq( 971 as the interrupt flag of :c:func:`request_irq()`.
911 972
912 The last argument of :c:func:`request_irq()` i 973 The last argument of :c:func:`request_irq()` is the data pointer
913 passed to the interrupt handler. Usually, the 974 passed to the interrupt handler. Usually, the chip-specific record is
914 used for that, but you can use what you like, 975 used for that, but you can use what you like, too.
915 976
916 I won't give details about the interrupt handl 977 I won't give details about the interrupt handler at this point, but at
917 least its appearance can be explained now. The 978 least its appearance can be explained now. The interrupt handler looks
918 usually as follows:: !! 979 usually like the following:
>> 980
>> 981 ::
919 982
920 static irqreturn_t snd_mychip_interrupt(int 983 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
921 { 984 {
922 struct mychip *chip = dev_id; 985 struct mychip *chip = dev_id;
923 .... 986 ....
924 return IRQ_HANDLED; 987 return IRQ_HANDLED;
925 } 988 }
926 989
927 After requesting the IRQ, you can passed it to <<
928 field:: <<
929 <<
930 card->irq = chip->irq; <<
931 <<
932 This allows the PCM core to automatically call <<
933 :c:func:`synchronize_irq()` at the right time, <<
934 See the later section `sync_stop callback`_ fo <<
935 990
936 Now let's write the corresponding destructor f 991 Now let's write the corresponding destructor for the resources above.
937 The role of destructor is simple: disable the 992 The role of destructor is simple: disable the hardware (if already
938 activated) and release the resources. So far, 993 activated) and release the resources. So far, we have no hardware part,
939 so the disabling code is not written here. 994 so the disabling code is not written here.
940 995
941 To release the resources, the “check-and-rel 996 To release the resources, the “check-and-release” method is a safer way.
942 For the interrupt, do like this:: !! 997 For the interrupt, do like this:
>> 998
>> 999 ::
943 1000
944 if (chip->irq >= 0) 1001 if (chip->irq >= 0)
945 free_irq(chip->irq, chip); 1002 free_irq(chip->irq, chip);
946 1003
947 Since the irq number can start from 0, you sho 1004 Since the irq number can start from 0, you should initialize
948 ``chip->irq`` with a negative value (e.g. -1), 1005 ``chip->irq`` with a negative value (e.g. -1), so that you can check
949 the validity of the irq number as above. 1006 the validity of the irq number as above.
950 1007
951 When you requested I/O ports or memory regions 1008 When you requested I/O ports or memory regions via
952 :c:func:`pci_request_region()` or 1009 :c:func:`pci_request_region()` or
953 :c:func:`pci_request_regions()` like in this e 1010 :c:func:`pci_request_regions()` like in this example, release the
954 resource(s) using the corresponding function, 1011 resource(s) using the corresponding function,
955 :c:func:`pci_release_region()` or 1012 :c:func:`pci_release_region()` or
956 :c:func:`pci_release_regions()`:: !! 1013 :c:func:`pci_release_regions()`.
>> 1014
>> 1015 ::
957 1016
958 pci_release_regions(chip->pci); 1017 pci_release_regions(chip->pci);
959 1018
960 When you requested manually via :c:func:`reque 1019 When you requested manually via :c:func:`request_region()` or
961 :c:func:`request_mem_region()`, you can releas 1020 :c:func:`request_mem_region()`, you can release it via
962 :c:func:`release_resource()`. Suppose that you 1021 :c:func:`release_resource()`. Suppose that you keep the resource
963 pointer returned from :c:func:`request_region( 1022 pointer returned from :c:func:`request_region()` in
964 chip->res_port, the release procedure looks li !! 1023 chip->res_port, the release procedure looks like:
>> 1024
>> 1025 ::
965 1026
966 release_and_free_resource(chip->res_port); 1027 release_and_free_resource(chip->res_port);
967 1028
968 Don't forget to call :c:func:`pci_disable_devi 1029 Don't forget to call :c:func:`pci_disable_device()` before the
969 end. 1030 end.
970 1031
971 And finally, release the chip-specific record: !! 1032 And finally, release the chip-specific record.
>> 1033
>> 1034 ::
972 1035
973 kfree(chip); 1036 kfree(chip);
974 1037
975 We didn't implement the hardware disabling par !! 1038 We didn't implement the hardware disabling part in the above. If you
976 need to do this, please note that the destruct 1039 need to do this, please note that the destructor may be called even
977 before the initialization of the chip is compl 1040 before the initialization of the chip is completed. It would be better
978 to have a flag to skip hardware disabling if t 1041 to have a flag to skip hardware disabling if the hardware was not
979 initialized yet. 1042 initialized yet.
980 1043
981 When the chip-data is assigned to the card usi 1044 When the chip-data is assigned to the card using
982 :c:func:`snd_device_new()` with ``SNDRV_DEV_LO !! 1045 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
983 destructor is called last. That is, it is assu !! 1046 destructor is called at the last. That is, it is assured that all other
984 components like PCMs and controls have already 1047 components like PCMs and controls have already been released. You don't
985 have to stop PCMs, etc. explicitly, but just c 1048 have to stop PCMs, etc. explicitly, but just call low-level hardware
986 stopping. 1049 stopping.
987 1050
988 The management of a memory-mapped region is al 1051 The management of a memory-mapped region is almost as same as the
989 management of an I/O port. You'll need two fie !! 1052 management of an I/O port. You'll need three fields like the
>> 1053 following:
>> 1054
>> 1055 ::
990 1056
991 struct mychip { 1057 struct mychip {
992 .... 1058 ....
993 unsigned long iobase_phys; 1059 unsigned long iobase_phys;
994 void __iomem *iobase_virt; 1060 void __iomem *iobase_virt;
995 }; 1061 };
996 1062
997 and the allocation would look like below:: !! 1063 and the allocation would be like below:
998 1064
999 err = pci_request_regions(pci, "My Chip"); !! 1065 ::
1000 if (err < 0) { !! 1066
>> 1067 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1001 kfree(chip); 1068 kfree(chip);
1002 return err; 1069 return err;
1003 } 1070 }
1004 chip->iobase_phys = pci_resource_start(pci, 1071 chip->iobase_phys = pci_resource_start(pci, 0);
1005 chip->iobase_virt = ioremap(chip->iobase_ph !! 1072 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1006 pci_res 1073 pci_resource_len(pci, 0));
1007 1074
1008 and the corresponding destructor would be:: !! 1075 and the corresponding destructor would be:
>> 1076
>> 1077 ::
1009 1078
1010 static int snd_mychip_free(struct mychip *c 1079 static int snd_mychip_free(struct mychip *chip)
1011 { 1080 {
1012 .... 1081 ....
1013 if (chip->iobase_virt) 1082 if (chip->iobase_virt)
1014 iounmap(chip->iobase_virt); 1083 iounmap(chip->iobase_virt);
1015 .... 1084 ....
1016 pci_release_regions(chip->pci); 1085 pci_release_regions(chip->pci);
1017 .... 1086 ....
1018 } 1087 }
1019 1088
1020 Of course, a modern way with :c:func:`pci_iom <<
1021 bit easier, too:: <<
1022 <<
1023 err = pci_request_regions(pci, "My Chip"); <<
1024 if (err < 0) { <<
1025 kfree(chip); <<
1026 return err; <<
1027 } <<
1028 chip->iobase_virt = pci_iomap(pci, 0, 0); <<
1029 <<
1030 which is paired with :c:func:`pci_iounmap()` <<
1031 <<
1032 <<
1033 PCI Entries 1089 PCI Entries
1034 ----------- 1090 -----------
1035 1091
1036 So far, so good. Let's finish the missing PCI 1092 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1037 struct pci_device_id table for !! 1093 :c:type:`struct pci_device_id <pci_device_id>` table for
1038 this chipset. It's a table of PCI vendor/devi 1094 this chipset. It's a table of PCI vendor/device ID number, and some
1039 masks. 1095 masks.
1040 1096
1041 For example:: !! 1097 For example,
>> 1098
>> 1099 ::
1042 1100
1043 static struct pci_device_id snd_mychip_ids[ 1101 static struct pci_device_id snd_mychip_ids[] = {
1044 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_ 1102 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1045 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, 1103 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1046 .... 1104 ....
1047 { 0, } 1105 { 0, }
1048 }; 1106 };
1049 MODULE_DEVICE_TABLE(pci, snd_mychip_ids); 1107 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1050 1108
1051 The first and second fields of the struct pci !! 1109 The first and second fields of the :c:type:`struct pci_device_id
1052 and device IDs. If you have no reason to filt !! 1110 <pci_device_id>` structure are the vendor and device IDs. If you
1053 leave the remaining fields as above. The last !! 1111 have no reason to filter the matching devices, you can leave the
1054 struct pci_device_id contains private data fo !! 1112 remaining fields as above. The last field of the :c:type:`struct
1055 any value here, for example, to define specif !! 1113 pci_device_id <pci_device_id>` struct contains private data
1056 device IDs. Such an example is found in the i !! 1114 for this entry. You can specify any value here, for example, to define
>> 1115 specific operations for supported device IDs. Such an example is found
>> 1116 in the intel8x0 driver.
1057 1117
1058 The last entry of this list is the terminator 1118 The last entry of this list is the terminator. You must specify this
1059 all-zero entry. 1119 all-zero entry.
1060 1120
1061 Then, prepare the struct pci_driver !! 1121 Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1062 record:: !! 1122 record:
>> 1123
>> 1124 ::
1063 1125
1064 static struct pci_driver driver = { 1126 static struct pci_driver driver = {
1065 .name = KBUILD_MODNAME, 1127 .name = KBUILD_MODNAME,
1066 .id_table = snd_mychip_ids, 1128 .id_table = snd_mychip_ids,
1067 .probe = snd_mychip_probe, 1129 .probe = snd_mychip_probe,
1068 .remove = snd_mychip_remove, 1130 .remove = snd_mychip_remove,
1069 }; 1131 };
1070 1132
1071 The ``probe`` and ``remove`` functions have a 1133 The ``probe`` and ``remove`` functions have already been defined in
1072 the previous sections. The ``name`` field is 1134 the previous sections. The ``name`` field is the name string of this
1073 device. Note that you must not use slashes ( !! 1135 device. Note that you must not use a slash “/” in this string.
>> 1136
>> 1137 And at last, the module entries:
1074 1138
1075 And at last, the module entries:: !! 1139 ::
1076 1140
1077 static int __init alsa_card_mychip_init(voi 1141 static int __init alsa_card_mychip_init(void)
1078 { 1142 {
1079 return pci_register_driver(&driver) 1143 return pci_register_driver(&driver);
1080 } 1144 }
1081 1145
1082 static void __exit alsa_card_mychip_exit(vo 1146 static void __exit alsa_card_mychip_exit(void)
1083 { 1147 {
1084 pci_unregister_driver(&driver); 1148 pci_unregister_driver(&driver);
1085 } 1149 }
1086 1150
1087 module_init(alsa_card_mychip_init) 1151 module_init(alsa_card_mychip_init)
1088 module_exit(alsa_card_mychip_exit) 1152 module_exit(alsa_card_mychip_exit)
1089 1153
1090 Note that these module entries are tagged wit 1154 Note that these module entries are tagged with ``__init`` and ``__exit``
1091 prefixes. 1155 prefixes.
1092 1156
>> 1157 Oh, one thing was forgotten. If you have no exported symbols, you need
>> 1158 to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
>> 1159
>> 1160 ::
>> 1161
>> 1162 EXPORT_NO_SYMBOLS;
>> 1163
1093 That's all! 1164 That's all!
1094 1165
1095 PCM Interface 1166 PCM Interface
1096 ============= 1167 =============
1097 1168
1098 General 1169 General
1099 ------- 1170 -------
1100 1171
1101 The PCM middle layer of ALSA is quite powerfu 1172 The PCM middle layer of ALSA is quite powerful and it is only necessary
1102 for each driver to implement the low-level fu 1173 for each driver to implement the low-level functions to access its
1103 hardware. 1174 hardware.
1104 1175
1105 To access the PCM layer, you need to include !! 1176 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1106 first. In addition, ``<sound/pcm_params.h>`` 1177 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1107 access some functions related with hw_param. !! 1178 access to some functions related with hw_param.
1108 1179
1109 Each card device can have up to four PCM inst !! 1180 Each card device can have up to four pcm instances. A pcm instance
1110 corresponds to a PCM device file. The limitat !! 1181 corresponds to a pcm device file. The limitation of number of instances
1111 comes only from the available bit size of Lin !! 1182 comes only from the available bit size of the Linux's device numbers.
1112 Once 64bit device numbers are used, we'll hav !! 1183 Once when 64bit device number is used, we'll have more pcm instances
1113 available. 1184 available.
1114 1185
1115 A PCM instance consists of PCM playback and c !! 1186 A pcm instance consists of pcm playback and capture streams, and each
1116 PCM stream consists of one or more PCM substr !! 1187 pcm stream consists of one or more pcm substreams. Some soundcards
1117 support multiple playback functions. For exam 1188 support multiple playback functions. For example, emu10k1 has a PCM
1118 playback of 32 stereo substreams. In this cas 1189 playback of 32 stereo substreams. In this case, at each open, a free
1119 substream is (usually) automatically chosen a 1190 substream is (usually) automatically chosen and opened. Meanwhile, when
1120 only one substream exists and it was already !! 1191 only one substream exists and it was already opened, the successful open
1121 will either block or error with ``EAGAIN`` ac 1192 will either block or error with ``EAGAIN`` according to the file open
1122 mode. But you don't have to care about such d 1193 mode. But you don't have to care about such details in your driver. The
1123 PCM middle layer will take care of such work. 1194 PCM middle layer will take care of such work.
1124 1195
1125 Full Code Example 1196 Full Code Example
1126 ----------------- 1197 -----------------
1127 1198
1128 The example code below does not include any h 1199 The example code below does not include any hardware access routines but
1129 shows only the skeleton, how to build up the !! 1200 shows only the skeleton, how to build up the PCM interfaces.
>> 1201
>> 1202 ::
1130 1203
1131 #include <sound/pcm.h> 1204 #include <sound/pcm.h>
1132 .... 1205 ....
1133 1206
1134 /* hardware definition */ 1207 /* hardware definition */
1135 static struct snd_pcm_hardware snd_mych 1208 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1136 .info = (SNDRV_PCM_INFO_MMAP | 1209 .info = (SNDRV_PCM_INFO_MMAP |
1137 SNDRV_PCM_INFO_INTERLE 1210 SNDRV_PCM_INFO_INTERLEAVED |
1138 SNDRV_PCM_INFO_BLOCK_T 1211 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1139 SNDRV_PCM_INFO_MMAP_VA 1212 SNDRV_PCM_INFO_MMAP_VALID),
1140 .formats = SNDRV_PCM_F 1213 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1141 .rates = SNDRV_PCM_R 1214 .rates = SNDRV_PCM_RATE_8000_48000,
1142 .rate_min = 8000, 1215 .rate_min = 8000,
1143 .rate_max = 48000, 1216 .rate_max = 48000,
1144 .channels_min = 2, 1217 .channels_min = 2,
1145 .channels_max = 2, 1218 .channels_max = 2,
1146 .buffer_bytes_max = 32768, 1219 .buffer_bytes_max = 32768,
1147 .period_bytes_min = 4096, 1220 .period_bytes_min = 4096,
1148 .period_bytes_max = 32768, 1221 .period_bytes_max = 32768,
1149 .periods_min = 1, 1222 .periods_min = 1,
1150 .periods_max = 1024, 1223 .periods_max = 1024,
1151 }; 1224 };
1152 1225
1153 /* hardware definition */ 1226 /* hardware definition */
1154 static struct snd_pcm_hardware snd_mych 1227 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1155 .info = (SNDRV_PCM_INFO_MMAP | 1228 .info = (SNDRV_PCM_INFO_MMAP |
1156 SNDRV_PCM_INFO_INTERLE 1229 SNDRV_PCM_INFO_INTERLEAVED |
1157 SNDRV_PCM_INFO_BLOCK_T 1230 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1158 SNDRV_PCM_INFO_MMAP_VA 1231 SNDRV_PCM_INFO_MMAP_VALID),
1159 .formats = SNDRV_PCM_F 1232 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1160 .rates = SNDRV_PCM_R 1233 .rates = SNDRV_PCM_RATE_8000_48000,
1161 .rate_min = 8000, 1234 .rate_min = 8000,
1162 .rate_max = 48000, 1235 .rate_max = 48000,
1163 .channels_min = 2, 1236 .channels_min = 2,
1164 .channels_max = 2, 1237 .channels_max = 2,
1165 .buffer_bytes_max = 32768, 1238 .buffer_bytes_max = 32768,
1166 .period_bytes_min = 4096, 1239 .period_bytes_min = 4096,
1167 .period_bytes_max = 32768, 1240 .period_bytes_max = 32768,
1168 .periods_min = 1, 1241 .periods_min = 1,
1169 .periods_max = 1024, 1242 .periods_max = 1024,
1170 }; 1243 };
1171 1244
1172 /* open callback */ 1245 /* open callback */
1173 static int snd_mychip_playback_open(str 1246 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1174 { 1247 {
1175 struct mychip *chip = snd_pcm_s 1248 struct mychip *chip = snd_pcm_substream_chip(substream);
1176 struct snd_pcm_runtime *runtime 1249 struct snd_pcm_runtime *runtime = substream->runtime;
1177 1250
1178 runtime->hw = snd_mychip_playba 1251 runtime->hw = snd_mychip_playback_hw;
1179 /* more hardware-initialization 1252 /* more hardware-initialization will be done here */
1180 .... 1253 ....
1181 return 0; 1254 return 0;
1182 } 1255 }
1183 1256
1184 /* close callback */ 1257 /* close callback */
1185 static int snd_mychip_playback_close(st 1258 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1186 { 1259 {
1187 struct mychip *chip = snd_pcm_s 1260 struct mychip *chip = snd_pcm_substream_chip(substream);
1188 /* the hardware-specific codes 1261 /* the hardware-specific codes will be here */
1189 .... 1262 ....
1190 return 0; 1263 return 0;
1191 1264
1192 } 1265 }
1193 1266
1194 /* open callback */ 1267 /* open callback */
1195 static int snd_mychip_capture_open(stru 1268 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1196 { 1269 {
1197 struct mychip *chip = snd_pcm_s 1270 struct mychip *chip = snd_pcm_substream_chip(substream);
1198 struct snd_pcm_runtime *runtime 1271 struct snd_pcm_runtime *runtime = substream->runtime;
1199 1272
1200 runtime->hw = snd_mychip_captur 1273 runtime->hw = snd_mychip_capture_hw;
1201 /* more hardware-initialization 1274 /* more hardware-initialization will be done here */
1202 .... 1275 ....
1203 return 0; 1276 return 0;
1204 } 1277 }
1205 1278
1206 /* close callback */ 1279 /* close callback */
1207 static int snd_mychip_capture_close(str 1280 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1208 { 1281 {
1209 struct mychip *chip = snd_pcm_s 1282 struct mychip *chip = snd_pcm_substream_chip(substream);
1210 /* the hardware-specific codes 1283 /* the hardware-specific codes will be here */
1211 .... 1284 ....
1212 return 0; 1285 return 0;
>> 1286
1213 } 1287 }
1214 1288
1215 /* hw_params callback */ 1289 /* hw_params callback */
1216 static int snd_mychip_pcm_hw_params(str 1290 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1217 struct snd 1291 struct snd_pcm_hw_params *hw_params)
1218 { 1292 {
1219 /* the hardware-specific codes !! 1293 return snd_pcm_lib_malloc_pages(substream,
1220 .... !! 1294 params_buffer_bytes(hw_params));
1221 return 0; <<
1222 } 1295 }
1223 1296
1224 /* hw_free callback */ 1297 /* hw_free callback */
1225 static int snd_mychip_pcm_hw_free(struc 1298 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1226 { 1299 {
1227 /* the hardware-specific codes !! 1300 return snd_pcm_lib_free_pages(substream);
1228 .... <<
1229 return 0; <<
1230 } 1301 }
1231 1302
1232 /* prepare callback */ 1303 /* prepare callback */
1233 static int snd_mychip_pcm_prepare(struc 1304 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1234 { 1305 {
1235 struct mychip *chip = snd_pcm_s 1306 struct mychip *chip = snd_pcm_substream_chip(substream);
1236 struct snd_pcm_runtime *runtime 1307 struct snd_pcm_runtime *runtime = substream->runtime;
1237 1308
1238 /* set up the hardware with the 1309 /* set up the hardware with the current configuration
1239 * for example... 1310 * for example...
1240 */ 1311 */
1241 mychip_set_sample_format(chip, 1312 mychip_set_sample_format(chip, runtime->format);
1242 mychip_set_sample_rate(chip, ru 1313 mychip_set_sample_rate(chip, runtime->rate);
1243 mychip_set_channels(chip, runti 1314 mychip_set_channels(chip, runtime->channels);
1244 mychip_set_dma_setup(chip, runt 1315 mychip_set_dma_setup(chip, runtime->dma_addr,
1245 chip->buff 1316 chip->buffer_size,
1246 chip->peri 1317 chip->period_size);
1247 return 0; 1318 return 0;
1248 } 1319 }
1249 1320
1250 /* trigger callback */ 1321 /* trigger callback */
1251 static int snd_mychip_pcm_trigger(struc 1322 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1252 int c 1323 int cmd)
1253 { 1324 {
1254 switch (cmd) { 1325 switch (cmd) {
1255 case SNDRV_PCM_TRIGGER_START: 1326 case SNDRV_PCM_TRIGGER_START:
1256 /* do something to star 1327 /* do something to start the PCM engine */
1257 .... 1328 ....
1258 break; 1329 break;
1259 case SNDRV_PCM_TRIGGER_STOP: 1330 case SNDRV_PCM_TRIGGER_STOP:
1260 /* do something to stop 1331 /* do something to stop the PCM engine */
1261 .... 1332 ....
1262 break; 1333 break;
1263 default: 1334 default:
1264 return -EINVAL; 1335 return -EINVAL;
1265 } 1336 }
1266 } 1337 }
1267 1338
1268 /* pointer callback */ 1339 /* pointer callback */
1269 static snd_pcm_uframes_t 1340 static snd_pcm_uframes_t
1270 snd_mychip_pcm_pointer(struct snd_pcm_s 1341 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1271 { 1342 {
1272 struct mychip *chip = snd_pcm_s 1343 struct mychip *chip = snd_pcm_substream_chip(substream);
1273 unsigned int current_ptr; 1344 unsigned int current_ptr;
1274 1345
1275 /* get the current hardware poi 1346 /* get the current hardware pointer */
1276 current_ptr = mychip_get_hw_poi 1347 current_ptr = mychip_get_hw_pointer(chip);
1277 return current_ptr; 1348 return current_ptr;
1278 } 1349 }
1279 1350
1280 /* operators */ 1351 /* operators */
1281 static struct snd_pcm_ops snd_mychip_pl 1352 static struct snd_pcm_ops snd_mychip_playback_ops = {
1282 .open = snd_mychip_playb 1353 .open = snd_mychip_playback_open,
1283 .close = snd_mychip_playb 1354 .close = snd_mychip_playback_close,
>> 1355 .ioctl = snd_pcm_lib_ioctl,
1284 .hw_params = snd_mychip_pcm_h 1356 .hw_params = snd_mychip_pcm_hw_params,
1285 .hw_free = snd_mychip_pcm_h 1357 .hw_free = snd_mychip_pcm_hw_free,
1286 .prepare = snd_mychip_pcm_p 1358 .prepare = snd_mychip_pcm_prepare,
1287 .trigger = snd_mychip_pcm_t 1359 .trigger = snd_mychip_pcm_trigger,
1288 .pointer = snd_mychip_pcm_p 1360 .pointer = snd_mychip_pcm_pointer,
1289 }; 1361 };
1290 1362
1291 /* operators */ 1363 /* operators */
1292 static struct snd_pcm_ops snd_mychip_ca 1364 static struct snd_pcm_ops snd_mychip_capture_ops = {
1293 .open = snd_mychip_captu 1365 .open = snd_mychip_capture_open,
1294 .close = snd_mychip_captu 1366 .close = snd_mychip_capture_close,
>> 1367 .ioctl = snd_pcm_lib_ioctl,
1295 .hw_params = snd_mychip_pcm_h 1368 .hw_params = snd_mychip_pcm_hw_params,
1296 .hw_free = snd_mychip_pcm_h 1369 .hw_free = snd_mychip_pcm_hw_free,
1297 .prepare = snd_mychip_pcm_p 1370 .prepare = snd_mychip_pcm_prepare,
1298 .trigger = snd_mychip_pcm_t 1371 .trigger = snd_mychip_pcm_trigger,
1299 .pointer = snd_mychip_pcm_p 1372 .pointer = snd_mychip_pcm_pointer,
1300 }; 1373 };
1301 1374
1302 /* 1375 /*
1303 * definitions of capture are omitted 1376 * definitions of capture are omitted here...
1304 */ 1377 */
1305 1378
1306 /* create a pcm device */ 1379 /* create a pcm device */
1307 static int snd_mychip_new_pcm(struct my 1380 static int snd_mychip_new_pcm(struct mychip *chip)
1308 { 1381 {
1309 struct snd_pcm *pcm; 1382 struct snd_pcm *pcm;
1310 int err; 1383 int err;
1311 1384
1312 err = snd_pcm_new(chip->card, " 1385 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1313 if (err < 0) 1386 if (err < 0)
1314 return err; 1387 return err;
1315 pcm->private_data = chip; 1388 pcm->private_data = chip;
1316 strcpy(pcm->name, "My Chip"); 1389 strcpy(pcm->name, "My Chip");
1317 chip->pcm = pcm; 1390 chip->pcm = pcm;
1318 /* set operators */ 1391 /* set operators */
1319 snd_pcm_set_ops(pcm, SNDRV_PCM_ 1392 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1320 &snd_mychip_pla 1393 &snd_mychip_playback_ops);
1321 snd_pcm_set_ops(pcm, SNDRV_PCM_ 1394 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1322 &snd_mychip_cap 1395 &snd_mychip_capture_ops);
1323 /* pre-allocation of buffers */ 1396 /* pre-allocation of buffers */
1324 /* NOTE: this may fail */ 1397 /* NOTE: this may fail */
1325 snd_pcm_set_managed_buffer_all( !! 1398 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1326 !! 1399 snd_dma_pci_data(chip->pci),
1327 !! 1400 64*1024, 64*1024);
1328 return 0; 1401 return 0;
1329 } 1402 }
1330 1403
1331 1404
1332 PCM Constructor 1405 PCM Constructor
1333 --------------- 1406 ---------------
1334 1407
1335 A PCM instance is allocated by the :c:func:`s !! 1408 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1336 function. It would be better to create a cons !! 1409 function. It would be better to create a constructor for pcm, namely,
>> 1410
>> 1411 ::
1337 1412
1338 static int snd_mychip_new_pcm(struct mychip 1413 static int snd_mychip_new_pcm(struct mychip *chip)
1339 { 1414 {
1340 struct snd_pcm *pcm; 1415 struct snd_pcm *pcm;
1341 int err; 1416 int err;
1342 1417
1343 err = snd_pcm_new(chip->card, "My C 1418 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1344 if (err < 0) 1419 if (err < 0)
1345 return err; 1420 return err;
1346 pcm->private_data = chip; 1421 pcm->private_data = chip;
1347 strcpy(pcm->name, "My Chip"); 1422 strcpy(pcm->name, "My Chip");
1348 chip->pcm = pcm; 1423 chip->pcm = pcm;
1349 ... !! 1424 ....
1350 return 0; 1425 return 0;
1351 } 1426 }
1352 1427
1353 The :c:func:`snd_pcm_new()` function takes si !! 1428 The :c:func:`snd_pcm_new()` function takes four arguments. The
1354 first argument is the card pointer to which t !! 1429 first argument is the card pointer to which this pcm is assigned, and
1355 the second is the ID string. 1430 the second is the ID string.
1356 1431
1357 The third argument (``index``, 0 in the above 1432 The third argument (``index``, 0 in the above) is the index of this new
1358 PCM. It begins from zero. If you create more !! 1433 pcm. It begins from zero. If you create more than one pcm instances,
1359 specify the different numbers in this argumen 1434 specify the different numbers in this argument. For example, ``index =
1360 1`` for the second PCM device. 1435 1`` for the second PCM device.
1361 1436
1362 The fourth and fifth arguments are the number 1437 The fourth and fifth arguments are the number of substreams for playback
1363 and capture, respectively. Here 1 is used for 1438 and capture, respectively. Here 1 is used for both arguments. When no
1364 playback or capture substreams are available, 1439 playback or capture substreams are available, pass 0 to the
1365 corresponding argument. 1440 corresponding argument.
1366 1441
1367 If a chip supports multiple playbacks or capt 1442 If a chip supports multiple playbacks or captures, you can specify more
1368 numbers, but they must be handled properly in 1443 numbers, but they must be handled properly in open/close, etc.
1369 callbacks. When you need to know which substr 1444 callbacks. When you need to know which substream you are referring to,
1370 then it can be obtained from struct snd_pcm_s !! 1445 then it can be obtained from :c:type:`struct snd_pcm_substream
1371 callback as follows:: !! 1446 <snd_pcm_substream>` data passed to each callback as follows:
>> 1447
>> 1448 ::
1372 1449
1373 struct snd_pcm_substream *substream; 1450 struct snd_pcm_substream *substream;
1374 int index = substream->number; 1451 int index = substream->number;
1375 1452
1376 1453
1377 After the PCM is created, you need to set ope !! 1454 After the pcm is created, you need to set operators for each pcm stream.
>> 1455
>> 1456 ::
1378 1457
1379 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYB 1458 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1380 &snd_mychip_playback_ops); 1459 &snd_mychip_playback_ops);
1381 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTU 1460 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1382 &snd_mychip_capture_ops); 1461 &snd_mychip_capture_ops);
1383 1462
1384 The operators are defined typically like this !! 1463 The operators are defined typically like this:
>> 1464
>> 1465 ::
1385 1466
1386 static struct snd_pcm_ops snd_mychip_playba 1467 static struct snd_pcm_ops snd_mychip_playback_ops = {
1387 .open = snd_mychip_pcm_open, 1468 .open = snd_mychip_pcm_open,
1388 .close = snd_mychip_pcm_close 1469 .close = snd_mychip_pcm_close,
>> 1470 .ioctl = snd_pcm_lib_ioctl,
1389 .hw_params = snd_mychip_pcm_hw_pa 1471 .hw_params = snd_mychip_pcm_hw_params,
1390 .hw_free = snd_mychip_pcm_hw_fr 1472 .hw_free = snd_mychip_pcm_hw_free,
1391 .prepare = snd_mychip_pcm_prepa 1473 .prepare = snd_mychip_pcm_prepare,
1392 .trigger = snd_mychip_pcm_trigg 1474 .trigger = snd_mychip_pcm_trigger,
1393 .pointer = snd_mychip_pcm_point 1475 .pointer = snd_mychip_pcm_pointer,
1394 }; 1476 };
1395 1477
1396 All the callbacks are described in the Operat 1478 All the callbacks are described in the Operators_ subsection.
1397 1479
1398 After setting the operators, you probably wil 1480 After setting the operators, you probably will want to pre-allocate the
1399 buffer and set up the managed allocation mode !! 1481 buffer. For the pre-allocation, simply call the following:
1400 For that, simply call the following:: !! 1482
>> 1483 ::
1401 1484
1402 snd_pcm_set_managed_buffer_all(pcm, SNDRV_D !! 1485 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1403 &chip->pci-> !! 1486 snd_dma_pci_data(chip->pci),
1404 64*1024, 64* !! 1487 64*1024, 64*1024);
1405 1488
1406 It will allocate a buffer up to 64kB by defau !! 1489 It will allocate a buffer up to 64kB as default. Buffer management
1407 details will be described in the later sectio 1490 details will be described in the later section `Buffer and Memory
1408 Management`_. 1491 Management`_.
1409 1492
1410 Additionally, you can set some extra informat !! 1493 Additionally, you can set some extra information for this pcm in
1411 ``pcm->info_flags``. The available values are 1494 ``pcm->info_flags``. The available values are defined as
1412 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>` 1495 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1413 hardware definition (described later). When y 1496 hardware definition (described later). When your soundchip supports only
1414 half-duplex, specify it like this:: !! 1497 half-duplex, specify like this:
>> 1498
>> 1499 ::
1415 1500
1416 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLE 1501 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1417 1502
1418 1503
1419 ... And the Destructor? 1504 ... And the Destructor?
1420 ----------------------- 1505 -----------------------
1421 1506
1422 The destructor for a PCM instance is not alwa !! 1507 The destructor for a pcm instance is not always necessary. Since the pcm
1423 device will be released by the middle layer c 1508 device will be released by the middle layer code automatically, you
1424 don't have to call the destructor explicitly. 1509 don't have to call the destructor explicitly.
1425 1510
1426 The destructor would be necessary if you crea 1511 The destructor would be necessary if you created special records
1427 internally and needed to release them. In suc 1512 internally and needed to release them. In such a case, set the
1428 destructor function to ``pcm->private_free``: !! 1513 destructor function to ``pcm->private_free``:
>> 1514
>> 1515 ::
1429 1516
1430 static void mychip_pcm_free(struct snd_ 1517 static void mychip_pcm_free(struct snd_pcm *pcm)
1431 { 1518 {
1432 struct mychip *chip = snd_pcm_c 1519 struct mychip *chip = snd_pcm_chip(pcm);
1433 /* free your own data */ 1520 /* free your own data */
1434 kfree(chip->my_private_pcm_data 1521 kfree(chip->my_private_pcm_data);
1435 /* do what you like else */ 1522 /* do what you like else */
1436 .... 1523 ....
1437 } 1524 }
1438 1525
1439 static int snd_mychip_new_pcm(struct my 1526 static int snd_mychip_new_pcm(struct mychip *chip)
1440 { 1527 {
1441 struct snd_pcm *pcm; 1528 struct snd_pcm *pcm;
1442 .... 1529 ....
1443 /* allocate your own data */ 1530 /* allocate your own data */
1444 chip->my_private_pcm_data = kma 1531 chip->my_private_pcm_data = kmalloc(...);
1445 /* set the destructor */ 1532 /* set the destructor */
1446 pcm->private_data = chip; 1533 pcm->private_data = chip;
1447 pcm->private_free = mychip_pcm_ 1534 pcm->private_free = mychip_pcm_free;
1448 .... 1535 ....
1449 } 1536 }
1450 1537
1451 1538
1452 1539
1453 Runtime Pointer - The Chest of PCM Informatio 1540 Runtime Pointer - The Chest of PCM Information
1454 --------------------------------------------- 1541 ----------------------------------------------
1455 1542
1456 When the PCM substream is opened, a PCM runti 1543 When the PCM substream is opened, a PCM runtime instance is allocated
1457 and assigned to the substream. This pointer i 1544 and assigned to the substream. This pointer is accessible via
1458 ``substream->runtime``. This runtime pointer 1545 ``substream->runtime``. This runtime pointer holds most information you
1459 need to control the PCM: a copy of hw_params !! 1546 need to control the PCM: the copy of hw_params and sw_params
1460 configurations, the buffer pointers, mmap rec 1547 configurations, the buffer pointers, mmap records, spinlocks, etc.
1461 1548
1462 The definition of runtime instance is found i 1549 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1463 is the relevant part of this file:: !! 1550 are the contents of this file:
>> 1551
>> 1552 ::
1464 1553
1465 struct _snd_pcm_runtime { 1554 struct _snd_pcm_runtime {
1466 /* -- Status -- */ 1555 /* -- Status -- */
1467 struct snd_pcm_substream *trigger_m 1556 struct snd_pcm_substream *trigger_master;
1468 snd_timestamp_t trigger_tstamp; 1557 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1469 int overrange; 1558 int overrange;
1470 snd_pcm_uframes_t avail_max; 1559 snd_pcm_uframes_t avail_max;
1471 snd_pcm_uframes_t hw_ptr_base; 1560 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1472 snd_pcm_uframes_t hw_ptr_interrupt; 1561 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1473 1562
1474 /* -- HW params -- */ 1563 /* -- HW params -- */
1475 snd_pcm_access_t access; /* ac 1564 snd_pcm_access_t access; /* access mode */
1476 snd_pcm_format_t format; /* SN 1565 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1477 snd_pcm_subformat_t subformat; 1566 snd_pcm_subformat_t subformat; /* subformat */
1478 unsigned int rate; /* ra 1567 unsigned int rate; /* rate in Hz */
1479 unsigned int channels; 1568 unsigned int channels; /* channels */
1480 snd_pcm_uframes_t period_size; 1569 snd_pcm_uframes_t period_size; /* period size */
1481 unsigned int periods; /* pe 1570 unsigned int periods; /* periods */
1482 snd_pcm_uframes_t buffer_size; 1571 snd_pcm_uframes_t buffer_size; /* buffer size */
1483 unsigned int tick_time; 1572 unsigned int tick_time; /* tick time */
1484 snd_pcm_uframes_t min_align; /* Mi 1573 snd_pcm_uframes_t min_align; /* Min alignment for the format */
1485 size_t byte_align; 1574 size_t byte_align;
1486 unsigned int frame_bits; 1575 unsigned int frame_bits;
1487 unsigned int sample_bits; 1576 unsigned int sample_bits;
1488 unsigned int info; 1577 unsigned int info;
1489 unsigned int rate_num; 1578 unsigned int rate_num;
1490 unsigned int rate_den; 1579 unsigned int rate_den;
1491 1580
1492 /* -- SW params -- */ 1581 /* -- SW params -- */
1493 struct timespec tstamp_mode; /* mm 1582 struct timespec tstamp_mode; /* mmap timestamp is updated */
1494 unsigned int period_step; 1583 unsigned int period_step;
1495 unsigned int sleep_min; 1584 unsigned int sleep_min; /* min ticks to sleep */
1496 snd_pcm_uframes_t start_threshold; 1585 snd_pcm_uframes_t start_threshold;
1497 /* !! 1586 snd_pcm_uframes_t stop_threshold;
1498 * The following two thresholds all !! 1587 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1499 * hw_avail drops below the thresho !! 1588 noise is nearest than this */
1500 */ !! 1589 snd_pcm_uframes_t silence_size; /* Silence filling size */
1501 snd_pcm_uframes_t stop_threshold; <<
1502 snd_pcm_uframes_t silence_threshold <<
1503 snd_pcm_uframes_t silence_size; <<
1504 <<
1505 snd_pcm_uframes_t boundary; /* po 1590 snd_pcm_uframes_t boundary; /* pointers wrap point */
1506 1591
1507 /* internal data of auto-silencer * !! 1592 snd_pcm_uframes_t silenced_start;
1508 snd_pcm_uframes_t silence_start; /* !! 1593 snd_pcm_uframes_t silenced_size;
1509 snd_pcm_uframes_t silence_filled; / <<
1510 1594
1511 snd_pcm_sync_id_t sync; 1595 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1512 1596
1513 /* -- mmap -- */ 1597 /* -- mmap -- */
1514 volatile struct snd_pcm_mmap_status 1598 volatile struct snd_pcm_mmap_status *status;
1515 volatile struct snd_pcm_mmap_contro 1599 volatile struct snd_pcm_mmap_control *control;
1516 atomic_t mmap_count; 1600 atomic_t mmap_count;
1517 1601
1518 /* -- locking / scheduling -- */ 1602 /* -- locking / scheduling -- */
1519 spinlock_t lock; 1603 spinlock_t lock;
1520 wait_queue_head_t sleep; 1604 wait_queue_head_t sleep;
1521 struct timer_list tick_timer; 1605 struct timer_list tick_timer;
1522 struct fasync_struct *fasync; 1606 struct fasync_struct *fasync;
1523 1607
1524 /* -- private section -- */ 1608 /* -- private section -- */
1525 void *private_data; 1609 void *private_data;
1526 void (*private_free)(struct snd_pcm 1610 void (*private_free)(struct snd_pcm_runtime *runtime);
1527 1611
1528 /* -- hardware description -- */ 1612 /* -- hardware description -- */
1529 struct snd_pcm_hardware hw; 1613 struct snd_pcm_hardware hw;
1530 struct snd_pcm_hw_constraints hw_co 1614 struct snd_pcm_hw_constraints hw_constraints;
1531 1615
1532 /* -- timer -- */ 1616 /* -- timer -- */
1533 unsigned int timer_resolution; 1617 unsigned int timer_resolution; /* timer resolution */
1534 1618
1535 /* -- DMA -- */ 1619 /* -- DMA -- */
1536 unsigned char *dma_area; /* DM 1620 unsigned char *dma_area; /* DMA area */
1537 dma_addr_t dma_addr; /* ph 1621 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1538 size_t dma_bytes; /* si 1622 size_t dma_bytes; /* size of DMA area */
1539 1623
1540 struct snd_dma_buffer *dma_buffer_p 1624 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1541 1625
1542 #if defined(CONFIG_SND_PCM_OSS) || defined( 1626 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1543 /* -- OSS things -- */ 1627 /* -- OSS things -- */
1544 struct snd_pcm_oss_runtime oss; 1628 struct snd_pcm_oss_runtime oss;
1545 #endif 1629 #endif
1546 }; 1630 };
1547 1631
1548 1632
1549 For the operators (callbacks) of each sound d 1633 For the operators (callbacks) of each sound driver, most of these
1550 records are supposed to be read-only. Only th 1634 records are supposed to be read-only. Only the PCM middle-layer changes
1551 / updates them. The exceptions are the hardwa 1635 / updates them. The exceptions are the hardware description (hw) DMA
1552 buffer information and the private data. Besi 1636 buffer information and the private data. Besides, if you use the
1553 standard managed buffer allocation mode, you !! 1637 standard buffer allocation method via
>> 1638 :c:func:`snd_pcm_lib_malloc_pages()`, you don't need to set the
1554 DMA buffer information by yourself. 1639 DMA buffer information by yourself.
1555 1640
1556 In the sections below, important records are 1641 In the sections below, important records are explained.
1557 1642
1558 Hardware Description 1643 Hardware Description
1559 ~~~~~~~~~~~~~~~~~~~~ 1644 ~~~~~~~~~~~~~~~~~~~~
1560 1645
1561 The hardware descriptor (struct snd_pcm_hardw !! 1646 The hardware descriptor (:c:type:`struct snd_pcm_hardware
1562 the fundamental hardware configuration. Above !! 1647 <snd_pcm_hardware>`) contains the definitions of the fundamental
1563 in the `PCM open callback`_. Note that the ru !! 1648 hardware configuration. Above all, you'll need to define this in the
1564 the descriptor, not a pointer to the existing !! 1649 `PCM open callback`_. Note that the runtime instance holds the copy of
>> 1650 the descriptor, not the pointer to the existing descriptor. That is,
1565 in the open callback, you can modify the copi 1651 in the open callback, you can modify the copied descriptor
1566 (``runtime->hw``) as you need. For example, i 1652 (``runtime->hw``) as you need. For example, if the maximum number of
1567 channels is 1 only on some chip models, you c 1653 channels is 1 only on some chip models, you can still use the same
1568 hardware descriptor and change the channels_m !! 1654 hardware descriptor and change the channels_max later:
>> 1655
>> 1656 ::
1569 1657
1570 struct snd_pcm_runtime *runtime = s 1658 struct snd_pcm_runtime *runtime = substream->runtime;
1571 ... 1659 ...
1572 runtime->hw = snd_mychip_playback_h 1660 runtime->hw = snd_mychip_playback_hw; /* common definition */
1573 if (chip->model == VERY_OLD_ONE) 1661 if (chip->model == VERY_OLD_ONE)
1574 runtime->hw.channels_max = 1662 runtime->hw.channels_max = 1;
1575 1663
1576 Typically, you'll have a hardware descriptor !! 1664 Typically, you'll have a hardware descriptor as below:
>> 1665
>> 1666 ::
1577 1667
1578 static struct snd_pcm_hardware snd_mychip_p 1668 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1579 .info = (SNDRV_PCM_INFO_MMAP | 1669 .info = (SNDRV_PCM_INFO_MMAP |
1580 SNDRV_PCM_INFO_INTERLEAVED 1670 SNDRV_PCM_INFO_INTERLEAVED |
1581 SNDRV_PCM_INFO_BLOCK_TRANS 1671 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1582 SNDRV_PCM_INFO_MMAP_VALID) 1672 SNDRV_PCM_INFO_MMAP_VALID),
1583 .formats = SNDRV_PCM_FMTBI 1673 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1584 .rates = SNDRV_PCM_RATE_ 1674 .rates = SNDRV_PCM_RATE_8000_48000,
1585 .rate_min = 8000, 1675 .rate_min = 8000,
1586 .rate_max = 48000, 1676 .rate_max = 48000,
1587 .channels_min = 2, 1677 .channels_min = 2,
1588 .channels_max = 2, 1678 .channels_max = 2,
1589 .buffer_bytes_max = 32768, 1679 .buffer_bytes_max = 32768,
1590 .period_bytes_min = 4096, 1680 .period_bytes_min = 4096,
1591 .period_bytes_max = 32768, 1681 .period_bytes_max = 32768,
1592 .periods_min = 1, 1682 .periods_min = 1,
1593 .periods_max = 1024, 1683 .periods_max = 1024,
1594 }; 1684 };
1595 1685
1596 - The ``info`` field contains the type and c 1686 - The ``info`` field contains the type and capabilities of this
1597 PCM. The bit flags are defined in ``<sound !! 1687 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1598 ``SNDRV_PCM_INFO_XXX``. Here, at least, yo 1688 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1599 mmap is supported and which interleaving f !! 1689 the mmap is supported and which interleaved format is
1600 supported. When the hardware supports mmap 1690 supported. When the hardware supports mmap, add the
1601 ``SNDRV_PCM_INFO_MMAP`` flag here. When th 1691 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1602 interleaved or the non-interleaved formats !! 1692 interleaved or the non-interleaved formats,
1603 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_ 1693 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1604 flag must be set, respectively. If both ar 1694 flag must be set, respectively. If both are supported, you can set
1605 both, too. 1695 both, too.
1606 1696
1607 In the above example, ``MMAP_VALID`` and ` 1697 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1608 specified for the OSS mmap mode. Usually b 1698 specified for the OSS mmap mode. Usually both are set. Of course,
1609 ``MMAP_VALID`` is set only if mmap is real !! 1699 ``MMAP_VALID`` is set only if the mmap is really supported.
1610 1700
1611 The other possible flags are ``SNDRV_PCM_I 1701 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1612 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` b !! 1702 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1613 supports the “pause” operation, while 1703 supports the “pause” operation, while the ``RESUME`` bit means that
1614 the PCM supports the full “suspend/resum !! 1704 the pcm supports the full “suspend/resume” operation. If the
1615 ``PAUSE`` flag is set, the ``trigger`` cal 1705 ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1616 the corresponding (pause push/release) com 1706 the corresponding (pause push/release) commands. The suspend/resume
1617 trigger commands can be defined even witho 1707 trigger commands can be defined even without the ``RESUME``
1618 flag. See the `Power Management`_ section !! 1708 flag. See `Power Management`_ section for details.
1619 1709
1620 When the PCM substreams can be synchronize 1710 When the PCM substreams can be synchronized (typically,
1621 synchronized start/stop of a playback and !! 1711 synchronized start/stop of a playback and a capture streams), you
1622 can give ``SNDRV_PCM_INFO_SYNC_START``, to 1712 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1623 need to check the linked-list of PCM subst 1713 need to check the linked-list of PCM substreams in the trigger
1624 callback. This will be described in a late !! 1714 callback. This will be described in the later section.
1625 1715
1626 - The ``formats`` field contains the bit-fla !! 1716 - ``formats`` field contains the bit-flags of supported formats
1627 (``SNDRV_PCM_FMTBIT_XXX``). If the hardwar 1717 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1628 format, give all or'ed bits. In the exampl 1718 format, give all or'ed bits. In the example above, the signed 16bit
1629 little-endian format is specified. 1719 little-endian format is specified.
1630 1720
1631 - The ``rates`` field contains the bit-flags !! 1721 - ``rates`` field contains the bit-flags of supported rates
1632 (``SNDRV_PCM_RATE_XXX``). When the chip su 1722 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1633 pass the ``CONTINUOUS`` bit additionally. !! 1723 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1634 are provided only for typical rates. If yo !! 1724 provided only for typical rates. If your chip supports
1635 unconventional rates, you need to add the 1725 unconventional rates, you need to add the ``KNOT`` bit and set up
1636 the hardware constraint manually (explaine 1726 the hardware constraint manually (explained later).
1637 1727
1638 - ``rate_min`` and ``rate_max`` define the m 1728 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1639 rate. This should correspond somehow to `` 1729 rate. This should correspond somehow to ``rates`` bits.
1640 1730
1641 - ``channels_min`` and ``channels_max`` defi !! 1731 - ``channel_min`` and ``channel_max`` define, as you might already
1642 expected, the minimum and maximum number o 1732 expected, the minimum and maximum number of channels.
1643 1733
1644 - ``buffer_bytes_max`` defines the maximum b 1734 - ``buffer_bytes_max`` defines the maximum buffer size in
1645 bytes. There is no ``buffer_bytes_min`` fi 1735 bytes. There is no ``buffer_bytes_min`` field, since it can be
1646 calculated from the minimum period size an 1736 calculated from the minimum period size and the minimum number of
1647 periods. Meanwhile, ``period_bytes_min`` a !! 1737 periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1648 define the minimum and maximum size of the !! 1738 maximum size of the period in bytes. ``periods_max`` and
1649 ``periods_max`` and ``periods_min`` define !! 1739 ``periods_min`` define the maximum and minimum number of periods in
1650 number of periods in the buffer. !! 1740 the buffer.
1651 1741
1652 The “period” is a term that correspond 1742 The “period” is a term that corresponds to a fragment in the OSS
1653 world. The period defines the point at whi !! 1743 world. The period defines the size at which a PCM interrupt is
1654 generated. This point strongly depends on !! 1744 generated. This size strongly depends on the hardware. Generally,
1655 a smaller period size will give you more i !! 1745 the smaller period size will give you more interrupts, that is,
1656 in being able to fill/drain the buffer mor !! 1746 more controls. In the case of capture, this size defines the input
1657 capture, this size defines the input laten !! 1747 latency. On the other hand, the whole buffer size defines the
1658 the whole buffer size defines the output l !! 1748 output latency for the playback direction.
1659 direction. <<
1660 1749
1661 - There is also a field ``fifo_size``. This 1750 - There is also a field ``fifo_size``. This specifies the size of the
1662 hardware FIFO, but currently it is neither !! 1751 hardware FIFO, but currently it is neither used in the driver nor
1663 in the alsa-lib. So, you can ignore this f 1752 in the alsa-lib. So, you can ignore this field.
1664 1753
1665 PCM Configurations 1754 PCM Configurations
1666 ~~~~~~~~~~~~~~~~~~ 1755 ~~~~~~~~~~~~~~~~~~
1667 1756
1668 Ok, let's go back again to the PCM runtime re 1757 Ok, let's go back again to the PCM runtime records. The most
1669 frequently referred records in the runtime in 1758 frequently referred records in the runtime instance are the PCM
1670 configurations. The PCM configurations are st 1759 configurations. The PCM configurations are stored in the runtime
1671 instance after the application sends ``hw_par 1760 instance after the application sends ``hw_params`` data via
1672 alsa-lib. There are many fields copied from h 1761 alsa-lib. There are many fields copied from hw_params and sw_params
1673 structs. For example, ``format`` holds the fo 1762 structs. For example, ``format`` holds the format type chosen by the
1674 application. This field contains the enum val 1763 application. This field contains the enum value
1675 ``SNDRV_PCM_FORMAT_XXX``. 1764 ``SNDRV_PCM_FORMAT_XXX``.
1676 1765
1677 One thing to be noted is that the configured 1766 One thing to be noted is that the configured buffer and period sizes
1678 are stored in “frames” in the runtime. In 1767 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1679 channels \* samples-size``. For conversion be 1768 channels \* samples-size``. For conversion between frames and bytes,
1680 you can use the :c:func:`frames_to_bytes()` a 1769 you can use the :c:func:`frames_to_bytes()` and
1681 :c:func:`bytes_to_frames()` helper functions: !! 1770 :c:func:`bytes_to_frames()` helper functions.
>> 1771
>> 1772 ::
1682 1773
1683 period_bytes = frames_to_bytes(runtime, run 1774 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1684 1775
1685 Also, many software parameters (sw_params) ar 1776 Also, many software parameters (sw_params) are stored in frames, too.
1686 Please check the type of the field. ``snd_pcm !! 1777 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1687 frames as unsigned integer while ``snd_pcm_sf !! 1778 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1688 frames as signed integer. 1779 frames as signed integer.
1689 1780
1690 DMA Buffer Information 1781 DMA Buffer Information
1691 ~~~~~~~~~~~~~~~~~~~~~~ 1782 ~~~~~~~~~~~~~~~~~~~~~~
1692 1783
1693 The DMA buffer is defined by the following fo !! 1784 The DMA buffer is defined by the following four fields, ``dma_area``,
1694 ``dma_addr``, ``dma_bytes`` and ``dma_private !! 1785 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1695 holds the buffer pointer (the logical address 1786 holds the buffer pointer (the logical address). You can call
1696 :c:func:`memcpy()` from/to this pointer. Mean 1787 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1697 the physical address of the buffer. This fiel 1788 the physical address of the buffer. This field is specified only when
1698 the buffer is a linear buffer. ``dma_bytes`` !! 1789 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1699 buffer in bytes. ``dma_private`` is used for !! 1790 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1700 1791
1701 If you use either the managed buffer allocati !! 1792 If you use a standard ALSA function,
1702 API function :c:func:`snd_pcm_lib_malloc_page !! 1793 :c:func:`snd_pcm_lib_malloc_pages()`, for allocating the buffer,
1703 these fields are set by the ALSA middle layer 1794 these fields are set by the ALSA middle layer, and you should *not*
1704 change them by yourself. You can read them bu 1795 change them by yourself. You can read them but not write them. On the
1705 other hand, if you want to allocate the buffe 1796 other hand, if you want to allocate the buffer by yourself, you'll
1706 need to manage it in the hw_params callback. !! 1797 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1707 mandatory. ``dma_area`` is necessary when the 1798 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1708 your driver doesn't support mmap, this field 1799 your driver doesn't support mmap, this field is not
1709 necessary. ``dma_addr`` is also optional. You 1800 necessary. ``dma_addr`` is also optional. You can use dma_private as
1710 you like, too. 1801 you like, too.
1711 1802
1712 Running Status 1803 Running Status
1713 ~~~~~~~~~~~~~~ 1804 ~~~~~~~~~~~~~~
1714 1805
1715 The running status can be referred via ``runt 1806 The running status can be referred via ``runtime->status``. This is
1716 a pointer to a struct snd_pcm_mmap_status rec !! 1807 the pointer to the :c:type:`struct snd_pcm_mmap_status
1717 For example, you can get the current !! 1808 <snd_pcm_mmap_status>` record. For example, you can get the current
1718 DMA hardware pointer via ``runtime->status->h 1809 DMA hardware pointer via ``runtime->status->hw_ptr``.
1719 1810
1720 The DMA application pointer can be referred v 1811 The DMA application pointer can be referred via ``runtime->control``,
1721 which points to a struct snd_pcm_mmap_control !! 1812 which points to the :c:type:`struct snd_pcm_mmap_control
1722 However, accessing this value directly is not !! 1813 <snd_pcm_mmap_control>` record. However, accessing directly to
>> 1814 this value is not recommended.
1723 1815
1724 Private Data 1816 Private Data
1725 ~~~~~~~~~~~~ 1817 ~~~~~~~~~~~~
1726 1818
1727 You can allocate a record for the substream a 1819 You can allocate a record for the substream and store it in
1728 ``runtime->private_data``. Usually, this is d 1820 ``runtime->private_data``. Usually, this is done in the `PCM open
1729 callback`_. Don't mix this with ``pcm->privat 1821 callback`_. Don't mix this with ``pcm->private_data``. The
1730 ``pcm->private_data`` usually points to the c 1822 ``pcm->private_data`` usually points to the chip instance assigned
1731 statically at creation time of the PCM device !! 1823 statically at the creation of PCM, while the ``runtime->private_data``
1732 ``runtime->private_data`` !! 1824 points to a dynamic data structure created at the PCM open
1733 points to a dynamic data structure created in !! 1825 callback.
1734 callback:: !! 1826
>> 1827 ::
1735 1828
1736 static int snd_xxx_open(struct snd_pcm_subs 1829 static int snd_xxx_open(struct snd_pcm_substream *substream)
1737 { 1830 {
1738 struct my_pcm_data *data; 1831 struct my_pcm_data *data;
1739 .... 1832 ....
1740 data = kmalloc(sizeof(*data), GFP_K 1833 data = kmalloc(sizeof(*data), GFP_KERNEL);
1741 substream->runtime->private_data = 1834 substream->runtime->private_data = data;
1742 .... 1835 ....
1743 } 1836 }
1744 1837
1745 1838
1746 The allocated object must be released in the 1839 The allocated object must be released in the `close callback`_.
1747 1840
1748 Operators 1841 Operators
1749 --------- 1842 ---------
1750 1843
1751 OK, now let me give details about each PCM ca !! 1844 OK, now let me give details about each pcm callback (``ops``). In
1752 general, every callback must return 0 if succ 1845 general, every callback must return 0 if successful, or a negative
1753 error number such as ``-EINVAL``. To choose a 1846 error number such as ``-EINVAL``. To choose an appropriate error
1754 number, it is advised to check what value oth 1847 number, it is advised to check what value other parts of the kernel
1755 return when the same kind of request fails. 1848 return when the same kind of request fails.
1756 1849
1757 Each callback function takes at least one arg !! 1850 The callback function takes at least the argument with :c:type:`struct
1758 struct snd_pcm_substream pointer. To retrieve !! 1851 snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1759 record from the given substream instance, you 1852 record from the given substream instance, you can use the following
1760 macro:: !! 1853 macro.
>> 1854
>> 1855 ::
1761 1856
1762 int xxx(...) { !! 1857 int xxx() {
1763 struct mychip *chip = snd_pcm_subst 1858 struct mychip *chip = snd_pcm_substream_chip(substream);
1764 .... 1859 ....
1765 } 1860 }
1766 1861
1767 The macro reads ``substream->private_data``, 1862 The macro reads ``substream->private_data``, which is a copy of
1768 ``pcm->private_data``. You can override the f 1863 ``pcm->private_data``. You can override the former if you need to
1769 assign different data records per PCM substre 1864 assign different data records per PCM substream. For example, the
1770 cmi8330 driver assigns different ``private_da 1865 cmi8330 driver assigns different ``private_data`` for playback and
1771 capture directions, because it uses two diffe 1866 capture directions, because it uses two different codecs (SB- and
1772 AD-compatible) for different directions. 1867 AD-compatible) for different directions.
1773 1868
1774 PCM open callback 1869 PCM open callback
1775 ~~~~~~~~~~~~~~~~~ 1870 ~~~~~~~~~~~~~~~~~
1776 1871
1777 :: 1872 ::
1778 1873
1779 static int snd_xxx_open(struct snd_pcm_subs 1874 static int snd_xxx_open(struct snd_pcm_substream *substream);
1780 1875
1781 This is called when a PCM substream is opened !! 1876 This is called when a pcm substream is opened.
1782 1877
1783 At least, here you have to initialize the ``r 1878 At least, here you have to initialize the ``runtime->hw``
1784 record. Typically, this is done like this:: !! 1879 record. Typically, this is done by like this:
>> 1880
>> 1881 ::
1785 1882
1786 static int snd_xxx_open(struct snd_pcm_subs 1883 static int snd_xxx_open(struct snd_pcm_substream *substream)
1787 { 1884 {
1788 struct mychip *chip = snd_pcm_subst 1885 struct mychip *chip = snd_pcm_substream_chip(substream);
1789 struct snd_pcm_runtime *runtime = s 1886 struct snd_pcm_runtime *runtime = substream->runtime;
1790 1887
1791 runtime->hw = snd_mychip_playback_h 1888 runtime->hw = snd_mychip_playback_hw;
1792 return 0; 1889 return 0;
1793 } 1890 }
1794 1891
1795 where ``snd_mychip_playback_hw`` is the pre-d 1892 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1796 description. 1893 description.
1797 1894
1798 You can allocate private data in this callbac !! 1895 You can allocate a private data in this callback, as described in
1799 `Private Data`_ section. 1896 `Private Data`_ section.
1800 1897
1801 If the hardware configuration needs more cons 1898 If the hardware configuration needs more constraints, set the hardware
1802 constraints here, too. See Constraints_ for m 1899 constraints here, too. See Constraints_ for more details.
1803 1900
1804 close callback 1901 close callback
1805 ~~~~~~~~~~~~~~ 1902 ~~~~~~~~~~~~~~
1806 1903
1807 :: 1904 ::
1808 1905
1809 static int snd_xxx_close(struct snd_pcm_sub 1906 static int snd_xxx_close(struct snd_pcm_substream *substream);
1810 1907
1811 1908
1812 Obviously, this is called when a PCM substrea !! 1909 Obviously, this is called when a pcm substream is closed.
>> 1910
>> 1911 Any private instance for a pcm substream allocated in the ``open``
>> 1912 callback will be released here.
1813 1913
1814 Any private instance for a PCM substream allo !! 1914 ::
1815 callback will be released here:: <<
1816 1915
1817 static int snd_xxx_close(struct snd_pcm_sub 1916 static int snd_xxx_close(struct snd_pcm_substream *substream)
1818 { 1917 {
1819 .... 1918 ....
1820 kfree(substream->runtime->private_d 1919 kfree(substream->runtime->private_data);
1821 .... 1920 ....
1822 } 1921 }
1823 1922
1824 ioctl callback 1923 ioctl callback
1825 ~~~~~~~~~~~~~~ 1924 ~~~~~~~~~~~~~~
1826 1925
1827 This is used for any special call to PCM ioct !! 1926 This is used for any special call to pcm ioctls. But usually you can
1828 leave it NULL, then the PCM core calls the ge !! 1927 pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`.
1829 function :c:func:`snd_pcm_lib_ioctl()`. If y <<
1830 unique setup of channel info or reset procedu <<
1831 callback function here. <<
1832 1928
1833 hw_params callback 1929 hw_params callback
1834 ~~~~~~~~~~~~~~~~~~~ 1930 ~~~~~~~~~~~~~~~~~~~
1835 1931
1836 :: 1932 ::
1837 1933
1838 static int snd_xxx_hw_params(struct snd_pcm 1934 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1839 struct snd_pcm 1935 struct snd_pcm_hw_params *hw_params);
1840 1936
1841 This is called when the hardware parameters ( !! 1937 This is called when the hardware parameter (``hw_params``) is set up
1842 by the application, that is, once when the bu 1938 by the application, that is, once when the buffer size, the period
1843 size, the format, etc. are defined for the PC !! 1939 size, the format, etc. are defined for the pcm substream.
1844 1940
1845 Many hardware setups should be done in this c 1941 Many hardware setups should be done in this callback, including the
1846 allocation of buffers. 1942 allocation of buffers.
1847 1943
1848 Parameters to be initialized are retrieved by !! 1944 Parameters to be initialized are retrieved by
1849 :c:func:`params_xxx()` macros. !! 1945 :c:func:`params_xxx()` macros. To allocate buffer, you can call a
>> 1946 helper function,
1850 1947
1851 When you choose managed buffer allocation mod !! 1948 ::
1852 a buffer is already allocated before this cal <<
1853 called. Alternatively, you can call a helper <<
1854 allocating the buffer:: <<
1855 1949
1856 snd_pcm_lib_malloc_pages(substream, params_ 1950 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1857 1951
1858 :c:func:`snd_pcm_lib_malloc_pages()` is avail 1952 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1859 DMA buffers have been pre-allocated. See the 1953 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1860 for more details. 1954 for more details.
1861 1955
1862 Note that this one and the ``prepare`` callba !! 1956 Note that this and ``prepare`` callbacks may be called multiple times
1863 times per initialization. For example, the OS !! 1957 per initialization. For example, the OSS emulation may call these
1864 callbacks at each change via its ioctl. 1958 callbacks at each change via its ioctl.
1865 1959
1866 Thus, you need to be careful not to allocate 1960 Thus, you need to be careful not to allocate the same buffers many
1867 times, which will lead to memory leaks! Calli 1961 times, which will lead to memory leaks! Calling the helper function
1868 above many times is OK. It will release the p 1962 above many times is OK. It will release the previous buffer
1869 automatically when it was already allocated. 1963 automatically when it was already allocated.
1870 1964
1871 Another note is that this callback is non-ato !! 1965 Another note is that this callback is non-atomic (schedulable) as
1872 default, i.e. when no ``nonatomic`` flag set. 1966 default, i.e. when no ``nonatomic`` flag set. This is important,
1873 because the ``trigger`` callback is atomic (n 1967 because the ``trigger`` callback is atomic (non-schedulable). That is,
1874 mutexes or any schedule-related functions are !! 1968 mutexes or any schedule-related functions are not available in
1875 ``trigger`` callback. Please see the subsecti 1969 ``trigger`` callback. Please see the subsection Atomicity_ for
1876 details. 1970 details.
1877 1971
1878 hw_free callback 1972 hw_free callback
1879 ~~~~~~~~~~~~~~~~~ 1973 ~~~~~~~~~~~~~~~~~
1880 1974
1881 :: 1975 ::
1882 1976
1883 static int snd_xxx_hw_free(struct snd_pcm_s 1977 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1884 1978
1885 This is called to release the resources alloc 1979 This is called to release the resources allocated via
1886 ``hw_params``. !! 1980 ``hw_params``. For example, releasing the buffer via
1887 !! 1981 :c:func:`snd_pcm_lib_malloc_pages()` is done by calling the
1888 This function is always called before the clo !! 1982 following:
1889 Also, the callback may be called multiple tim <<
1890 whether each resource was already released. <<
1891 1983
1892 When you have chosen managed buffer allocatio !! 1984 ::
1893 substream, the allocated PCM buffer will be a <<
1894 after this callback gets called. Otherwise y <<
1895 buffer manually. Typically, when the buffer <<
1896 pre-allocated pool, you can use the standard <<
1897 :c:func:`snd_pcm_lib_malloc_pages()` like:: <<
1898 1985
1899 snd_pcm_lib_free_pages(substream); 1986 snd_pcm_lib_free_pages(substream);
1900 1987
>> 1988 This function is always called before the close callback is called.
>> 1989 Also, the callback may be called multiple times, too. Keep track
>> 1990 whether the resource was already released.
>> 1991
1901 prepare callback 1992 prepare callback
1902 ~~~~~~~~~~~~~~~~ 1993 ~~~~~~~~~~~~~~~~
1903 1994
1904 :: 1995 ::
1905 1996
1906 static int snd_xxx_prepare(struct snd_pcm_s 1997 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1907 1998
1908 This callback is called when the PCM is “pr !! 1999 This callback is called when the pcm is “prepared”. You can set the
1909 format type, sample rate, etc. here. The diff 2000 format type, sample rate, etc. here. The difference from ``hw_params``
1910 is that the ``prepare`` callback will be call 2001 is that the ``prepare`` callback will be called each time
1911 :c:func:`snd_pcm_prepare()` is called, i.e. w 2002 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
1912 underruns, etc. 2003 underruns, etc.
1913 2004
1914 Note that this callback is non-atomic. You ca !! 2005 Note that this callback is now non-atomic. You can use
1915 schedule-related functions safely in this cal 2006 schedule-related functions safely in this callback.
1916 2007
1917 In this and the following callbacks, you can 2008 In this and the following callbacks, you can refer to the values via
1918 the runtime record, ``substream->runtime``. F 2009 the runtime record, ``substream->runtime``. For example, to get the
1919 current rate, format or channels, access to ` 2010 current rate, format or channels, access to ``runtime->rate``,
1920 ``runtime->format`` or ``runtime->channels``, 2011 ``runtime->format`` or ``runtime->channels``, respectively. The
1921 physical address of the allocated buffer is s 2012 physical address of the allocated buffer is set to
1922 ``runtime->dma_area``. The buffer and period 2013 ``runtime->dma_area``. The buffer and period sizes are in
1923 ``runtime->buffer_size`` and ``runtime->perio 2014 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
1924 2015
1925 Be careful that this callback will be called 2016 Be careful that this callback will be called many times at each setup,
1926 too. 2017 too.
1927 2018
1928 trigger callback 2019 trigger callback
1929 ~~~~~~~~~~~~~~~~ 2020 ~~~~~~~~~~~~~~~~
1930 2021
1931 :: 2022 ::
1932 2023
1933 static int snd_xxx_trigger(struct snd_pcm_s 2024 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
1934 2025
1935 This is called when the PCM is started, stopp !! 2026 This is called when the pcm is started, stopped or paused.
1936 2027
1937 The action is specified in the second argumen !! 2028 Which action is specified in the second argument,
1938 defined in ``<sound/pcm.h>``. At least, the ` !! 2029 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
1939 and ``STOP`` commands must be defined in this !! 2030 and ``STOP`` commands must be defined in this callback.
>> 2031
>> 2032 ::
1940 2033
1941 switch (cmd) { 2034 switch (cmd) {
1942 case SNDRV_PCM_TRIGGER_START: 2035 case SNDRV_PCM_TRIGGER_START:
1943 /* do something to start the PCM en 2036 /* do something to start the PCM engine */
1944 break; 2037 break;
1945 case SNDRV_PCM_TRIGGER_STOP: 2038 case SNDRV_PCM_TRIGGER_STOP:
1946 /* do something to stop the PCM eng 2039 /* do something to stop the PCM engine */
1947 break; 2040 break;
1948 default: 2041 default:
1949 return -EINVAL; 2042 return -EINVAL;
1950 } 2043 }
1951 2044
1952 When the PCM supports the pause operation (gi !! 2045 When the pcm supports the pause operation (given in the info field of
1953 the hardware table), the ``PAUSE_PUSH`` and ` 2046 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
1954 must be handled here, too. The former is the !! 2047 must be handled here, too. The former is the command to pause the pcm,
1955 and the latter to restart the PCM again. !! 2048 and the latter to restart the pcm again.
1956 2049
1957 When the PCM supports the suspend/resume oper !! 2050 When the pcm supports the suspend/resume operation, regardless of full
1958 or partial suspend/resume support, the ``SUSP 2051 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
1959 commands must be handled, too. These commands 2052 commands must be handled, too. These commands are issued when the
1960 power-management status is changed. Obviously 2053 power-management status is changed. Obviously, the ``SUSPEND`` and
1961 ``RESUME`` commands suspend and resume the PC !! 2054 ``RESUME`` commands suspend and resume the pcm substream, and usually,
1962 they are identical to the ``STOP`` and ``STAR 2055 they are identical to the ``STOP`` and ``START`` commands, respectively.
1963 See the `Power Management`_ section for detai 2056 See the `Power Management`_ section for details.
1964 2057
1965 As mentioned, this callback is atomic by defa !! 2058 As mentioned, this callback is atomic as default unless ``nonatomic``
1966 flag set, and you cannot call functions which 2059 flag set, and you cannot call functions which may sleep. The
1967 ``trigger`` callback should be as minimal as 2060 ``trigger`` callback should be as minimal as possible, just really
1968 triggering the DMA. The other stuff should be !! 2061 triggering the DMA. The other stuff should be initialized
1969 ``hw_params`` and ``prepare`` callbacks prope 2062 ``hw_params`` and ``prepare`` callbacks properly beforehand.
1970 2063
1971 sync_stop callback <<
1972 ~~~~~~~~~~~~~~~~~~ <<
1973 <<
1974 :: <<
1975 <<
1976 static int snd_xxx_sync_stop(struct snd_pcm <<
1977 <<
1978 This callback is optional, and NULL can be pa <<
1979 the PCM core stops the stream, before it chan <<
1980 ``prepare``, ``hw_params`` or ``hw_free``. <<
1981 Since the IRQ handler might be still pending, <<
1982 the pending task finishes before moving to th <<
1983 might lead to a crash due to resource conflic <<
1984 resources. A typical behavior is to call a s <<
1985 like :c:func:`synchronize_irq()` here. <<
1986 <<
1987 For the majority of drivers that need only a <<
1988 :c:func:`synchronize_irq()`, there is a simpl <<
1989 While keeping the ``sync_stop`` PCM callback <<
1990 the ``card->sync_irq`` field to the returned <<
1991 requesting an IRQ, instead. Then PCM core w <<
1992 :c:func:`synchronize_irq()` with the given IR <<
1993 <<
1994 If the IRQ handler is released by the card de <<
1995 to clear ``card->sync_irq``, as the card itse <<
1996 So, usually you'll need to add just a single <<
1997 ``card->sync_irq`` in the driver code unless <<
1998 the IRQ. When the driver frees and re-acquir <<
1999 (e.g. for suspend/resume), it needs to clear <<
2000 ``card->sync_irq`` again appropriately. <<
2001 <<
2002 pointer callback 2064 pointer callback
2003 ~~~~~~~~~~~~~~~~ 2065 ~~~~~~~~~~~~~~~~
2004 2066
2005 :: 2067 ::
2006 2068
2007 static snd_pcm_uframes_t snd_xxx_pointer(st 2069 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2008 2070
2009 This callback is called when the PCM middle l 2071 This callback is called when the PCM middle layer inquires the current
2010 hardware position in the buffer. The position !! 2072 hardware position on the buffer. The position must be returned in
2011 frames, ranging from 0 to ``buffer_size - 1`` 2073 frames, ranging from 0 to ``buffer_size - 1``.
2012 2074
2013 This is usually called from the buffer-update !! 2075 This is called usually from the buffer-update routine in the pcm
2014 middle layer, which is invoked when :c:func:` 2076 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2015 is called by the interrupt routine. Then the !! 2077 is called in the interrupt routine. Then the pcm middle layer updates
2016 the position and calculates the available spa 2078 the position and calculates the available space, and wakes up the
2017 sleeping poll threads, etc. 2079 sleeping poll threads, etc.
2018 2080
2019 This callback is also atomic by default. !! 2081 This callback is also atomic as default.
2020 2082
2021 copy and fill_silence ops !! 2083 copy_user, copy_kernel and fill_silence ops
2022 ~~~~~~~~~~~~~~~~~~~~~~~~~ !! 2084 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2023 2085
2024 These callbacks are not mandatory, and can be 2086 These callbacks are not mandatory, and can be omitted in most cases.
2025 These callbacks are used when the hardware bu 2087 These callbacks are used when the hardware buffer cannot be in the
2026 normal memory space. Some chips have their ow !! 2088 normal memory space. Some chips have their own buffer on the hardware
2027 which is not mappable. In such a case, you ha 2089 which is not mappable. In such a case, you have to transfer the data
2028 manually from the memory buffer to the hardwa 2090 manually from the memory buffer to the hardware buffer. Or, if the
2029 buffer is non-contiguous on both physical and 2091 buffer is non-contiguous on both physical and virtual memory spaces,
2030 these callbacks must be defined, too. 2092 these callbacks must be defined, too.
2031 2093
2032 If these two callbacks are defined, copy and 2094 If these two callbacks are defined, copy and set-silence operations
2033 are done by them. The details will be describ !! 2095 are done by them. The detailed will be described in the later section
2034 `Buffer and Memory Management`_. 2096 `Buffer and Memory Management`_.
2035 2097
2036 ack callback 2098 ack callback
2037 ~~~~~~~~~~~~ 2099 ~~~~~~~~~~~~
2038 2100
2039 This callback is also not mandatory. This cal 2101 This callback is also not mandatory. This callback is called when the
2040 ``appl_ptr`` is updated in read or write oper 2102 ``appl_ptr`` is updated in read or write operations. Some drivers like
2041 emu10k1-fx and cs46xx need to track the curre 2103 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2042 internal buffer, and this callback is useful 2104 internal buffer, and this callback is useful only for such a purpose.
2043 2105
2044 The callback function may return 0 or a negat !! 2106 This callback is atomic as default.
2045 return value is ``-EPIPE``, PCM core treats t <<
2046 and changes the state to ``SNDRV_PCM_STATE_XR <<
2047 <<
2048 This callback is atomic by default. <<
2049 2107
2050 page callback 2108 page callback
2051 ~~~~~~~~~~~~~ 2109 ~~~~~~~~~~~~~
2052 2110
2053 This callback is optional too. The mmap calls !! 2111 This callback is optional too. This callback is used mainly for
2054 page fault address. !! 2112 non-contiguous buffers. The mmap calls this callback to get the page
2055 !! 2113 address. Some examples will be explained in the later section `Buffer
2056 You need no special callback for the standard !! 2114 and Memory Management`_, too.
2057 buffer. Hence this callback should be rarely <<
2058 <<
2059 mmap callback <<
2060 ~~~~~~~~~~~~~ <<
2061 <<
2062 This is another optional callback for control <<
2063 When defined, the PCM core calls this callbac <<
2064 memory-mapped, instead of using the standard <<
2065 If you need special handling (due to some arc <<
2066 device-specific issues), implement everything <<
2067 <<
2068 2115
2069 PCM Interrupt Handler 2116 PCM Interrupt Handler
2070 --------------------- 2117 ---------------------
2071 2118
2072 The remainder of the PCM stuff is the PCM int !! 2119 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2073 of the PCM <<
2074 interrupt handler in the sound driver is to u 2120 interrupt handler in the sound driver is to update the buffer position
2075 and to tell the PCM middle layer when the buf 2121 and to tell the PCM middle layer when the buffer position goes across
2076 the specified period boundary. To inform abou !! 2122 the prescribed period size. To inform this, call the
2077 :c:func:`snd_pcm_period_elapsed()` function. 2123 :c:func:`snd_pcm_period_elapsed()` function.
2078 2124
2079 There are several ways sound chips can genera !! 2125 There are several types of sound chips to generate the interrupts.
2080 2126
2081 Interrupts at the period (fragment) boundary 2127 Interrupts at the period (fragment) boundary
2082 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2083 2129
2084 This is the most frequently found type: the h 2130 This is the most frequently found type: the hardware generates an
2085 interrupt at each period boundary. In this ca 2131 interrupt at each period boundary. In this case, you can call
2086 :c:func:`snd_pcm_period_elapsed()` at each in 2132 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2087 2133
2088 :c:func:`snd_pcm_period_elapsed()` takes the 2134 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2089 its argument. Thus, you need to keep the subs 2135 its argument. Thus, you need to keep the substream pointer accessible
2090 from the chip instance. For example, define ` 2136 from the chip instance. For example, define ``substream`` field in the
2091 chip record to hold the current running subst 2137 chip record to hold the current running substream pointer, and set the
2092 pointer value at ``open`` callback (and reset 2138 pointer value at ``open`` callback (and reset at ``close`` callback).
2093 2139
2094 If you acquire a spinlock in the interrupt ha 2140 If you acquire a spinlock in the interrupt handler, and the lock is used
2095 in other PCM callbacks, too, then you have to !! 2141 in other pcm callbacks, too, then you have to release the lock before
2096 calling :c:func:`snd_pcm_period_elapsed()`, b 2142 calling :c:func:`snd_pcm_period_elapsed()`, because
2097 :c:func:`snd_pcm_period_elapsed()` calls othe !! 2143 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2098 inside. 2144 inside.
2099 2145
2100 Typical code would look like:: !! 2146 Typical code would be like:
>> 2147
>> 2148 ::
2101 2149
2102 2150
2103 static irqreturn_t snd_mychip_interrupt 2151 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2104 { 2152 {
2105 struct mychip *chip = dev_id; 2153 struct mychip *chip = dev_id;
2106 spin_lock(&chip->lock); 2154 spin_lock(&chip->lock);
2107 .... 2155 ....
2108 if (pcm_irq_invoked(chip)) { 2156 if (pcm_irq_invoked(chip)) {
2109 /* call updater, unlock 2157 /* call updater, unlock before it */
2110 spin_unlock(&chip->lock 2158 spin_unlock(&chip->lock);
2111 snd_pcm_period_elapsed( 2159 snd_pcm_period_elapsed(chip->substream);
2112 spin_lock(&chip->lock); 2160 spin_lock(&chip->lock);
2113 /* acknowledge the inte 2161 /* acknowledge the interrupt if necessary */
2114 } 2162 }
2115 .... 2163 ....
2116 spin_unlock(&chip->lock); 2164 spin_unlock(&chip->lock);
2117 return IRQ_HANDLED; 2165 return IRQ_HANDLED;
2118 } 2166 }
2119 2167
2120 Also, when the device can detect a buffer und <<
2121 can notify the XRUN status to the PCM core by <<
2122 :c:func:`snd_pcm_stop_xrun()`. This function <<
2123 the PCM state to ``SNDRV_PCM_STATE_XRUN``. No <<
2124 outside the PCM stream lock, hence it can't b <<
2125 callback. <<
2126 2168
2127 2169
2128 High frequency timer interrupts 2170 High frequency timer interrupts
2129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2130 2172
2131 This happens when the hardware doesn't genera 2173 This happens when the hardware doesn't generate interrupts at the period
2132 boundary but issues timer interrupts at a fix 2174 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2133 or ymfpci drivers). In this case, you need to 2175 or ymfpci drivers). In this case, you need to check the current hardware
2134 position and accumulate the processed sample 2176 position and accumulate the processed sample length at each interrupt.
2135 When the accumulated size exceeds the period 2177 When the accumulated size exceeds the period size, call
2136 :c:func:`snd_pcm_period_elapsed()` and reset 2178 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2137 2179
2138 Typical code would look as follows:: !! 2180 Typical code would be like the following.
>> 2181
>> 2182 ::
2139 2183
2140 2184
2141 static irqreturn_t snd_mychip_interrupt 2185 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2142 { 2186 {
2143 struct mychip *chip = dev_id; 2187 struct mychip *chip = dev_id;
2144 spin_lock(&chip->lock); 2188 spin_lock(&chip->lock);
2145 .... 2189 ....
2146 if (pcm_irq_invoked(chip)) { 2190 if (pcm_irq_invoked(chip)) {
2147 unsigned int last_ptr, 2191 unsigned int last_ptr, size;
2148 /* get the current hard 2192 /* get the current hardware pointer (in frames) */
2149 last_ptr = get_hw_ptr(c 2193 last_ptr = get_hw_ptr(chip);
2150 /* calculate the proces 2194 /* calculate the processed frames since the
2151 * last update 2195 * last update
2152 */ 2196 */
2153 if (last_ptr < chip->la 2197 if (last_ptr < chip->last_ptr)
2154 size = runtime- 2198 size = runtime->buffer_size + last_ptr
2155 - chip 2199 - chip->last_ptr;
2156 else 2200 else
2157 size = last_ptr 2201 size = last_ptr - chip->last_ptr;
2158 /* remember the last up 2202 /* remember the last updated point */
2159 chip->last_ptr = last_p 2203 chip->last_ptr = last_ptr;
2160 /* accumulate the size 2204 /* accumulate the size */
2161 chip->size += size; 2205 chip->size += size;
2162 /* over the period boun 2206 /* over the period boundary? */
2163 if (chip->size >= runti 2207 if (chip->size >= runtime->period_size) {
2164 /* reset the ac 2208 /* reset the accumulator */
2165 chip->size %= r 2209 chip->size %= runtime->period_size;
2166 /* call updater 2210 /* call updater */
2167 spin_unlock(&ch 2211 spin_unlock(&chip->lock);
2168 snd_pcm_period_ 2212 snd_pcm_period_elapsed(substream);
2169 spin_lock(&chip 2213 spin_lock(&chip->lock);
2170 } 2214 }
2171 /* acknowledge the inte 2215 /* acknowledge the interrupt if necessary */
2172 } 2216 }
2173 .... 2217 ....
2174 spin_unlock(&chip->lock); 2218 spin_unlock(&chip->lock);
2175 return IRQ_HANDLED; 2219 return IRQ_HANDLED;
2176 } 2220 }
2177 2221
2178 2222
2179 2223
2180 On calling :c:func:`snd_pcm_period_elapsed()` 2224 On calling :c:func:`snd_pcm_period_elapsed()`
2181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2182 2226
2183 In both cases, even if more than one period h !! 2227 In both cases, even if more than one period are elapsed, you don't have
2184 to call :c:func:`snd_pcm_period_elapsed()` ma 2228 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2185 once. And the PCM layer will check the curren !! 2229 once. And the pcm layer will check the current hardware pointer and
2186 update to the latest status. 2230 update to the latest status.
2187 2231
2188 Atomicity 2232 Atomicity
2189 --------- 2233 ---------
2190 2234
2191 One of the most important (and thus difficult 2235 One of the most important (and thus difficult to debug) problems in
2192 kernel programming are race conditions. In th 2236 kernel programming are race conditions. In the Linux kernel, they are
2193 usually avoided via spin-locks, mutexes or se 2237 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2194 race condition can happen in an interrupt han 2238 race condition can happen in an interrupt handler, it has to be managed
2195 atomically, and you have to use a spinlock to 2239 atomically, and you have to use a spinlock to protect the critical
2196 section. If the critical section is not in in !! 2240 session. If the critical section is not in interrupt handler code and if
2197 taking a relatively long time to execute is a 2241 taking a relatively long time to execute is acceptable, you should use
2198 mutexes or semaphores instead. 2242 mutexes or semaphores instead.
2199 2243
2200 As already seen, some PCM callbacks are atomi !! 2244 As already seen, some pcm callbacks are atomic and some are not. For
2201 example, the ``hw_params`` callback is non-at !! 2245 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2202 callback is atomic. This means, the latter is 2246 callback is atomic. This means, the latter is called already in a
2203 spinlock held by the PCM middle layer, the PC !! 2247 spinlock held by the PCM middle layer. Please take this atomicity into
2204 take this atomicity into account when you cho !! 2248 account when you choose a locking scheme in the callbacks.
2205 the callbacks. <<
2206 2249
2207 In the atomic callbacks, you cannot use funct 2250 In the atomic callbacks, you cannot use functions which may call
2208 :c:func:`schedule()` or go to :c:func:`sleep( 2251 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2209 mutexes can sleep, and hence they cannot be u 2252 mutexes can sleep, and hence they cannot be used inside the atomic
2210 callbacks (e.g. ``trigger`` callback). To imp 2253 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2211 callback, please use :c:func:`udelay()` or :c 2254 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2212 2255
2213 All three atomic callbacks (trigger, pointer, 2256 All three atomic callbacks (trigger, pointer, and ack) are called with
2214 local interrupts disabled. 2257 local interrupts disabled.
2215 2258
2216 However, it is possible to request all PCM op !! 2259 The recent changes in PCM core code, however, allow all PCM operations
2217 This assumes that all call sites are in !! 2260 to be non-atomic. This assumes that the all caller sides are in
2218 non-atomic contexts. For example, the functio 2261 non-atomic contexts. For example, the function
2219 :c:func:`snd_pcm_period_elapsed()` is called 2262 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2220 interrupt handler. But, if you set up the dri 2263 interrupt handler. But, if you set up the driver to use a threaded
2221 interrupt handler, this call can be in non-at 2264 interrupt handler, this call can be in non-atomic context, too. In such
2222 a case, you can set the ``nonatomic`` field o !! 2265 a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2223 after creating it. When this flag is set, mut !! 2266 <snd_pcm>` object after creating it. When this flag is set, mutex
2224 in the PCM core instead of spin and rwlocks, !! 2267 and rwsem are used internally in the PCM core instead of spin and
2225 functions safely in a non-atomic !! 2268 rwlocks, so that you can call all PCM functions safely in a non-atomic
2226 context. 2269 context.
2227 2270
2228 Also, in some cases, you might need to call <<
2229 :c:func:`snd_pcm_period_elapsed()` in the ato <<
2230 period gets elapsed during ``ack`` or other c <<
2231 variant that can be called inside the PCM str <<
2232 :c:func:`snd_pcm_period_elapsed_under_stream_ <<
2233 too. <<
2234 <<
2235 Constraints 2271 Constraints
2236 ----------- 2272 -----------
2237 2273
2238 Due to physical limitations, hardware is not !! 2274 If your chip supports unconventional sample rates, or only the limited
2239 These limitations are expressed by setting co !! 2275 samples, you need to set a constraint for the condition.
2240 2276
2241 For example, in order to restrict the sample !! 2277 For example, in order to restrict the sample rates in the some supported
2242 values, use :c:func:`snd_pcm_hw_constraint_li 2278 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2243 call this function in the open callback:: !! 2279 call this function in the open callback.
>> 2280
>> 2281 ::
2244 2282
2245 static unsigned int rates[] = 2283 static unsigned int rates[] =
2246 {4000, 10000, 22050, 44100}; 2284 {4000, 10000, 22050, 44100};
2247 static struct snd_pcm_hw_constraint_lis 2285 static struct snd_pcm_hw_constraint_list constraints_rates = {
2248 .count = ARRAY_SIZE(rates), 2286 .count = ARRAY_SIZE(rates),
2249 .list = rates, 2287 .list = rates,
2250 .mask = 0, 2288 .mask = 0,
2251 }; 2289 };
2252 2290
2253 static int snd_mychip_pcm_open(struct s 2291 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2254 { 2292 {
2255 int err; 2293 int err;
2256 .... 2294 ....
2257 err = snd_pcm_hw_constraint_lis 2295 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2258 2296 SNDRV_PCM_HW_PARAM_RATE,
2259 2297 &constraints_rates);
2260 if (err < 0) 2298 if (err < 0)
2261 return err; 2299 return err;
2262 .... 2300 ....
2263 } 2301 }
2264 2302
>> 2303
>> 2304
2265 There are many different constraints. Look at 2305 There are many different constraints. Look at ``sound/pcm.h`` for a
2266 complete list. You can even define your own c 2306 complete list. You can even define your own constraint rules. For
2267 example, let's suppose my_chip can manage a s 2307 example, let's suppose my_chip can manage a substream of 1 channel if
2268 and only if the format is ``S16_LE``, otherwi 2308 and only if the format is ``S16_LE``, otherwise it supports any format
2269 specified in struct snd_pcm_hardware (or in a !! 2309 specified in the :c:type:`struct snd_pcm_hardware
2270 constraint_list). You can build a rule like t !! 2310 <snd_pcm_hardware>` structure (or in any other
>> 2311 constraint_list). You can build a rule like this:
>> 2312
>> 2313 ::
2271 2314
2272 static int hw_rule_channels_by_format(s 2315 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2273 s 2316 struct snd_pcm_hw_rule *rule)
2274 { 2317 {
2275 struct snd_interval *c = hw_par 2318 struct snd_interval *c = hw_param_interval(params,
2276 SNDRV_PCM_HW_PARA 2319 SNDRV_PCM_HW_PARAM_CHANNELS);
2277 struct snd_mask *f = hw_param_m 2320 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2278 struct snd_interval ch; 2321 struct snd_interval ch;
2279 2322
2280 snd_interval_any(&ch); 2323 snd_interval_any(&ch);
2281 if (f->bits[0] == SNDRV_PCM_FMT 2324 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2282 ch.min = ch.max = 1; 2325 ch.min = ch.max = 1;
2283 ch.integer = 1; 2326 ch.integer = 1;
2284 return snd_interval_ref 2327 return snd_interval_refine(c, &ch);
2285 } 2328 }
2286 return 0; 2329 return 0;
2287 } 2330 }
2288 2331
2289 2332
2290 Then you need to call this function to add yo !! 2333 Then you need to call this function to add your rule:
>> 2334
>> 2335 ::
2291 2336
2292 snd_pcm_hw_rule_add(substream->runtime, 0, 2337 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2293 hw_rule_channels_by_for 2338 hw_rule_channels_by_format, NULL,
2294 SNDRV_PCM_HW_PARAM_FORM 2339 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2295 2340
2296 The rule function is called when an applicati 2341 The rule function is called when an application sets the PCM format, and
2297 it refines the number of channels accordingly 2342 it refines the number of channels accordingly. But an application may
2298 set the number of channels before setting the 2343 set the number of channels before setting the format. Thus you also need
2299 to define the inverse rule:: !! 2344 to define the inverse rule:
>> 2345
>> 2346 ::
2300 2347
2301 static int hw_rule_format_by_channels(s 2348 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2302 s 2349 struct snd_pcm_hw_rule *rule)
2303 { 2350 {
2304 struct snd_interval *c = hw_par 2351 struct snd_interval *c = hw_param_interval(params,
2305 SNDRV_PCM_HW_PARAM_CHANNE 2352 SNDRV_PCM_HW_PARAM_CHANNELS);
2306 struct snd_mask *f = hw_param_m 2353 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2307 struct snd_mask fmt; 2354 struct snd_mask fmt;
2308 2355
2309 snd_mask_any(&fmt); /* Init 2356 snd_mask_any(&fmt); /* Init the struct */
2310 if (c->min < 2) { 2357 if (c->min < 2) {
2311 fmt.bits[0] &= SNDRV_PC 2358 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2312 return snd_mask_refine( 2359 return snd_mask_refine(f, &fmt);
2313 } 2360 }
2314 return 0; 2361 return 0;
2315 } 2362 }
2316 2363
2317 2364
2318 ... and in the open callback:: !! 2365 ... and in the open callback:
>> 2366
>> 2367 ::
2319 2368
2320 snd_pcm_hw_rule_add(substream->runtime, 0, 2369 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2321 hw_rule_format_by_chann 2370 hw_rule_format_by_channels, NULL,
2322 SNDRV_PCM_HW_PARAM_CHAN 2371 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2323 2372
2324 One typical usage of the hw constraints is to <<
2325 with the period size. By default, ALSA PCM c <<
2326 buffer size to be aligned with the period siz <<
2327 possible to have a combination like 256 perio <<
2328 bytes. <<
2329 <<
2330 Many device chips, however, require the buffe <<
2331 periods. In such a case, call <<
2332 :c:func:`snd_pcm_hw_constraint_integer()` for <<
2333 ``SNDRV_PCM_HW_PARAM_PERIODS``:: <<
2334 <<
2335 snd_pcm_hw_constraint_integer(substream->ru <<
2336 SNDRV_PCM_HW_ <<
2337 <<
2338 This assures that the number of periods is in <<
2339 size is aligned with the period size. <<
2340 <<
2341 The hw constraint is a very powerful mechanis <<
2342 preferred PCM configuration, and there are re <<
2343 I won't give more details here, rather I woul 2373 I won't give more details here, rather I would like to say, “Luke, use
2344 the source.” 2374 the source.”
2345 2375
2346 Control Interface 2376 Control Interface
2347 ================= 2377 =================
2348 2378
2349 General 2379 General
2350 ------- 2380 -------
2351 2381
2352 The control interface is used widely for many 2382 The control interface is used widely for many switches, sliders, etc.
2353 which are accessed from user-space. Its most 2383 which are accessed from user-space. Its most important use is the mixer
2354 interface. In other words, since ALSA 0.9.x, 2384 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2355 implemented on the control kernel API. 2385 implemented on the control kernel API.
2356 2386
2357 ALSA has a well-defined AC97 control module. 2387 ALSA has a well-defined AC97 control module. If your chip supports only
2358 the AC97 and nothing else, you can skip this 2388 the AC97 and nothing else, you can skip this section.
2359 2389
2360 The control API is defined in ``<sound/contro 2390 The control API is defined in ``<sound/control.h>``. Include this file
2361 if you want to add your own controls. 2391 if you want to add your own controls.
2362 2392
2363 Definition of Controls 2393 Definition of Controls
2364 ---------------------- 2394 ----------------------
2365 2395
2366 To create a new control, you need to define t 2396 To create a new control, you need to define the following three
2367 callbacks: ``info``, ``get`` and ``put``. The 2397 callbacks: ``info``, ``get`` and ``put``. Then, define a
2368 struct snd_kcontrol_new record, such as:: !! 2398 :c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
>> 2399
>> 2400 ::
2369 2401
2370 2402
2371 static struct snd_kcontrol_new my_contr 2403 static struct snd_kcontrol_new my_control = {
2372 .iface = SNDRV_CTL_ELEM_IFACE_M 2404 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2373 .name = "PCM Playback Switch", 2405 .name = "PCM Playback Switch",
2374 .index = 0, 2406 .index = 0,
2375 .access = SNDRV_CTL_ELEM_ACCESS 2407 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2376 .private_value = 0xffff, 2408 .private_value = 0xffff,
2377 .info = my_control_info, 2409 .info = my_control_info,
2378 .get = my_control_get, 2410 .get = my_control_get,
2379 .put = my_control_put 2411 .put = my_control_put
2380 }; 2412 };
2381 2413
2382 2414
2383 The ``iface`` field specifies the control typ 2415 The ``iface`` field specifies the control type,
2384 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usuall 2416 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2385 for global controls that are not logically pa 2417 for global controls that are not logically part of the mixer. If the
2386 control is closely associated with some speci 2418 control is closely associated with some specific device on the sound
2387 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, `` 2419 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2388 and specify the device number with the ``devi 2420 and specify the device number with the ``device`` and ``subdevice``
2389 fields. 2421 fields.
2390 2422
2391 The ``name`` is the name identifier string. S 2423 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2392 control name is very important, because its r 2424 control name is very important, because its role is classified from
2393 its name. There are pre-defined standard cont 2425 its name. There are pre-defined standard control names. The details
2394 are described in the `Control Names`_ subsect 2426 are described in the `Control Names`_ subsection.
2395 2427
2396 The ``index`` field holds the index number of 2428 The ``index`` field holds the index number of this control. If there
2397 are several different controls with the same 2429 are several different controls with the same name, they can be
2398 distinguished by the index number. This is th 2430 distinguished by the index number. This is the case when several
2399 codecs exist on the card. If the index is zer 2431 codecs exist on the card. If the index is zero, you can omit the
2400 definition above. 2432 definition above.
2401 2433
2402 The ``access`` field contains the access type 2434 The ``access`` field contains the access type of this control. Give
2403 the combination of bit masks, ``SNDRV_CTL_ELE 2435 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2404 there. The details will be explained in the ` 2436 there. The details will be explained in the `Access Flags`_
2405 subsection. 2437 subsection.
2406 2438
2407 The ``private_value`` field contains an arbit 2439 The ``private_value`` field contains an arbitrary long integer value
2408 for this record. When using the generic ``inf 2440 for this record. When using the generic ``info``, ``get`` and ``put``
2409 callbacks, you can pass a value through this 2441 callbacks, you can pass a value through this field. If several small
2410 numbers are necessary, you can combine them i 2442 numbers are necessary, you can combine them in bitwise. Or, it's
2411 possible to store a pointer (casted to unsign !! 2443 possible to give a pointer (casted to unsigned long) of some record to
2412 this field, too. 2444 this field, too.
2413 2445
2414 The ``tlv`` field can be used to provide meta 2446 The ``tlv`` field can be used to provide metadata about the control;
2415 see the `Metadata`_ subsection. 2447 see the `Metadata`_ subsection.
2416 2448
2417 The other three are `Control Callbacks`_. 2449 The other three are `Control Callbacks`_.
2418 2450
2419 Control Names 2451 Control Names
2420 ------------- 2452 -------------
2421 2453
2422 There are some standards to define the contro 2454 There are some standards to define the control names. A control is
2423 usually defined from the three parts as “SO 2455 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2424 2456
2425 The first, ``SOURCE``, specifies the source o 2457 The first, ``SOURCE``, specifies the source of the control, and is a
2426 string such as “Master”, “PCM”, “CD 2458 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2427 pre-defined sources. 2459 pre-defined sources.
2428 2460
2429 The second, ``DIRECTION``, is one of the foll 2461 The second, ``DIRECTION``, is one of the following strings according to
2430 the direction of the control: “Playback”, 2462 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2431 and “Bypass Capture”. Or, it can be omitt 2463 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2432 capture directions. 2464 capture directions.
2433 2465
2434 The third, ``FUNCTION``, is one of the follow 2466 The third, ``FUNCTION``, is one of the following strings according to
2435 the function of the control: “Switch”, 2467 the function of the control: “Switch”, “Volume” and “Route”.
2436 2468
2437 The example of control names are, thus, “Ma 2469 The example of control names are, thus, “Master Capture Switch” or “PCM
2438 Playback Volume”. 2470 Playback Volume”.
2439 2471
2440 There are some exceptions: 2472 There are some exceptions:
2441 2473
2442 Global capture and playback 2474 Global capture and playback
2443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2444 2476
2445 “Capture Source”, “Capture Switch” an 2477 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2446 global capture (input) source, switch and vol 2478 global capture (input) source, switch and volume. Similarly, “Playback
2447 Switch” and “Playback Volume” are used 2479 Switch” and “Playback Volume” are used for the global output gain switch
2448 and volume. 2480 and volume.
2449 2481
2450 Tone-controls 2482 Tone-controls
2451 ~~~~~~~~~~~~~ 2483 ~~~~~~~~~~~~~
2452 2484
2453 tone-control switch and volumes are specified 2485 tone-control switch and volumes are specified like “Tone Control - XXX”,
2454 e.g. “Tone Control - Switch”, “Tone Con 2486 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2455 Center”. 2487 Center”.
2456 2488
2457 3D controls 2489 3D controls
2458 ~~~~~~~~~~~ 2490 ~~~~~~~~~~~
2459 2491
2460 3D-control switches and volumes are specified 2492 3D-control switches and volumes are specified like “3D Control - XXX”,
2461 e.g. “3D Control - Switch”, “3D Control 2493 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2462 2494
2463 Mic boost 2495 Mic boost
2464 ~~~~~~~~~ 2496 ~~~~~~~~~
2465 2497
2466 Mic-boost switch is set as “Mic Boost” or 2498 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2467 2499
2468 More precise information can be found in 2500 More precise information can be found in
2469 ``Documentation/sound/designs/control-names.r !! 2501 ``Documentation/sound/alsa/ControlNames.txt``.
2470 2502
2471 Access Flags 2503 Access Flags
2472 ------------ 2504 ------------
2473 2505
2474 The access flag is the bitmask which specifie 2506 The access flag is the bitmask which specifies the access type of the
2475 given control. The default access type is 2507 given control. The default access type is
2476 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which me 2508 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2477 allowed to this control. When the access flag 2509 allowed to this control. When the access flag is omitted (i.e. = 0), it
2478 is considered as ``READWRITE`` access by defa !! 2510 is considered as ``READWRITE`` access as default.
2479 2511
2480 When the control is read-only, pass ``SNDRV_C 2512 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2481 instead. In this case, you don't have to defi 2513 instead. In this case, you don't have to define the ``put`` callback.
2482 Similarly, when the control is write-only (al 2514 Similarly, when the control is write-only (although it's a rare case),
2483 you can use the ``WRITE`` flag instead, and y 2515 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2484 callback. 2516 callback.
2485 2517
2486 If the control value changes frequently (e.g. 2518 If the control value changes frequently (e.g. the VU meter),
2487 ``VOLATILE`` flag should be given. This means 2519 ``VOLATILE`` flag should be given. This means that the control may be
2488 changed without `Change notification`_. Appli 2520 changed without `Change notification`_. Applications should poll such
2489 a control constantly. 2521 a control constantly.
2490 2522
2491 When the control may be updated, but currentl !! 2523 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2492 setting the ``INACTIVE`` flag may be appropri !! 2524 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2493 controls should be inactive while no PCM devi <<
2494 <<
2495 There are ``LOCK`` and ``OWNER`` flags to cha <<
2496 2525
2497 Control Callbacks 2526 Control Callbacks
2498 ----------------- 2527 -----------------
2499 2528
2500 info callback 2529 info callback
2501 ~~~~~~~~~~~~~ 2530 ~~~~~~~~~~~~~
2502 2531
2503 The ``info`` callback is used to get detailed 2532 The ``info`` callback is used to get detailed information on this
2504 control. This must store the values of the gi !! 2533 control. This must store the values of the given :c:type:`struct
2505 struct snd_ctl_elem_info object. For example, !! 2534 snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2506 for a boolean control with a single element:: !! 2535 for a boolean control with a single element:
>> 2536
>> 2537 ::
2507 2538
2508 2539
2509 static int snd_myctl_mono_info(struct s 2540 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2510 struct snd_ctl_ 2541 struct snd_ctl_elem_info *uinfo)
2511 { 2542 {
2512 uinfo->type = SNDRV_CTL_ELEM_TY 2543 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513 uinfo->count = 1; 2544 uinfo->count = 1;
2514 uinfo->value.integer.min = 0; 2545 uinfo->value.integer.min = 0;
2515 uinfo->value.integer.max = 1; 2546 uinfo->value.integer.max = 1;
2516 return 0; 2547 return 0;
2517 } 2548 }
2518 2549
2519 2550
2520 2551
2521 The ``type`` field specifies the type of the 2552 The ``type`` field specifies the type of the control. There are
2522 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``B 2553 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2523 ``INTEGER64``. The ``count`` field specifies 2554 ``INTEGER64``. The ``count`` field specifies the number of elements in
2524 this control. For example, a stereo volume wo 2555 this control. For example, a stereo volume would have count = 2. The
2525 ``value`` field is a union, and the values st !! 2556 ``value`` field is a union, and the values stored are depending on the
2526 type. The boolean and integer types are ident 2557 type. The boolean and integer types are identical.
2527 2558
2528 The enumerated type is a bit different from t !! 2559 The enumerated type is a bit different from others. You'll need to set
2529 set the string for the selectec item index:: !! 2560 the string for the currently given item index.
>> 2561
>> 2562 ::
2530 2563
2531 static int snd_myctl_enum_info(struct snd_k 2564 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2532 struct snd_ctl_elem 2565 struct snd_ctl_elem_info *uinfo)
2533 { 2566 {
2534 static char *texts[4] = { 2567 static char *texts[4] = {
2535 "First", "Second", "Third", 2568 "First", "Second", "Third", "Fourth"
2536 }; 2569 };
2537 uinfo->type = SNDRV_CTL_ELEM_TYPE_E 2570 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2538 uinfo->count = 1; 2571 uinfo->count = 1;
2539 uinfo->value.enumerated.items = 4; 2572 uinfo->value.enumerated.items = 4;
2540 if (uinfo->value.enumerated.item > 2573 if (uinfo->value.enumerated.item > 3)
2541 uinfo->value.enumerated.ite 2574 uinfo->value.enumerated.item = 3;
2542 strcpy(uinfo->value.enumerated.name 2575 strcpy(uinfo->value.enumerated.name,
2543 texts[uinfo->value.enumerate 2576 texts[uinfo->value.enumerated.item]);
2544 return 0; 2577 return 0;
2545 } 2578 }
2546 2579
2547 The above callback can be simplified with a h 2580 The above callback can be simplified with a helper function,
2548 :c:func:`snd_ctl_enum_info()`. The final code 2581 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2549 (You can pass ``ARRAY_SIZE(texts)`` instead o 2582 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2550 it's a matter of taste.) 2583 it's a matter of taste.)
2551 2584
2552 :: 2585 ::
2553 2586
2554 static int snd_myctl_enum_info(struct snd_k 2587 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2555 struct snd_ctl_elem 2588 struct snd_ctl_elem_info *uinfo)
2556 { 2589 {
2557 static char *texts[4] = { 2590 static char *texts[4] = {
2558 "First", "Second", "Third", 2591 "First", "Second", "Third", "Fourth"
2559 }; 2592 };
2560 return snd_ctl_enum_info(uinfo, 1, 2593 return snd_ctl_enum_info(uinfo, 1, 4, texts);
2561 } 2594 }
2562 2595
2563 2596
2564 Some common info callbacks are available for 2597 Some common info callbacks are available for your convenience:
2565 :c:func:`snd_ctl_boolean_mono_info()` and 2598 :c:func:`snd_ctl_boolean_mono_info()` and
2566 :c:func:`snd_ctl_boolean_stereo_info()`. Obvi 2599 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2567 is an info callback for a mono channel boolea 2600 is an info callback for a mono channel boolean item, just like
2568 :c:func:`snd_myctl_mono_info()` above, and th 2601 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2569 stereo channel boolean item. 2602 stereo channel boolean item.
2570 2603
2571 get callback 2604 get callback
2572 ~~~~~~~~~~~~ 2605 ~~~~~~~~~~~~
2573 2606
2574 This callback is used to read the current val !! 2607 This callback is used to read the current value of the control and to
2575 can be returned to user-space. !! 2608 return to user-space.
>> 2609
>> 2610 For example,
>> 2611
>> 2612 ::
2576 2613
2577 For example:: <<
2578 2614
2579 static int snd_myctl_get(struct snd_kco 2615 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2580 struct snd_ctl 2616 struct snd_ctl_elem_value *ucontrol)
2581 { 2617 {
2582 struct mychip *chip = snd_kcont 2618 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2583 ucontrol->value.integer.value[0 2619 ucontrol->value.integer.value[0] = get_some_value(chip);
2584 return 0; 2620 return 0;
2585 } 2621 }
2586 2622
2587 2623
2588 2624
2589 The ``value`` field depends on the type of co 2625 The ``value`` field depends on the type of control as well as on the
2590 info callback. For example, the sb driver use 2626 info callback. For example, the sb driver uses this field to store the
2591 register offset, the bit-shift and the bit-ma 2627 register offset, the bit-shift and the bit-mask. The ``private_value``
2592 field is set as follows:: !! 2628 field is set as follows:
>> 2629
>> 2630 ::
2593 2631
2594 .private_value = reg | (shift << 16) | (mas 2632 .private_value = reg | (shift << 16) | (mask << 24)
2595 2633
2596 and is retrieved in callbacks like:: !! 2634 and is retrieved in callbacks like
>> 2635
>> 2636 ::
2597 2637
2598 static int snd_sbmixer_get_single(struct sn 2638 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2599 struct sn 2639 struct snd_ctl_elem_value *ucontrol)
2600 { 2640 {
2601 int reg = kcontrol->private_value & 2641 int reg = kcontrol->private_value & 0xff;
2602 int shift = (kcontrol->private_valu 2642 int shift = (kcontrol->private_value >> 16) & 0xff;
2603 int mask = (kcontrol->private_value 2643 int mask = (kcontrol->private_value >> 24) & 0xff;
2604 .... 2644 ....
2605 } 2645 }
2606 2646
2607 In the ``get`` callback, you have to fill all 2647 In the ``get`` callback, you have to fill all the elements if the
2608 control has more than one element, i.e. ``cou !! 2648 control has more than one elements, i.e. ``count > 1``. In the example
2609 above, we filled only one element (``value.in 2649 above, we filled only one element (``value.integer.value[0]``) since
2610 ``count = 1`` is assumed. !! 2650 it's assumed as ``count = 1``.
2611 2651
2612 put callback 2652 put callback
2613 ~~~~~~~~~~~~ 2653 ~~~~~~~~~~~~
2614 2654
2615 This callback is used to write a value coming !! 2655 This callback is used to write a value from user-space.
>> 2656
>> 2657 For example,
>> 2658
>> 2659 ::
2616 2660
2617 For example:: <<
2618 2661
2619 static int snd_myctl_put(struct snd_kco 2662 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2620 struct snd_ctl 2663 struct snd_ctl_elem_value *ucontrol)
2621 { 2664 {
2622 struct mychip *chip = snd_kcont 2665 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2623 int changed = 0; 2666 int changed = 0;
2624 if (chip->current_value != 2667 if (chip->current_value !=
2625 ucontrol->value.integer.va 2668 ucontrol->value.integer.value[0]) {
2626 change_current_value(ch 2669 change_current_value(chip,
2627 ucontrol->v 2670 ucontrol->value.integer.value[0]);
2628 changed = 1; 2671 changed = 1;
2629 } 2672 }
2630 return changed; 2673 return changed;
2631 } 2674 }
2632 2675
2633 2676
2634 2677
2635 As seen above, you have to return 1 if the va 2678 As seen above, you have to return 1 if the value is changed. If the
2636 value is not changed, return 0 instead. If an 2679 value is not changed, return 0 instead. If any fatal error happens,
2637 return a negative error code as usual. 2680 return a negative error code as usual.
2638 2681
2639 As in the ``get`` callback, when the control 2682 As in the ``get`` callback, when the control has more than one
2640 element, all elements must be evaluated in th !! 2683 elements, all elements must be evaluated in this callback, too.
2641 2684
2642 Callbacks are not atomic 2685 Callbacks are not atomic
2643 ~~~~~~~~~~~~~~~~~~~~~~~~ 2686 ~~~~~~~~~~~~~~~~~~~~~~~~
2644 2687
2645 All these three callbacks are not-atomic. !! 2688 All these three callbacks are basically not atomic.
2646 2689
2647 Control Constructor 2690 Control Constructor
2648 ------------------- 2691 -------------------
2649 2692
2650 When everything is ready, finally we can crea 2693 When everything is ready, finally we can create a new control. To create
2651 a control, there are two functions to be call 2694 a control, there are two functions to be called,
2652 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl 2695 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2653 2696
2654 In the simplest way, you can do it like this: !! 2697 In the simplest way, you can do like this:
>> 2698
>> 2699 ::
2655 2700
2656 err = snd_ctl_add(card, snd_ctl_new1(&my_co 2701 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2657 if (err < 0) 2702 if (err < 0)
2658 return err; 2703 return err;
2659 2704
2660 where ``my_control`` is the struct snd_kcontr !! 2705 where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2661 and chip is the object pointer to be passed t !! 2706 <snd_kcontrol_new>` object defined above, and chip is the object
2662 can be referred to in callbacks. !! 2707 pointer to be passed to kcontrol->private_data which can be referred
>> 2708 to in callbacks.
2663 2709
2664 :c:func:`snd_ctl_new1()` allocates a new stru !! 2710 :c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
>> 2711 snd_kcontrol <snd_kcontrol>` instance, and
2665 :c:func:`snd_ctl_add()` assigns the given con 2712 :c:func:`snd_ctl_add()` assigns the given control component to the
2666 card. 2713 card.
2667 2714
2668 Change Notification 2715 Change Notification
2669 ------------------- 2716 -------------------
2670 2717
2671 If you need to change and update a control in 2718 If you need to change and update a control in the interrupt routine, you
2672 can call :c:func:`snd_ctl_notify()`. For exam !! 2719 can call :c:func:`snd_ctl_notify()`. For example,
>> 2720
>> 2721 ::
2673 2722
2674 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_V 2723 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2675 2724
2676 This function takes the card pointer, the eve 2725 This function takes the card pointer, the event-mask, and the control id
2677 pointer for the notification. The event-mask 2726 pointer for the notification. The event-mask specifies the types of
2678 notification, for example, in the above examp 2727 notification, for example, in the above example, the change of control
2679 values is notified. The id pointer is the poi !! 2728 values is notified. The id pointer is the pointer of :c:type:`struct
2680 to be notified. You can find some examples in !! 2729 snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2681 for hardware volume interrupts. !! 2730 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
>> 2731 interrupts.
2682 2732
2683 Metadata 2733 Metadata
2684 -------- 2734 --------
2685 2735
2686 To provide information about the dB values of !! 2736 To provide information about the dB values of a mixer control, use on of
2687 the ``DECLARE_TLV_xxx`` macros from ``<sound/ 2737 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2688 variable containing this information, set the 2738 variable containing this information, set the ``tlv.p`` field to point to
2689 this variable, and include the ``SNDRV_CTL_EL 2739 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2690 in the ``access`` field; like this:: !! 2740 in the ``access`` field; like this:
>> 2741
>> 2742 ::
2691 2743
2692 static DECLARE_TLV_DB_SCALE(db_scale_my_con 2744 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2693 2745
2694 static struct snd_kcontrol_new my_control = 2746 static struct snd_kcontrol_new my_control = {
2695 ... 2747 ...
2696 .access = SNDRV_CTL_ELEM_ACCESS_REA 2748 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2697 SNDRV_CTL_ELEM_ACCESS_TLV 2749 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2698 ... 2750 ...
2699 .tlv.p = db_scale_my_control, 2751 .tlv.p = db_scale_my_control,
2700 }; 2752 };
2701 2753
2702 2754
2703 The :c:func:`DECLARE_TLV_DB_SCALE()` macro de 2755 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2704 about a mixer control where each step in the 2756 about a mixer control where each step in the control's value changes the
2705 dB value by a constant dB amount. The first p 2757 dB value by a constant dB amount. The first parameter is the name of the
2706 variable to be defined. The second parameter 2758 variable to be defined. The second parameter is the minimum value, in
2707 units of 0.01 dB. The third parameter is the 2759 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2708 dB. Set the fourth parameter to 1 if the mini 2760 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2709 the control. 2761 the control.
2710 2762
2711 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro d 2763 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2712 about a mixer control where the control's val 2764 about a mixer control where the control's value affects the output
2713 linearly. The first parameter is the name of 2765 linearly. The first parameter is the name of the variable to be defined.
2714 The second parameter is the minimum value, in 2766 The second parameter is the minimum value, in units of 0.01 dB. The
2715 third parameter is the maximum value, in unit 2767 third parameter is the maximum value, in units of 0.01 dB. If the
2716 minimum value mutes the control, set the seco 2768 minimum value mutes the control, set the second parameter to
2717 ``TLV_DB_GAIN_MUTE``. 2769 ``TLV_DB_GAIN_MUTE``.
2718 2770
2719 API for AC97 Codec 2771 API for AC97 Codec
2720 ================== 2772 ==================
2721 2773
2722 General 2774 General
2723 ------- 2775 -------
2724 2776
2725 The ALSA AC97 codec layer is a well-defined o 2777 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2726 write much code to control it. Only low-level 2778 write much code to control it. Only low-level control routines are
2727 necessary. The AC97 codec API is defined in ` 2779 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2728 2780
2729 Full Code Example 2781 Full Code Example
2730 ----------------- 2782 -----------------
2731 2783
2732 :: 2784 ::
2733 2785
2734 struct mychip { 2786 struct mychip {
2735 .... 2787 ....
2736 struct snd_ac97 *ac97; 2788 struct snd_ac97 *ac97;
2737 .... 2789 ....
2738 }; 2790 };
2739 2791
2740 static unsigned short snd_mychip_ac97_r 2792 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2741 2793 unsigned short reg)
2742 { 2794 {
2743 struct mychip *chip = ac97->pri 2795 struct mychip *chip = ac97->private_data;
2744 .... 2796 ....
2745 /* read a register value here f 2797 /* read a register value here from the codec */
2746 return the_register_value; 2798 return the_register_value;
2747 } 2799 }
2748 2800
2749 static void snd_mychip_ac97_write(struc 2801 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2750 unsign 2802 unsigned short reg, unsigned short val)
2751 { 2803 {
2752 struct mychip *chip = ac97->pri 2804 struct mychip *chip = ac97->private_data;
2753 .... 2805 ....
2754 /* write the given register val 2806 /* write the given register value to the codec */
2755 } 2807 }
2756 2808
2757 static int snd_mychip_ac97(struct mychi 2809 static int snd_mychip_ac97(struct mychip *chip)
2758 { 2810 {
2759 struct snd_ac97_bus *bus; 2811 struct snd_ac97_bus *bus;
2760 struct snd_ac97_template ac97; 2812 struct snd_ac97_template ac97;
2761 int err; 2813 int err;
2762 static struct snd_ac97_bus_ops 2814 static struct snd_ac97_bus_ops ops = {
2763 .write = snd_mychip_ac9 2815 .write = snd_mychip_ac97_write,
2764 .read = snd_mychip_ac97 2816 .read = snd_mychip_ac97_read,
2765 }; 2817 };
2766 2818
2767 err = snd_ac97_bus(chip->card, 2819 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2768 if (err < 0) 2820 if (err < 0)
2769 return err; 2821 return err;
2770 memset(&ac97, 0, sizeof(ac97)); 2822 memset(&ac97, 0, sizeof(ac97));
2771 ac97.private_data = chip; 2823 ac97.private_data = chip;
2772 return snd_ac97_mixer(bus, &ac9 2824 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2773 } 2825 }
2774 2826
2775 2827
2776 AC97 Constructor 2828 AC97 Constructor
2777 ---------------- 2829 ----------------
2778 2830
2779 To create an ac97 instance, first call :c:fun 2831 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2780 with an ``ac97_bus_ops_t`` record with callba !! 2832 with an ``ac97_bus_ops_t`` record with callback functions.
>> 2833
>> 2834 ::
2781 2835
2782 struct snd_ac97_bus *bus; 2836 struct snd_ac97_bus *bus;
2783 static struct snd_ac97_bus_ops ops = { 2837 static struct snd_ac97_bus_ops ops = {
2784 .write = snd_mychip_ac97_write, 2838 .write = snd_mychip_ac97_write,
2785 .read = snd_mychip_ac97_read, 2839 .read = snd_mychip_ac97_read,
2786 }; 2840 };
2787 2841
2788 snd_ac97_bus(card, 0, &ops, NULL, &pbus); 2842 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2789 2843
2790 The bus record is shared among all belonging 2844 The bus record is shared among all belonging ac97 instances.
2791 2845
2792 And then call :c:func:`snd_ac97_mixer()` with !! 2846 And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2793 record together with the bus pointer created !! 2847 snd_ac97_template <snd_ac97_template>` record together with
>> 2848 the bus pointer created above.
>> 2849
>> 2850 ::
2794 2851
2795 struct snd_ac97_template ac97; 2852 struct snd_ac97_template ac97;
2796 int err; 2853 int err;
2797 2854
2798 memset(&ac97, 0, sizeof(ac97)); 2855 memset(&ac97, 0, sizeof(ac97));
2799 ac97.private_data = chip; 2856 ac97.private_data = chip;
2800 snd_ac97_mixer(bus, &ac97, &chip->ac97); 2857 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2801 2858
2802 where chip->ac97 is a pointer to a newly crea 2859 where chip->ac97 is a pointer to a newly created ``ac97_t``
2803 instance. In this case, the chip pointer is s 2860 instance. In this case, the chip pointer is set as the private data,
2804 so that the read/write callback functions can 2861 so that the read/write callback functions can refer to this chip
2805 instance. This instance is not necessarily st 2862 instance. This instance is not necessarily stored in the chip
2806 record. If you need to change the register va 2863 record. If you need to change the register values from the driver, or
2807 need the suspend/resume of ac97 codecs, keep 2864 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2808 the corresponding functions. 2865 the corresponding functions.
2809 2866
2810 AC97 Callbacks 2867 AC97 Callbacks
2811 -------------- 2868 --------------
2812 2869
2813 The standard callbacks are ``read`` and ``wri 2870 The standard callbacks are ``read`` and ``write``. Obviously they
2814 correspond to the functions for read and writ 2871 correspond to the functions for read and write accesses to the
2815 hardware low-level codes. 2872 hardware low-level codes.
2816 2873
2817 The ``read`` callback returns the register va 2874 The ``read`` callback returns the register value specified in the
2818 argument:: !! 2875 argument.
>> 2876
>> 2877 ::
2819 2878
2820 static unsigned short snd_mychip_ac97_read( 2879 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2821 2880 unsigned short reg)
2822 { 2881 {
2823 struct mychip *chip = ac97->private 2882 struct mychip *chip = ac97->private_data;
2824 .... 2883 ....
2825 return the_register_value; 2884 return the_register_value;
2826 } 2885 }
2827 2886
2828 Here, the chip can be cast from ``ac97->priva 2887 Here, the chip can be cast from ``ac97->private_data``.
2829 2888
2830 Meanwhile, the ``write`` callback is used to 2889 Meanwhile, the ``write`` callback is used to set the register
2831 value:: !! 2890 value
>> 2891
>> 2892 ::
2832 2893
2833 static void snd_mychip_ac97_write(struct sn 2894 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2834 unsigned short reg, un 2895 unsigned short reg, unsigned short val)
2835 2896
2836 2897
2837 These callbacks are non-atomic like the contr 2898 These callbacks are non-atomic like the control API callbacks.
2838 2899
2839 There are also other callbacks: ``reset``, `` 2900 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2840 2901
2841 The ``reset`` callback is used to reset the c 2902 The ``reset`` callback is used to reset the codec. If the chip
2842 requires a special kind of reset, you can def 2903 requires a special kind of reset, you can define this callback.
2843 2904
2844 The ``wait`` callback is used to add some wai 2905 The ``wait`` callback is used to add some waiting time in the standard
2845 initialization of the codec. If the chip requ 2906 initialization of the codec. If the chip requires the extra waiting
2846 time, define this callback. 2907 time, define this callback.
2847 2908
2848 The ``init`` callback is used for additional 2909 The ``init`` callback is used for additional initialization of the
2849 codec. 2910 codec.
2850 2911
2851 Updating Registers in The Driver 2912 Updating Registers in The Driver
2852 -------------------------------- 2913 --------------------------------
2853 2914
2854 If you need to access to the codec from the d 2915 If you need to access to the codec from the driver, you can call the
2855 following functions: :c:func:`snd_ac97_write( 2916 following functions: :c:func:`snd_ac97_write()`,
2856 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_ 2917 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2857 :c:func:`snd_ac97_update_bits()`. 2918 :c:func:`snd_ac97_update_bits()`.
2858 2919
2859 Both :c:func:`snd_ac97_write()` and 2920 Both :c:func:`snd_ac97_write()` and
2860 :c:func:`snd_ac97_update()` functions are use 2921 :c:func:`snd_ac97_update()` functions are used to set a value to
2861 the given register (``AC97_XXX``). The differ 2922 the given register (``AC97_XXX``). The difference between them is that
2862 :c:func:`snd_ac97_update()` doesn't write a v 2923 :c:func:`snd_ac97_update()` doesn't write a value if the given
2863 value has been already set, while :c:func:`sn 2924 value has been already set, while :c:func:`snd_ac97_write()`
2864 always rewrites the value:: !! 2925 always rewrites the value.
>> 2926
>> 2927 ::
2865 2928
2866 snd_ac97_write(ac97, AC97_MASTER, 0x8080); 2929 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2867 snd_ac97_update(ac97, AC97_MASTER, 0x8080); 2930 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2868 2931
2869 :c:func:`snd_ac97_read()` is used to read the 2932 :c:func:`snd_ac97_read()` is used to read the value of the given
2870 register. For example:: !! 2933 register. For example,
>> 2934
>> 2935 ::
2871 2936
2872 value = snd_ac97_read(ac97, AC97_MASTER); 2937 value = snd_ac97_read(ac97, AC97_MASTER);
2873 2938
2874 :c:func:`snd_ac97_update_bits()` is used to u 2939 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2875 the given register:: !! 2940 the given register.
>> 2941
>> 2942 ::
2876 2943
2877 snd_ac97_update_bits(ac97, reg, mask, value 2944 snd_ac97_update_bits(ac97, reg, mask, value);
2878 2945
2879 Also, there is a function to change the sampl 2946 Also, there is a function to change the sample rate (of a given register
2880 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA 2947 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2881 codec: :c:func:`snd_ac97_set_rate()`:: !! 2948 codec: :c:func:`snd_ac97_set_rate()`.
>> 2949
>> 2950 ::
2882 2951
2883 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_ 2952 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2884 2953
2885 2954
2886 The following registers are available to set 2955 The following registers are available to set the rate:
2887 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_D 2956 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2888 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. Whe 2957 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2889 specified, the register is not really changed 2958 specified, the register is not really changed but the corresponding
2890 IEC958 status bits will be updated. 2959 IEC958 status bits will be updated.
2891 2960
2892 Clock Adjustment 2961 Clock Adjustment
2893 ---------------- 2962 ----------------
2894 2963
2895 In some chips, the clock of the codec isn't 4 2964 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2896 (to save a quartz!). In this case, change the 2965 (to save a quartz!). In this case, change the field ``bus->clock`` to
2897 the corresponding value. For example, intel8x 2966 the corresponding value. For example, intel8x0 and es1968 drivers have
2898 their own function to read from the clock. 2967 their own function to read from the clock.
2899 2968
2900 Proc Files 2969 Proc Files
2901 ---------- 2970 ----------
2902 2971
2903 The ALSA AC97 interface will create a proc fi 2972 The ALSA AC97 interface will create a proc file such as
2904 ``/proc/asound/card0/codec97#0/ac97#0-0`` and 2973 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2905 can refer to these files to see the current s 2974 can refer to these files to see the current status and registers of
2906 the codec. 2975 the codec.
2907 2976
2908 Multiple Codecs 2977 Multiple Codecs
2909 --------------- 2978 ---------------
2910 2979
2911 When there are several codecs on the same car 2980 When there are several codecs on the same card, you need to call
2912 :c:func:`snd_ac97_mixer()` multiple times wit 2981 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
2913 greater. The ``num`` field specifies the code 2982 greater. The ``num`` field specifies the codec number.
2914 2983
2915 If you set up multiple codecs, you either nee 2984 If you set up multiple codecs, you either need to write different
2916 callbacks for each codec or check ``ac97->num 2985 callbacks for each codec or check ``ac97->num`` in the callback
2917 routines. 2986 routines.
2918 2987
2919 MIDI (MPU401-UART) Interface 2988 MIDI (MPU401-UART) Interface
2920 ============================ 2989 ============================
2921 2990
2922 General 2991 General
2923 ------- 2992 -------
2924 2993
2925 Many soundcards have built-in MIDI (MPU401-UA 2994 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
2926 soundcard supports the standard MPU401-UART i 2995 soundcard supports the standard MPU401-UART interface, most likely you
2927 can use the ALSA MPU401-UART API. The MPU401- 2996 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2928 ``<sound/mpu401.h>``. 2997 ``<sound/mpu401.h>``.
2929 2998
2930 Some soundchips have a similar but slightly d 2999 Some soundchips have a similar but slightly different implementation of
2931 mpu401 stuff. For example, emu10k1 has its ow 3000 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
2932 3001
2933 MIDI Constructor 3002 MIDI Constructor
2934 ---------------- 3003 ----------------
2935 3004
2936 To create a rawmidi object, call :c:func:`snd !! 3005 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
>> 3006
>> 3007 ::
2937 3008
2938 struct snd_rawmidi *rmidi; 3009 struct snd_rawmidi *rmidi;
2939 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU4 3010 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
2940 irq, &rmidi); 3011 irq, &rmidi);
2941 3012
2942 3013
2943 The first argument is the card pointer, and t 3014 The first argument is the card pointer, and the second is the index of
2944 this component. You can create up to 8 rawmid 3015 this component. You can create up to 8 rawmidi devices.
2945 3016
2946 The third argument is the type of the hardwar 3017 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
2947 it's not a special one, you can use ``MPU401_ 3018 it's not a special one, you can use ``MPU401_HW_MPU401``.
2948 3019
2949 The 4th argument is the I/O port address. Man 3020 The 4th argument is the I/O port address. Many backward-compatible
2950 MPU401 have an I/O port such as 0x330. Or, it 3021 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
2951 PCI I/O region. It depends on the chip design 3022 PCI I/O region. It depends on the chip design.
2952 3023
2953 The 5th argument is a bitflag for additional 3024 The 5th argument is a bitflag for additional information. When the I/O
2954 port address above is part of the PCI I/O reg 3025 port address above is part of the PCI I/O region, the MPU401 I/O port
2955 might have been already allocated (reserved) 3026 might have been already allocated (reserved) by the driver itself. In
2956 such a case, pass a bit flag ``MPU401_INFO_IN 3027 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
2957 mpu401-uart layer will allocate the I/O ports 3028 mpu401-uart layer will allocate the I/O ports by itself.
2958 3029
2959 When the controller supports only the input o 3030 When the controller supports only the input or output MIDI stream, pass
2960 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OU 3031 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
2961 respectively. Then the rawmidi instance is cr 3032 respectively. Then the rawmidi instance is created as a single stream.
2962 3033
2963 ``MPU401_INFO_MMIO`` bitflag is used to chang 3034 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
2964 (via readb and writeb) instead of iob and out 3035 (via readb and writeb) instead of iob and outb. In this case, you have
2965 to pass the iomapped address to :c:func:`snd_ 3036 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
2966 3037
2967 When ``MPU401_INFO_TX_IRQ`` is set, the outpu 3038 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
2968 the default interrupt handler. The driver nee 3039 the default interrupt handler. The driver needs to call
2969 :c:func:`snd_mpu401_uart_interrupt_tx()` by i 3040 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
2970 processing the output stream in the irq handl 3041 processing the output stream in the irq handler.
2971 3042
2972 If the MPU-401 interface shares its interrupt 3043 If the MPU-401 interface shares its interrupt with the other logical
2973 devices on the card, set ``MPU401_INFO_IRQ_HO 3044 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
2974 `below <MIDI Interrupt Handler_>`__). !! 3045 `below <#MIDI-Interrupt-Handler>`__).
2975 3046
2976 Usually, the port address corresponds to the 3047 Usually, the port address corresponds to the command port and port + 1
2977 corresponds to the data port. If not, you may 3048 corresponds to the data port. If not, you may change the ``cport``
2978 field of struct snd_mpu401 manually afterward !! 3049 field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
2979 However, struct snd_mpu401 pointer is !! 3050 However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
2980 not returned explicitly by :c:func:`snd_mpu40 3051 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
2981 need to cast ``rmidi->private_data`` to struc !! 3052 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
>> 3053 <snd_mpu401>` explicitly,
>> 3054
>> 3055 ::
2982 3056
2983 struct snd_mpu401 *mpu; 3057 struct snd_mpu401 *mpu;
2984 mpu = rmidi->private_data; 3058 mpu = rmidi->private_data;
2985 3059
2986 and reset the ``cport`` as you like:: !! 3060 and reset the ``cport`` as you like:
>> 3061
>> 3062 ::
2987 3063
2988 mpu->cport = my_own_control_port; 3064 mpu->cport = my_own_control_port;
2989 3065
2990 The 6th argument specifies the ISA irq number 3066 The 6th argument specifies the ISA irq number that will be allocated. If
2991 no interrupt is to be allocated (because your 3067 no interrupt is to be allocated (because your code is already allocating
2992 a shared interrupt, or because the device doe 3068 a shared interrupt, or because the device does not use interrupts), pass
2993 -1 instead. For a MPU-401 device without an i 3069 -1 instead. For a MPU-401 device without an interrupt, a polling timer
2994 will be used instead. 3070 will be used instead.
2995 3071
2996 MIDI Interrupt Handler 3072 MIDI Interrupt Handler
2997 ---------------------- 3073 ----------------------
2998 3074
2999 When the interrupt is allocated in 3075 When the interrupt is allocated in
3000 :c:func:`snd_mpu401_uart_new()`, an exclusive 3076 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3001 handler is automatically used, hence you don' 3077 handler is automatically used, hence you don't have anything else to do
3002 than creating the mpu401 stuff. Otherwise, yo 3078 than creating the mpu401 stuff. Otherwise, you have to set
3003 ``MPU401_INFO_IRQ_HOOK``, and call 3079 ``MPU401_INFO_IRQ_HOOK``, and call
3004 :c:func:`snd_mpu401_uart_interrupt()` explici 3080 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3005 interrupt handler when it has determined that 3081 interrupt handler when it has determined that a UART interrupt has
3006 occurred. 3082 occurred.
3007 3083
3008 In this case, you need to pass the private_da 3084 In this case, you need to pass the private_data of the returned rawmidi
3009 object from :c:func:`snd_mpu401_uart_new()` a 3085 object from :c:func:`snd_mpu401_uart_new()` as the second
3010 argument of :c:func:`snd_mpu401_uart_interrup !! 3086 argument of :c:func:`snd_mpu401_uart_interrupt()`.
>> 3087
>> 3088 ::
3011 3089
3012 snd_mpu401_uart_interrupt(irq, rmidi->priva 3090 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3013 3091
3014 3092
3015 RawMIDI Interface 3093 RawMIDI Interface
3016 ================= 3094 =================
3017 3095
3018 Overview 3096 Overview
3019 -------- 3097 --------
3020 3098
3021 The raw MIDI interface is used for hardware M 3099 The raw MIDI interface is used for hardware MIDI ports that can be
3022 accessed as a byte stream. It is not used for 3100 accessed as a byte stream. It is not used for synthesizer chips that do
3023 not directly understand MIDI. 3101 not directly understand MIDI.
3024 3102
3025 ALSA handles file and buffer management. All 3103 ALSA handles file and buffer management. All you have to do is to write
3026 some code to move data between the buffer and 3104 some code to move data between the buffer and the hardware.
3027 3105
3028 The rawmidi API is defined in ``<sound/rawmid 3106 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3029 3107
3030 RawMIDI Constructor 3108 RawMIDI Constructor
3031 ------------------- 3109 -------------------
3032 3110
3033 To create a rawmidi device, call the :c:func: 3111 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3034 function:: !! 3112 function:
>> 3113
>> 3114 ::
3035 3115
3036 struct snd_rawmidi *rmidi; 3116 struct snd_rawmidi *rmidi;
3037 err = snd_rawmidi_new(chip->card, "MyMIDI", 3117 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3038 if (err < 0) 3118 if (err < 0)
3039 return err; 3119 return err;
3040 rmidi->private_data = chip; 3120 rmidi->private_data = chip;
3041 strcpy(rmidi->name, "My MIDI"); 3121 strcpy(rmidi->name, "My MIDI");
3042 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTP 3122 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3043 SNDRV_RAWMIDI_INFO_INPU 3123 SNDRV_RAWMIDI_INFO_INPUT |
3044 SNDRV_RAWMIDI_INFO_DUPL 3124 SNDRV_RAWMIDI_INFO_DUPLEX;
3045 3125
3046 The first argument is the card pointer, the s 3126 The first argument is the card pointer, the second argument is the ID
3047 string. 3127 string.
3048 3128
3049 The third argument is the index of this compo 3129 The third argument is the index of this component. You can create up to
3050 8 rawmidi devices. 3130 8 rawmidi devices.
3051 3131
3052 The fourth and fifth arguments are the number 3132 The fourth and fifth arguments are the number of output and input
3053 substreams, respectively, of this device (a s 3133 substreams, respectively, of this device (a substream is the equivalent
3054 of a MIDI port). 3134 of a MIDI port).
3055 3135
3056 Set the ``info_flags`` field to specify the c 3136 Set the ``info_flags`` field to specify the capabilities of the
3057 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if 3137 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3058 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if 3138 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3059 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` 3139 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3060 output and input at the same time. 3140 output and input at the same time.
3061 3141
3062 After the rawmidi device is created, you need 3142 After the rawmidi device is created, you need to set the operators
3063 (callbacks) for each substream. There are hel 3143 (callbacks) for each substream. There are helper functions to set the
3064 operators for all the substreams of a device: !! 3144 operators for all the substreams of a device:
>> 3145
>> 3146 ::
3065 3147
3066 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_ST 3148 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3067 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_ST 3149 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3068 3150
3069 The operators are usually defined like this:: !! 3151 The operators are usually defined like this:
>> 3152
>> 3153 ::
3070 3154
3071 static struct snd_rawmidi_ops snd_mymidi_ou 3155 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3072 .open = snd_mymidi_output_open, 3156 .open = snd_mymidi_output_open,
3073 .close = snd_mymidi_output_close, 3157 .close = snd_mymidi_output_close,
3074 .trigger = snd_mymidi_output_trigge 3158 .trigger = snd_mymidi_output_trigger,
3075 }; 3159 };
3076 3160
3077 These callbacks are explained in the `RawMIDI 3161 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3078 3162
3079 If there are more than one substream, you sho 3163 If there are more than one substream, you should give a unique name to
3080 each of them:: !! 3164 each of them:
>> 3165
>> 3166 ::
3081 3167
3082 struct snd_rawmidi_substream *substream; 3168 struct snd_rawmidi_substream *substream;
3083 list_for_each_entry(substream, 3169 list_for_each_entry(substream,
3084 &rmidi->streams[SNDRV_R 3170 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3085 list { 3171 list {
3086 sprintf(substream->name, "My MIDI P 3172 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3087 } 3173 }
3088 /* same for SNDRV_RAWMIDI_STREAM_INPUT */ 3174 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3089 3175
3090 RawMIDI Callbacks 3176 RawMIDI Callbacks
3091 ----------------- 3177 -----------------
3092 3178
3093 In all the callbacks, the private data that y 3179 In all the callbacks, the private data that you've set for the rawmidi
3094 device can be accessed as ``substream->rmidi- 3180 device can be accessed as ``substream->rmidi->private_data``.
3095 3181
3096 If there is more than one port, your callback 3182 If there is more than one port, your callbacks can determine the port
3097 index from the struct snd_rawmidi_substream d 3183 index from the struct snd_rawmidi_substream data passed to each
3098 callback:: !! 3184 callback:
>> 3185
>> 3186 ::
3099 3187
3100 struct snd_rawmidi_substream *substream; 3188 struct snd_rawmidi_substream *substream;
3101 int index = substream->number; 3189 int index = substream->number;
3102 3190
3103 RawMIDI open callback 3191 RawMIDI open callback
3104 ~~~~~~~~~~~~~~~~~~~~~ 3192 ~~~~~~~~~~~~~~~~~~~~~
3105 3193
3106 :: 3194 ::
3107 3195
3108 static int snd_xxx_open(struct snd_rawm 3196 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3109 3197
3110 3198
3111 This is called when a substream is opened. Yo 3199 This is called when a substream is opened. You can initialize the
3112 hardware here, but you shouldn't start transm 3200 hardware here, but you shouldn't start transmitting/receiving data yet.
3113 3201
3114 RawMIDI close callback 3202 RawMIDI close callback
3115 ~~~~~~~~~~~~~~~~~~~~~~ 3203 ~~~~~~~~~~~~~~~~~~~~~~
3116 3204
3117 :: 3205 ::
3118 3206
3119 static int snd_xxx_close(struct snd_raw 3207 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3120 3208
3121 Guess what. 3209 Guess what.
3122 3210
3123 The ``open`` and ``close`` callbacks of a raw 3211 The ``open`` and ``close`` callbacks of a rawmidi device are
3124 serialized with a mutex, and can sleep. 3212 serialized with a mutex, and can sleep.
3125 3213
3126 Rawmidi trigger callback for output substream 3214 Rawmidi trigger callback for output substreams
3127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3128 3216
3129 :: 3217 ::
3130 3218
3131 static void snd_xxx_output_trigger(stru 3219 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3132 3220
3133 3221
3134 This is called with a nonzero ``up`` paramete 3222 This is called with a nonzero ``up`` parameter when there is some data
3135 in the substream buffer that must be transmit 3223 in the substream buffer that must be transmitted.
3136 3224
3137 To read data from the buffer, call 3225 To read data from the buffer, call
3138 :c:func:`snd_rawmidi_transmit_peek()`. It wil 3226 :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3139 of bytes that have been read; this will be le 3227 of bytes that have been read; this will be less than the number of bytes
3140 requested when there are no more data in the 3228 requested when there are no more data in the buffer. After the data have
3141 been transmitted successfully, call 3229 been transmitted successfully, call
3142 :c:func:`snd_rawmidi_transmit_ack()` to remov 3230 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3143 substream buffer:: !! 3231 substream buffer:
>> 3232
>> 3233 ::
3144 3234
3145 unsigned char data; 3235 unsigned char data;
3146 while (snd_rawmidi_transmit_peek(substream, 3236 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3147 if (snd_mychip_try_to_transmit(data 3237 if (snd_mychip_try_to_transmit(data))
3148 snd_rawmidi_transmit_ack(su 3238 snd_rawmidi_transmit_ack(substream, 1);
3149 else 3239 else
3150 break; /* hardware FIFO ful 3240 break; /* hardware FIFO full */
3151 } 3241 }
3152 3242
3153 If you know beforehand that the hardware will 3243 If you know beforehand that the hardware will accept data, you can use
3154 the :c:func:`snd_rawmidi_transmit()` function 3244 the :c:func:`snd_rawmidi_transmit()` function which reads some
3155 data and removes them from the buffer at once !! 3245 data and removes them from the buffer at once:
>> 3246
>> 3247 ::
3156 3248
3157 while (snd_mychip_transmit_possible()) { 3249 while (snd_mychip_transmit_possible()) {
3158 unsigned char data; 3250 unsigned char data;
3159 if (snd_rawmidi_transmit(substream, 3251 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3160 break; /* no more data */ 3252 break; /* no more data */
3161 snd_mychip_transmit(data); 3253 snd_mychip_transmit(data);
3162 } 3254 }
3163 3255
3164 If you know beforehand how many bytes you can 3256 If you know beforehand how many bytes you can accept, you can use a
3165 buffer size greater than one with the ``snd_r !! 3257 buffer size greater than one with the
>> 3258 :c:func:`snd_rawmidi_transmit\*()` functions.
3166 3259
3167 The ``trigger`` callback must not sleep. If t 3260 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3168 before the substream buffer has been emptied, 3261 before the substream buffer has been emptied, you have to continue
3169 transmitting data later, either in an interru 3262 transmitting data later, either in an interrupt handler, or with a
3170 timer if the hardware doesn't have a MIDI tra 3263 timer if the hardware doesn't have a MIDI transmit interrupt.
3171 3264
3172 The ``trigger`` callback is called with a zer 3265 The ``trigger`` callback is called with a zero ``up`` parameter when
3173 the transmission of data should be aborted. 3266 the transmission of data should be aborted.
3174 3267
3175 RawMIDI trigger callback for input substreams 3268 RawMIDI trigger callback for input substreams
3176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3177 3270
3178 :: 3271 ::
3179 3272
3180 static void snd_xxx_input_trigger(struc 3273 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3181 3274
3182 3275
3183 This is called with a nonzero ``up`` paramete 3276 This is called with a nonzero ``up`` parameter to enable receiving data,
3184 or with a zero ``up`` parameter do disable re 3277 or with a zero ``up`` parameter do disable receiving data.
3185 3278
3186 The ``trigger`` callback must not sleep; the 3279 The ``trigger`` callback must not sleep; the actual reading of data
3187 from the device is usually done in an interru 3280 from the device is usually done in an interrupt handler.
3188 3281
3189 When data reception is enabled, your interrup 3282 When data reception is enabled, your interrupt handler should call
3190 :c:func:`snd_rawmidi_receive()` for all recei !! 3283 :c:func:`snd_rawmidi_receive()` for all received data:
>> 3284
>> 3285 ::
3191 3286
3192 void snd_mychip_midi_interrupt(...) 3287 void snd_mychip_midi_interrupt(...)
3193 { 3288 {
3194 while (mychip_midi_available()) { 3289 while (mychip_midi_available()) {
3195 unsigned char data; 3290 unsigned char data;
3196 data = mychip_midi_read(); 3291 data = mychip_midi_read();
3197 snd_rawmidi_receive(substre 3292 snd_rawmidi_receive(substream, &data, 1);
3198 } 3293 }
3199 } 3294 }
3200 3295
3201 3296
3202 drain callback 3297 drain callback
3203 ~~~~~~~~~~~~~~ 3298 ~~~~~~~~~~~~~~
3204 3299
3205 :: 3300 ::
3206 3301
3207 static void snd_xxx_drain(struct snd_ra 3302 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3208 3303
3209 3304
3210 This is only used with output substreams. Thi 3305 This is only used with output substreams. This function should wait
3211 until all data read from the substream buffer 3306 until all data read from the substream buffer have been transmitted.
3212 This ensures that the device can be closed an 3307 This ensures that the device can be closed and the driver unloaded
3213 without losing data. 3308 without losing data.
3214 3309
3215 This callback is optional. If you do not set 3310 This callback is optional. If you do not set ``drain`` in the struct
3216 snd_rawmidi_ops structure, ALSA will simply w !! 3311 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3217 instead. 3312 instead.
3218 3313
3219 Miscellaneous Devices 3314 Miscellaneous Devices
3220 ===================== 3315 =====================
3221 3316
3222 FM OPL3 3317 FM OPL3
3223 ------- 3318 -------
3224 3319
3225 The FM OPL3 is still used in many chips (main 3320 The FM OPL3 is still used in many chips (mainly for backward
3226 compatibility). ALSA has a nice OPL3 FM contr 3321 compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3227 is defined in ``<sound/opl3.h>``. 3322 is defined in ``<sound/opl3.h>``.
3228 3323
3229 FM registers can be directly accessed through 3324 FM registers can be directly accessed through the direct-FM API, defined
3230 in ``<sound/asound_fm.h>``. In ALSA native mo 3325 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3231 accessed through the Hardware-Dependent Devic 3326 accessed through the Hardware-Dependent Device direct-FM extension API,
3232 whereas in OSS compatible mode, FM registers 3327 whereas in OSS compatible mode, FM registers can be accessed with the
3233 OSS direct-FM compatible API in ``/dev/dmfmX` 3328 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3234 3329
3235 To create the OPL3 component, you have two fu 3330 To create the OPL3 component, you have two functions to call. The first
3236 one is a constructor for the ``opl3_t`` insta !! 3331 one is a constructor for the ``opl3_t`` instance.
>> 3332
>> 3333 ::
3237 3334
3238 struct snd_opl3 *opl3; 3335 struct snd_opl3 *opl3;
3239 snd_opl3_create(card, lport, rport, OPL3_HW 3336 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3240 integrated, &opl3); 3337 integrated, &opl3);
3241 3338
3242 The first argument is the card pointer, the s 3339 The first argument is the card pointer, the second one is the left port
3243 address, and the third is the right port addr 3340 address, and the third is the right port address. In most cases, the
3244 right port is placed at the left port + 2. 3341 right port is placed at the left port + 2.
3245 3342
3246 The fourth argument is the hardware type. 3343 The fourth argument is the hardware type.
3247 3344
3248 When the left and right ports have been alrea 3345 When the left and right ports have been already allocated by the card
3249 driver, pass non-zero to the fifth argument ( 3346 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3250 the opl3 module will allocate the specified p 3347 the opl3 module will allocate the specified ports by itself.
3251 3348
3252 When the accessing the hardware requires spec 3349 When the accessing the hardware requires special method instead of the
3253 standard I/O access, you can create opl3 inst 3350 standard I/O access, you can create opl3 instance separately with
3254 :c:func:`snd_opl3_new()`:: !! 3351 :c:func:`snd_opl3_new()`.
>> 3352
>> 3353 ::
3255 3354
3256 struct snd_opl3 *opl3; 3355 struct snd_opl3 *opl3;
3257 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3) 3356 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3258 3357
3259 Then set ``command``, ``private_data`` and `` 3358 Then set ``command``, ``private_data`` and ``private_free`` for the
3260 private access function, the private data and 3359 private access function, the private data and the destructor. The
3261 ``l_port`` and ``r_port`` are not necessarily 3360 ``l_port`` and ``r_port`` are not necessarily set. Only the command
3262 must be set properly. You can retrieve the da 3361 must be set properly. You can retrieve the data from the
3263 ``opl3->private_data`` field. 3362 ``opl3->private_data`` field.
3264 3363
3265 After creating the opl3 instance via :c:func: 3364 After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3266 call :c:func:`snd_opl3_init()` to initialize 3365 call :c:func:`snd_opl3_init()` to initialize the chip to the
3267 proper state. Note that :c:func:`snd_opl3_cre 3366 proper state. Note that :c:func:`snd_opl3_create()` always calls
3268 it internally. 3367 it internally.
3269 3368
3270 If the opl3 instance is created successfully, 3369 If the opl3 instance is created successfully, then create a hwdep device
3271 for this opl3:: !! 3370 for this opl3.
>> 3371
>> 3372 ::
3272 3373
3273 struct snd_hwdep *opl3hwdep; 3374 struct snd_hwdep *opl3hwdep;
3274 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); 3375 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3275 3376
3276 The first argument is the ``opl3_t`` instance 3377 The first argument is the ``opl3_t`` instance you created, and the
3277 second is the index number, usually 0. 3378 second is the index number, usually 0.
3278 3379
3279 The third argument is the index-offset for th 3380 The third argument is the index-offset for the sequencer client assigned
3280 to the OPL3 port. When there is an MPU401-UAR 3381 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3281 always takes 0). 3382 always takes 0).
3282 3383
3283 Hardware-Dependent Devices 3384 Hardware-Dependent Devices
3284 -------------------------- 3385 --------------------------
3285 3386
3286 Some chips need user-space access for special 3387 Some chips need user-space access for special controls or for loading
3287 the micro code. In such a case, you can creat 3388 the micro code. In such a case, you can create a hwdep
3288 (hardware-dependent) device. The hwdep API is 3389 (hardware-dependent) device. The hwdep API is defined in
3289 ``<sound/hwdep.h>``. You can find examples in 3390 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3290 ``isa/sb/sb16_csp.c``. 3391 ``isa/sb/sb16_csp.c``.
3291 3392
3292 The creation of the ``hwdep`` instance is don 3393 The creation of the ``hwdep`` instance is done via
3293 :c:func:`snd_hwdep_new()`:: !! 3394 :c:func:`snd_hwdep_new()`.
>> 3395
>> 3396 ::
3294 3397
3295 struct snd_hwdep *hw; 3398 struct snd_hwdep *hw;
3296 snd_hwdep_new(card, "My HWDEP", 0, &hw); 3399 snd_hwdep_new(card, "My HWDEP", 0, &hw);
3297 3400
3298 where the third argument is the index number. 3401 where the third argument is the index number.
3299 3402
3300 You can then pass any pointer value to the `` 3403 You can then pass any pointer value to the ``private_data``. If you
3301 assign private data, you should define a dest !! 3404 assign a private data, you should define the destructor, too. The
3302 destructor function is set in the ``private_f !! 3405 destructor function is set in the ``private_free`` field.
>> 3406
>> 3407 ::
3303 3408
3304 struct mydata *p = kmalloc(sizeof(*p), GFP_ 3409 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3305 hw->private_data = p; 3410 hw->private_data = p;
3306 hw->private_free = mydata_free; 3411 hw->private_free = mydata_free;
3307 3412
3308 and the implementation of the destructor woul !! 3413 and the implementation of the destructor would be:
>> 3414
>> 3415 ::
3309 3416
3310 static void mydata_free(struct snd_hwdep *h 3417 static void mydata_free(struct snd_hwdep *hw)
3311 { 3418 {
3312 struct mydata *p = hw->private_data 3419 struct mydata *p = hw->private_data;
3313 kfree(p); 3420 kfree(p);
3314 } 3421 }
3315 3422
3316 The arbitrary file operations can be defined 3423 The arbitrary file operations can be defined for this instance. The file
3317 operators are defined in the ``ops`` table. F 3424 operators are defined in the ``ops`` table. For example, assume that
3318 this chip needs an ioctl:: !! 3425 this chip needs an ioctl.
>> 3426
>> 3427 ::
3319 3428
3320 hw->ops.open = mydata_open; 3429 hw->ops.open = mydata_open;
3321 hw->ops.ioctl = mydata_ioctl; 3430 hw->ops.ioctl = mydata_ioctl;
3322 hw->ops.release = mydata_release; 3431 hw->ops.release = mydata_release;
3323 3432
3324 And implement the callback functions as you l 3433 And implement the callback functions as you like.
3325 3434
3326 IEC958 (S/PDIF) 3435 IEC958 (S/PDIF)
3327 --------------- 3436 ---------------
3328 3437
3329 Usually the controls for IEC958 devices are i 3438 Usually the controls for IEC958 devices are implemented via the control
3330 interface. There is a macro to compose a name 3439 interface. There is a macro to compose a name string for IEC958
3331 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` d 3440 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3332 ``<include/asound.h>``. 3441 ``<include/asound.h>``.
3333 3442
3334 There are some standard controls for IEC958 s 3443 There are some standard controls for IEC958 status bits. These controls
3335 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, 3444 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3336 fixed as 4 bytes array (value.iec958.status[x 3445 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3337 callback, you don't specify the value field f 3446 callback, you don't specify the value field for this type (the count
3338 field must be set, though). 3447 field must be set, though).
3339 3448
3340 “IEC958 Playback Con Mask” is used to ret 3449 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3341 status bits of consumer mode. Similarly, “I 3450 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3342 returns the bitmask for professional mode. Th !! 3451 returns the bitmask for professional mode. They are read-only controls,
>> 3452 and are defined as MIXER controls (iface =
>> 3453 ``SNDRV_CTL_ELEM_IFACE_MIXER``).
3343 3454
3344 Meanwhile, “IEC958 Playback Default” cont 3455 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3345 setting the current default IEC958 bits. !! 3456 setting the current default IEC958 bits. Note that this one is usually
3346 !! 3457 defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3347 Due to historical reasons, both variants of t !! 3458 although in some places it's defined as a MIXER control.
3348 Playback Default controls can be implemented <<
3349 ``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL <<
3350 Drivers should expose the mask and default on <<
3351 3459
3352 In addition, you can define the control switc 3460 In addition, you can define the control switches to enable/disable or to
3353 set the raw bit mode. The implementation will 3461 set the raw bit mode. The implementation will depend on the chip, but
3354 the control should be named as “IEC958 xxx 3462 the control should be named as “IEC958 xxx”, preferably using the
3355 :c:func:`SNDRV_CTL_NAME_IEC958()` macro. 3463 :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3356 3464
3357 You can find several cases, for example, ``pc 3465 You can find several cases, for example, ``pci/emu10k1``,
3358 ``pci/ice1712``, or ``pci/cmipci.c``. 3466 ``pci/ice1712``, or ``pci/cmipci.c``.
3359 3467
3360 Buffer and Memory Management 3468 Buffer and Memory Management
3361 ============================ 3469 ============================
3362 3470
3363 Buffer Types 3471 Buffer Types
3364 ------------ 3472 ------------
3365 3473
3366 ALSA provides several different buffer alloca 3474 ALSA provides several different buffer allocation functions depending on
3367 the bus and the architecture. All these have 3475 the bus and the architecture. All these have a consistent API. The
3368 allocation of physically-contiguous pages is !! 3476 allocation of physically-contiguous pages is done via
3369 :c:func:`snd_malloc_xxx_pages()` function, wh 3477 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3370 type. 3478 type.
3371 3479
3372 The allocation of pages with fallback is done !! 3480 The allocation of pages with fallback is
3373 :c:func:`snd_dma_alloc_pages_fallback()`. Thi !! 3481 :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3374 to allocate the specified number of pages, bu !! 3482 to allocate the specified pages but if the pages are not available, it
3375 available, it tries to reduce the request siz !! 3483 tries to reduce the page sizes until enough space is found.
3376 is found, down to one page. <<
3377 3484
3378 To release the pages, call the :c:func:`snd_d !! 3485 The release the pages, call :c:func:`snd_free_xxx_pages()`
3379 function. 3486 function.
3380 3487
3381 Usually, ALSA drivers try to allocate and res 3488 Usually, ALSA drivers try to allocate and reserve a large contiguous
3382 physical space at the time the module is load !! 3489 physical space at the time the module is loaded for the later use. This
3383 is called “pre-allocation”. As already wr 3490 is called “pre-allocation”. As already written, you can call the
3384 following function at PCM instance constructi !! 3491 following function at pcm instance construction time (in the case of PCI
3385 bus):: !! 3492 bus).
>> 3493
>> 3494 ::
3386 3495
3387 snd_pcm_lib_preallocate_pages_for_all(pcm, 3496 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3388 &pci- !! 3497 snd_dma_pci_data(pci), size, max);
3389 3498
3390 where ``size`` is the byte size to be pre-all !! 3499 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3391 the maximum size settable via the ``prealloc` !! 3500 the maximum size to be changed via the ``prealloc`` proc file. The
3392 allocator will try to get an area as large as 3501 allocator will try to get an area as large as possible within the
3393 given size. 3502 given size.
3394 3503
3395 The second argument (type) and the third argu 3504 The second argument (type) and the third argument (device pointer) are
3396 dependent on the bus. For normal devices, pas !! 3505 dependent on the bus. In the case of the ISA bus, pass
3397 (typically identical as ``card->dev``) to the !! 3506 :c:func:`snd_dma_isa_data()` as the third argument with
3398 ``SNDRV_DMA_TYPE_DEV`` type. !! 3507 ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3399 !! 3508 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the
3400 A continuous buffer unrelated to the !! 3509 ``snd_dma_continuous_data(GFP_KERNEL)`` device pointer, where
3401 bus can be pre-allocated with ``SNDRV_DMA_TYP !! 3510 ``GFP_KERNEL`` is the kernel allocation flag to use. For the PCI
3402 You can pass NULL to the device pointer in th !! 3511 scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with
3403 default mode implying to allocate with the `` !! 3512 ``snd_dma_pci_data(pci)`` (see the `Non-Contiguous Buffers`_
3404 If you need a restricted (lower) address, set !! 3513 section).
3405 bits for the device, and pass the device poin <<
3406 device memory allocations. For this type, it <<
3407 NULL to the device pointer, too, if no addres <<
3408 <<
3409 For the scatter-gather buffers, use ``SNDRV_D <<
3410 device pointer (see the `Non-Contiguous Buffe <<
3411 3514
3412 Once the buffer is pre-allocated, you can use 3515 Once the buffer is pre-allocated, you can use the allocator in the
3413 ``hw_params`` callback:: !! 3516 ``hw_params`` callback:
>> 3517
>> 3518 ::
3414 3519
3415 snd_pcm_lib_malloc_pages(substream, size); 3520 snd_pcm_lib_malloc_pages(substream, size);
3416 3521
3417 Note that you have to pre-allocate to use thi 3522 Note that you have to pre-allocate to use this function.
3418 3523
3419 But most drivers use the "managed buffer allo <<
3420 of manual allocation and release. <<
3421 This is done by calling :c:func:`snd_pcm_set_ <<
3422 instead of :c:func:`snd_pcm_lib_preallocate_p <<
3423 <<
3424 snd_pcm_set_managed_buffer_all(pcm, SNDRV_D <<
3425 &pci->dev, s <<
3426 <<
3427 where the passed arguments are identical for <<
3428 The difference in the managed mode is that PC <<
3429 :c:func:`snd_pcm_lib_malloc_pages()` internal <<
3430 the PCM ``hw_params`` callback, and call :c:f <<
3431 after the PCM ``hw_free`` callback automatica <<
3432 doesn't have to call these functions explicit <<
3433 longer. This allows many drivers to have NUL <<
3434 ``hw_free`` entries. <<
3435 <<
3436 External Hardware Buffers 3524 External Hardware Buffers
3437 ------------------------- 3525 -------------------------
3438 3526
3439 Some chips have their own hardware buffers an !! 3527 Some chips have their own hardware buffers and the DMA transfer from the
3440 host memory is not available. In such a case, 3528 host memory is not available. In such a case, you need to either 1)
3441 copy/set the audio data directly to the exter 3529 copy/set the audio data directly to the external hardware buffer, or 2)
3442 make an intermediate buffer and copy/set the 3530 make an intermediate buffer and copy/set the data from it to the
3443 external hardware buffer in interrupts (or in 3531 external hardware buffer in interrupts (or in tasklets, preferably).
3444 3532
3445 The first case works fine if the external har 3533 The first case works fine if the external hardware buffer is large
3446 enough. This method doesn't need any extra bu 3534 enough. This method doesn't need any extra buffers and thus is more
3447 efficient. You need to define the ``copy`` ca !! 3535 effective. You need to define the ``copy_user`` and ``copy_kernel``
3448 for the data transfer, in addition to the ``f !! 3536 callbacks for the data transfer, in addition to ``fill_silence``
3449 callback for playback. However, there is a dr 3537 callback for playback. However, there is a drawback: it cannot be
3450 mmapped. The examples are GUS's GF1 PCM or em 3538 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3451 3539
3452 The second case allows for mmap on the buffer 3540 The second case allows for mmap on the buffer, although you have to
3453 handle an interrupt or a tasklet to transfer 3541 handle an interrupt or a tasklet to transfer the data from the
3454 intermediate buffer to the hardware buffer. Y 3542 intermediate buffer to the hardware buffer. You can find an example in
3455 the vxpocket driver. 3543 the vxpocket driver.
3456 3544
3457 Another case is when the chip uses a PCI memo 3545 Another case is when the chip uses a PCI memory-map region for the
3458 buffer instead of the host memory. In this ca 3546 buffer instead of the host memory. In this case, mmap is available only
3459 on certain architectures like the Intel one. 3547 on certain architectures like the Intel one. In non-mmap mode, the data
3460 cannot be transferred as in the normal way. T 3548 cannot be transferred as in the normal way. Thus you need to define the
3461 ``copy`` and ``fill_silence`` callbacks as we !! 3549 ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3462 as in the cases above. Examples are found in !! 3550 as in the cases above. The examples are found in ``rme32.c`` and
3463 ``rme96.c``. 3551 ``rme96.c``.
3464 3552
3465 The implementation of the ``copy`` and !! 3553 The implementation of the ``copy_user``, ``copy_kernel`` and
3466 ``silence`` callbacks depends upon whether th 3554 ``silence`` callbacks depends upon whether the hardware supports
3467 interleaved or non-interleaved samples. The ` !! 3555 interleaved or non-interleaved samples. The ``copy_user`` callback is
3468 defined like below, a bit differently dependi !! 3556 defined like below, a bit differently depending whether the direction
3469 is playback or capture:: !! 3557 is playback or capture:
>> 3558
>> 3559 ::
3470 3560
3471 static int playback_copy(struct snd_pcm_sub !! 3561 static int playback_copy_user(struct snd_pcm_substream *substream,
3472 int channel, unsigned long pos 3562 int channel, unsigned long pos,
3473 struct iov_iter *src, unsigned !! 3563 void __user *src, unsigned long count);
3474 static int capture_copy(struct snd_pcm_subs !! 3564 static int capture_copy_user(struct snd_pcm_substream *substream,
3475 int channel, unsigned long pos 3565 int channel, unsigned long pos,
3476 struct iov_iter *dst, unsigned !! 3566 void __user *dst, unsigned long count);
3477 3567
3478 In the case of interleaved samples, the secon 3568 In the case of interleaved samples, the second argument (``channel``) is
3479 not used. The third argument (``pos``) specif !! 3569 not used. The third argument (``pos``) points the current position
>> 3570 offset in bytes.
3480 3571
3481 The meaning of the fourth argument is differe 3572 The meaning of the fourth argument is different between playback and
3482 capture. For playback, it holds the source da 3573 capture. For playback, it holds the source data pointer, and for
3483 capture, it's the destination data pointer. 3574 capture, it's the destination data pointer.
3484 3575
3485 The last argument is the number of bytes to b 3576 The last argument is the number of bytes to be copied.
3486 3577
3487 What you have to do in this callback is again 3578 What you have to do in this callback is again different between playback
3488 and capture directions. In the playback case, 3579 and capture directions. In the playback case, you copy the given amount
3489 of data (``count``) at the specified pointer 3580 of data (``count``) at the specified pointer (``src``) to the specified
3490 offset (``pos``) in the hardware buffer. When !! 3581 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3491 way, the copy would look like:: !! 3582 way, the copy would be like:
3492 3583
3493 my_memcpy_from_iter(my_buffer + pos, src, c !! 3584 ::
>> 3585
>> 3586 my_memcpy_from_user(my_buffer + pos, src, count);
3494 3587
3495 For the capture direction, you copy the given 3588 For the capture direction, you copy the given amount of data (``count``)
3496 at the specified offset (``pos``) in the hard !! 3589 at the specified offset (``pos``) on the hardware buffer to the
3497 specified pointer (``dst``):: !! 3590 specified pointer (``dst``).
>> 3591
>> 3592 ::
3498 3593
3499 my_memcpy_to_iter(dst, my_buffer + pos, cou !! 3594 my_memcpy_to_user(dst, my_buffer + pos, count);
3500 3595
3501 The given ``src`` or ``dst`` a struct iov_ite !! 3596 Here the functions are named as ``from_user`` and ``to_user`` because
3502 pointer and the size. Use the existing helpe !! 3597 it's the user-space buffer that is passed to these callbacks. That
3503 data as defined in ``linux/uio.h``. !! 3598 is, the callback is supposed to copy from/to the user-space data
>> 3599 directly to/from the hardware buffer.
3504 3600
3505 Careful readers might notice that these callb 3601 Careful readers might notice that these callbacks receive the
3506 arguments in bytes, not in frames like other 3602 arguments in bytes, not in frames like other callbacks. It's because
3507 this makes coding easier like in the examples !! 3603 it would make coding easier like the examples above, and also it makes
3508 it easier to unify both the interleaved and n !! 3604 easier to unify both the interleaved and non-interleaved cases, as
3509 explained below. !! 3605 explained in the following.
3510 3606
3511 In the case of non-interleaved samples, the i 3607 In the case of non-interleaved samples, the implementation will be a bit
3512 more complicated. The callback is called for !! 3608 more complicated. The callback is called for each channel, passed by
3513 the second argument, so in total it's called !! 3609 the second argument, so totally it's called for N-channels times per
>> 3610 transfer.
>> 3611
>> 3612 The meaning of other arguments are almost same as the interleaved
>> 3613 case. The callback is supposed to copy the data from/to the given
>> 3614 user-space buffer, but only for the given channel. For the detailed
>> 3615 implementations, please check ``isa/gus/gus_pcm.c`` or
>> 3616 "pci/rme9652/rme9652.c" as examples.
>> 3617
>> 3618 The above callbacks are the copy from/to the user-space buffer. There
>> 3619 are some cases where we want copy from/to the kernel-space buffer
>> 3620 instead. In such a case, ``copy_kernel`` callback is called. It'd
>> 3621 look like:
>> 3622
>> 3623 ::
>> 3624
>> 3625 static int playback_copy_kernel(struct snd_pcm_substream *substream,
>> 3626 int channel, unsigned long pos,
>> 3627 void *src, unsigned long count);
>> 3628 static int capture_copy_kernel(struct snd_pcm_substream *substream,
>> 3629 int channel, unsigned long pos,
>> 3630 void *dst, unsigned long count);
>> 3631
>> 3632 As found easily, the only difference is that the buffer pointer is
>> 3633 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
>> 3634 in the fourth argument. Correspondingly, the implementation would be
>> 3635 a version without the user-copy, such as:
>> 3636
>> 3637 ::
3514 3638
3515 The meaning of the other arguments are almost !! 3639 my_memcpy(my_buffer + pos, src, count);
3516 interleaved case. The callback is supposed t <<
3517 the given user-space buffer, but only for the <<
3518 details, please check ``isa/gus/gus_pcm.c`` o <<
3519 as examples. <<
3520 3640
3521 Usually for the playback, another callback `` 3641 Usually for the playback, another callback ``fill_silence`` is
3522 defined. It's implemented in a similar way a 3642 defined. It's implemented in a similar way as the copy callbacks
3523 above:: !! 3643 above:
>> 3644
>> 3645 ::
3524 3646
3525 static int silence(struct snd_pcm_substream 3647 static int silence(struct snd_pcm_substream *substream, int channel,
3526 unsigned long pos, unsig 3648 unsigned long pos, unsigned long count);
3527 3649
3528 The meanings of arguments are the same as in !! 3650 The meanings of arguments are the same as in the ``copy_user`` and
3529 although there is no buffer pointer !! 3651 ``copy_kernel`` callbacks, although there is no buffer pointer
3530 argument. In the case of interleaved samples, 3652 argument. In the case of interleaved samples, the channel argument has
3531 no meaning, as for the ``copy`` callback. !! 3653 no meaning, as well as on ``copy_*`` callbacks.
3532 3654
3533 The role of the ``fill_silence`` callback is !! 3655 The role of ``fill_silence`` callback is to set the given amount
3534 (``count``) of silence data at the specified !! 3656 (``count``) of silence data at the specified offset (``pos``) on the
3535 hardware buffer. Suppose that the data format 3657 hardware buffer. Suppose that the data format is signed (that is, the
3536 silent-data is 0), and the implementation usi 3658 silent-data is 0), and the implementation using a memset-like function
3537 would look like:: !! 3659 would be like:
>> 3660
>> 3661 ::
3538 3662
3539 my_memset(my_buffer + pos, 0, count); 3663 my_memset(my_buffer + pos, 0, count);
3540 3664
3541 In the case of non-interleaved samples, again 3665 In the case of non-interleaved samples, again, the implementation
3542 becomes a bit more complicated, as it's calle !! 3666 becomes a bit more complicated, as it's called N-times per transfer
3543 for each channel. See, for example, ``isa/gus 3667 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3544 3668
3545 Non-Contiguous Buffers 3669 Non-Contiguous Buffers
3546 ---------------------- 3670 ----------------------
3547 3671
3548 If your hardware supports a page table as in !! 3672 If your hardware supports the page table as in emu10k1 or the buffer
3549 descriptors as in via82xx, you can use scatte !! 3673 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3550 provides an interface for handling SG-buffers 3674 provides an interface for handling SG-buffers. The API is provided in
3551 ``<sound/pcm.h>``. 3675 ``<sound/pcm.h>``.
3552 3676
3553 For creating the SG-buffer handler, call 3677 For creating the SG-buffer handler, call
3554 :c:func:`snd_pcm_set_managed_buffer()` or !! 3678 :c:func:`snd_pcm_lib_preallocate_pages()` or
3555 :c:func:`snd_pcm_set_managed_buffer_all()` wi !! 3679 :c:func:`snd_pcm_lib_preallocate_pages_for_all()` with
3556 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM construc !! 3680 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3557 pre-allocations. You need to pass ``&pci->dev !! 3681 pre-allocator. You need to pass ``snd_dma_pci_data(pci)``, where pci is
3558 the struct pci_dev pointer of the chip as wel !! 3682 the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3559 !! 3683 well. The ``struct snd_sg_buf`` instance is created as
3560 snd_pcm_set_managed_buffer_all(pcm, SNDRV_D !! 3684 ``substream->dma_private``. You can cast the pointer like:
3561 &pci->dev, s <<
3562 3685
3563 The ``struct snd_sg_buf`` instance is created !! 3686 ::
3564 ``substream->dma_private`` in turn. You can c <<
3565 3687
3566 struct snd_sg_buf *sgbuf = (struct snd_sg_b 3688 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3567 3689
3568 Then in the :c:func:`snd_pcm_lib_malloc_pages !! 3690 Then call :c:func:`snd_pcm_lib_malloc_pages()` in the ``hw_params``
>> 3691 callback as well as in the case of normal PCI buffer. The SG-buffer
3569 handler will allocate the non-contiguous kern 3692 handler will allocate the non-contiguous kernel pages of the given size
3570 and map them as virtually contiguous memory. !! 3693 and map them onto the virtually contiguous memory. The virtual pointer
3571 is addressed via runtime->dma_area. The physi !! 3694 is addressed in runtime->dma_area. The physical address
3572 (``runtime->dma_addr``) is set to zero, becau 3695 (``runtime->dma_addr``) is set to zero, because the buffer is
3573 physically non-contiguous. The physical addre 3696 physically non-contiguous. The physical address table is set up in
3574 ``sgbuf->table``. You can get the physical ad 3697 ``sgbuf->table``. You can get the physical address at a certain offset
3575 via :c:func:`snd_pcm_sgbuf_get_addr()`. 3698 via :c:func:`snd_pcm_sgbuf_get_addr()`.
3576 3699
3577 If you need to release the SG-buffer data exp !! 3700 When a SG-handler is used, you need to set
3578 standard API function :c:func:`snd_pcm_lib_fr !! 3701 :c:func:`snd_pcm_sgbuf_ops_page()` as the ``page`` callback. (See
>> 3702 `page callback`_ section.)
>> 3703
>> 3704 To release the data, call :c:func:`snd_pcm_lib_free_pages()` in
>> 3705 the ``hw_free`` callback as usual.
3579 3706
3580 Vmalloc'ed Buffers 3707 Vmalloc'ed Buffers
3581 ------------------ 3708 ------------------
3582 3709
3583 It's possible to use a buffer allocated via : 3710 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3584 example, for an intermediate buffer. !! 3711 example, for an intermediate buffer. Since the allocated pages are not
3585 You can simply allocate it via the standard !! 3712 contiguous, you need to set the ``page`` callback to obtain the physical
3586 :c:func:`snd_pcm_lib_malloc_pages()` and co. !! 3713 address at every offset.
3587 buffer preallocation with ``SNDRV_DMA_TYPE_VM !! 3714
3588 !! 3715 The implementation of ``page`` callback would be like this:
3589 snd_pcm_set_managed_buffer_all(pcm, SNDRV_D !! 3716
3590 NULL, 0, 0); !! 3717 ::
3591 !! 3718
3592 NULL is passed as the device pointer argument !! 3719 #include <linux/vmalloc.h>
3593 that default pages (GFP_KERNEL and GFP_HIGHME !! 3720
3594 allocated. !! 3721 /* get the physical page pointer on the given offset */
3595 !! 3722 static struct page *mychip_page(struct snd_pcm_substream *substream,
3596 Also, note that zero is passed as both the si !! 3723 unsigned long offset)
3597 argument here. Since each vmalloc call shoul !! 3724 {
3598 we don't need to pre-allocate the buffers lik !! 3725 void *pageptr = substream->runtime->dma_area + offset;
3599 pages. !! 3726 return vmalloc_to_page(pageptr);
>> 3727 }
3600 3728
3601 Proc Interface 3729 Proc Interface
3602 ============== 3730 ==============
3603 3731
3604 ALSA provides an easy interface for procfs. T 3732 ALSA provides an easy interface for procfs. The proc files are very
3605 useful for debugging. I recommend you set up 3733 useful for debugging. I recommend you set up proc files if you write a
3606 driver and want to get a running status or re 3734 driver and want to get a running status or register dumps. The API is
3607 found in ``<sound/info.h>``. 3735 found in ``<sound/info.h>``.
3608 3736
3609 To create a proc file, call :c:func:`snd_card !! 3737 To create a proc file, call :c:func:`snd_card_proc_new()`.
>> 3738
>> 3739 ::
3610 3740
3611 struct snd_info_entry *entry; 3741 struct snd_info_entry *entry;
3612 int err = snd_card_proc_new(card, "my-file" 3742 int err = snd_card_proc_new(card, "my-file", &entry);
3613 3743
3614 where the second argument specifies the name 3744 where the second argument specifies the name of the proc file to be
3615 created. The above example will create a file 3745 created. The above example will create a file ``my-file`` under the
3616 card directory, e.g. ``/proc/asound/card0/my- 3746 card directory, e.g. ``/proc/asound/card0/my-file``.
3617 3747
3618 Like other components, the proc entry created 3748 Like other components, the proc entry created via
3619 :c:func:`snd_card_proc_new()` will be registe 3749 :c:func:`snd_card_proc_new()` will be registered and released
3620 automatically in the card registration and re 3750 automatically in the card registration and release functions.
3621 3751
3622 When the creation is successful, the function 3752 When the creation is successful, the function stores a new instance in
3623 the pointer given in the third argument. It i 3753 the pointer given in the third argument. It is initialized as a text
3624 proc file for read only. To use this proc fil 3754 proc file for read only. To use this proc file as a read-only text file
3625 as-is, set the read callback with private dat !! 3755 as it is, set the read callback with a private data via
3626 :c:func:`snd_info_set_text_ops()`:: !! 3756 :c:func:`snd_info_set_text_ops()`.
>> 3757
>> 3758 ::
3627 3759
3628 snd_info_set_text_ops(entry, chip, my_proc_ 3760 snd_info_set_text_ops(entry, chip, my_proc_read);
3629 3761
3630 where the second argument (``chip``) is the p 3762 where the second argument (``chip``) is the private data to be used in
3631 the callback. The third parameter specifies t !! 3763 the callbacks. The third parameter specifies the read buffer size and
3632 the fourth (``my_proc_read``) is the callback 3764 the fourth (``my_proc_read``) is the callback function, which is
3633 defined like:: !! 3765 defined like
>> 3766
>> 3767 ::
3634 3768
3635 static void my_proc_read(struct snd_info_en 3769 static void my_proc_read(struct snd_info_entry *entry,
3636 struct snd_info_bu 3770 struct snd_info_buffer *buffer);
3637 3771
3638 In the read callback, use :c:func:`snd_iprint 3772 In the read callback, use :c:func:`snd_iprintf()` for output
3639 strings, which works just like normal :c:func 3773 strings, which works just like normal :c:func:`printf()`. For
3640 example:: !! 3774 example,
>> 3775
>> 3776 ::
3641 3777
3642 static void my_proc_read(struct snd_info_en 3778 static void my_proc_read(struct snd_info_entry *entry,
3643 struct snd_info_bu 3779 struct snd_info_buffer *buffer)
3644 { 3780 {
3645 struct my_chip *chip = entry->priva 3781 struct my_chip *chip = entry->private_data;
3646 3782
3647 snd_iprintf(buffer, "This is my chi 3783 snd_iprintf(buffer, "This is my chip!\n");
3648 snd_iprintf(buffer, "Port = %ld\n", 3784 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3649 } 3785 }
3650 3786
3651 The file permissions can be changed afterward !! 3787 The file permissions can be changed afterwards. As default, it's set as
3652 read only for all users. If you want to add w 3788 read only for all users. If you want to add write permission for the
3653 user (root by default), do as follows:: !! 3789 user (root as default), do as follows:
>> 3790
>> 3791 ::
3654 3792
3655 entry->mode = S_IFREG | S_IRUGO | S_IWUSR; 3793 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3656 3794
3657 and set the write buffer size and the callbac !! 3795 and set the write buffer size and the callback
>> 3796
>> 3797 ::
3658 3798
3659 entry->c.text.write = my_proc_write; 3799 entry->c.text.write = my_proc_write;
3660 3800
3661 In the write callback, you can use :c:func:`s !! 3801 For the write callback, you can use :c:func:`snd_info_get_line()`
3662 to get a text line, and :c:func:`snd_info_get 3802 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3663 a string from the line. Some examples are fou 3803 a string from the line. Some examples are found in
3664 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_ 3804 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3665 3805
3666 For a raw-data proc-file, set the attributes !! 3806 For a raw-data proc-file, set the attributes as follows:
>> 3807
>> 3808 ::
3667 3809
3668 static const struct snd_info_entry_ops my_f !! 3810 static struct snd_info_entry_ops my_file_io_ops = {
3669 .read = my_file_io_read, 3811 .read = my_file_io_read,
3670 }; 3812 };
3671 3813
3672 entry->content = SNDRV_INFO_CONTENT_DATA; 3814 entry->content = SNDRV_INFO_CONTENT_DATA;
3673 entry->private_data = chip; 3815 entry->private_data = chip;
3674 entry->c.ops = &my_file_io_ops; 3816 entry->c.ops = &my_file_io_ops;
3675 entry->size = 4096; 3817 entry->size = 4096;
3676 entry->mode = S_IFREG | S_IRUGO; 3818 entry->mode = S_IFREG | S_IRUGO;
3677 3819
3678 For raw data, ``size`` field must be set prop !! 3820 For the raw data, ``size`` field must be set properly. This specifies
3679 the maximum size of the proc file access. 3821 the maximum size of the proc file access.
3680 3822
3681 The read/write callbacks of raw mode are more 3823 The read/write callbacks of raw mode are more direct than the text mode.
3682 You need to use a low-level I/O functions suc 3824 You need to use a low-level I/O functions such as
3683 :c:func:`copy_from_user()` and :c:func:`copy_ !! 3825 :c:func:`copy_from/to_user()` to transfer the data.
3684 data:: !! 3826
>> 3827 ::
3685 3828
3686 static ssize_t my_file_io_read(struct snd_i 3829 static ssize_t my_file_io_read(struct snd_info_entry *entry,
3687 void *file_priv 3830 void *file_private_data,
3688 struct file *fi 3831 struct file *file,
3689 char *buf, 3832 char *buf,
3690 size_t count, 3833 size_t count,
3691 loff_t pos) 3834 loff_t pos)
3692 { 3835 {
3693 if (copy_to_user(buf, local_data + 3836 if (copy_to_user(buf, local_data + pos, count))
3694 return -EFAULT; 3837 return -EFAULT;
3695 return count; 3838 return count;
3696 } 3839 }
3697 3840
3698 If the size of the info entry has been set up 3841 If the size of the info entry has been set up properly, ``count`` and
3699 ``pos`` are guaranteed to fit within 0 and th 3842 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3700 have to check the range in the callbacks unle 3843 have to check the range in the callbacks unless any other condition is
3701 required. 3844 required.
3702 3845
3703 Power Management 3846 Power Management
3704 ================ 3847 ================
3705 3848
3706 If the chip is supposed to work with suspend/ 3849 If the chip is supposed to work with suspend/resume functions, you need
3707 to add power-management code to the driver. T 3850 to add power-management code to the driver. The additional code for
3708 power-management should be ifdef-ed with ``CO !! 3851 power-management should be ifdef-ed with ``CONFIG_PM``.
3709 with __maybe_unused attribute; otherwise the <<
3710 3852
3711 If the driver *fully* supports suspend/resume 3853 If the driver *fully* supports suspend/resume that is, the device can be
3712 properly resumed to its state when suspend wa 3854 properly resumed to its state when suspend was called, you can set the
3713 ``SNDRV_PCM_INFO_RESUME`` flag in the PCM inf !! 3855 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3714 possible when the registers of the chip can b 3856 possible when the registers of the chip can be safely saved and restored
3715 to RAM. If this is set, the trigger callback 3857 to RAM. If this is set, the trigger callback is called with
3716 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume 3858 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3717 3859
3718 Even if the driver doesn't support PM fully b 3860 Even if the driver doesn't support PM fully but partial suspend/resume
3719 is still possible, it's still worthy to imple 3861 is still possible, it's still worthy to implement suspend/resume
3720 callbacks. In such a case, applications would 3862 callbacks. In such a case, applications would reset the status by
3721 calling :c:func:`snd_pcm_prepare()` and resta 3863 calling :c:func:`snd_pcm_prepare()` and restart the stream
3722 appropriately. Hence, you can define suspend/ 3864 appropriately. Hence, you can define suspend/resume callbacks below but
3723 don't set the ``SNDRV_PCM_INFO_RESUME`` info !! 3865 don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3724 3866
3725 Note that the trigger with SUSPEND can always 3867 Note that the trigger with SUSPEND can always be called when
3726 :c:func:`snd_pcm_suspend_all()` is called, re 3868 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3727 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME` 3869 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3728 behavior of :c:func:`snd_pcm_resume()`. (Thus 3870 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3729 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to 3871 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3730 callback when no ``SNDRV_PCM_INFO_RESUME`` fl 3872 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3731 to keep it for compatibility reasons.) 3873 to keep it for compatibility reasons.)
3732 3874
3733 The driver needs to define the !! 3875 In the earlier version of ALSA drivers, a common power-management layer
>> 3876 was provided, but it has been removed. The driver needs to define the
3734 suspend/resume hooks according to the bus the 3877 suspend/resume hooks according to the bus the device is connected to. In
3735 the case of PCI drivers, the callbacks look l !! 3878 the case of PCI drivers, the callbacks look like below:
3736 3879
3737 static int __maybe_unused snd_my_suspend(st !! 3880 ::
>> 3881
>> 3882 #ifdef CONFIG_PM
>> 3883 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
3738 { 3884 {
3739 .... /* do things for suspend */ 3885 .... /* do things for suspend */
3740 return 0; 3886 return 0;
3741 } 3887 }
3742 static int __maybe_unused snd_my_resume(str !! 3888 static int snd_my_resume(struct pci_dev *pci)
3743 { 3889 {
3744 .... /* do things for suspend */ 3890 .... /* do things for suspend */
3745 return 0; 3891 return 0;
3746 } 3892 }
>> 3893 #endif
3747 3894
3748 The scheme of the real suspend job is as foll !! 3895 The scheme of the real suspend job is as follows.
3749 3896
3750 1. Retrieve the card and the chip data. 3897 1. Retrieve the card and the chip data.
3751 3898
3752 2. Call :c:func:`snd_power_change_state()` wi 3899 2. Call :c:func:`snd_power_change_state()` with
3753 ``SNDRV_CTL_POWER_D3hot`` to change the po 3900 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3754 3901
3755 3. If AC97 codecs are used, call :c:func:`snd !! 3902 3. Call :c:func:`snd_pcm_suspend_all()` to suspend the running
>> 3903 PCM streams.
>> 3904
>> 3905 4. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3756 each codec. 3906 each codec.
3757 3907
3758 4. Save the register values if necessary. !! 3908 5. Save the register values if necessary.
>> 3909
>> 3910 6. Stop the hardware if necessary.
>> 3911
>> 3912 7. Disable the PCI device by calling
>> 3913 :c:func:`pci_disable_device()`. Then, call
>> 3914 :c:func:`pci_save_state()` at last.
3759 3915
3760 5. Stop the hardware if necessary. !! 3916 A typical code would be like:
3761 3917
3762 Typical code would look like:: !! 3918 ::
3763 3919
3764 static int __maybe_unused mychip_suspend(st !! 3920 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
3765 { 3921 {
3766 /* (1) */ 3922 /* (1) */
3767 struct snd_card *card = dev_get_drv !! 3923 struct snd_card *card = pci_get_drvdata(pci);
3768 struct mychip *chip = card->private 3924 struct mychip *chip = card->private_data;
3769 /* (2) */ 3925 /* (2) */
3770 snd_power_change_state(card, SNDRV_ 3926 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3771 /* (3) */ 3927 /* (3) */
3772 snd_ac97_suspend(chip->ac97); !! 3928 snd_pcm_suspend_all(chip->pcm);
3773 /* (4) */ 3929 /* (4) */
3774 snd_mychip_save_registers(chip); !! 3930 snd_ac97_suspend(chip->ac97);
3775 /* (5) */ 3931 /* (5) */
>> 3932 snd_mychip_save_registers(chip);
>> 3933 /* (6) */
3776 snd_mychip_stop_hardware(chip); 3934 snd_mychip_stop_hardware(chip);
>> 3935 /* (7) */
>> 3936 pci_disable_device(pci);
>> 3937 pci_save_state(pci);
3777 return 0; 3938 return 0;
3778 } 3939 }
3779 3940
3780 3941
3781 The scheme of the real resume job is as follo !! 3942 The scheme of the real resume job is as follows.
3782 3943
3783 1. Retrieve the card and the chip data. 3944 1. Retrieve the card and the chip data.
3784 3945
3785 2. Re-initialize the chip. !! 3946 2. Set up PCI. First, call :c:func:`pci_restore_state()`. Then
>> 3947 enable the pci device again by calling
>> 3948 :c:func:`pci_enable_device()`. Call
>> 3949 :c:func:`pci_set_master()` if necessary, too.
>> 3950
>> 3951 3. Re-initialize the chip.
3786 3952
3787 3. Restore the saved registers if necessary. !! 3953 4. Restore the saved registers if necessary.
3788 3954
3789 4. Resume the mixer, e.g. by calling :c:func: !! 3955 5. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
3790 3956
3791 5. Restart the hardware (if any). !! 3957 6. Restart the hardware (if any).
3792 3958
3793 6. Call :c:func:`snd_power_change_state()` wi !! 3959 7. Call :c:func:`snd_power_change_state()` with
3794 ``SNDRV_CTL_POWER_D0`` to notify the proce 3960 ``SNDRV_CTL_POWER_D0`` to notify the processes.
3795 3961
3796 Typical code would look like:: !! 3962 A typical code would be like:
>> 3963
>> 3964 ::
3797 3965
3798 static int __maybe_unused mychip_resume(str !! 3966 static int mychip_resume(struct pci_dev *pci)
3799 { 3967 {
3800 /* (1) */ 3968 /* (1) */
3801 struct snd_card *card = dev_get_drv !! 3969 struct snd_card *card = pci_get_drvdata(pci);
3802 struct mychip *chip = card->private 3970 struct mychip *chip = card->private_data;
3803 /* (2) */ 3971 /* (2) */
3804 snd_mychip_reinit_chip(chip); !! 3972 pci_restore_state(pci);
>> 3973 pci_enable_device(pci);
>> 3974 pci_set_master(pci);
3805 /* (3) */ 3975 /* (3) */
3806 snd_mychip_restore_registers(chip); !! 3976 snd_mychip_reinit_chip(chip);
3807 /* (4) */ 3977 /* (4) */
3808 snd_ac97_resume(chip->ac97); !! 3978 snd_mychip_restore_registers(chip);
3809 /* (5) */ 3979 /* (5) */
3810 snd_mychip_restart_chip(chip); !! 3980 snd_ac97_resume(chip->ac97);
3811 /* (6) */ 3981 /* (6) */
>> 3982 snd_mychip_restart_chip(chip);
>> 3983 /* (7) */
3812 snd_power_change_state(card, SNDRV_ 3984 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
3813 return 0; 3985 return 0;
3814 } 3986 }
3815 3987
3816 Note that, at the time this callback gets cal !! 3988 As shown in the above, it's better to save registers after suspending
3817 been already suspended via its own PM ops cal !! 3989 the PCM operations via :c:func:`snd_pcm_suspend_all()` or
3818 :c:func:`snd_pcm_suspend_all()` internally. !! 3990 :c:func:`snd_pcm_suspend()`. It means that the PCM streams are
>> 3991 already stopped when the register snapshot is taken. But, remember that
>> 3992 you don't have to restart the PCM stream in the resume callback. It'll
>> 3993 be restarted via trigger call with ``SNDRV_PCM_TRIGGER_RESUME`` when
>> 3994 necessary.
3819 3995
3820 OK, we have all callbacks now. Let's set them 3996 OK, we have all callbacks now. Let's set them up. In the initialization
3821 of the card, make sure that you can get the c 3997 of the card, make sure that you can get the chip data from the card
3822 instance, typically via ``private_data`` fiel 3998 instance, typically via ``private_data`` field, in case you created the
3823 chip data individually:: !! 3999 chip data individually.
>> 4000
>> 4001 ::
3824 4002
3825 static int snd_mychip_probe(struct pci_dev 4003 static int snd_mychip_probe(struct pci_dev *pci,
3826 const struct pc 4004 const struct pci_device_id *pci_id)
3827 { 4005 {
3828 .... 4006 ....
3829 struct snd_card *card; 4007 struct snd_card *card;
3830 struct mychip *chip; 4008 struct mychip *chip;
3831 int err; 4009 int err;
3832 .... 4010 ....
3833 err = snd_card_new(&pci->dev, index 4011 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3834 0, &card); 4012 0, &card);
3835 .... 4013 ....
3836 chip = kzalloc(sizeof(*chip), GFP_K 4014 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
3837 .... 4015 ....
3838 card->private_data = chip; 4016 card->private_data = chip;
3839 .... 4017 ....
3840 } 4018 }
3841 4019
3842 When you created the chip data with :c:func:` 4020 When you created the chip data with :c:func:`snd_card_new()`, it's
3843 anyway accessible via ``private_data`` field: !! 4021 anyway accessible via ``private_data`` field.
>> 4022
>> 4023 ::
3844 4024
3845 static int snd_mychip_probe(struct pci_dev 4025 static int snd_mychip_probe(struct pci_dev *pci,
3846 const struct pc 4026 const struct pci_device_id *pci_id)
3847 { 4027 {
3848 .... 4028 ....
3849 struct snd_card *card; 4029 struct snd_card *card;
3850 struct mychip *chip; 4030 struct mychip *chip;
3851 int err; 4031 int err;
3852 .... 4032 ....
3853 err = snd_card_new(&pci->dev, index 4033 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3854 sizeof(struct my 4034 sizeof(struct mychip), &card);
3855 .... 4035 ....
3856 chip = card->private_data; 4036 chip = card->private_data;
3857 .... 4037 ....
3858 } 4038 }
3859 4039
3860 If you need space to save the registers, allo !! 4040 If you need a space to save the registers, allocate the buffer for it
3861 here, too, since it would be fatal if you can 4041 here, too, since it would be fatal if you cannot allocate a memory in
3862 the suspend phase. The allocated buffer shoul 4042 the suspend phase. The allocated buffer should be released in the
3863 corresponding destructor. 4043 corresponding destructor.
3864 4044
3865 And next, set suspend/resume callbacks to the !! 4045 And next, set suspend/resume callbacks to the pci_driver.
3866 4046
3867 static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_o !! 4047 ::
3868 4048
3869 static struct pci_driver driver = { 4049 static struct pci_driver driver = {
3870 .name = KBUILD_MODNAME, 4050 .name = KBUILD_MODNAME,
3871 .id_table = snd_my_ids, 4051 .id_table = snd_my_ids,
3872 .probe = snd_my_probe, 4052 .probe = snd_my_probe,
3873 .remove = snd_my_remove, 4053 .remove = snd_my_remove,
3874 .driver = { !! 4054 #ifdef CONFIG_PM
3875 .pm = &snd_my_pm_ops, !! 4055 .suspend = snd_my_suspend,
3876 }, !! 4056 .resume = snd_my_resume,
>> 4057 #endif
3877 }; 4058 };
3878 4059
3879 Module Parameters 4060 Module Parameters
3880 ================= 4061 =================
3881 4062
3882 There are standard module options for ALSA. A 4063 There are standard module options for ALSA. At least, each module should
3883 have the ``index``, ``id`` and ``enable`` opt 4064 have the ``index``, ``id`` and ``enable`` options.
3884 4065
3885 If the module supports multiple cards (usuall 4066 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
3886 cards), they should be arrays. The default in 4067 cards), they should be arrays. The default initial values are defined
3887 already as constants for easier programming:: !! 4068 already as constants for easier programming:
>> 4069
>> 4070 ::
3888 4071
3889 static int index[SNDRV_CARDS] = SNDRV_DEFAU 4072 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
3890 static char *id[SNDRV_CARDS] = SNDRV_DEFAUL 4073 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
3891 static int enable[SNDRV_CARDS] = SNDRV_DEFA 4074 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
3892 4075
3893 If the module supports only a single card, th 4076 If the module supports only a single card, they could be single
3894 variables, instead. ``enable`` option is not 4077 variables, instead. ``enable`` option is not always necessary in this
3895 case, but it would be better to have a dummy 4078 case, but it would be better to have a dummy option for compatibility.
3896 4079
3897 The module parameters must be declared with t 4080 The module parameters must be declared with the standard
3898 ``module_param()``, ``module_param_array()`` !! 4081 ``module_param()()``, ``module_param_array()()`` and
3899 :c:func:`MODULE_PARM_DESC()` macros. 4082 :c:func:`MODULE_PARM_DESC()` macros.
3900 4083
3901 Typical code would look as below:: !! 4084 The typical coding would be like below:
>> 4085
>> 4086 ::
3902 4087
3903 #define CARD_NAME "My Chip" 4088 #define CARD_NAME "My Chip"
3904 4089
3905 module_param_array(index, int, NULL, 0444); 4090 module_param_array(index, int, NULL, 0444);
3906 MODULE_PARM_DESC(index, "Index value for " 4091 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
3907 module_param_array(id, charp, NULL, 0444); 4092 module_param_array(id, charp, NULL, 0444);
3908 MODULE_PARM_DESC(id, "ID string for " CARD_ 4093 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
3909 module_param_array(enable, bool, NULL, 0444 4094 module_param_array(enable, bool, NULL, 0444);
3910 MODULE_PARM_DESC(enable, "Enable " CARD_NAM 4095 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
3911 4096
3912 Also, don't forget to define the module descr !! 4097 Also, don't forget to define the module description, classes, license
3913 Especially, the recent modprobe requires to d !! 4098 and devices. Especially, the recent modprobe requires to define the
3914 module license as GPL, etc., otherwise the sy !! 4099 module license as GPL, etc., otherwise the system is shown as “tainted”.
3915 <<
3916 MODULE_DESCRIPTION("Sound driver for My Chi <<
3917 MODULE_LICENSE("GPL"); <<
3918 <<
3919 4100
3920 Device-Managed Resources !! 4101 ::
3921 ======================== <<
3922 4102
3923 In the examples above, all resources are allo !! 4103 MODULE_DESCRIPTION("My Chip");
3924 manually. But human beings are lazy in natur !! 4104 MODULE_LICENSE("GPL");
3925 are lazier. So there are some ways to automa !! 4105 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
3926 the (device-)managed resources aka devres or <<
3927 example, an object allocated via :c:func:`dev <<
3928 freed automatically at unbinding the device. <<
3929 <<
3930 ALSA core provides also the device-managed he <<
3931 :c:func:`snd_devm_card_new()` for creating a <<
3932 Call this functions instead of the normal :c: <<
3933 and you can forget the explicit :c:func:`snd_ <<
3934 it's called automagically at error and remova <<
3935 <<
3936 One caveat is that the call of :c:func:`snd_c <<
3937 at the beginning of the call chain only after <<
3938 :c:func:`snd_card_register()`. <<
3939 <<
3940 Also, the ``private_free`` callback is always <<
3941 so be careful to put the hardware clean-up pr <<
3942 ``private_free`` callback. It might be calle <<
3943 actually set up at an earlier error path. Fo <<
3944 invalid initialization, you can set ``private <<
3945 :c:func:`snd_card_register()` call succeeds. <<
3946 <<
3947 Another thing to be remarked is that you shou <<
3948 helpers for each component as much as possibl <<
3949 the card in that way. Mixing up with the nor <<
3950 resources may screw up the release order. <<
3951 4106
3952 4107
3953 How To Put Your Driver Into ALSA Tree 4108 How To Put Your Driver Into ALSA Tree
3954 ===================================== 4109 =====================================
3955 4110
3956 General 4111 General
3957 ------- 4112 -------
3958 4113
3959 So far, you've learned how to write the drive 4114 So far, you've learned how to write the driver codes. And you might have
3960 a question now: how to put my own driver into 4115 a question now: how to put my own driver into the ALSA driver tree? Here
3961 (finally :) the standard procedure is describ 4116 (finally :) the standard procedure is described briefly.
3962 4117
3963 Suppose that you create a new PCI driver for 4118 Suppose that you create a new PCI driver for the card “xyz”. The card
3964 module name would be snd-xyz. The new driver 4119 module name would be snd-xyz. The new driver is usually put into the
3965 alsa-driver tree, ``sound/pci`` directory in !! 4120 alsa-driver tree, ``alsa-driver/pci`` directory in the case of PCI
3966 cards. !! 4121 cards. Then the driver is evaluated, audited and tested by developers
>> 4122 and users. After a certain time, the driver will go to the alsa-kernel
>> 4123 tree (to the corresponding directory, such as ``alsa-kernel/pci``) and
>> 4124 eventually will be integrated into the Linux 2.6 tree (the directory
>> 4125 would be ``linux/sound/pci``).
3967 4126
3968 In the following sections, the driver code is 4127 In the following sections, the driver code is supposed to be put into
3969 Linux kernel tree. The two cases are covered: !! 4128 alsa-driver tree. The two cases are covered: a driver consisting of a
3970 single source file and one consisting of seve 4129 single source file and one consisting of several source files.
3971 4130
3972 Driver with A Single Source File 4131 Driver with A Single Source File
3973 -------------------------------- 4132 --------------------------------
3974 4133
3975 1. Modify sound/pci/Makefile !! 4134 1. Modify alsa-driver/pci/Makefile
3976 4135
3977 Suppose you have a file xyz.c. Add the fol !! 4136 Suppose you have a file xyz.c. Add the following two lines
3978 4137
3979 snd-xyz-y := xyz.o !! 4138 ::
3980 obj-$(CONFIG_SND_XYZ) += snd-xyz.o !! 4139
>> 4140 snd-xyz-objs := xyz.o
>> 4141 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3981 4142
3982 2. Create the Kconfig entry 4143 2. Create the Kconfig entry
3983 4144
3984 Add the new entry of Kconfig for your xyz !! 4145 Add the new entry of Kconfig for your xyz driver. config SND_XYZ
>> 4146 tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
>> 4147 to include support for Foobar XYZ soundcard. To compile this driver
>> 4148 as a module, choose M here: the module will be called snd-xyz. the
>> 4149 line, select SND_PCM, specifies that the driver xyz supports PCM. In
>> 4150 addition to SND_PCM, the following components are supported for
>> 4151 select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
>> 4152 SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
>> 4153 SND_AC97_CODEC. Add the select command for each supported
>> 4154 component.
>> 4155
>> 4156 Note that some selections imply the lowlevel selections. For example,
>> 4157 PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
>> 4158 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
>> 4159 the lowlevel selections again.
3985 4160
3986 config SND_XYZ !! 4161 For the details of Kconfig script, refer to the kbuild documentation.
3987 tristate "Foobar XYZ" <<
3988 depends on SND <<
3989 select SND_PCM <<
3990 help <<
3991 Say Y here to include support for Fo <<
3992 To compile this driver as a module, <<
3993 the module will be called snd-xyz. <<
3994 <<
3995 The line ``select SND_PCM`` specifies that th <<
3996 In addition to SND_PCM, the following compone <<
3997 select command: SND_RAWMIDI, SND_TIMER, SND_H <<
3998 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_A <<
3999 Add the select command for each supported com <<
4000 <<
4001 Note that some selections imply the lowlevel <<
4002 PCM includes TIMER, MPU401_UART includes RAWM <<
4003 includes PCM, and OPL3_LIB includes HWDEP. Yo <<
4004 the lowlevel selections again. <<
4005 4162
4006 For the details of Kconfig script, refer to t !! 4163 3. Run cvscompile script to re-generate the configure script and build
>> 4164 the whole stuff again.
4007 4165
4008 Drivers with Several Source Files 4166 Drivers with Several Source Files
4009 --------------------------------- 4167 ---------------------------------
4010 4168
4011 Suppose that the driver snd-xyz have several 4169 Suppose that the driver snd-xyz have several source files. They are
4012 located in the new subdirectory, sound/pci/xy !! 4170 located in the new subdirectory, pci/xyz.
>> 4171
>> 4172 1. Add a new directory (``xyz``) in ``alsa-driver/pci/Makefile`` as
>> 4173 below
4013 4174
4014 1. Add a new directory (``sound/pci/xyz``) in !! 4175 ::
4015 as below:: !! 4176
>> 4177 obj-$(CONFIG_SND) += xyz/
>> 4178
>> 4179
>> 4180 2. Under the directory ``xyz``, create a Makefile
>> 4181
>> 4182 ::
4016 4183
4017 obj-$(CONFIG_SND) += sound/pci/xyz/ !! 4184 ifndef SND_TOPDIR
>> 4185 SND_TOPDIR=../..
>> 4186 endif
4018 4187
>> 4188 include $(SND_TOPDIR)/toplevel.config
>> 4189 include $(SND_TOPDIR)/Makefile.conf
4019 4190
4020 2. Under the directory ``sound/pci/xyz``, cre !! 4191 snd-xyz-objs := xyz.o abc.o def.o
4021 4192
4022 snd-xyz-y := xyz.o abc.o def.o <<
4023 obj-$(CONFIG_SND_XYZ) += snd-xyz.o 4193 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4024 4194
>> 4195 include $(SND_TOPDIR)/Rules.make
>> 4196
4025 3. Create the Kconfig entry 4197 3. Create the Kconfig entry
4026 4198
4027 This procedure is as same as in the last s 4199 This procedure is as same as in the last section.
4028 4200
>> 4201 4. Run cvscompile script to re-generate the configure script and build
>> 4202 the whole stuff again.
4029 4203
4030 Useful Functions 4204 Useful Functions
4031 ================ 4205 ================
4032 4206
>> 4207 :c:func:`snd_printk()` and friends
>> 4208 ---------------------------------------
>> 4209
>> 4210 ALSA provides a verbose version of the :c:func:`printk()` function.
>> 4211 If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
>> 4212 prints the given message together with the file name and the line of the
>> 4213 caller. The ``KERN_XXX`` prefix is processed as well as the original
>> 4214 :c:func:`printk()` does, so it's recommended to add this prefix,
>> 4215 e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
>> 4216
>> 4217 There are also :c:func:`printk()`'s for debugging.
>> 4218 :c:func:`snd_printd()` can be used for general debugging purposes.
>> 4219 If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
>> 4220 just like :c:func:`snd_printk()`. If the ALSA is compiled without
>> 4221 the debugging flag, it's ignored.
>> 4222
>> 4223 :c:func:`snd_printdd()` is compiled in only when
>> 4224 ``CONFIG_SND_DEBUG_VERBOSE`` is set. Please note that
>> 4225 ``CONFIG_SND_DEBUG_VERBOSE`` is not set as default even if you configure
>> 4226 the alsa-driver with ``--with-debug=full`` option. You need to give
>> 4227 explicitly ``--with-debug=detect`` option instead.
>> 4228
4033 :c:func:`snd_BUG()` 4229 :c:func:`snd_BUG()`
4034 ------------------- !! 4230 ------------------------
4035 4231
4036 It shows the ``BUG?`` message and stack trace 4232 It shows the ``BUG?`` message and stack trace as well as
4037 :c:func:`snd_BUG_ON()` at the point. It's use 4233 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4038 fatal error happens there. 4234 fatal error happens there.
4039 4235
4040 When no debug flag is set, this macro is igno 4236 When no debug flag is set, this macro is ignored.
4041 4237
4042 :c:func:`snd_BUG_ON()` 4238 :c:func:`snd_BUG_ON()`
4043 ---------------------- !! 4239 ----------------------------
4044 4240
4045 :c:func:`snd_BUG_ON()` macro is similar with 4241 :c:func:`snd_BUG_ON()` macro is similar with
4046 :c:func:`WARN_ON()` macro. For example, snd_B 4242 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4047 it can be used as the condition, if (snd_BUG_ 4243 it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4048 return -EINVAL; 4244 return -EINVAL;
4049 4245
4050 The macro takes an conditional expression to 4246 The macro takes an conditional expression to evaluate. When
4051 ``CONFIG_SND_DEBUG``, is set, if the expressi 4247 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4052 the warning message such as ``BUG? (xxx)`` no 4248 the warning message such as ``BUG? (xxx)`` normally followed by stack
4053 trace. In both cases it returns the evaluated 4249 trace. In both cases it returns the evaluated value.
4054 4250
4055 Acknowledgments 4251 Acknowledgments
4056 =============== 4252 ===============
4057 4253
4058 I would like to thank Phil Kerr for his help 4254 I would like to thank Phil Kerr for his help for improvement and
4059 corrections of this document. 4255 corrections of this document.
4060 4256
4061 Kevin Conder reformatted the original plain-t 4257 Kevin Conder reformatted the original plain-text to the DocBook format.
4062 4258
4063 Giuliano Pochini corrected typos and contribu 4259 Giuliano Pochini corrected typos and contributed the example codes in
4064 the hardware constraints section. 4260 the hardware constraints section.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.