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