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