| blob | a0b268466cb1db1653a005de4d46cb8ebe934389 |
1 ======================
2 Writing an ALSA Driver
3 ======================
5 :Author: Takashi Iwai <tiwai@suse.de>
6 :Date: Oct 15, 2007
7 :Edition: 0.3.7
9 Preface
10 =======
12 This document describes how to write an `ALSA (Advanced Linux Sound
13 Architecture) <http://www.alsa-project.org/>`__ driver. The document
14 focuses mainly on PCI soundcards. In the case of other device types, the
15 API might be different, too. However, at least the ALSA kernel API is
16 consistent, and therefore it would be still a bit help for writing them.
18 This document targets people who already have enough C language skills
19 and have basic linux kernel programming knowledge. This document doesn't
20 explain the general topic of linux kernel coding and doesn't cover
21 low-level driver implementation details. It only describes the standard
22 way to write a PCI sound driver on ALSA.
24 If you are already familiar with the older ALSA ver.0.5.x API, you can
25 check the drivers such as ``sound/pci/es1938.c`` or
26 ``sound/pci/maestro3.c`` which have also almost the same code-base in
27 the ALSA 0.5.x tree, so you can compare the differences.
29 This document is still a draft version. Any feedback and corrections,
30 please!!
32 File Tree Structure
33 ===================
35 General
36 -------
38 The ALSA drivers are provided in two ways.
40 One is the trees provided as a tarball or via cvs from the ALSA's ftp
41 site, and another is the 2.6 (or later) Linux kernel tree. To
42 synchronize both, the ALSA driver tree is split into two different
43 trees: alsa-kernel and alsa-driver. The former contains purely the
44 source code for the Linux 2.6 (or later) tree. This tree is designed
45 only for compilation on 2.6 or later environment. The latter,
46 alsa-driver, contains many subtle files for compiling ALSA drivers
47 outside of the Linux kernel tree, wrapper functions for older 2.2 and
48 2.4 kernels, to adapt the latest kernel API, and additional drivers
49 which are still in development or in tests. The drivers in alsa-driver
50 tree will be moved to alsa-kernel (and eventually to the 2.6 kernel
51 tree) when they are finished and confirmed to work fine.
53 The file tree structure of ALSA driver is depicted below. Both
54 alsa-kernel and alsa-driver have almost the same file structure, except
55 for “core” directory. It's named as “acore” in alsa-driver tree.
57 ::
59 sound
60 /core
61 /oss
62 /seq
63 /oss
64 /instr
65 /ioctl32
66 /include
67 /drivers
68 /mpu401
69 /opl3
70 /i2c
71 /l3
72 /synth
73 /emux
74 /pci
75 /(cards)
76 /isa
77 /(cards)
78 /arm
79 /ppc
80 /sparc
81 /usb
82 /pcmcia /(cards)
83 /oss
86 core directory
87 --------------
89 This directory contains the middle layer which is the heart of ALSA
90 drivers. In this directory, the native ALSA modules are stored. The
91 sub-directories contain different modules and are dependent upon the
92 kernel config.
94 core/oss
95 ~~~~~~~~
97 The codes for PCM and mixer OSS emulation modules are stored in this
98 directory. The rawmidi OSS emulation is included in the ALSA rawmidi
99 code since it's quite small. The sequencer code is stored in
100 ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
102 core/ioctl32
103 ~~~~~~~~~~~~
105 This directory contains the 32bit-ioctl wrappers for 64bit architectures
106 such like x86-64, ppc64 and sparc64. For 32bit and alpha architectures,
107 these are not compiled.
109 core/seq
110 ~~~~~~~~
112 This directory and its sub-directories are for the ALSA sequencer. This
113 directory contains the sequencer core and primary sequencer modules such
114 like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
115 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
117 core/seq/oss
118 ~~~~~~~~~~~~
120 This contains the OSS sequencer emulation codes.
122 core/seq/instr
123 ~~~~~~~~~~~~~~
125 This directory contains the modules for the sequencer instrument layer.
127 include directory
128 -----------------
130 This is the place for the public header files of ALSA drivers, which are
131 to be exported to user-space, or included by several files at different
132 directories. Basically, the private header files should not be placed in
133 this directory, but you may still find files there, due to historical
134 reasons :)
136 drivers directory
137 -----------------
139 This directory contains code shared among different drivers on different
140 architectures. They are hence supposed not to be architecture-specific.
141 For example, the dummy pcm driver and the serial MIDI driver are found
142 in this directory. In the sub-directories, there is code for components
143 which are independent from bus and cpu architectures.
145 drivers/mpu401
146 ~~~~~~~~~~~~~~
148 The MPU401 and MPU401-UART modules are stored here.
150 drivers/opl3 and opl4
151 ~~~~~~~~~~~~~~~~~~~~~
153 The OPL3 and OPL4 FM-synth stuff is found here.
155 i2c directory
156 -------------
158 This contains the ALSA i2c components.
160 Although there is a standard i2c layer on Linux, ALSA has its own i2c
161 code for some cards, because the soundcard needs only a simple operation
162 and the standard i2c API is too complicated for such a purpose.
164 i2c/l3
165 ~~~~~~
167 This is a sub-directory for ARM L3 i2c.
169 synth directory
170 ---------------
172 This contains the synth middle-level modules.
174 So far, there is only Emu8000/Emu10k1 synth driver under the
175 ``synth/emux`` sub-directory.
177 pci directory
178 -------------
180 This directory and its sub-directories hold the top-level card modules
181 for PCI soundcards and the code specific to the PCI BUS.
183 The drivers compiled from a single file are stored directly in the pci
184 directory, while the drivers with several source files are stored on
185 their own sub-directory (e.g. emu10k1, ice1712).
187 isa directory
188 -------------
190 This directory and its sub-directories hold the top-level card modules
191 for ISA soundcards.
193 arm, ppc, and sparc directories
194 -------------------------------
196 They are used for top-level card modules which are specific to one of
197 these architectures.
199 usb directory
200 -------------
202 This directory contains the USB-audio driver. In the latest version, the
203 USB MIDI driver is integrated in the usb-audio driver.
205 pcmcia directory
206 ----------------
208 The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
209 be in the pci directory, because their API is identical to that of
210 standard PCI cards.
212 oss directory
213 -------------
215 The OSS/Lite source files are stored here in Linux 2.6 (or later) tree.
216 In the ALSA driver tarball, this directory is empty, of course :)
218 Basic Flow for PCI Drivers
219 ==========================
221 Outline
222 -------
224 The minimum flow for PCI soundcards is as follows:
226 - define the PCI ID table (see the section `PCI Entries`_).
228 - create ``probe`` callback.
230 - create ``remove`` callback.
232 - create a :c:type:`struct pci_driver <pci_driver>` structure
233 containing the three pointers above.
235 - create an ``init`` function just calling the
236 :c:func:`pci_register_driver()` to register the pci_driver
237 table defined above.
239 - create an ``exit`` function to call the
240 :c:func:`pci_unregister_driver()` function.
242 Full Code Example
243 -----------------
245 The code example is shown below. Some parts are kept unimplemented at
246 this moment but will be filled in the next sections. The numbers in the
247 comment lines of the :c:func:`snd_mychip_probe()` function refer
248 to details explained in the following section.
250 ::
252 #include <linux/init.h>
253 #include <linux/pci.h>
254 #include <linux/slab.h>
255 #include <sound/core.h>
256 #include <sound/initval.h>
258 /* module parameters (see "Module Parameters") */
259 /* SNDRV_CARDS: maximum number of cards supported by this module */
260 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
261 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
262 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
264 /* definition of the chip-specific record */
265 struct mychip {
266 struct snd_card *card;
267 /* the rest of the implementation will be in section
268 * "PCI Resource Management"
269 */
270 };
272 /* chip-specific destructor
273 * (see "PCI Resource Management")
274 */
275 static int snd_mychip_free(struct mychip *chip)
276 {
277 .... /* will be implemented later... */
278 }
280 /* component-destructor
281 * (see "Management of Cards and Components")
282 */
283 static int snd_mychip_dev_free(struct snd_device *device)
284 {
285 return snd_mychip_free(device->device_data);
286 }
288 /* chip-specific constructor
289 * (see "Management of Cards and Components")
290 */
291 static int snd_mychip_create(struct snd_card *card,
292 struct pci_dev *pci,
293 struct mychip **rchip)
294 {
295 struct mychip *chip;
296 int err;
297 static struct snd_device_ops ops = {
298 .dev_free = snd_mychip_dev_free,
299 };
301 *rchip = NULL;
303 /* check PCI availability here
304 * (see "PCI Resource Management")
305 */
306 ....
308 /* allocate a chip-specific data with zero filled */
309 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
310 if (chip == NULL)
311 return -ENOMEM;
313 chip->card = card;
315 /* rest of initialization here; will be implemented
316 * later, see "PCI Resource Management"
317 */
318 ....
320 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
321 if (err < 0) {
322 snd_mychip_free(chip);
323 return err;
324 }
326 *rchip = chip;
327 return 0;
328 }
330 /* constructor -- see "Driver Constructor" sub-section */
331 static int snd_mychip_probe(struct pci_dev *pci,
332 const struct pci_device_id *pci_id)
333 {
334 static int dev;
335 struct snd_card *card;
336 struct mychip *chip;
337 int err;
339 /* (1) */
340 if (dev >= SNDRV_CARDS)
341 return -ENODEV;
342 if (!enable[dev]) {
343 dev++;
344 return -ENOENT;
345 }
347 /* (2) */
348 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
349 0, &card);
350 if (err < 0)
351 return err;
353 /* (3) */
354 err = snd_mychip_create(card, pci, &chip);
355 if (err < 0) {
356 snd_card_free(card);
357 return err;
358 }
360 /* (4) */
361 strcpy(card->driver, "My Chip");
362 strcpy(card->shortname, "My Own Chip 123");
363 sprintf(card->longname, "%s at 0x%lx irq %i",
364 card->shortname, chip->ioport, chip->irq);
366 /* (5) */
367 .... /* implemented later */
369 /* (6) */
370 err = snd_card_register(card);
371 if (err < 0) {
372 snd_card_free(card);
373 return err;
374 }
376 /* (7) */
377 pci_set_drvdata(pci, card);
378 dev++;
379 return 0;
380 }
382 /* destructor -- see the "Destructor" sub-section */
383 static void snd_mychip_remove(struct pci_dev *pci)
384 {
385 snd_card_free(pci_get_drvdata(pci));
386 pci_set_drvdata(pci, NULL);
387 }
391 Driver Constructor
392 ------------------
394 The real constructor of PCI drivers is the ``probe`` callback. The
395 ``probe`` callback and other component-constructors which are called
396 from the ``probe`` callback cannot be used with the ``__init`` prefix
397 because any PCI device could be a hotplug device.
399 In the ``probe`` callback, the following scheme is often used.
401 1) Check and increment the device index.
402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
404 ::
406 static int dev;
407 ....
408 if (dev >= SNDRV_CARDS)
409 return -ENODEV;
410 if (!enable[dev]) {
411 dev++;
412 return -ENOENT;
413 }
416 where ``enable[dev]`` is the module option.
418 Each time the ``probe`` callback is called, check the availability of
419 the device. If not available, simply increment the device index and
420 returns. dev will be incremented also later (`step 7
421 <#set-the-pci-driver-data-and-return-zero>`__).
423 2) Create a card instance
424 ~~~~~~~~~~~~~~~~~~~~~~~~~
426 ::
428 struct snd_card *card;
429 int err;
430 ....
431 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
432 0, &card);
435 The details will be explained in the section `Management of Cards and
436 Components`_.
438 3) Create a main component
439 ~~~~~~~~~~~~~~~~~~~~~~~~~~
441 In this part, the PCI resources are allocated.
443 ::
445 struct mychip *chip;
446 ....
447 err = snd_mychip_create(card, pci, &chip);
448 if (err < 0) {
449 snd_card_free(card);
450 return err;
451 }
453 The details will be explained in the section `PCI Resource
454 Management`_.
456 4) Set the driver ID and name strings.
457 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
459 ::
461 strcpy(card->driver, "My Chip");
462 strcpy(card->shortname, "My Own Chip 123");
463 sprintf(card->longname, "%s at 0x%lx irq %i",
464 card->shortname, chip->ioport, chip->irq);
466 The driver field holds the minimal ID string of the chip. This is used
467 by alsa-lib's configurator, so keep it simple but unique. Even the
468 same driver can have different driver IDs to distinguish the
469 functionality of each chip type.
471 The shortname field is a string shown as more verbose name. The longname
472 field contains the information shown in ``/proc/asound/cards``.
474 5) Create other components, such as mixer, MIDI, etc.
475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
477 Here you define the basic components such as `PCM <#PCM-Interface>`__,
478 mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
479 `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
480 Also, if you want a `proc file <#Proc-Interface>`__, define it here,
481 too.
483 6) Register the card instance.
484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486 ::
488 err = snd_card_register(card);
489 if (err < 0) {
490 snd_card_free(card);
491 return err;
492 }
494 Will be explained in the section `Management of Cards and
495 Components`_, too.
497 7) Set the PCI driver data and return zero.
498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500 ::
502 pci_set_drvdata(pci, card);
503 dev++;
504 return 0;
506 In the above, the card record is stored. This pointer is used in the
507 remove callback and power-management callbacks, too.
509 Destructor
510 ----------
512 The destructor, remove callback, simply releases the card instance. Then
513 the ALSA middle layer will release all the attached components
514 automatically.
516 It would be typically like the following:
518 ::
520 static void snd_mychip_remove(struct pci_dev *pci)
521 {
522 snd_card_free(pci_get_drvdata(pci));
523 pci_set_drvdata(pci, NULL);
524 }
527 The above code assumes that the card pointer is set to the PCI driver
528 data.
530 Header Files
531 ------------
533 For the above example, at least the following include files are
534 necessary.
536 ::
538 #include <linux/init.h>
539 #include <linux/pci.h>
540 #include <linux/slab.h>
541 #include <sound/core.h>
542 #include <sound/initval.h>
544 where the last one is necessary only when module options are defined
545 in the source file. If the code is split into several files, the files
546 without module options don't need them.
548 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
549 interrupt handling, and ``<asm/io.h>`` for I/O access. If you use the
550 :c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
551 to include ``<linux/delay.h>`` too.
553 The ALSA interfaces like the PCM and control APIs are defined in other
554 ``<sound/xxx.h>`` header files. They have to be included after
555 ``<sound/core.h>``.
557 Management of Cards and Components
558 ==================================
560 Card Instance
561 -------------
563 For each soundcard, a “card” record must be allocated.
565 A card record is the headquarters of the soundcard. It manages the whole
566 list of devices (components) on the soundcard, such as PCM, mixers,
567 MIDI, synthesizer, and so on. Also, the card record holds the ID and the
568 name strings of the card, manages the root of proc files, and controls
569 the power-management states and hotplug disconnections. The component
570 list on the card record is used to manage the correct release of
571 resources at destruction.
573 As mentioned above, to create a card instance, call
574 :c:func:`snd_card_new()`.
576 ::
578 struct snd_card *card;
579 int err;
580 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
583 The function takes six arguments: the parent device pointer, the
584 card-index number, the id string, the module pointer (usually
585 ``THIS_MODULE``), the size of extra-data space, and the pointer to
586 return the card instance. The extra_size argument is used to allocate
587 card->private_data for the chip-specific data. Note that these data are
588 allocated by :c:func:`snd_card_new()`.
590 The first argument, the pointer of struct :c:type:`struct device
591 <device>`, specifies the parent device. For PCI devices, typically
592 ``&pci->`` is passed there.
594 Components
595 ----------
597 After the card is created, you can attach the components (devices) to
598 the card instance. In an ALSA driver, a component is represented as a
599 :c:type:`struct snd_device <snd_device>` object. A component
600 can be a PCM instance, a control interface, a raw MIDI interface, etc.
601 Each such instance has one component entry.
603 A component can be created via :c:func:`snd_device_new()`
604 function.
606 ::
608 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
610 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
611 data pointer, and the callback pointers (``&ops``). The device-level
612 defines the type of components and the order of registration and
613 de-registration. For most components, the device-level is already
614 defined. For a user-defined component, you can use
615 ``SNDRV_DEV_LOWLEVEL``.
617 This function itself doesn't allocate the data space. The data must be
618 allocated manually beforehand, and its pointer is passed as the
619 argument. This pointer (``chip`` in the above example) is used as the
620 identifier for the instance.
622 Each pre-defined ALSA component such as ac97 and pcm calls
623 :c:func:`snd_device_new()` inside its constructor. The destructor
624 for each component is defined in the callback pointers. Hence, you don't
625 need to take care of calling a destructor for such a component.
627 If you wish to create your own component, you need to set the destructor
628 function to the dev_free callback in the ``ops``, so that it can be
629 released automatically via :c:func:`snd_card_free()`. The next
630 example will show an implementation of chip-specific data.
632 Chip-Specific Data
633 ------------------
635 Chip-specific information, e.g. the I/O port address, its resource
636 pointer, or the irq number, is stored in the chip-specific record.
638 ::
640 struct mychip {
641 ....
642 };
645 In general, there are two ways of allocating the chip record.
647 1. Allocating via :c:func:`snd_card_new()`.
648 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
650 As mentioned above, you can pass the extra-data-length to the 5th
651 argument of :c:func:`snd_card_new()`, i.e.
653 ::
655 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
656 sizeof(struct mychip), &card);
658 :c:type:`struct mychip <mychip>` is the type of the chip record.
660 In return, the allocated record can be accessed as
662 ::
664 struct mychip *chip = card->private_data;
666 With this method, you don't have to allocate twice. The record is
667 released together with the card instance.
669 2. Allocating an extra device.
670 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
672 After allocating a card instance via :c:func:`snd_card_new()`
673 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
675 ::
677 struct snd_card *card;
678 struct mychip *chip;
679 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
680 0, &card);
681 .....
682 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
684 The chip record should have the field to hold the card pointer at least,
686 ::
688 struct mychip {
689 struct snd_card *card;
690 ....
691 };
694 Then, set the card pointer in the returned chip instance.
696 ::
698 chip->card = card;
700 Next, initialize the fields, and register this chip record as a
701 low-level device with a specified ``ops``,
703 ::
705 static struct snd_device_ops ops = {
706 .dev_free = snd_mychip_dev_free,
707 };
708 ....
709 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
711 :c:func:`snd_mychip_dev_free()` is the device-destructor
712 function, which will call the real destructor.
714 ::
716 static int snd_mychip_dev_free(struct snd_device *device)
717 {
718 return snd_mychip_free(device->device_data);
719 }
721 where :c:func:`snd_mychip_free()` is the real destructor.
723 Registration and Release
724 ------------------------
726 After all components are assigned, register the card instance by calling
727 :c:func:`snd_card_register()`. Access to the device files is
728 enabled at this point. That is, before
729 :c:func:`snd_card_register()` is called, the components are safely
730 inaccessible from external side. If this call fails, exit the probe
731 function after releasing the card via :c:func:`snd_card_free()`.
733 For releasing the card instance, you can call simply
734 :c:func:`snd_card_free()`. As mentioned earlier, all components
735 are released automatically by this call.
737 For a device which allows hotplugging, you can use
738 :c:func:`snd_card_free_when_closed()`. This one will postpone
739 the destruction until all devices are closed.
741 PCI Resource Management
742 =======================
744 Full Code Example
745 -----------------
747 In this section, we'll complete the chip-specific constructor,
748 destructor and PCI entries. Example code is shown first, below.
750 ::
752 struct mychip {
753 struct snd_card *card;
754 struct pci_dev *pci;
756 unsigned long port;
757 int irq;
758 };
760 static int snd_mychip_free(struct mychip *chip)
761 {
762 /* disable hardware here if any */
763 .... /* (not implemented in this document) */
765 /* release the irq */
766 if (chip->irq >= 0)
767 free_irq(chip->irq, chip);
768 /* release the I/O ports & memory */
769 pci_release_regions(chip->pci);
770 /* disable the PCI entry */
771 pci_disable_device(chip->pci);
772 /* release the data */
773 kfree(chip);
774 return 0;
775 }
777 /* chip-specific constructor */
778 static int snd_mychip_create(struct snd_card *card,
779 struct pci_dev *pci,
780 struct mychip **rchip)
781 {
782 struct mychip *chip;
783 int err;
784 static struct snd_device_ops ops = {
785 .dev_free = snd_mychip_dev_free,
786 };
788 *rchip = NULL;
790 /* initialize the PCI entry */
791 err = pci_enable_device(pci);
792 if (err < 0)
793 return err;
794 /* check PCI availability (28bit DMA) */
795 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
796 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
797 printk(KERN_ERR "error to set 28bit mask DMA\n");
798 pci_disable_device(pci);
799 return -ENXIO;
800 }
802 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
803 if (chip == NULL) {
804 pci_disable_device(pci);
805 return -ENOMEM;
806 }
808 /* initialize the stuff */
809 chip->card = card;
810 chip->pci = pci;
811 chip->irq = -1;
813 /* (1) PCI resource allocation */
814 err = pci_request_regions(pci, "My Chip");
815 if (err < 0) {
816 kfree(chip);
817 pci_disable_device(pci);
818 return err;
819 }
820 chip->port = pci_resource_start(pci, 0);
821 if (request_irq(pci->irq, snd_mychip_interrupt,
822 IRQF_SHARED, KBUILD_MODNAME, chip)) {
823 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
824 snd_mychip_free(chip);
825 return -EBUSY;
826 }
827 chip->irq = pci->irq;
829 /* (2) initialization of the chip hardware */
830 .... /* (not implemented in this document) */
832 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
833 if (err < 0) {
834 snd_mychip_free(chip);
835 return err;
836 }
838 *rchip = chip;
839 return 0;
840 }
842 /* PCI IDs */
843 static struct pci_device_id snd_mychip_ids[] = {
844 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
845 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
846 ....
847 { 0, }
848 };
849 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
851 /* pci_driver definition */
852 static struct pci_driver driver = {
853 .name = KBUILD_MODNAME,
854 .id_table = snd_mychip_ids,
855 .probe = snd_mychip_probe,
856 .remove = snd_mychip_remove,
857 };
859 /* module initialization */
860 static int __init alsa_card_mychip_init(void)
861 {
862 return pci_register_driver(&driver);
863 }
865 /* module clean up */
866 static void __exit alsa_card_mychip_exit(void)
867 {
868 pci_unregister_driver(&driver);
869 }
871 module_init(alsa_card_mychip_init)
872 module_exit(alsa_card_mychip_exit)
874 EXPORT_NO_SYMBOLS; /* for old kernels only */
876 Some Hafta's
877 ------------
879 The allocation of PCI resources is done in the ``probe`` function, and
880 usually an extra :c:func:`xxx_create()` function is written for this
881 purpose.
883 In the case of PCI devices, you first have to call the
884 :c:func:`pci_enable_device()` function before allocating
885 resources. Also, you need to set the proper PCI DMA mask to limit the
886 accessed I/O range. In some cases, you might need to call
887 :c:func:`pci_set_master()` function, too.
889 Suppose the 28bit mask, and the code to be added would be like:
891 ::
893 err = pci_enable_device(pci);
894 if (err < 0)
895 return err;
896 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
897 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
898 printk(KERN_ERR "error to set 28bit mask DMA\n");
899 pci_disable_device(pci);
900 return -ENXIO;
901 }
904 Resource Allocation
905 -------------------
907 The allocation of I/O ports and irqs is done via standard kernel
908 functions. Unlike ALSA ver.0.5.x., there are no helpers for that. And
909 these resources must be released in the destructor function (see below).
910 Also, on ALSA 0.9.x, you don't need to allocate (pseudo-)DMA for PCI
911 like in ALSA 0.5.x.
913 Now assume that the PCI device has an I/O port with 8 bytes and an
914 interrupt. Then :c:type:`struct mychip <mychip>` will have the
915 following fields:
917 ::
919 struct mychip {
920 struct snd_card *card;
922 unsigned long port;
923 int irq;
924 };
927 For an I/O port (and also a memory region), you need to have the
928 resource pointer for the standard resource management. For an irq, you
929 have to keep only the irq number (integer). But you need to initialize
930 this number as -1 before actual allocation, since irq 0 is valid. The
931 port address and its resource pointer can be initialized as null by
932 :c:func:`kzalloc()` automatically, so you don't have to take care of
933 resetting them.
935 The allocation of an I/O port is done like this:
937 ::
939 err = pci_request_regions(pci, "My Chip");
940 if (err < 0) {
941 kfree(chip);
942 pci_disable_device(pci);
943 return err;
944 }
945 chip->port = pci_resource_start(pci, 0);
947 It will reserve the I/O port region of 8 bytes of the given PCI device.
948 The returned value, ``chip->res_port``, is allocated via
949 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
950 must be released via :c:func:`kfree()`, but there is a problem with
951 this. This issue will be explained later.
953 The allocation of an interrupt source is done like this:
955 ::
957 if (request_irq(pci->irq, snd_mychip_interrupt,
958 IRQF_SHARED, KBUILD_MODNAME, chip)) {
959 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
960 snd_mychip_free(chip);
961 return -EBUSY;
962 }
963 chip->irq = pci->irq;
965 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
966 defined `later <#pcm-interface-interrupt-handler>`__. Note that
967 ``chip->irq`` should be defined only when :c:func:`request_irq()`
968 succeeded.
970 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
971 as the interrupt flag of :c:func:`request_irq()`.
973 The last argument of :c:func:`request_irq()` is the data pointer
974 passed to the interrupt handler. Usually, the chip-specific record is
975 used for that, but you can use what you like, too.
977 I won't give details about the interrupt handler at this point, but at
978 least its appearance can be explained now. The interrupt handler looks
979 usually like the following:
981 ::
983 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
984 {
985 struct mychip *chip = dev_id;
986 ....
987 return IRQ_HANDLED;
988 }
991 Now let's write the corresponding destructor for the resources above.
992 The role of destructor is simple: disable the hardware (if already
993 activated) and release the resources. So far, we have no hardware part,
994 so the disabling code is not written here.
996 To release the resources, the “check-and-release” method is a safer way.
997 For the interrupt, do like this:
999 ::
1001 if (chip->irq >= 0)
1002 free_irq(chip->irq, chip);
1004 Since the irq number can start from 0, you should initialize
1005 ``chip->irq`` with a negative value (e.g. -1), so that you can check
1006 the validity of the irq number as above.
1008 When you requested I/O ports or memory regions via
1009 :c:func:`pci_request_region()` or
1010 :c:func:`pci_request_regions()` like in this example, release the
1011 resource(s) using the corresponding function,
1012 :c:func:`pci_release_region()` or
1013 :c:func:`pci_release_regions()`.
1015 ::
1017 pci_release_regions(chip->pci);
1019 When you requested manually via :c:func:`request_region()` or
1020 :c:func:`request_mem_region()`, you can release it via
1021 :c:func:`release_resource()`. Suppose that you keep the resource
1022 pointer returned from :c:func:`request_region()` in
1023 chip->res_port, the release procedure looks like:
1025 ::
1027 release_and_free_resource(chip->res_port);
1029 Don't forget to call :c:func:`pci_disable_device()` before the
1030 end.
1032 And finally, release the chip-specific record.
1034 ::
1036 kfree(chip);
1038 We didn't implement the hardware disabling part in the above. If you
1039 need to do this, please note that the destructor may be called even
1040 before the initialization of the chip is completed. It would be better
1041 to have a flag to skip hardware disabling if the hardware was not
1042 initialized yet.
1044 When the chip-data is assigned to the card using
1045 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1046 destructor is called at the last. That is, it is assured that all other
1047 components like PCMs and controls have already been released. You don't
1048 have to stop PCMs, etc. explicitly, but just call low-level hardware
1049 stopping.
1051 The management of a memory-mapped region is almost as same as the
1052 management of an I/O port. You'll need three fields like the
1053 following:
1055 ::
1057 struct mychip {
1058 ....
1059 unsigned long iobase_phys;
1060 void __iomem *iobase_virt;
1061 };
1063 and the allocation would be like below:
1065 ::
1067 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1068 kfree(chip);
1069 return err;
1070 }
1071 chip->iobase_phys = pci_resource_start(pci, 0);
1072 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1073 pci_resource_len(pci, 0));
1075 and the corresponding destructor would be:
1077 ::
1079 static int snd_mychip_free(struct mychip *chip)
1080 {
1081 ....
1082 if (chip->iobase_virt)
1083 iounmap(chip->iobase_virt);
1084 ....
1085 pci_release_regions(chip->pci);
1086 ....
1087 }
1089 PCI Entries
1090 -----------
1092 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1093 :c:type:`struct pci_device_id <pci_device_id>` table for
1094 this chipset. It's a table of PCI vendor/device ID number, and some
1095 masks.
1097 For example,
1099 ::
1101 static struct pci_device_id snd_mychip_ids[] = {
1102 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1103 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1104 ....
1105 { 0, }
1106 };
1107 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1109 The first and second fields of the :c:type:`struct pci_device_id
1110 <pci_device_id>` structure are the vendor and device IDs. If you
1111 have no reason to filter the matching devices, you can leave the
1112 remaining fields as above. The last field of the :c:type:`struct
1113 pci_device_id <pci_device_id>` struct contains private data
1114 for this entry. You can specify any value here, for example, to define
1115 specific operations for supported device IDs. Such an example is found
1116 in the intel8x0 driver.
1118 The last entry of this list is the terminator. You must specify this
1119 all-zero entry.
1121 Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1122 record:
1124 ::
1126 static struct pci_driver driver = {
1127 .name = KBUILD_MODNAME,
1128 .id_table = snd_mychip_ids,
1129 .probe = snd_mychip_probe,
1130 .remove = snd_mychip_remove,
1131 };
1133 The ``probe`` and ``remove`` functions have already been defined in
1134 the previous sections. The ``name`` field is the name string of this
1135 device. Note that you must not use a slash “/” in this string.
1137 And at last, the module entries:
1139 ::
1141 static int __init alsa_card_mychip_init(void)
1142 {
1143 return pci_register_driver(&driver);
1144 }
1146 static void __exit alsa_card_mychip_exit(void)
1147 {
1148 pci_unregister_driver(&driver);
1149 }
1151 module_init(alsa_card_mychip_init)
1152 module_exit(alsa_card_mychip_exit)
1154 Note that these module entries are tagged with ``__init`` and ``__exit``
1155 prefixes.
1157 Oh, one thing was forgotten. If you have no exported symbols, you need
1158 to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1160 ::
1162 EXPORT_NO_SYMBOLS;
1164 That's all!
1166 PCM Interface
1167 =============
1169 General
1170 -------
1172 The PCM middle layer of ALSA is quite powerful and it is only necessary
1173 for each driver to implement the low-level functions to access its
1174 hardware.
1176 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1177 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1178 access to some functions related with hw_param.
1180 Each card device can have up to four pcm instances. A pcm instance
1181 corresponds to a pcm device file. The limitation of number of instances
1182 comes only from the available bit size of the Linux's device numbers.
1183 Once when 64bit device number is used, we'll have more pcm instances
1184 available.
1186 A pcm instance consists of pcm playback and capture streams, and each
1187 pcm stream consists of one or more pcm substreams. Some soundcards
1188 support multiple playback functions. For example, emu10k1 has a PCM
1189 playback of 32 stereo substreams. In this case, at each open, a free
1190 substream is (usually) automatically chosen and opened. Meanwhile, when
1191 only one substream exists and it was already opened, the successful open
1192 will either block or error with ``EAGAIN`` according to the file open
1193 mode. But you don't have to care about such details in your driver. The
1194 PCM middle layer will take care of such work.
1196 Full Code Example
1197 -----------------
1199 The example code below does not include any hardware access routines but
1200 shows only the skeleton, how to build up the PCM interfaces.
1202 ::
1204 #include <sound/pcm.h>
1205 ....
1207 /* hardware definition */
1208 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1209 .info = (SNDRV_PCM_INFO_MMAP |
1210 SNDRV_PCM_INFO_INTERLEAVED |
1211 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1212 SNDRV_PCM_INFO_MMAP_VALID),
1213 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1214 .rates = SNDRV_PCM_RATE_8000_48000,
1215 .rate_min = 8000,
1216 .rate_max = 48000,
1217 .channels_min = 2,
1218 .channels_max = 2,
1219 .buffer_bytes_max = 32768,
1220 .period_bytes_min = 4096,
1221 .period_bytes_max = 32768,
1222 .periods_min = 1,
1223 .periods_max = 1024,
1224 };
1226 /* hardware definition */
1227 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1228 .info = (SNDRV_PCM_INFO_MMAP |
1229 SNDRV_PCM_INFO_INTERLEAVED |
1230 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1231 SNDRV_PCM_INFO_MMAP_VALID),
1232 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1233 .rates = SNDRV_PCM_RATE_8000_48000,
1234 .rate_min = 8000,
1235 .rate_max = 48000,
1236 .channels_min = 2,
1237 .channels_max = 2,
1238 .buffer_bytes_max = 32768,
1239 .period_bytes_min = 4096,
1240 .period_bytes_max = 32768,
1241 .periods_min = 1,
1242 .periods_max = 1024,
1243 };
1245 /* open callback */
1246 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1247 {
1248 struct mychip *chip = snd_pcm_substream_chip(substream);
1249 struct snd_pcm_runtime *runtime = substream->runtime;
1251 runtime->hw = snd_mychip_playback_hw;
1252 /* more hardware-initialization will be done here */
1253 ....
1254 return 0;
1255 }
1257 /* close callback */
1258 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1259 {
1260 struct mychip *chip = snd_pcm_substream_chip(substream);
1261 /* the hardware-specific codes will be here */
1262 ....
1263 return 0;
1265 }
1267 /* open callback */
1268 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1269 {
1270 struct mychip *chip = snd_pcm_substream_chip(substream);
1271 struct snd_pcm_runtime *runtime = substream->runtime;
1273 runtime->hw = snd_mychip_capture_hw;
1274 /* more hardware-initialization will be done here */
1275 ....
1276 return 0;
1277 }
1279 /* close callback */
1280 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1281 {
1282 struct mychip *chip = snd_pcm_substream_chip(substream);
1283 /* the hardware-specific codes will be here */
1284 ....
1285 return 0;
1287 }
1289 /* hw_params callback */
1290 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1291 struct snd_pcm_hw_params *hw_params)
1292 {
1293 return snd_pcm_lib_malloc_pages(substream,
1294 params_buffer_bytes(hw_params));
1295 }
1297 /* hw_free callback */
1298 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1299 {
1300 return snd_pcm_lib_free_pages(substream);
1301 }
1303 /* prepare callback */
1304 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1305 {
1306 struct mychip *chip = snd_pcm_substream_chip(substream);
1307 struct snd_pcm_runtime *runtime = substream->runtime;
1309 /* set up the hardware with the current configuration
1310 * for example...
1311 */
1312 mychip_set_sample_format(chip, runtime->format);
1313 mychip_set_sample_rate(chip, runtime->rate);
1314 mychip_set_channels(chip, runtime->channels);
1315 mychip_set_dma_setup(chip, runtime->dma_addr,
1316 chip->buffer_size,
1317 chip->period_size);
1318 return 0;
1319 }
1321 /* trigger callback */
1322 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1323 int cmd)
1324 {
1325 switch (cmd) {
1326 case SNDRV_PCM_TRIGGER_START:
1327 /* do something to start the PCM engine */
1328 ....
1329 break;
1330 case SNDRV_PCM_TRIGGER_STOP:
1331 /* do something to stop the PCM engine */
1332 ....
1333 break;
1334 default:
1335 return -EINVAL;
1336 }
1337 }
1339 /* pointer callback */
1340 static snd_pcm_uframes_t
1341 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1342 {
1343 struct mychip *chip = snd_pcm_substream_chip(substream);
1344 unsigned int current_ptr;
1346 /* get the current hardware pointer */
1347 current_ptr = mychip_get_hw_pointer(chip);
1348 return current_ptr;
1349 }
1351 /* operators */
1352 static struct snd_pcm_ops snd_mychip_playback_ops = {
1353 .open = snd_mychip_playback_open,
1354 .close = snd_mychip_playback_close,
1355 .ioctl = snd_pcm_lib_ioctl,
1356 .hw_params = snd_mychip_pcm_hw_params,
1357 .hw_free = snd_mychip_pcm_hw_free,
1358 .prepare = snd_mychip_pcm_prepare,
1359 .trigger = snd_mychip_pcm_trigger,
1360 .pointer = snd_mychip_pcm_pointer,
1361 };
1363 /* operators */
1364 static struct snd_pcm_ops snd_mychip_capture_ops = {
1365 .open = snd_mychip_capture_open,
1366 .close = snd_mychip_capture_close,
1367 .ioctl = snd_pcm_lib_ioctl,
1368 .hw_params = snd_mychip_pcm_hw_params,
1369 .hw_free = snd_mychip_pcm_hw_free,
1370 .prepare = snd_mychip_pcm_prepare,
1371 .trigger = snd_mychip_pcm_trigger,
1372 .pointer = snd_mychip_pcm_pointer,
1373 };
1375 /*
1376 * definitions of capture are omitted here...
1377 */
1379 /* create a pcm device */
1380 static int snd_mychip_new_pcm(struct mychip *chip)
1381 {
1382 struct snd_pcm *pcm;
1383 int err;
1385 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1386 if (err < 0)
1387 return err;
1388 pcm->private_data = chip;
1389 strcpy(pcm->name, "My Chip");
1390 chip->pcm = pcm;
1391 /* set operators */
1392 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1393 &snd_mychip_playback_ops);
1394 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1395 &snd_mychip_capture_ops);
1396 /* pre-allocation of buffers */
1397 /* NOTE: this may fail */
1398 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1399 snd_dma_pci_data(chip->pci),
1400 64*1024, 64*1024);
1401 return 0;
1402 }
1405 PCM Constructor
1406 ---------------
1408 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1409 function. It would be better to create a constructor for pcm, namely,
1411 ::
1413 static int snd_mychip_new_pcm(struct mychip *chip)
1414 {
1415 struct snd_pcm *pcm;
1416 int err;
1418 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1419 if (err < 0)
1420 return err;
1421 pcm->private_data = chip;
1422 strcpy(pcm->name, "My Chip");
1423 chip->pcm = pcm;
1424 ....
1425 return 0;
1426 }
1428 The :c:func:`snd_pcm_new()` function takes four arguments. The
1429 first argument is the card pointer to which this pcm is assigned, and
1430 the second is the ID string.
1432 The third argument (``index``, 0 in the above) is the index of this new
1433 pcm. It begins from zero. If you create more than one pcm instances,
1434 specify the different numbers in this argument. For example, ``index =
1435 1`` for the second PCM device.
1437 The fourth and fifth arguments are the number of substreams for playback
1438 and capture, respectively. Here 1 is used for both arguments. When no
1439 playback or capture substreams are available, pass 0 to the
1440 corresponding argument.
1442 If a chip supports multiple playbacks or captures, you can specify more
1443 numbers, but they must be handled properly in open/close, etc.
1444 callbacks. When you need to know which substream you are referring to,
1445 then it can be obtained from :c:type:`struct snd_pcm_substream
1446 <snd_pcm_substream>` data passed to each callback as follows:
1448 ::
1450 struct snd_pcm_substream *substream;
1451 int index = substream->number;
1454 After the pcm is created, you need to set operators for each pcm stream.
1456 ::
1458 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1459 &snd_mychip_playback_ops);
1460 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1461 &snd_mychip_capture_ops);
1463 The operators are defined typically like this:
1465 ::
1467 static struct snd_pcm_ops snd_mychip_playback_ops = {
1468 .open = snd_mychip_pcm_open,
1469 .close = snd_mychip_pcm_close,
1470 .ioctl = snd_pcm_lib_ioctl,
1471 .hw_params = snd_mychip_pcm_hw_params,
1472 .hw_free = snd_mychip_pcm_hw_free,
1473 .prepare = snd_mychip_pcm_prepare,
1474 .trigger = snd_mychip_pcm_trigger,
1475 .pointer = snd_mychip_pcm_pointer,
1476 };
1478 All the callbacks are described in the Operators_ subsection.
1480 After setting the operators, you probably will want to pre-allocate the
1481 buffer. For the pre-allocation, simply call the following:
1483 ::
1485 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1486 snd_dma_pci_data(chip->pci),
1487 64*1024, 64*1024);
1489 It will allocate a buffer up to 64kB as default. Buffer management
1490 details will be described in the later section `Buffer and Memory
1491 Management`_.
1493 Additionally, you can set some extra information for this pcm in
1494 ``pcm->info_flags``. The available values are defined as
1495 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1496 hardware definition (described later). When your soundchip supports only
1497 half-duplex, specify like this:
1499 ::
1501 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1504 ... And the Destructor?
1505 -----------------------
1507 The destructor for a pcm instance is not always necessary. Since the pcm
1508 device will be released by the middle layer code automatically, you
1509 don't have to call the destructor explicitly.
1511 The destructor would be necessary if you created special records
1512 internally and needed to release them. In such a case, set the
1513 destructor function to ``pcm->private_free``:
1515 ::
1517 static void mychip_pcm_free(struct snd_pcm *pcm)
1518 {
1519 struct mychip *chip = snd_pcm_chip(pcm);
1520 /* free your own data */
1521 kfree(chip->my_private_pcm_data);
1522 /* do what you like else */
1523 ....
1524 }
1526 static int snd_mychip_new_pcm(struct mychip *chip)
1527 {
1528 struct snd_pcm *pcm;
1529 ....
1530 /* allocate your own data */
1531 chip->my_private_pcm_data = kmalloc(...);
1532 /* set the destructor */
1533 pcm->private_data = chip;
1534 pcm->private_free = mychip_pcm_free;
1535 ....
1536 }
1540 Runtime Pointer - The Chest of PCM Information
1541 ----------------------------------------------
1543 When the PCM substream is opened, a PCM runtime instance is allocated
1544 and assigned to the substream. This pointer is accessible via
1545 ``substream->runtime``. This runtime pointer holds most information you
1546 need to control the PCM: the copy of hw_params and sw_params
1547 configurations, the buffer pointers, mmap records, spinlocks, etc.
1549 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1550 are the contents of this file:
1552 ::
1554 struct _snd_pcm_runtime {
1555 /* -- Status -- */
1556 struct snd_pcm_substream *trigger_master;
1557 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1558 int overrange;
1559 snd_pcm_uframes_t avail_max;
1560 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1561 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1563 /* -- HW params -- */
1564 snd_pcm_access_t access; /* access mode */
1565 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1566 snd_pcm_subformat_t subformat; /* subformat */
1567 unsigned int rate; /* rate in Hz */
1568 unsigned int channels; /* channels */
1569 snd_pcm_uframes_t period_size; /* period size */
1570 unsigned int periods; /* periods */
1571 snd_pcm_uframes_t buffer_size; /* buffer size */
1572 unsigned int tick_time; /* tick time */
1573 snd_pcm_uframes_t min_align; /* Min alignment for the format */
1574 size_t byte_align;
1575 unsigned int frame_bits;
1576 unsigned int sample_bits;
1577 unsigned int info;
1578 unsigned int rate_num;
1579 unsigned int rate_den;
1581 /* -- SW params -- */
1582 struct timespec tstamp_mode; /* mmap timestamp is updated */
1583 unsigned int period_step;
1584 unsigned int sleep_min; /* min ticks to sleep */
1585 snd_pcm_uframes_t start_threshold;
1586 snd_pcm_uframes_t stop_threshold;
1587 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1588 noise is nearest than this */
1589 snd_pcm_uframes_t silence_size; /* Silence filling size */
1590 snd_pcm_uframes_t boundary; /* pointers wrap point */
1592 snd_pcm_uframes_t silenced_start;
1593 snd_pcm_uframes_t silenced_size;
1595 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1597 /* -- mmap -- */
1598 volatile struct snd_pcm_mmap_status *status;
1599 volatile struct snd_pcm_mmap_control *control;
1600 atomic_t mmap_count;
1602 /* -- locking / scheduling -- */
1603 spinlock_t lock;
1604 wait_queue_head_t sleep;
1605 struct timer_list tick_timer;
1606 struct fasync_struct *fasync;
1608 /* -- private section -- */
1609 void *private_data;
1610 void (*private_free)(struct snd_pcm_runtime *runtime);
1612 /* -- hardware description -- */
1613 struct snd_pcm_hardware hw;
1614 struct snd_pcm_hw_constraints hw_constraints;
1616 /* -- timer -- */
1617 unsigned int timer_resolution; /* timer resolution */
1619 /* -- DMA -- */
1620 unsigned char *dma_area; /* DMA area */
1621 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1622 size_t dma_bytes; /* size of DMA area */
1624 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1626 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1627 /* -- OSS things -- */
1628 struct snd_pcm_oss_runtime oss;
1629 #endif
1630 };
1633 For the operators (callbacks) of each sound driver, most of these
1634 records are supposed to be read-only. Only the PCM middle-layer changes
1635 / updates them. The exceptions are the hardware description (hw) DMA
1636 buffer information and the private data. Besides, if you use the
1637 standard buffer allocation method via
1638 :c:func:`snd_pcm_lib_malloc_pages()`, you don't need to set the
1639 DMA buffer information by yourself.
1641 In the sections below, important records are explained.
1643 Hardware Description
1644 ~~~~~~~~~~~~~~~~~~~~
1646 The hardware descriptor (:c:type:`struct snd_pcm_hardware
1647 <snd_pcm_hardware>`) contains the definitions of the fundamental
1648 hardware configuration. Above all, you'll need to define this in the
1649 `PCM open callback`_. Note that the runtime instance holds the copy of
1650 the descriptor, not the pointer to the existing descriptor. That is,
1651 in the open callback, you can modify the copied descriptor
1652 (``runtime->hw``) as you need. For example, if the maximum number of
1653 channels is 1 only on some chip models, you can still use the same
1654 hardware descriptor and change the channels_max later:
1656 ::
1658 struct snd_pcm_runtime *runtime = substream->runtime;
1659 ...
1660 runtime->hw = snd_mychip_playback_hw; /* common definition */
1661 if (chip->model == VERY_OLD_ONE)
1662 runtime->hw.channels_max = 1;
1664 Typically, you'll have a hardware descriptor as below:
1666 ::
1668 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1669 .info = (SNDRV_PCM_INFO_MMAP |
1670 SNDRV_PCM_INFO_INTERLEAVED |
1671 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1672 SNDRV_PCM_INFO_MMAP_VALID),
1673 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1674 .rates = SNDRV_PCM_RATE_8000_48000,
1675 .rate_min = 8000,
1676 .rate_max = 48000,
1677 .channels_min = 2,
1678 .channels_max = 2,
1679 .buffer_bytes_max = 32768,
1680 .period_bytes_min = 4096,
1681 .period_bytes_max = 32768,
1682 .periods_min = 1,
1683 .periods_max = 1024,
1684 };
1686 - The ``info`` field contains the type and capabilities of this
1687 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1688 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1689 the mmap is supported and which interleaved format is
1690 supported. When the hardware supports mmap, add the
1691 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1692 interleaved or the non-interleaved formats,
1693 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1694 flag must be set, respectively. If both are supported, you can set
1695 both, too.
1697 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1698 specified for the OSS mmap mode. Usually both are set. Of course,
1699 ``MMAP_VALID`` is set only if the mmap is really supported.
1701 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1702 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1703 supports the “pause” operation, while the ``RESUME`` bit means that
1704 the pcm supports the full “suspend/resume” operation. If the
1705 ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1706 the corresponding (pause push/release) commands. The suspend/resume
1707 trigger commands can be defined even without the ``RESUME``
1708 flag. See `Power Management`_ section for details.
1710 When the PCM substreams can be synchronized (typically,
1711 synchronized start/stop of a playback and a capture streams), you
1712 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1713 need to check the linked-list of PCM substreams in the trigger
1714 callback. This will be described in the later section.
1716 - ``formats`` field contains the bit-flags of supported formats
1717 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1718 format, give all or'ed bits. In the example above, the signed 16bit
1719 little-endian format is specified.
1721 - ``rates`` field contains the bit-flags of supported rates
1722 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1723 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1724 provided only for typical rates. If your chip supports
1725 unconventional rates, you need to add the ``KNOT`` bit and set up
1726 the hardware constraint manually (explained later).
1728 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1729 rate. This should correspond somehow to ``rates`` bits.
1731 - ``channel_min`` and ``channel_max`` define, as you might already
1732 expected, the minimum and maximum number of channels.
1734 - ``buffer_bytes_max`` defines the maximum buffer size in
1735 bytes. There is no ``buffer_bytes_min`` field, since it can be
1736 calculated from the minimum period size and the minimum number of
1737 periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1738 maximum size of the period in bytes. ``periods_max`` and
1739 ``periods_min`` define the maximum and minimum number of periods in
1740 the buffer.
1742 The “period” is a term that corresponds to a fragment in the OSS
1743 world. The period defines the size at which a PCM interrupt is
1744 generated. This size strongly depends on the hardware. Generally,
1745 the smaller period size will give you more interrupts, that is,
1746 more controls. In the case of capture, this size defines the input
1747 latency. On the other hand, the whole buffer size defines the
1748 output latency for the playback direction.
1750 - There is also a field ``fifo_size``. This specifies the size of the
1751 hardware FIFO, but currently it is neither used in the driver nor
1752 in the alsa-lib. So, you can ignore this field.
1754 PCM Configurations
1755 ~~~~~~~~~~~~~~~~~~
1757 Ok, let's go back again to the PCM runtime records. The most
1758 frequently referred records in the runtime instance are the PCM
1759 configurations. The PCM configurations are stored in the runtime
1760 instance after the application sends ``hw_params`` data via
1761 alsa-lib. There are many fields copied from hw_params and sw_params
1762 structs. For example, ``format`` holds the format type chosen by the
1763 application. This field contains the enum value
1764 ``SNDRV_PCM_FORMAT_XXX``.
1766 One thing to be noted is that the configured buffer and period sizes
1767 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1768 channels \* samples-size``. For conversion between frames and bytes,
1769 you can use the :c:func:`frames_to_bytes()` and
1770 :c:func:`bytes_to_frames()` helper functions.
1772 ::
1774 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1776 Also, many software parameters (sw_params) are stored in frames, too.
1777 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1778 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1779 frames as signed integer.
1781 DMA Buffer Information
1782 ~~~~~~~~~~~~~~~~~~~~~~
1784 The DMA buffer is defined by the following four fields, ``dma_area``,
1785 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1786 holds the buffer pointer (the logical address). You can call
1787 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1788 the physical address of the buffer. This field is specified only when
1789 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1790 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1792 If you use a standard ALSA function,
1793 :c:func:`snd_pcm_lib_malloc_pages()`, for allocating the buffer,
1794 these fields are set by the ALSA middle layer, and you should *not*
1795 change them by yourself. You can read them but not write them. On the
1796 other hand, if you want to allocate the buffer by yourself, you'll
1797 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1798 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1799 your driver doesn't support mmap, this field is not
1800 necessary. ``dma_addr`` is also optional. You can use dma_private as
1801 you like, too.
1803 Running Status
1804 ~~~~~~~~~~~~~~
1806 The running status can be referred via ``runtime->status``. This is
1807 the pointer to the :c:type:`struct snd_pcm_mmap_status
1808 <snd_pcm_mmap_status>` record. For example, you can get the current
1809 DMA hardware pointer via ``runtime->status->hw_ptr``.
1811 The DMA application pointer can be referred via ``runtime->control``,
1812 which points to the :c:type:`struct snd_pcm_mmap_control
1813 <snd_pcm_mmap_control>` record. However, accessing directly to
1814 this value is not recommended.
1816 Private Data
1817 ~~~~~~~~~~~~
1819 You can allocate a record for the substream and store it in
1820 ``runtime->private_data``. Usually, this is done in the `PCM open
1821 callback`_. Don't mix this with ``pcm->private_data``. The
1822 ``pcm->private_data`` usually points to the chip instance assigned
1823 statically at the creation of PCM, while the ``runtime->private_data``
1824 points to a dynamic data structure created at the PCM open
1825 callback.
1827 ::
1829 static int snd_xxx_open(struct snd_pcm_substream *substream)
1830 {
1831 struct my_pcm_data *data;
1832 ....
1833 data = kmalloc(sizeof(*data), GFP_KERNEL);
1834 substream->runtime->private_data = data;
1835 ....
1836 }
1839 The allocated object must be released in the `close callback`_.
1841 Operators
1842 ---------
1844 OK, now let me give details about each pcm callback (``ops``). In
1845 general, every callback must return 0 if successful, or a negative
1846 error number such as ``-EINVAL``. To choose an appropriate error
1847 number, it is advised to check what value other parts of the kernel
1848 return when the same kind of request fails.
1850 The callback function takes at least the argument with :c:type:`struct
1851 snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1852 record from the given substream instance, you can use the following
1853 macro.
1855 ::
1857 int xxx() {
1858 struct mychip *chip = snd_pcm_substream_chip(substream);
1859 ....
1860 }
1862 The macro reads ``substream->private_data``, which is a copy of
1863 ``pcm->private_data``. You can override the former if you need to
1864 assign different data records per PCM substream. For example, the
1865 cmi8330 driver assigns different ``private_data`` for playback and
1866 capture directions, because it uses two different codecs (SB- and
1867 AD-compatible) for different directions.
1869 PCM open callback
1870 ~~~~~~~~~~~~~~~~~
1872 ::
1874 static int snd_xxx_open(struct snd_pcm_substream *substream);
1876 This is called when a pcm substream is opened.
1878 At least, here you have to initialize the ``runtime->hw``
1879 record. Typically, this is done by like this:
1881 ::
1883 static int snd_xxx_open(struct snd_pcm_substream *substream)
1884 {
1885 struct mychip *chip = snd_pcm_substream_chip(substream);
1886 struct snd_pcm_runtime *runtime = substream->runtime;
1888 runtime->hw = snd_mychip_playback_hw;
1889 return 0;
1890 }
1892 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1893 description.
1895 You can allocate a private data in this callback, as described in
1896 `Private Data`_ section.
1898 If the hardware configuration needs more constraints, set the hardware
1899 constraints here, too. See Constraints_ for more details.
1901 close callback
1902 ~~~~~~~~~~~~~~
1904 ::
1906 static int snd_xxx_close(struct snd_pcm_substream *substream);
1909 Obviously, this is called when a pcm substream is closed.
1911 Any private instance for a pcm substream allocated in the ``open``
1912 callback will be released here.
1914 ::
1916 static int snd_xxx_close(struct snd_pcm_substream *substream)
1917 {
1918 ....
1919 kfree(substream->runtime->private_data);
1920 ....
1921 }
1923 ioctl callback
1924 ~~~~~~~~~~~~~~
1926 This is used for any special call to pcm ioctls. But usually you can
1927 pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`.
1929 hw_params callback
1930 ~~~~~~~~~~~~~~~~~~~
1932 ::
1934 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1935 struct snd_pcm_hw_params *hw_params);
1937 This is called when the hardware parameter (``hw_params``) is set up
1938 by the application, that is, once when the buffer size, the period
1939 size, the format, etc. are defined for the pcm substream.
1941 Many hardware setups should be done in this callback, including the
1942 allocation of buffers.
1944 Parameters to be initialized are retrieved by
1945 :c:func:`params_xxx()` macros. To allocate buffer, you can call a
1946 helper function,
1948 ::
1950 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1952 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1953 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1954 for more details.
1956 Note that this and ``prepare`` callbacks may be called multiple times
1957 per initialization. For example, the OSS emulation may call these
1958 callbacks at each change via its ioctl.
1960 Thus, you need to be careful not to allocate the same buffers many
1961 times, which will lead to memory leaks! Calling the helper function
1962 above many times is OK. It will release the previous buffer
1963 automatically when it was already allocated.
1965 Another note is that this callback is non-atomic (schedulable) as
1966 default, i.e. when no ``nonatomic`` flag set. This is important,
1967 because the ``trigger`` callback is atomic (non-schedulable). That is,
1968 mutexes or any schedule-related functions are not available in
1969 ``trigger`` callback. Please see the subsection Atomicity_ for
1970 details.
1972 hw_free callback
1973 ~~~~~~~~~~~~~~~~~
1975 ::
1977 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1979 This is called to release the resources allocated via
1980 ``hw_params``. For example, releasing the buffer via
1981 :c:func:`snd_pcm_lib_malloc_pages()` is done by calling the
1982 following:
1984 ::
1986 snd_pcm_lib_free_pages(substream);
1988 This function is always called before the close callback is called.
1989 Also, the callback may be called multiple times, too. Keep track
1990 whether the resource was already released.
1992 prepare callback
1993 ~~~~~~~~~~~~~~~~
1995 ::
1997 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1999 This callback is called when the pcm is “prepared”. You can set the
2000 format type, sample rate, etc. here. The difference from ``hw_params``
2001 is that the ``prepare`` callback will be called each time
2002 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2003 underruns, etc.
2005 Note that this callback is now non-atomic. You can use
2006 schedule-related functions safely in this callback.
2008 In this and the following callbacks, you can refer to the values via
2009 the runtime record, ``substream->runtime``. For example, to get the
2010 current rate, format or channels, access to ``runtime->rate``,
2011 ``runtime->format`` or ``runtime->channels``, respectively. The
2012 physical address of the allocated buffer is set to
2013 ``runtime->dma_area``. The buffer and period sizes are in
2014 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2016 Be careful that this callback will be called many times at each setup,
2017 too.
2019 trigger callback
2020 ~~~~~~~~~~~~~~~~
2022 ::
2024 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2026 This is called when the pcm is started, stopped or paused.
2028 Which action is specified in the second argument,
2029 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2030 and ``STOP`` commands must be defined in this callback.
2032 ::
2034 switch (cmd) {
2035 case SNDRV_PCM_TRIGGER_START:
2036 /* do something to start the PCM engine */
2037 break;
2038 case SNDRV_PCM_TRIGGER_STOP:
2039 /* do something to stop the PCM engine */
2040 break;
2041 default:
2042 return -EINVAL;
2043 }
2045 When the pcm supports the pause operation (given in the info field of
2046 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2047 must be handled here, too. The former is the command to pause the pcm,
2048 and the latter to restart the pcm again.
2050 When the pcm supports the suspend/resume operation, regardless of full
2051 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2052 commands must be handled, too. These commands are issued when the
2053 power-management status is changed. Obviously, the ``SUSPEND`` and
2054 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2055 they are identical to the ``STOP`` and ``START`` commands, respectively.
2056 See the `Power Management`_ section for details.
2058 As mentioned, this callback is atomic as default unless ``nonatomic``
2059 flag set, and you cannot call functions which may sleep. The
2060 ``trigger`` callback should be as minimal as possible, just really
2061 triggering the DMA. The other stuff should be initialized
2062 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2064 pointer callback
2065 ~~~~~~~~~~~~~~~~
2067 ::
2069 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2071 This callback is called when the PCM middle layer inquires the current
2072 hardware position on the buffer. The position must be returned in
2073 frames, ranging from 0 to ``buffer_size - 1``.
2075 This is called usually from the buffer-update routine in the pcm
2076 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2077 is called in the interrupt routine. Then the pcm middle layer updates
2078 the position and calculates the available space, and wakes up the
2079 sleeping poll threads, etc.
2081 This callback is also atomic as default.
2083 copy_user, copy_kernel and fill_silence ops
2084 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2086 These callbacks are not mandatory, and can be omitted in most cases.
2087 These callbacks are used when the hardware buffer cannot be in the
2088 normal memory space. Some chips have their own buffer on the hardware
2089 which is not mappable. In such a case, you have to transfer the data
2090 manually from the memory buffer to the hardware buffer. Or, if the
2091 buffer is non-contiguous on both physical and virtual memory spaces,
2092 these callbacks must be defined, too.
2094 If these two callbacks are defined, copy and set-silence operations
2095 are done by them. The detailed will be described in the later section
2096 `Buffer and Memory Management`_.
2098 ack callback
2099 ~~~~~~~~~~~~
2101 This callback is also not mandatory. This callback is called when the
2102 ``appl_ptr`` is updated in read or write operations. Some drivers like
2103 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2104 internal buffer, and this callback is useful only for such a purpose.
2106 This callback is atomic as default.
2108 page callback
2109 ~~~~~~~~~~~~~
2111 This callback is optional too. This callback is used mainly for
2112 non-contiguous buffers. The mmap calls this callback to get the page
2113 address. Some examples will be explained in the later section `Buffer
2114 and Memory Management`_, too.
2116 PCM Interrupt Handler
2117 ---------------------
2119 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2120 interrupt handler in the sound driver is to update the buffer position
2121 and to tell the PCM middle layer when the buffer position goes across
2122 the prescribed period size. To inform this, call the
2123 :c:func:`snd_pcm_period_elapsed()` function.
2125 There are several types of sound chips to generate the interrupts.
2127 Interrupts at the period (fragment) boundary
2128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2130 This is the most frequently found type: the hardware generates an
2131 interrupt at each period boundary. In this case, you can call
2132 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2134 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2135 its argument. Thus, you need to keep the substream pointer accessible
2136 from the chip instance. For example, define ``substream`` field in the
2137 chip record to hold the current running substream pointer, and set the
2138 pointer value at ``open`` callback (and reset at ``close`` callback).
2140 If you acquire a spinlock in the interrupt handler, and the lock is used
2141 in other pcm callbacks, too, then you have to release the lock before
2142 calling :c:func:`snd_pcm_period_elapsed()`, because
2143 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2144 inside.
2146 Typical code would be like:
2148 ::
2151 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2152 {
2153 struct mychip *chip = dev_id;
2154 spin_lock(&chip->lock);
2155 ....
2156 if (pcm_irq_invoked(chip)) {
2157 /* call updater, unlock before it */
2158 spin_unlock(&chip->lock);
2159 snd_pcm_period_elapsed(chip->substream);
2160 spin_lock(&chip->lock);
2161 /* acknowledge the interrupt if necessary */
2162 }
2163 ....
2164 spin_unlock(&chip->lock);
2165 return IRQ_HANDLED;
2166 }
2170 High frequency timer interrupts
2171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2173 This happens when the hardware doesn't generate interrupts at the period
2174 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2175 or ymfpci drivers). In this case, you need to check the current hardware
2176 position and accumulate the processed sample length at each interrupt.
2177 When the accumulated size exceeds the period size, call
2178 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2180 Typical code would be like the following.
2182 ::
2185 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2186 {
2187 struct mychip *chip = dev_id;
2188 spin_lock(&chip->lock);
2189 ....
2190 if (pcm_irq_invoked(chip)) {
2191 unsigned int last_ptr, size;
2192 /* get the current hardware pointer (in frames) */
2193 last_ptr = get_hw_ptr(chip);
2194 /* calculate the processed frames since the
2195 * last update
2196 */
2197 if (last_ptr < chip->last_ptr)
2198 size = runtime->buffer_size + last_ptr
2199 - chip->last_ptr;
2200 else
2201 size = last_ptr - chip->last_ptr;
2202 /* remember the last updated point */
2203 chip->last_ptr = last_ptr;
2204 /* accumulate the size */
2205 chip->size += size;
2206 /* over the period boundary? */
2207 if (chip->size >= runtime->period_size) {
2208 /* reset the accumulator */
2209 chip->size %= runtime->period_size;
2210 /* call updater */
2211 spin_unlock(&chip->lock);
2212 snd_pcm_period_elapsed(substream);
2213 spin_lock(&chip->lock);
2214 }
2215 /* acknowledge the interrupt if necessary */
2216 }
2217 ....
2218 spin_unlock(&chip->lock);
2219 return IRQ_HANDLED;
2220 }
2224 On calling :c:func:`snd_pcm_period_elapsed()`
2225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2227 In both cases, even if more than one period are elapsed, you don't have
2228 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2229 once. And the pcm layer will check the current hardware pointer and
2230 update to the latest status.
2232 Atomicity
2233 ---------
2235 One of the most important (and thus difficult to debug) problems in
2236 kernel programming are race conditions. In the Linux kernel, they are
2237 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2238 race condition can happen in an interrupt handler, it has to be managed
2239 atomically, and you have to use a spinlock to protect the critical
2240 session. If the critical section is not in interrupt handler code and if
2241 taking a relatively long time to execute is acceptable, you should use
2242 mutexes or semaphores instead.
2244 As already seen, some pcm callbacks are atomic and some are not. For
2245 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2246 callback is atomic. This means, the latter is called already in a
2247 spinlock held by the PCM middle layer. Please take this atomicity into
2248 account when you choose a locking scheme in the callbacks.
2250 In the atomic callbacks, you cannot use functions which may call
2251 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2252 mutexes can sleep, and hence they cannot be used inside the atomic
2253 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2254 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2256 All three atomic callbacks (trigger, pointer, and ack) are called with
2257 local interrupts disabled.
2259 The recent changes in PCM core code, however, allow all PCM operations
2260 to be non-atomic. This assumes that the all caller sides are in
2261 non-atomic contexts. For example, the function
2262 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2263 interrupt handler. But, if you set up the driver to use a threaded
2264 interrupt handler, this call can be in non-atomic context, too. In such
2265 a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2266 <snd_pcm>` object after creating it. When this flag is set, mutex
2267 and rwsem are used internally in the PCM core instead of spin and
2268 rwlocks, so that you can call all PCM functions safely in a non-atomic
2269 context.
2271 Constraints
2272 -----------
2274 If your chip supports unconventional sample rates, or only the limited
2275 samples, you need to set a constraint for the condition.
2277 For example, in order to restrict the sample rates in the some supported
2278 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2279 call this function in the open callback.
2281 ::
2283 static unsigned int rates[] =
2284 {4000, 10000, 22050, 44100};
2285 static struct snd_pcm_hw_constraint_list constraints_rates = {
2286 .count = ARRAY_SIZE(rates),
2287 .list = rates,
2288 .mask = 0,
2289 };
2291 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2292 {
2293 int err;
2294 ....
2295 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2296 SNDRV_PCM_HW_PARAM_RATE,
2297 &constraints_rates);
2298 if (err < 0)
2299 return err;
2300 ....
2301 }
2305 There are many different constraints. Look at ``sound/pcm.h`` for a
2306 complete list. You can even define your own constraint rules. For
2307 example, let's suppose my_chip can manage a substream of 1 channel if
2308 and only if the format is ``S16_LE``, otherwise it supports any format
2309 specified in the :c:type:`struct snd_pcm_hardware
2310 <snd_pcm_hardware>` structure (or in any other
2311 constraint_list). You can build a rule like this:
2313 ::
2315 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2316 struct snd_pcm_hw_rule *rule)
2317 {
2318 struct snd_interval *c = hw_param_interval(params,
2319 SNDRV_PCM_HW_PARAM_CHANNELS);
2320 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2321 struct snd_interval ch;
2323 snd_interval_any(&ch);
2324 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2325 ch.min = ch.max = 1;
2326 ch.integer = 1;
2327 return snd_interval_refine(c, &ch);
2328 }
2329 return 0;
2330 }
2333 Then you need to call this function to add your rule:
2335 ::
2337 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2338 hw_rule_channels_by_format, NULL,
2339 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2341 The rule function is called when an application sets the PCM format, and
2342 it refines the number of channels accordingly. But an application may
2343 set the number of channels before setting the format. Thus you also need
2344 to define the inverse rule:
2346 ::
2348 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2349 struct snd_pcm_hw_rule *rule)
2350 {
2351 struct snd_interval *c = hw_param_interval(params,
2352 SNDRV_PCM_HW_PARAM_CHANNELS);
2353 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2354 struct snd_mask fmt;
2356 snd_mask_any(&fmt); /* Init the struct */
2357 if (c->min < 2) {
2358 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2359 return snd_mask_refine(f, &fmt);
2360 }
2361 return 0;
2362 }
2365 ... and in the open callback:
2367 ::
2369 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2370 hw_rule_format_by_channels, NULL,
2371 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2373 I won't give more details here, rather I would like to say, “Luke, use
2374 the source.”
2376 Control Interface
2377 =================
2379 General
2380 -------
2382 The control interface is used widely for many switches, sliders, etc.
2383 which are accessed from user-space. Its most important use is the mixer
2384 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2385 implemented on the control kernel API.
2387 ALSA has a well-defined AC97 control module. If your chip supports only
2388 the AC97 and nothing else, you can skip this section.
2390 The control API is defined in ``<sound/control.h>``. Include this file
2391 if you want to add your own controls.
2393 Definition of Controls
2394 ----------------------
2396 To create a new control, you need to define the following three
2397 callbacks: ``info``, ``get`` and ``put``. Then, define a
2398 :c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
2400 ::
2403 static struct snd_kcontrol_new my_control = {
2404 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2405 .name = "PCM Playback Switch",
2406 .index = 0,
2407 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2408 .private_value = 0xffff,
2409 .info = my_control_info,
2410 .get = my_control_get,
2411 .put = my_control_put
2412 };
2415 The ``iface`` field specifies the control type,
2416 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2417 for global controls that are not logically part of the mixer. If the
2418 control is closely associated with some specific device on the sound
2419 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2420 and specify the device number with the ``device`` and ``subdevice``
2421 fields.
2423 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2424 control name is very important, because its role is classified from
2425 its name. There are pre-defined standard control names. The details
2426 are described in the `Control Names`_ subsection.
2428 The ``index`` field holds the index number of this control. If there
2429 are several different controls with the same name, they can be
2430 distinguished by the index number. This is the case when several
2431 codecs exist on the card. If the index is zero, you can omit the
2432 definition above.
2434 The ``access`` field contains the access type of this control. Give
2435 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2436 there. The details will be explained in the `Access Flags`_
2437 subsection.
2439 The ``private_value`` field contains an arbitrary long integer value
2440 for this record. When using the generic ``info``, ``get`` and ``put``
2441 callbacks, you can pass a value through this field. If several small
2442 numbers are necessary, you can combine them in bitwise. Or, it's
2443 possible to give a pointer (casted to unsigned long) of some record to
2444 this field, too.
2446 The ``tlv`` field can be used to provide metadata about the control;
2447 see the `Metadata`_ subsection.
2449 The other three are `Control Callbacks`_.
2451 Control Names
2452 -------------
2454 There are some standards to define the control names. A control is
2455 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2457 The first, ``SOURCE``, specifies the source of the control, and is a
2458 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2459 pre-defined sources.
2461 The second, ``DIRECTION``, is one of the following strings according to
2462 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2463 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2464 capture directions.
2466 The third, ``FUNCTION``, is one of the following strings according to
2467 the function of the control: “Switch”, “Volume” and “Route”.
2469 The example of control names are, thus, “Master Capture Switch” or “PCM
2470 Playback Volume”.
2472 There are some exceptions:
2474 Global capture and playback
2475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2477 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2478 global capture (input) source, switch and volume. Similarly, “Playback
2479 Switch” and “Playback Volume” are used for the global output gain switch
2480 and volume.
2482 Tone-controls
2483 ~~~~~~~~~~~~~
2485 tone-control switch and volumes are specified like “Tone Control - XXX”,
2486 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2487 Center”.
2489 3D controls
2490 ~~~~~~~~~~~
2492 3D-control switches and volumes are specified like “3D Control - XXX”,
2493 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2495 Mic boost
2496 ~~~~~~~~~
2498 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2500 More precise information can be found in
2501 ``Documentation/sound/designs/control-names.rst``.
2503 Access Flags
2504 ------------
2506 The access flag is the bitmask which specifies the access type of the
2507 given control. The default access type is
2508 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2509 allowed to this control. When the access flag is omitted (i.e. = 0), it
2510 is considered as ``READWRITE`` access as default.
2512 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2513 instead. In this case, you don't have to define the ``put`` callback.
2514 Similarly, when the control is write-only (although it's a rare case),
2515 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2516 callback.
2518 If the control value changes frequently (e.g. the VU meter),
2519 ``VOLATILE`` flag should be given. This means that the control may be
2520 changed without `Change notification`_. Applications should poll such
2521 a control constantly.
2523 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2524 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2526 Control Callbacks
2527 -----------------
2529 info callback
2530 ~~~~~~~~~~~~~
2532 The ``info`` callback is used to get detailed information on this
2533 control. This must store the values of the given :c:type:`struct
2534 snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2535 for a boolean control with a single element:
2537 ::
2540 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2541 struct snd_ctl_elem_info *uinfo)
2542 {
2543 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2544 uinfo->count = 1;
2545 uinfo->value.integer.min = 0;
2546 uinfo->value.integer.max = 1;
2547 return 0;
2548 }
2552 The ``type`` field specifies the type of the control. There are
2553 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2554 ``INTEGER64``. The ``count`` field specifies the number of elements in
2555 this control. For example, a stereo volume would have count = 2. The
2556 ``value`` field is a union, and the values stored are depending on the
2557 type. The boolean and integer types are identical.
2559 The enumerated type is a bit different from others. You'll need to set
2560 the string for the currently given item index.
2562 ::
2564 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2565 struct snd_ctl_elem_info *uinfo)
2566 {
2567 static char *texts[4] = {
2568 "First", "Second", "Third", "Fourth"
2569 };
2570 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2571 uinfo->count = 1;
2572 uinfo->value.enumerated.items = 4;
2573 if (uinfo->value.enumerated.item > 3)
2574 uinfo->value.enumerated.item = 3;
2575 strcpy(uinfo->value.enumerated.name,
2576 texts[uinfo->value.enumerated.item]);
2577 return 0;
2578 }
2580 The above callback can be simplified with a helper function,
2581 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2582 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2583 it's a matter of taste.)
2585 ::
2587 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2588 struct snd_ctl_elem_info *uinfo)
2589 {
2590 static char *texts[4] = {
2591 "First", "Second", "Third", "Fourth"
2592 };
2593 return snd_ctl_enum_info(uinfo, 1, 4, texts);
2594 }
2597 Some common info callbacks are available for your convenience:
2598 :c:func:`snd_ctl_boolean_mono_info()` and
2599 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2600 is an info callback for a mono channel boolean item, just like
2601 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2602 stereo channel boolean item.
2604 get callback
2605 ~~~~~~~~~~~~
2607 This callback is used to read the current value of the control and to
2608 return to user-space.
2610 For example,
2612 ::
2615 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2616 struct snd_ctl_elem_value *ucontrol)
2617 {
2618 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2619 ucontrol->value.integer.value[0] = get_some_value(chip);
2620 return 0;
2621 }
2625 The ``value`` field depends on the type of control as well as on the
2626 info callback. For example, the sb driver uses this field to store the
2627 register offset, the bit-shift and the bit-mask. The ``private_value``
2628 field is set as follows:
2630 ::
2632 .private_value = reg | (shift << 16) | (mask << 24)
2634 and is retrieved in callbacks like
2636 ::
2638 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2639 struct snd_ctl_elem_value *ucontrol)
2640 {
2641 int reg = kcontrol->private_value & 0xff;
2642 int shift = (kcontrol->private_value >> 16) & 0xff;
2643 int mask = (kcontrol->private_value >> 24) & 0xff;
2644 ....
2645 }
2647 In the ``get`` callback, you have to fill all the elements if the
2648 control has more than one elements, i.e. ``count > 1``. In the example
2649 above, we filled only one element (``value.integer.value[0]``) since
2650 it's assumed as ``count = 1``.
2652 put callback
2653 ~~~~~~~~~~~~
2655 This callback is used to write a value from user-space.
2657 For example,
2659 ::
2662 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2663 struct snd_ctl_elem_value *ucontrol)
2664 {
2665 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2666 int changed = 0;
2667 if (chip->current_value !=
2668 ucontrol->value.integer.value[0]) {
2669 change_current_value(chip,
2670 ucontrol->value.integer.value[0]);
2671 changed = 1;
2672 }
2673 return changed;
2674 }
2678 As seen above, you have to return 1 if the value is changed. If the
2679 value is not changed, return 0 instead. If any fatal error happens,
2680 return a negative error code as usual.
2682 As in the ``get`` callback, when the control has more than one
2683 elements, all elements must be evaluated in this callback, too.
2685 Callbacks are not atomic
2686 ~~~~~~~~~~~~~~~~~~~~~~~~
2688 All these three callbacks are basically not atomic.
2690 Control Constructor
2691 -------------------
2693 When everything is ready, finally we can create a new control. To create
2694 a control, there are two functions to be called,
2695 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2697 In the simplest way, you can do like this:
2699 ::
2701 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2702 if (err < 0)
2703 return err;
2705 where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2706 <snd_kcontrol_new>` object defined above, and chip is the object
2707 pointer to be passed to kcontrol->private_data which can be referred
2708 to in callbacks.
2710 :c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2711 snd_kcontrol <snd_kcontrol>` instance, and
2712 :c:func:`snd_ctl_add()` assigns the given control component to the
2713 card.
2715 Change Notification
2716 -------------------
2718 If you need to change and update a control in the interrupt routine, you
2719 can call :c:func:`snd_ctl_notify()`. For example,
2721 ::
2723 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2725 This function takes the card pointer, the event-mask, and the control id
2726 pointer for the notification. The event-mask specifies the types of
2727 notification, for example, in the above example, the change of control
2728 values is notified. The id pointer is the pointer of :c:type:`struct
2729 snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2730 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2731 interrupts.
2733 Metadata
2734 --------
2736 To provide information about the dB values of a mixer control, use on of
2737 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2738 variable containing this information, set the ``tlv.p`` field to point to
2739 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2740 in the ``access`` field; like this:
2742 ::
2744 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2746 static struct snd_kcontrol_new my_control = {
2747 ...
2748 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2749 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2750 ...
2751 .tlv.p = db_scale_my_control,
2752 };
2755 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2756 about a mixer control where each step in the control's value changes the
2757 dB value by a constant dB amount. The first parameter is the name of the
2758 variable to be defined. The second parameter is the minimum value, in
2759 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2760 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2761 the control.
2763 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2764 about a mixer control where the control's value affects the output
2765 linearly. The first parameter is the name of the variable to be defined.
2766 The second parameter is the minimum value, in units of 0.01 dB. The
2767 third parameter is the maximum value, in units of 0.01 dB. If the
2768 minimum value mutes the control, set the second parameter to
2769 ``TLV_DB_GAIN_MUTE``.
2771 API for AC97 Codec
2772 ==================
2774 General
2775 -------
2777 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2778 write much code to control it. Only low-level control routines are
2779 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2781 Full Code Example
2782 -----------------
2784 ::
2786 struct mychip {
2787 ....
2788 struct snd_ac97 *ac97;
2789 ....
2790 };
2792 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2793 unsigned short reg)
2794 {
2795 struct mychip *chip = ac97->private_data;
2796 ....
2797 /* read a register value here from the codec */
2798 return the_register_value;
2799 }
2801 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2802 unsigned short reg, unsigned short val)
2803 {
2804 struct mychip *chip = ac97->private_data;
2805 ....
2806 /* write the given register value to the codec */
2807 }
2809 static int snd_mychip_ac97(struct mychip *chip)
2810 {
2811 struct snd_ac97_bus *bus;
2812 struct snd_ac97_template ac97;
2813 int err;
2814 static struct snd_ac97_bus_ops ops = {
2815 .write = snd_mychip_ac97_write,
2816 .read = snd_mychip_ac97_read,
2817 };
2819 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2820 if (err < 0)
2821 return err;
2822 memset(&ac97, 0, sizeof(ac97));
2823 ac97.private_data = chip;
2824 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2825 }
2828 AC97 Constructor
2829 ----------------
2831 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2832 with an ``ac97_bus_ops_t`` record with callback functions.
2834 ::
2836 struct snd_ac97_bus *bus;
2837 static struct snd_ac97_bus_ops ops = {
2838 .write = snd_mychip_ac97_write,
2839 .read = snd_mychip_ac97_read,
2840 };
2842 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2844 The bus record is shared among all belonging ac97 instances.
2846 And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2847 snd_ac97_template <snd_ac97_template>` record together with
2848 the bus pointer created above.
2850 ::
2852 struct snd_ac97_template ac97;
2853 int err;
2855 memset(&ac97, 0, sizeof(ac97));
2856 ac97.private_data = chip;
2857 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2859 where chip->ac97 is a pointer to a newly created ``ac97_t``
2860 instance. In this case, the chip pointer is set as the private data,
2861 so that the read/write callback functions can refer to this chip
2862 instance. This instance is not necessarily stored in the chip
2863 record. If you need to change the register values from the driver, or
2864 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2865 the corresponding functions.
2867 AC97 Callbacks
2868 --------------
2870 The standard callbacks are ``read`` and ``write``. Obviously they
2871 correspond to the functions for read and write accesses to the
2872 hardware low-level codes.
2874 The ``read`` callback returns the register value specified in the
2875 argument.
2877 ::
2879 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2880 unsigned short reg)
2881 {
2882 struct mychip *chip = ac97->private_data;
2883 ....
2884 return the_register_value;
2885 }
2887 Here, the chip can be cast from ``ac97->private_data``.
2889 Meanwhile, the ``write`` callback is used to set the register
2890 value
2892 ::
2894 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2895 unsigned short reg, unsigned short val)
2898 These callbacks are non-atomic like the control API callbacks.
2900 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2902 The ``reset`` callback is used to reset the codec. If the chip
2903 requires a special kind of reset, you can define this callback.
2905 The ``wait`` callback is used to add some waiting time in the standard
2906 initialization of the codec. If the chip requires the extra waiting
2907 time, define this callback.
2909 The ``init`` callback is used for additional initialization of the
2910 codec.
2912 Updating Registers in The Driver
2913 --------------------------------
2915 If you need to access to the codec from the driver, you can call the
2916 following functions: :c:func:`snd_ac97_write()`,
2917 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2918 :c:func:`snd_ac97_update_bits()`.
2920 Both :c:func:`snd_ac97_write()` and
2921 :c:func:`snd_ac97_update()` functions are used to set a value to
2922 the given register (``AC97_XXX``). The difference between them is that
2923 :c:func:`snd_ac97_update()` doesn't write a value if the given
2924 value has been already set, while :c:func:`snd_ac97_write()`
2925 always rewrites the value.
2927 ::
2929 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2930 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2932 :c:func:`snd_ac97_read()` is used to read the value of the given
2933 register. For example,
2935 ::
2937 value = snd_ac97_read(ac97, AC97_MASTER);
2939 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2940 the given register.
2942 ::
2944 snd_ac97_update_bits(ac97, reg, mask, value);
2946 Also, there is a function to change the sample rate (of a given register
2947 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2948 codec: :c:func:`snd_ac97_set_rate()`.
2950 ::
2952 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2955 The following registers are available to set the rate:
2956 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2957 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2958 specified, the register is not really changed but the corresponding
2959 IEC958 status bits will be updated.
2961 Clock Adjustment
2962 ----------------
2964 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2965 (to save a quartz!). In this case, change the field ``bus->clock`` to
2966 the corresponding value. For example, intel8x0 and es1968 drivers have
2967 their own function to read from the clock.
2969 Proc Files
2970 ----------
2972 The ALSA AC97 interface will create a proc file such as
2973 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2974 can refer to these files to see the current status and registers of
2975 the codec.
2977 Multiple Codecs
2978 ---------------
2980 When there are several codecs on the same card, you need to call
2981 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
2982 greater. The ``num`` field specifies the codec number.
2984 If you set up multiple codecs, you either need to write different
2985 callbacks for each codec or check ``ac97->num`` in the callback
2986 routines.
2988 MIDI (MPU401-UART) Interface
2989 ============================
2991 General
2992 -------
2994 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
2995 soundcard supports the standard MPU401-UART interface, most likely you
2996 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2997 ``<sound/mpu401.h>``.
2999 Some soundchips have a similar but slightly different implementation of
3000 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3002 MIDI Constructor
3003 ----------------
3005 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3007 ::
3009 struct snd_rawmidi *rmidi;
3010 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3011 irq, &rmidi);
3014 The first argument is the card pointer, and the second is the index of
3015 this component. You can create up to 8 rawmidi devices.
3017 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3018 it's not a special one, you can use ``MPU401_HW_MPU401``.
3020 The 4th argument is the I/O port address. Many backward-compatible
3021 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3022 PCI I/O region. It depends on the chip design.
3024 The 5th argument is a bitflag for additional information. When the I/O
3025 port address above is part of the PCI I/O region, the MPU401 I/O port
3026 might have been already allocated (reserved) by the driver itself. In
3027 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3028 mpu401-uart layer will allocate the I/O ports by itself.
3030 When the controller supports only the input or output MIDI stream, pass
3031 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3032 respectively. Then the rawmidi instance is created as a single stream.
3034 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3035 (via readb and writeb) instead of iob and outb. In this case, you have
3036 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3038 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3039 the default interrupt handler. The driver needs to call
3040 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3041 processing the output stream in the irq handler.
3043 If the MPU-401 interface shares its interrupt with the other logical
3044 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3045 `below <#MIDI-Interrupt-Handler>`__).
3047 Usually, the port address corresponds to the command port and port + 1
3048 corresponds to the data port. If not, you may change the ``cport``
3049 field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3050 However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
3051 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3052 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3053 <snd_mpu401>` explicitly,
3055 ::
3057 struct snd_mpu401 *mpu;
3058 mpu = rmidi->private_data;
3060 and reset the ``cport`` as you like:
3062 ::
3064 mpu->cport = my_own_control_port;
3066 The 6th argument specifies the ISA irq number that will be allocated. If
3067 no interrupt is to be allocated (because your code is already allocating
3068 a shared interrupt, or because the device does not use interrupts), pass
3069 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3070 will be used instead.
3072 MIDI Interrupt Handler
3073 ----------------------
3075 When the interrupt is allocated in
3076 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3077 handler is automatically used, hence you don't have anything else to do
3078 than creating the mpu401 stuff. Otherwise, you have to set
3079 ``MPU401_INFO_IRQ_HOOK``, and call
3080 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3081 interrupt handler when it has determined that a UART interrupt has
3082 occurred.
3084 In this case, you need to pass the private_data of the returned rawmidi
3085 object from :c:func:`snd_mpu401_uart_new()` as the second
3086 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3088 ::
3090 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3093 RawMIDI Interface
3094 =================
3096 Overview
3097 --------
3099 The raw MIDI interface is used for hardware MIDI ports that can be
3100 accessed as a byte stream. It is not used for synthesizer chips that do
3101 not directly understand MIDI.
3103 ALSA handles file and buffer management. All you have to do is to write
3104 some code to move data between the buffer and the hardware.
3106 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3108 RawMIDI Constructor
3109 -------------------
3111 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3112 function:
3114 ::
3116 struct snd_rawmidi *rmidi;
3117 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3118 if (err < 0)
3119 return err;
3120 rmidi->private_data = chip;
3121 strcpy(rmidi->name, "My MIDI");
3122 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3123 SNDRV_RAWMIDI_INFO_INPUT |
3124 SNDRV_RAWMIDI_INFO_DUPLEX;
3126 The first argument is the card pointer, the second argument is the ID
3127 string.
3129 The third argument is the index of this component. You can create up to
3130 8 rawmidi devices.
3132 The fourth and fifth arguments are the number of output and input
3133 substreams, respectively, of this device (a substream is the equivalent
3134 of a MIDI port).
3136 Set the ``info_flags`` field to specify the capabilities of the
3137 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3138 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3139 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3140 output and input at the same time.
3142 After the rawmidi device is created, you need to set the operators
3143 (callbacks) for each substream. There are helper functions to set the
3144 operators for all the substreams of a device:
3146 ::
3148 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3149 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3151 The operators are usually defined like this:
3153 ::
3155 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3156 .open = snd_mymidi_output_open,
3157 .close = snd_mymidi_output_close,
3158 .trigger = snd_mymidi_output_trigger,
3159 };
3161 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3163 If there are more than one substream, you should give a unique name to
3164 each of them:
3166 ::
3168 struct snd_rawmidi_substream *substream;
3169 list_for_each_entry(substream,
3170 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3171 list {
3172 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3173 }
3174 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3176 RawMIDI Callbacks
3177 -----------------
3179 In all the callbacks, the private data that you've set for the rawmidi
3180 device can be accessed as ``substream->rmidi->private_data``.
3182 If there is more than one port, your callbacks can determine the port
3183 index from the struct snd_rawmidi_substream data passed to each
3184 callback:
3186 ::
3188 struct snd_rawmidi_substream *substream;
3189 int index = substream->number;
3191 RawMIDI open callback
3192 ~~~~~~~~~~~~~~~~~~~~~
3194 ::
3196 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3199 This is called when a substream is opened. You can initialize the
3200 hardware here, but you shouldn't start transmitting/receiving data yet.
3202 RawMIDI close callback
3203 ~~~~~~~~~~~~~~~~~~~~~~
3205 ::
3207 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3209 Guess what.
3211 The ``open`` and ``close`` callbacks of a rawmidi device are
3212 serialized with a mutex, and can sleep.
3214 Rawmidi trigger callback for output substreams
3215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3217 ::
3219 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3222 This is called with a nonzero ``up`` parameter when there is some data
3223 in the substream buffer that must be transmitted.
3225 To read data from the buffer, call
3226 :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3227 of bytes that have been read; this will be less than the number of bytes
3228 requested when there are no more data in the buffer. After the data have
3229 been transmitted successfully, call
3230 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3231 substream buffer:
3233 ::
3235 unsigned char data;
3236 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3237 if (snd_mychip_try_to_transmit(data))
3238 snd_rawmidi_transmit_ack(substream, 1);
3239 else
3240 break; /* hardware FIFO full */
3241 }
3243 If you know beforehand that the hardware will accept data, you can use
3244 the :c:func:`snd_rawmidi_transmit()` function which reads some
3245 data and removes them from the buffer at once:
3247 ::
3249 while (snd_mychip_transmit_possible()) {
3250 unsigned char data;
3251 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3252 break; /* no more data */
3253 snd_mychip_transmit(data);
3254 }
3256 If you know beforehand how many bytes you can accept, you can use a
3257 buffer size greater than one with the
3258 :c:func:`snd_rawmidi_transmit\*()` functions.
3260 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3261 before the substream buffer has been emptied, you have to continue
3262 transmitting data later, either in an interrupt handler, or with a
3263 timer if the hardware doesn't have a MIDI transmit interrupt.
3265 The ``trigger`` callback is called with a zero ``up`` parameter when
3266 the transmission of data should be aborted.
3268 RawMIDI trigger callback for input substreams
3269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3271 ::
3273 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3276 This is called with a nonzero ``up`` parameter to enable receiving data,
3277 or with a zero ``up`` parameter do disable receiving data.
3279 The ``trigger`` callback must not sleep; the actual reading of data
3280 from the device is usually done in an interrupt handler.
3282 When data reception is enabled, your interrupt handler should call
3283 :c:func:`snd_rawmidi_receive()` for all received data:
3285 ::
3287 void snd_mychip_midi_interrupt(...)
3288 {
3289 while (mychip_midi_available()) {
3290 unsigned char data;
3291 data = mychip_midi_read();
3292 snd_rawmidi_receive(substream, &data, 1);
3293 }
3294 }
3297 drain callback
3298 ~~~~~~~~~~~~~~
3300 ::
3302 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3305 This is only used with output substreams. This function should wait
3306 until all data read from the substream buffer have been transmitted.
3307 This ensures that the device can be closed and the driver unloaded
3308 without losing data.
3310 This callback is optional. If you do not set ``drain`` in the struct
3311 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3312 instead.
3314 Miscellaneous Devices
3315 =====================
3317 FM OPL3
3318 -------
3320 The FM OPL3 is still used in many chips (mainly for backward
3321 compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3322 is defined in ``<sound/opl3.h>``.
3324 FM registers can be directly accessed through the direct-FM API, defined
3325 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3326 accessed through the Hardware-Dependent Device direct-FM extension API,
3327 whereas in OSS compatible mode, FM registers can be accessed with the
3328 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3330 To create the OPL3 component, you have two functions to call. The first
3331 one is a constructor for the ``opl3_t`` instance.
3333 ::
3335 struct snd_opl3 *opl3;
3336 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3337 integrated, &opl3);
3339 The first argument is the card pointer, the second one is the left port
3340 address, and the third is the right port address. In most cases, the
3341 right port is placed at the left port + 2.
3343 The fourth argument is the hardware type.
3345 When the left and right ports have been already allocated by the card
3346 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3347 the opl3 module will allocate the specified ports by itself.
3349 When the accessing the hardware requires special method instead of the
3350 standard I/O access, you can create opl3 instance separately with
3351 :c:func:`snd_opl3_new()`.
3353 ::
3355 struct snd_opl3 *opl3;
3356 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3358 Then set ``command``, ``private_data`` and ``private_free`` for the
3359 private access function, the private data and the destructor. The
3360 ``l_port`` and ``r_port`` are not necessarily set. Only the command
3361 must be set properly. You can retrieve the data from the
3362 ``opl3->private_data`` field.
3364 After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3365 call :c:func:`snd_opl3_init()` to initialize the chip to the
3366 proper state. Note that :c:func:`snd_opl3_create()` always calls
3367 it internally.
3369 If the opl3 instance is created successfully, then create a hwdep device
3370 for this opl3.
3372 ::
3374 struct snd_hwdep *opl3hwdep;
3375 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3377 The first argument is the ``opl3_t`` instance you created, and the
3378 second is the index number, usually 0.
3380 The third argument is the index-offset for the sequencer client assigned
3381 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3382 always takes 0).
3384 Hardware-Dependent Devices
3385 --------------------------
3387 Some chips need user-space access for special controls or for loading
3388 the micro code. In such a case, you can create a hwdep
3389 (hardware-dependent) device. The hwdep API is defined in
3390 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3391 ``isa/sb/sb16_csp.c``.
3393 The creation of the ``hwdep`` instance is done via
3394 :c:func:`snd_hwdep_new()`.
3396 ::
3398 struct snd_hwdep *hw;
3399 snd_hwdep_new(card, "My HWDEP", 0, &hw);
3401 where the third argument is the index number.
3403 You can then pass any pointer value to the ``private_data``. If you
3404 assign a private data, you should define the destructor, too. The
3405 destructor function is set in the ``private_free`` field.
3407 ::
3409 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3410 hw->private_data = p;
3411 hw->private_free = mydata_free;
3413 and the implementation of the destructor would be:
3415 ::
3417 static void mydata_free(struct snd_hwdep *hw)
3418 {
3419 struct mydata *p = hw->private_data;
3420 kfree(p);
3421 }
3423 The arbitrary file operations can be defined for this instance. The file
3424 operators are defined in the ``ops`` table. For example, assume that
3425 this chip needs an ioctl.
3427 ::
3429 hw->ops.open = mydata_open;
3430 hw->ops.ioctl = mydata_ioctl;
3431 hw->ops.release = mydata_release;
3433 And implement the callback functions as you like.
3435 IEC958 (S/PDIF)
3436 ---------------
3438 Usually the controls for IEC958 devices are implemented via the control
3439 interface. There is a macro to compose a name string for IEC958
3440 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3441 ``<include/asound.h>``.
3443 There are some standard controls for IEC958 status bits. These controls
3444 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3445 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3446 callback, you don't specify the value field for this type (the count
3447 field must be set, though).
3449 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3450 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3451 returns the bitmask for professional mode. They are read-only controls,
3452 and are defined as MIXER controls (iface =
3453 ``SNDRV_CTL_ELEM_IFACE_MIXER``).
3455 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3456 setting the current default IEC958 bits. Note that this one is usually
3457 defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3458 although in some places it's defined as a MIXER control.
3460 In addition, you can define the control switches to enable/disable or to
3461 set the raw bit mode. The implementation will depend on the chip, but
3462 the control should be named as “IEC958 xxx”, preferably using the
3463 :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3465 You can find several cases, for example, ``pci/emu10k1``,
3466 ``pci/ice1712``, or ``pci/cmipci.c``.
3468 Buffer and Memory Management
3469 ============================
3471 Buffer Types
3472 ------------
3474 ALSA provides several different buffer allocation functions depending on
3475 the bus and the architecture. All these have a consistent API. The
3476 allocation of physically-contiguous pages is done via
3477 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3478 type.
3480 The allocation of pages with fallback is
3481 :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3482 to allocate the specified pages but if the pages are not available, it
3483 tries to reduce the page sizes until enough space is found.
3485 The release the pages, call :c:func:`snd_free_xxx_pages()`
3486 function.
3488 Usually, ALSA drivers try to allocate and reserve a large contiguous
3489 physical space at the time the module is loaded for the later use. This
3490 is called “pre-allocation”. As already written, you can call the
3491 following function at pcm instance construction time (in the case of PCI
3492 bus).
3494 ::
3496 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3497 snd_dma_pci_data(pci), size, max);
3499 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3500 the maximum size to be changed via the ``prealloc`` proc file. The
3501 allocator will try to get an area as large as possible within the
3502 given size.
3504 The second argument (type) and the third argument (device pointer) are
3505 dependent on the bus. In the case of the ISA bus, pass
3506 :c:func:`snd_dma_isa_data()` as the third argument with
3507 ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3508 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the
3509 ``snd_dma_continuous_data(GFP_KERNEL)`` device pointer, where
3510 ``GFP_KERNEL`` is the kernel allocation flag to use. For the PCI
3511 scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with
3512 ``snd_dma_pci_data(pci)`` (see the `Non-Contiguous Buffers`_
3513 section).
3515 Once the buffer is pre-allocated, you can use the allocator in the
3516 ``hw_params`` callback:
3518 ::
3520 snd_pcm_lib_malloc_pages(substream, size);
3522 Note that you have to pre-allocate to use this function.
3524 External Hardware Buffers
3525 -------------------------
3527 Some chips have their own hardware buffers and the DMA transfer from the
3528 host memory is not available. In such a case, you need to either 1)
3529 copy/set the audio data directly to the external hardware buffer, or 2)
3530 make an intermediate buffer and copy/set the data from it to the
3531 external hardware buffer in interrupts (or in tasklets, preferably).
3533 The first case works fine if the external hardware buffer is large
3534 enough. This method doesn't need any extra buffers and thus is more
3535 effective. You need to define the ``copy_user`` and ``copy_kernel``
3536 callbacks for the data transfer, in addition to ``fill_silence``
3537 callback for playback. However, there is a drawback: it cannot be
3538 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3540 The second case allows for mmap on the buffer, although you have to
3541 handle an interrupt or a tasklet to transfer the data from the
3542 intermediate buffer to the hardware buffer. You can find an example in
3543 the vxpocket driver.
3545 Another case is when the chip uses a PCI memory-map region for the
3546 buffer instead of the host memory. In this case, mmap is available only
3547 on certain architectures like the Intel one. In non-mmap mode, the data
3548 cannot be transferred as in the normal way. Thus you need to define the
3549 ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3550 as in the cases above. The examples are found in ``rme32.c`` and
3551 ``rme96.c``.
3553 The implementation of the ``copy_user``, ``copy_kernel`` and
3554 ``silence`` callbacks depends upon whether the hardware supports
3555 interleaved or non-interleaved samples. The ``copy_user`` callback is
3556 defined like below, a bit differently depending whether the direction
3557 is playback or capture:
3559 ::
3561 static int playback_copy_user(struct snd_pcm_substream *substream,
3562 int channel, unsigned long pos,
3563 void __user *src, unsigned long count);
3564 static int capture_copy_user(struct snd_pcm_substream *substream,
3565 int channel, unsigned long pos,
3566 void __user *dst, unsigned long count);
3568 In the case of interleaved samples, the second argument (``channel``) is
3569 not used. The third argument (``pos``) points the current position
3570 offset in bytes.
3572 The meaning of the fourth argument is different between playback and
3573 capture. For playback, it holds the source data pointer, and for
3574 capture, it's the destination data pointer.
3576 The last argument is the number of bytes to be copied.
3578 What you have to do in this callback is again different between playback
3579 and capture directions. In the playback case, you copy the given amount
3580 of data (``count``) at the specified pointer (``src``) to the specified
3581 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3582 way, the copy would be like:
3584 ::
3586 my_memcpy_from_user(my_buffer + pos, src, count);
3588 For the capture direction, you copy the given amount of data (``count``)
3589 at the specified offset (``pos``) on the hardware buffer to the
3590 specified pointer (``dst``).
3592 ::
3594 my_memcpy_to_user(dst, my_buffer + pos, count);
3596 Here the functions are named as ``from_user`` and ``to_user`` because
3597 it's the user-space buffer that is passed to these callbacks. That
3598 is, the callback is supposed to copy from/to the user-space data
3599 directly to/from the hardware buffer.
3601 Careful readers might notice that these callbacks receive the
3602 arguments in bytes, not in frames like other callbacks. It's because
3603 it would make coding easier like the examples above, and also it makes
3604 easier to unify both the interleaved and non-interleaved cases, as
3605 explained in the following.
3607 In the case of non-interleaved samples, the implementation will be a bit
3608 more complicated. The callback is called for each channel, passed by
3609 the second argument, so totally it's called for N-channels times per
3610 transfer.
3612 The meaning of other arguments are almost same as the interleaved
3613 case. The callback is supposed to copy the data from/to the given
3614 user-space buffer, but only for the given channel. For the detailed
3615 implementations, please check ``isa/gus/gus_pcm.c`` or
3616 "pci/rme9652/rme9652.c" as examples.
3618 The above callbacks are the copy from/to the user-space buffer. There
3619 are some cases where we want copy from/to the kernel-space buffer
3620 instead. In such a case, ``copy_kernel`` callback is called. It'd
3621 look like:
3623 ::
3625 static int playback_copy_kernel(struct snd_pcm_substream *substream,
3626 int channel, unsigned long pos,
3627 void *src, unsigned long count);
3628 static int capture_copy_kernel(struct snd_pcm_substream *substream,
3629 int channel, unsigned long pos,
3630 void *dst, unsigned long count);
3632 As found easily, the only difference is that the buffer pointer is
3633 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3634 in the fourth argument. Correspondingly, the implementation would be
3635 a version without the user-copy, such as:
3637 ::
3639 my_memcpy(my_buffer + pos, src, count);
3641 Usually for the playback, another callback ``fill_silence`` is
3642 defined. It's implemented in a similar way as the copy callbacks
3643 above:
3645 ::
3647 static int silence(struct snd_pcm_substream *substream, int channel,
3648 unsigned long pos, unsigned long count);
3650 The meanings of arguments are the same as in the ``copy_user`` and
3651 ``copy_kernel`` callbacks, although there is no buffer pointer
3652 argument. In the case of interleaved samples, the channel argument has
3653 no meaning, as well as on ``copy_*`` callbacks.
3655 The role of ``fill_silence`` callback is to set the given amount
3656 (``count``) of silence data at the specified offset (``pos``) on the
3657 hardware buffer. Suppose that the data format is signed (that is, the
3658 silent-data is 0), and the implementation using a memset-like function
3659 would be like:
3661 ::
3663 my_memset(my_buffer + pos, 0, count);
3665 In the case of non-interleaved samples, again, the implementation
3666 becomes a bit more complicated, as it's called N-times per transfer
3667 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3669 Non-Contiguous Buffers
3670 ----------------------
3672 If your hardware supports the page table as in emu10k1 or the buffer
3673 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3674 provides an interface for handling SG-buffers. The API is provided in
3675 ``<sound/pcm.h>``.
3677 For creating the SG-buffer handler, call
3678 :c:func:`snd_pcm_lib_preallocate_pages()` or
3679 :c:func:`snd_pcm_lib_preallocate_pages_for_all()` with
3680 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3681 pre-allocator. You need to pass ``snd_dma_pci_data(pci)``, where pci is
3682 the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3683 well. The ``struct snd_sg_buf`` instance is created as
3684 ``substream->dma_private``. You can cast the pointer like:
3686 ::
3688 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3690 Then call :c:func:`snd_pcm_lib_malloc_pages()` in the ``hw_params``
3691 callback as well as in the case of normal PCI buffer. The SG-buffer
3692 handler will allocate the non-contiguous kernel pages of the given size
3693 and map them onto the virtually contiguous memory. The virtual pointer
3694 is addressed in runtime->dma_area. The physical address
3695 (``runtime->dma_addr``) is set to zero, because the buffer is
3696 physically non-contiguous. The physical address table is set up in
3697 ``sgbuf->table``. You can get the physical address at a certain offset
3698 via :c:func:`snd_pcm_sgbuf_get_addr()`.
3700 When a SG-handler is used, you need to set
3701 :c:func:`snd_pcm_sgbuf_ops_page()` as the ``page`` callback. (See
3702 `page callback`_ section.)
3704 To release the data, call :c:func:`snd_pcm_lib_free_pages()` in
3705 the ``hw_free`` callback as usual.
3707 Vmalloc'ed Buffers
3708 ------------------
3710 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3711 example, for an intermediate buffer. Since the allocated pages are not
3712 contiguous, you need to set the ``page`` callback to obtain the physical
3713 address at every offset.
3715 The implementation of ``page`` callback would be like this:
3717 ::
3719 #include <linux/vmalloc.h>
3721 /* get the physical page pointer on the given offset */
3722 static struct page *mychip_page(struct snd_pcm_substream *substream,
3723 unsigned long offset)
3724 {
3725 void *pageptr = substream->runtime->dma_area + offset;
3726 return vmalloc_to_page(pageptr);
3727 }
3729 Proc Interface
3730 ==============
3732 ALSA provides an easy interface for procfs. The proc files are very
3733 useful for debugging. I recommend you set up proc files if you write a
3734 driver and want to get a running status or register dumps. The API is
3735 found in ``<sound/info.h>``.
3737 To create a proc file, call :c:func:`snd_card_proc_new()`.
3739 ::
3741 struct snd_info_entry *entry;
3742 int err = snd_card_proc_new(card, "my-file", &entry);
3744 where the second argument specifies the name of the proc file to be
3745 created. The above example will create a file ``my-file`` under the
3746 card directory, e.g. ``/proc/asound/card0/my-file``.
3748 Like other components, the proc entry created via
3749 :c:func:`snd_card_proc_new()` will be registered and released
3750 automatically in the card registration and release functions.
3752 When the creation is successful, the function stores a new instance in
3753 the pointer given in the third argument. It is initialized as a text
3754 proc file for read only. To use this proc file as a read-only text file
3755 as it is, set the read callback with a private data via
3756 :c:func:`snd_info_set_text_ops()`.
3758 ::
3760 snd_info_set_text_ops(entry, chip, my_proc_read);
3762 where the second argument (``chip``) is the private data to be used in
3763 the callbacks. The third parameter specifies the read buffer size and
3764 the fourth (``my_proc_read``) is the callback function, which is
3765 defined like
3767 ::
3769 static void my_proc_read(struct snd_info_entry *entry,
3770 struct snd_info_buffer *buffer);
3772 In the read callback, use :c:func:`snd_iprintf()` for output
3773 strings, which works just like normal :c:func:`printf()`. For
3774 example,
3776 ::
3778 static void my_proc_read(struct snd_info_entry *entry,
3779 struct snd_info_buffer *buffer)
3780 {
3781 struct my_chip *chip = entry->private_data;
3783 snd_iprintf(buffer, "This is my chip!\n");
3784 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3785 }
3787 The file permissions can be changed afterwards. As default, it's set as
3788 read only for all users. If you want to add write permission for the
3789 user (root as default), do as follows:
3791 ::
3793 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3795 and set the write buffer size and the callback
3797 ::
3799 entry->c.text.write = my_proc_write;
3801 For the write callback, you can use :c:func:`snd_info_get_line()`
3802 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3803 a string from the line. Some examples are found in
3804 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3806 For a raw-data proc-file, set the attributes as follows:
3808 ::
3810 static struct snd_info_entry_ops my_file_io_ops = {
3811 .read = my_file_io_read,
3812 };
3814 entry->content = SNDRV_INFO_CONTENT_DATA;
3815 entry->private_data = chip;
3816 entry->c.ops = &my_file_io_ops;
3817 entry->size = 4096;
3818 entry->mode = S_IFREG | S_IRUGO;
3820 For the raw data, ``size`` field must be set properly. This specifies
3821 the maximum size of the proc file access.
3823 The read/write callbacks of raw mode are more direct than the text mode.
3824 You need to use a low-level I/O functions such as
3825 :c:func:`copy_from/to_user()` to transfer the data.
3827 ::
3829 static ssize_t my_file_io_read(struct snd_info_entry *entry,
3830 void *file_private_data,
3831 struct file *file,
3832 char *buf,
3833 size_t count,
3834 loff_t pos)
3835 {
3836 if (copy_to_user(buf, local_data + pos, count))
3837 return -EFAULT;
3838 return count;
3839 }
3841 If the size of the info entry has been set up properly, ``count`` and
3842 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3843 have to check the range in the callbacks unless any other condition is
3844 required.
3846 Power Management
3847 ================
3849 If the chip is supposed to work with suspend/resume functions, you need
3850 to add power-management code to the driver. The additional code for
3851 power-management should be ifdef-ed with ``CONFIG_PM``.
3853 If the driver *fully* supports suspend/resume that is, the device can be
3854 properly resumed to its state when suspend was called, you can set the
3855 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3856 possible when the registers of the chip can be safely saved and restored
3857 to RAM. If this is set, the trigger callback is called with
3858 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3860 Even if the driver doesn't support PM fully but partial suspend/resume
3861 is still possible, it's still worthy to implement suspend/resume
3862 callbacks. In such a case, applications would reset the status by
3863 calling :c:func:`snd_pcm_prepare()` and restart the stream
3864 appropriately. Hence, you can define suspend/resume callbacks below but
3865 don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3867 Note that the trigger with SUSPEND can always be called when
3868 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3869 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3870 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3871 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3872 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3873 to keep it for compatibility reasons.)
3875 In the earlier version of ALSA drivers, a common power-management layer
3876 was provided, but it has been removed. The driver needs to define the
3877 suspend/resume hooks according to the bus the device is connected to. In
3878 the case of PCI drivers, the callbacks look like below:
3880 ::
3882 #ifdef CONFIG_PM
3883 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
3884 {
3885 .... /* do things for suspend */
3886 return 0;
3887 }
3888 static int snd_my_resume(struct pci_dev *pci)
3889 {
3890 .... /* do things for suspend */
3891 return 0;
3892 }
3893 #endif
3895 The scheme of the real suspend job is as follows.
3897 1. Retrieve the card and the chip data.
3899 2. Call :c:func:`snd_power_change_state()` with
3900 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3902 3. Call :c:func:`snd_pcm_suspend_all()` to suspend the running
3903 PCM streams.
3905 4. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3906 each codec.
3908 5. Save the register values if necessary.
3910 6. Stop the hardware if necessary.
3912 7. Disable the PCI device by calling
3913 :c:func:`pci_disable_device()`. Then, call
3914 :c:func:`pci_save_state()` at last.
3916 A typical code would be like:
3918 ::
3920 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
3921 {
3922 /* (1) */
3923 struct snd_card *card = pci_get_drvdata(pci);
3924 struct mychip *chip = card->private_data;
3925 /* (2) */
3926 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3927 /* (3) */
3928 snd_pcm_suspend_all(chip->pcm);
3929 /* (4) */
3930 snd_ac97_suspend(chip->ac97);
3931 /* (5) */
3932 snd_mychip_save_registers(chip);
3933 /* (6) */
3934 snd_mychip_stop_hardware(chip);
3935 /* (7) */
3936 pci_disable_device(pci);
3937 pci_save_state(pci);
3938 return 0;
3939 }
3942 The scheme of the real resume job is as follows.
3944 1. Retrieve the card and the chip data.
3946 2. Set up PCI. First, call :c:func:`pci_restore_state()`. Then
3947 enable the pci device again by calling
3948 :c:func:`pci_enable_device()`. Call
3949 :c:func:`pci_set_master()` if necessary, too.
3951 3. Re-initialize the chip.
3953 4. Restore the saved registers if necessary.
3955 5. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
3957 6. Restart the hardware (if any).
3959 7. Call :c:func:`snd_power_change_state()` with
3960 ``SNDRV_CTL_POWER_D0`` to notify the processes.
3962 A typical code would be like:
3964 ::
3966 static int mychip_resume(struct pci_dev *pci)
3967 {
3968 /* (1) */
3969 struct snd_card *card = pci_get_drvdata(pci);
3970 struct mychip *chip = card->private_data;
3971 /* (2) */
3972 pci_restore_state(pci);
3973 pci_enable_device(pci);
3974 pci_set_master(pci);
3975 /* (3) */
3976 snd_mychip_reinit_chip(chip);
3977 /* (4) */
3978 snd_mychip_restore_registers(chip);
3979 /* (5) */
3980 snd_ac97_resume(chip->ac97);
3981 /* (6) */
3982 snd_mychip_restart_chip(chip);
3983 /* (7) */
3984 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
3985 return 0;
3986 }
3988 As shown in the above, it's better to save registers after suspending
3989 the PCM operations via :c:func:`snd_pcm_suspend_all()` or
3990 :c:func:`snd_pcm_suspend()`. It means that the PCM streams are
3991 already stopped when the register snapshot is taken. But, remember that
3992 you don't have to restart the PCM stream in the resume callback. It'll
3993 be restarted via trigger call with ``SNDRV_PCM_TRIGGER_RESUME`` when
3994 necessary.
3996 OK, we have all callbacks now. Let's set them up. In the initialization
3997 of the card, make sure that you can get the chip data from the card
3998 instance, typically via ``private_data`` field, in case you created the
3999 chip data individually.
4001 ::
4003 static int snd_mychip_probe(struct pci_dev *pci,
4004 const struct pci_device_id *pci_id)
4005 {
4006 ....
4007 struct snd_card *card;
4008 struct mychip *chip;
4009 int err;
4010 ....
4011 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4012 0, &card);
4013 ....
4014 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
4015 ....
4016 card->private_data = chip;
4017 ....
4018 }
4020 When you created the chip data with :c:func:`snd_card_new()`, it's
4021 anyway accessible via ``private_data`` field.
4023 ::
4025 static int snd_mychip_probe(struct pci_dev *pci,
4026 const struct pci_device_id *pci_id)
4027 {
4028 ....
4029 struct snd_card *card;
4030 struct mychip *chip;
4031 int err;
4032 ....
4033 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4034 sizeof(struct mychip), &card);
4035 ....
4036 chip = card->private_data;
4037 ....
4038 }
4040 If you need a space to save the registers, allocate the buffer for it
4041 here, too, since it would be fatal if you cannot allocate a memory in
4042 the suspend phase. The allocated buffer should be released in the
4043 corresponding destructor.
4045 And next, set suspend/resume callbacks to the pci_driver.
4047 ::
4049 static struct pci_driver driver = {
4050 .name = KBUILD_MODNAME,
4051 .id_table = snd_my_ids,
4052 .probe = snd_my_probe,
4053 .remove = snd_my_remove,
4054 #ifdef CONFIG_PM
4055 .suspend = snd_my_suspend,
4056 .resume = snd_my_resume,
4057 #endif
4058 };
4060 Module Parameters
4061 =================
4063 There are standard module options for ALSA. At least, each module should
4064 have the ``index``, ``id`` and ``enable`` options.
4066 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
4067 cards), they should be arrays. The default initial values are defined
4068 already as constants for easier programming:
4070 ::
4072 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
4073 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
4074 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
4076 If the module supports only a single card, they could be single
4077 variables, instead. ``enable`` option is not always necessary in this
4078 case, but it would be better to have a dummy option for compatibility.
4080 The module parameters must be declared with the standard
4081 ``module_param()()``, ``module_param_array()()`` and
4082 :c:func:`MODULE_PARM_DESC()` macros.
4084 The typical coding would be like below:
4086 ::
4088 #define CARD_NAME "My Chip"
4090 module_param_array(index, int, NULL, 0444);
4091 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
4092 module_param_array(id, charp, NULL, 0444);
4093 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
4094 module_param_array(enable, bool, NULL, 0444);
4095 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4097 Also, don't forget to define the module description, classes, license
4098 and devices. Especially, the recent modprobe requires to define the
4099 module license as GPL, etc., otherwise the system is shown as “tainted”.
4101 ::
4103 MODULE_DESCRIPTION("My Chip");
4104 MODULE_LICENSE("GPL");
4105 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
4108 How To Put Your Driver Into ALSA Tree
4109 =====================================
4111 General
4112 -------
4114 So far, you've learned how to write the driver codes. And you might have
4115 a question now: how to put my own driver into the ALSA driver tree? Here
4116 (finally :) the standard procedure is described briefly.
4118 Suppose that you create a new PCI driver for the card “xyz”. The card
4119 module name would be snd-xyz. The new driver is usually put into the
4120 alsa-driver tree, ``alsa-driver/pci`` directory in the case of PCI
4121 cards. Then the driver is evaluated, audited and tested by developers
4122 and users. After a certain time, the driver will go to the alsa-kernel
4123 tree (to the corresponding directory, such as ``alsa-kernel/pci``) and
4124 eventually will be integrated into the Linux 2.6 tree (the directory
4125 would be ``linux/sound/pci``).
4127 In the following sections, the driver code is supposed to be put into
4128 alsa-driver tree. The two cases are covered: a driver consisting of a
4129 single source file and one consisting of several source files.
4131 Driver with A Single Source File
4132 --------------------------------
4134 1. Modify alsa-driver/pci/Makefile
4136 Suppose you have a file xyz.c. Add the following two lines
4138 ::
4140 snd-xyz-objs := xyz.o
4141 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4143 2. Create the Kconfig entry
4145 Add the new entry of Kconfig for your xyz driver. config SND_XYZ
4146 tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
4147 to include support for Foobar XYZ soundcard. To compile this driver
4148 as a module, choose M here: the module will be called snd-xyz. the
4149 line, select SND_PCM, specifies that the driver xyz supports PCM. In
4150 addition to SND_PCM, the following components are supported for
4151 select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
4152 SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
4153 SND_AC97_CODEC. Add the select command for each supported
4154 component.
4156 Note that some selections imply the lowlevel selections. For example,
4157 PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4158 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4159 the lowlevel selections again.
4161 For the details of Kconfig script, refer to the kbuild documentation.
4163 3. Run cvscompile script to re-generate the configure script and build
4164 the whole stuff again.
4166 Drivers with Several Source Files
4167 ---------------------------------
4169 Suppose that the driver snd-xyz have several source files. They are
4170 located in the new subdirectory, pci/xyz.
4172 1. Add a new directory (``xyz``) in ``alsa-driver/pci/Makefile`` as
4173 below
4175 ::
4177 obj-$(CONFIG_SND) += xyz/
4180 2. Under the directory ``xyz``, create a Makefile
4182 ::
4184 ifndef SND_TOPDIR
4185 SND_TOPDIR=../..
4186 endif
4188 include $(SND_TOPDIR)/toplevel.config
4189 include $(SND_TOPDIR)/Makefile.conf
4191 snd-xyz-objs := xyz.o abc.o def.o
4193 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4195 include $(SND_TOPDIR)/Rules.make
4197 3. Create the Kconfig entry
4199 This procedure is as same as in the last section.
4201 4. Run cvscompile script to re-generate the configure script and build
4202 the whole stuff again.
4204 Useful Functions
4205 ================
4207 :c:func:`snd_printk()` and friends
4208 ---------------------------------------
4210 ALSA provides a verbose version of the :c:func:`printk()` function.
4211 If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4212 prints the given message together with the file name and the line of the
4213 caller. The ``KERN_XXX`` prefix is processed as well as the original
4214 :c:func:`printk()` does, so it's recommended to add this prefix,
4215 e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4217 There are also :c:func:`printk()`'s for debugging.
4218 :c:func:`snd_printd()` can be used for general debugging purposes.
4219 If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4220 just like :c:func:`snd_printk()`. If the ALSA is compiled without
4221 the debugging flag, it's ignored.
4223 :c:func:`snd_printdd()` is compiled in only when
4224 ``CONFIG_SND_DEBUG_VERBOSE`` is set. Please note that
4225 ``CONFIG_SND_DEBUG_VERBOSE`` is not set as default even if you configure
4226 the alsa-driver with ``--with-debug=full`` option. You need to give
4227 explicitly ``--with-debug=detect`` option instead.
4229 :c:func:`snd_BUG()`
4230 ------------------------
4232 It shows the ``BUG?`` message and stack trace as well as
4233 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4234 fatal error happens there.
4236 When no debug flag is set, this macro is ignored.
4238 :c:func:`snd_BUG_ON()`
4239 ----------------------------
4241 :c:func:`snd_BUG_ON()` macro is similar with
4242 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4243 it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4244 return -EINVAL;
4246 The macro takes an conditional expression to evaluate. When
4247 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4248 the warning message such as ``BUG? (xxx)`` normally followed by stack
4249 trace. In both cases it returns the evaluated value.
4251 Acknowledgments
4252 ===============
4254 I would like to thank Phil Kerr for his help for improvement and
4255 corrections of this document.
4257 Kevin Conder reformatted the original plain-text to the DocBook format.
4259 Giuliano Pochini corrected typos and contributed the example codes in
4260 the hardware constraints section.