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