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