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