5 :Author: Takashi Iwai <tiwai@suse.de>
10 This document describes how to write an `ALSA (Advanced Linux Sound
11 Architecture) <http://www.alsa-project.org/>`__ driver. The document
12 focuses mainly on PCI soundcards. In the case of other device types, the
13 API might be different, too. However, at least the ALSA kernel API is
14 consistent, and therefore it would be still a bit help for writing them.
16 This document targets people who already have enough C language skills
17 and have basic linux kernel programming knowledge. This document doesn't
18 explain the general topic of linux kernel coding and doesn't cover
19 low-level driver implementation details. It only describes the standard
20 way to write a PCI sound driver on ALSA.
22 This document is still a draft version. Any feedback and corrections,
31 The file tree structure of ALSA driver is depicted below.
63 This directory contains the middle layer which is the heart of ALSA
64 drivers. In this directory, the native ALSA modules are stored. The
65 sub-directories contain different modules and are dependent upon the
71 The codes for PCM and mixer OSS emulation modules are stored in this
72 directory. The rawmidi OSS emulation is included in the ALSA rawmidi
73 code since it's quite small. The sequencer code is stored in
74 ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
79 This directory and its sub-directories are for the ALSA sequencer. This
80 directory contains the sequencer core and primary sequencer modules such
81 like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
82 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
87 This contains the OSS sequencer emulation codes.
92 This is the place for the public header files of ALSA drivers, which are
93 to be exported to user-space, or included by several files at different
94 directories. Basically, the private header files should not be placed in
95 this directory, but you may still find files there, due to historical
101 This directory contains code shared among different drivers on different
102 architectures. They are hence supposed not to be architecture-specific.
103 For example, the dummy pcm driver and the serial MIDI driver are found
104 in this directory. In the sub-directories, there is code for components
105 which are independent from bus and cpu architectures.
110 The MPU401 and MPU401-UART modules are stored here.
112 drivers/opl3 and opl4
113 ~~~~~~~~~~~~~~~~~~~~~
115 The OPL3 and OPL4 FM-synth stuff is found here.
120 This contains the ALSA i2c components.
122 Although there is a standard i2c layer on Linux, ALSA has its own i2c
123 code for some cards, because the soundcard needs only a simple operation
124 and the standard i2c API is too complicated for such a purpose.
129 This contains the synth middle-level modules.
131 So far, there is only Emu8000/Emu10k1 synth driver under the
132 ``synth/emux`` sub-directory.
137 This directory and its sub-directories hold the top-level card modules
138 for PCI soundcards and the code specific to the PCI BUS.
140 The drivers compiled from a single file are stored directly in the pci
141 directory, while the drivers with several source files are stored on
142 their own sub-directory (e.g. emu10k1, ice1712).
147 This directory and its sub-directories hold the top-level card modules
150 arm, ppc, and sparc directories
151 -------------------------------
153 They are used for top-level card modules which are specific to one of
159 This directory contains the USB-audio driver. In the latest version, the
160 USB MIDI driver is integrated in the usb-audio driver.
165 The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
166 be in the pci directory, because their API is identical to that of
172 This directory contains the codes for ASoC (ALSA System on Chip)
173 layer including ASoC core, codec and machine drivers.
178 Here contains OSS/Lite codes.
179 All codes have been deprecated except for dmasound on m68k as of
183 Basic Flow for PCI Drivers
184 ==========================
189 The minimum flow for PCI soundcards is as follows:
191 - define the PCI ID table (see the section `PCI Entries`_).
193 - create ``probe`` callback.
195 - create ``remove`` callback.
197 - create a :c:type:`struct pci_driver <pci_driver>` structure
198 containing the three pointers above.
200 - create an ``init`` function just calling the
201 :c:func:`pci_register_driver()` to register the pci_driver
204 - create an ``exit`` function to call the
205 :c:func:`pci_unregister_driver()` function.
210 The code example is shown below. Some parts are kept unimplemented at
211 this moment but will be filled in the next sections. The numbers in the
212 comment lines of the :c:func:`snd_mychip_probe()` function refer
213 to details explained in the following section.
217 #include <linux/init.h>
218 #include <linux/pci.h>
219 #include <linux/slab.h>
220 #include <sound/core.h>
221 #include <sound/initval.h>
223 /* module parameters (see "Module Parameters") */
224 /* SNDRV_CARDS: maximum number of cards supported by this module */
225 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
226 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
227 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
229 /* definition of the chip-specific record */
231 struct snd_card *card;
232 /* the rest of the implementation will be in section
233 * "PCI Resource Management"
237 /* chip-specific destructor
238 * (see "PCI Resource Management")
240 static int snd_mychip_free(struct mychip *chip)
242 .... /* will be implemented later... */
245 /* component-destructor
246 * (see "Management of Cards and Components")
248 static int snd_mychip_dev_free(struct snd_device *device)
250 return snd_mychip_free(device->device_data);
253 /* chip-specific constructor
254 * (see "Management of Cards and Components")
256 static int snd_mychip_create(struct snd_card *card,
258 struct mychip **rchip)
262 static struct snd_device_ops ops = {
263 .dev_free = snd_mychip_dev_free,
268 /* check PCI availability here
269 * (see "PCI Resource Management")
273 /* allocate a chip-specific data with zero filled */
274 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
280 /* rest of initialization here; will be implemented
281 * later, see "PCI Resource Management"
285 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
287 snd_mychip_free(chip);
295 /* constructor -- see "Driver Constructor" sub-section */
296 static int snd_mychip_probe(struct pci_dev *pci,
297 const struct pci_device_id *pci_id)
300 struct snd_card *card;
305 if (dev >= SNDRV_CARDS)
313 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
319 err = snd_mychip_create(card, pci, &chip);
324 strcpy(card->driver, "My Chip");
325 strcpy(card->shortname, "My Own Chip 123");
326 sprintf(card->longname, "%s at 0x%lx irq %i",
327 card->shortname, chip->port, chip->irq);
330 .... /* implemented later */
333 err = snd_card_register(card);
338 pci_set_drvdata(pci, card);
347 /* destructor -- see the "Destructor" sub-section */
348 static void snd_mychip_remove(struct pci_dev *pci)
350 snd_card_free(pci_get_drvdata(pci));
358 The real constructor of PCI drivers is the ``probe`` callback. The
359 ``probe`` callback and other component-constructors which are called
360 from the ``probe`` callback cannot be used with the ``__init`` prefix
361 because any PCI device could be a hotplug device.
363 In the ``probe`` callback, the following scheme is often used.
365 1) Check and increment the device index.
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
372 if (dev >= SNDRV_CARDS)
380 where ``enable[dev]`` is the module option.
382 Each time the ``probe`` callback is called, check the availability of
383 the device. If not available, simply increment the device index and
384 returns. dev will be incremented also later (`step 7
385 <#set-the-pci-driver-data-and-return-zero>`__).
387 2) Create a card instance
388 ~~~~~~~~~~~~~~~~~~~~~~~~~
392 struct snd_card *card;
395 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
399 The details will be explained in the section `Management of Cards and
402 3) Create a main component
403 ~~~~~~~~~~~~~~~~~~~~~~~~~~
405 In this part, the PCI resources are allocated.
411 err = snd_mychip_create(card, pci, &chip);
415 The details will be explained in the section `PCI Resource
418 When something goes wrong, the probe function needs to deal with the
419 error. In this example, we have a single error handling path placed
420 at the end of the function.
428 Since each component can be properly freed, the single
429 :c:func:`snd_card_free()` call should suffice in most cases.
432 4) Set the driver ID and name strings.
433 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437 strcpy(card->driver, "My Chip");
438 strcpy(card->shortname, "My Own Chip 123");
439 sprintf(card->longname, "%s at 0x%lx irq %i",
440 card->shortname, chip->port, chip->irq);
442 The driver field holds the minimal ID string of the chip. This is used
443 by alsa-lib's configurator, so keep it simple but unique. Even the
444 same driver can have different driver IDs to distinguish the
445 functionality of each chip type.
447 The shortname field is a string shown as more verbose name. The longname
448 field contains the information shown in ``/proc/asound/cards``.
450 5) Create other components, such as mixer, MIDI, etc.
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
453 Here you define the basic components such as `PCM <#PCM-Interface>`__,
454 mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
455 `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
456 Also, if you want a `proc file <#Proc-Interface>`__, define it here,
459 6) Register the card instance.
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464 err = snd_card_register(card);
468 Will be explained in the section `Management of Cards and
471 7) Set the PCI driver data and return zero.
472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
476 pci_set_drvdata(pci, card);
480 In the above, the card record is stored. This pointer is used in the
481 remove callback and power-management callbacks, too.
486 The destructor, remove callback, simply releases the card instance. Then
487 the ALSA middle layer will release all the attached components
490 It would be typically just :c:func:`calling snd_card_free()`:
494 static void snd_mychip_remove(struct pci_dev *pci)
496 snd_card_free(pci_get_drvdata(pci));
500 The above code assumes that the card pointer is set to the PCI driver
506 For the above example, at least the following include files are
511 #include <linux/init.h>
512 #include <linux/pci.h>
513 #include <linux/slab.h>
514 #include <sound/core.h>
515 #include <sound/initval.h>
517 where the last one is necessary only when module options are defined
518 in the source file. If the code is split into several files, the files
519 without module options don't need them.
521 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
522 interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
523 :c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
524 to include ``<linux/delay.h>`` too.
526 The ALSA interfaces like the PCM and control APIs are defined in other
527 ``<sound/xxx.h>`` header files. They have to be included after
530 Management of Cards and Components
531 ==================================
536 For each soundcard, a “card” record must be allocated.
538 A card record is the headquarters of the soundcard. It manages the whole
539 list of devices (components) on the soundcard, such as PCM, mixers,
540 MIDI, synthesizer, and so on. Also, the card record holds the ID and the
541 name strings of the card, manages the root of proc files, and controls
542 the power-management states and hotplug disconnections. The component
543 list on the card record is used to manage the correct release of
544 resources at destruction.
546 As mentioned above, to create a card instance, call
547 :c:func:`snd_card_new()`.
551 struct snd_card *card;
553 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
556 The function takes six arguments: the parent device pointer, the
557 card-index number, the id string, the module pointer (usually
558 ``THIS_MODULE``), the size of extra-data space, and the pointer to
559 return the card instance. The extra_size argument is used to allocate
560 card->private_data for the chip-specific data. Note that these data are
561 allocated by :c:func:`snd_card_new()`.
563 The first argument, the pointer of struct :c:type:`struct device
564 <device>`, specifies the parent device. For PCI devices, typically
565 ``&pci->`` is passed there.
570 After the card is created, you can attach the components (devices) to
571 the card instance. In an ALSA driver, a component is represented as a
572 :c:type:`struct snd_device <snd_device>` object. A component
573 can be a PCM instance, a control interface, a raw MIDI interface, etc.
574 Each such instance has one component entry.
576 A component can be created via :c:func:`snd_device_new()`
581 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
583 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
584 data pointer, and the callback pointers (``&ops``). The device-level
585 defines the type of components and the order of registration and
586 de-registration. For most components, the device-level is already
587 defined. For a user-defined component, you can use
588 ``SNDRV_DEV_LOWLEVEL``.
590 This function itself doesn't allocate the data space. The data must be
591 allocated manually beforehand, and its pointer is passed as the
592 argument. This pointer (``chip`` in the above example) is used as the
593 identifier for the instance.
595 Each pre-defined ALSA component such as ac97 and pcm calls
596 :c:func:`snd_device_new()` inside its constructor. The destructor
597 for each component is defined in the callback pointers. Hence, you don't
598 need to take care of calling a destructor for such a component.
600 If you wish to create your own component, you need to set the destructor
601 function to the dev_free callback in the ``ops``, so that it can be
602 released automatically via :c:func:`snd_card_free()`. The next
603 example will show an implementation of chip-specific data.
608 Chip-specific information, e.g. the I/O port address, its resource
609 pointer, or the irq number, is stored in the chip-specific record.
618 In general, there are two ways of allocating the chip record.
620 1. Allocating via :c:func:`snd_card_new()`.
621 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623 As mentioned above, you can pass the extra-data-length to the 5th
624 argument of :c:func:`snd_card_new()`, i.e.
628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
629 sizeof(struct mychip), &card);
631 :c:type:`struct mychip <mychip>` is the type of the chip record.
633 In return, the allocated record can be accessed as
637 struct mychip *chip = card->private_data;
639 With this method, you don't have to allocate twice. The record is
640 released together with the card instance.
642 2. Allocating an extra device.
643 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
645 After allocating a card instance via :c:func:`snd_card_new()`
646 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
650 struct snd_card *card;
652 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
655 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
657 The chip record should have the field to hold the card pointer at least,
662 struct snd_card *card;
667 Then, set the card pointer in the returned chip instance.
673 Next, initialize the fields, and register this chip record as a
674 low-level device with a specified ``ops``,
678 static struct snd_device_ops ops = {
679 .dev_free = snd_mychip_dev_free,
682 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
684 :c:func:`snd_mychip_dev_free()` is the device-destructor
685 function, which will call the real destructor.
689 static int snd_mychip_dev_free(struct snd_device *device)
691 return snd_mychip_free(device->device_data);
694 where :c:func:`snd_mychip_free()` is the real destructor.
696 The demerit of this method is the obviously more amount of codes.
697 The merit is, however, you can trigger the own callback at registering
698 and disconnecting the card via setting in snd_device_ops.
699 About the registering and disconnecting the card, see the subsections
703 Registration and Release
704 ------------------------
706 After all components are assigned, register the card instance by calling
707 :c:func:`snd_card_register()`. Access to the device files is
708 enabled at this point. That is, before
709 :c:func:`snd_card_register()` is called, the components are safely
710 inaccessible from external side. If this call fails, exit the probe
711 function after releasing the card via :c:func:`snd_card_free()`.
713 For releasing the card instance, you can call simply
714 :c:func:`snd_card_free()`. As mentioned earlier, all components
715 are released automatically by this call.
717 For a device which allows hotplugging, you can use
718 :c:func:`snd_card_free_when_closed()`. This one will postpone
719 the destruction until all devices are closed.
721 PCI Resource Management
722 =======================
727 In this section, we'll complete the chip-specific constructor,
728 destructor and PCI entries. Example code is shown first, below.
733 struct snd_card *card;
740 static int snd_mychip_free(struct mychip *chip)
742 /* disable hardware here if any */
743 .... /* (not implemented in this document) */
745 /* release the irq */
747 free_irq(chip->irq, chip);
748 /* release the I/O ports & memory */
749 pci_release_regions(chip->pci);
750 /* disable the PCI entry */
751 pci_disable_device(chip->pci);
752 /* release the data */
757 /* chip-specific constructor */
758 static int snd_mychip_create(struct snd_card *card,
760 struct mychip **rchip)
764 static struct snd_device_ops ops = {
765 .dev_free = snd_mychip_dev_free,
770 /* initialize the PCI entry */
771 err = pci_enable_device(pci);
774 /* check PCI availability (28bit DMA) */
775 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
776 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
777 printk(KERN_ERR "error to set 28bit mask DMA\n");
778 pci_disable_device(pci);
782 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
784 pci_disable_device(pci);
788 /* initialize the stuff */
793 /* (1) PCI resource allocation */
794 err = pci_request_regions(pci, "My Chip");
797 pci_disable_device(pci);
800 chip->port = pci_resource_start(pci, 0);
801 if (request_irq(pci->irq, snd_mychip_interrupt,
802 IRQF_SHARED, KBUILD_MODNAME, chip)) {
803 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
804 snd_mychip_free(chip);
807 chip->irq = pci->irq;
809 /* (2) initialization of the chip hardware */
810 .... /* (not implemented in this document) */
812 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
814 snd_mychip_free(chip);
823 static struct pci_device_id snd_mychip_ids[] = {
824 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
825 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
829 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
831 /* pci_driver definition */
832 static struct pci_driver driver = {
833 .name = KBUILD_MODNAME,
834 .id_table = snd_mychip_ids,
835 .probe = snd_mychip_probe,
836 .remove = snd_mychip_remove,
839 /* module initialization */
840 static int __init alsa_card_mychip_init(void)
842 return pci_register_driver(&driver);
845 /* module clean up */
846 static void __exit alsa_card_mychip_exit(void)
848 pci_unregister_driver(&driver);
851 module_init(alsa_card_mychip_init)
852 module_exit(alsa_card_mychip_exit)
854 EXPORT_NO_SYMBOLS; /* for old kernels only */
859 The allocation of PCI resources is done in the ``probe`` function, and
860 usually an extra :c:func:`xxx_create()` function is written for this
863 In the case of PCI devices, you first have to call the
864 :c:func:`pci_enable_device()` function before allocating
865 resources. Also, you need to set the proper PCI DMA mask to limit the
866 accessed I/O range. In some cases, you might need to call
867 :c:func:`pci_set_master()` function, too.
869 Suppose the 28bit mask, and the code to be added would be like:
873 err = pci_enable_device(pci);
876 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
877 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
878 printk(KERN_ERR "error to set 28bit mask DMA\n");
879 pci_disable_device(pci);
887 The allocation of I/O ports and irqs is done via standard kernel
888 functions. These resources must be released in the destructor
889 function (see below).
891 Now assume that the PCI device has an I/O port with 8 bytes and an
892 interrupt. Then :c:type:`struct mychip <mychip>` will have the
898 struct snd_card *card;
905 For an I/O port (and also a memory region), you need to have the
906 resource pointer for the standard resource management. For an irq, you
907 have to keep only the irq number (integer). But you need to initialize
908 this number as -1 before actual allocation, since irq 0 is valid. The
909 port address and its resource pointer can be initialized as null by
910 :c:func:`kzalloc()` automatically, so you don't have to take care of
913 The allocation of an I/O port is done like this:
917 err = pci_request_regions(pci, "My Chip");
920 pci_disable_device(pci);
923 chip->port = pci_resource_start(pci, 0);
925 It will reserve the I/O port region of 8 bytes of the given PCI device.
926 The returned value, ``chip->res_port``, is allocated via
927 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
928 must be released via :c:func:`kfree()`, but there is a problem with
929 this. This issue will be explained later.
931 The allocation of an interrupt source is done like this:
935 if (request_irq(pci->irq, snd_mychip_interrupt,
936 IRQF_SHARED, KBUILD_MODNAME, chip)) {
937 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
938 snd_mychip_free(chip);
941 chip->irq = pci->irq;
943 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
944 defined `later <#pcm-interface-interrupt-handler>`__. Note that
945 ``chip->irq`` should be defined only when :c:func:`request_irq()`
948 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
949 as the interrupt flag of :c:func:`request_irq()`.
951 The last argument of :c:func:`request_irq()` is the data pointer
952 passed to the interrupt handler. Usually, the chip-specific record is
953 used for that, but you can use what you like, too.
955 I won't give details about the interrupt handler at this point, but at
956 least its appearance can be explained now. The interrupt handler looks
957 usually like the following:
961 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
963 struct mychip *chip = dev_id;
969 Now let's write the corresponding destructor for the resources above.
970 The role of destructor is simple: disable the hardware (if already
971 activated) and release the resources. So far, we have no hardware part,
972 so the disabling code is not written here.
974 To release the resources, the “check-and-release” method is a safer way.
975 For the interrupt, do like this:
980 free_irq(chip->irq, chip);
982 Since the irq number can start from 0, you should initialize
983 ``chip->irq`` with a negative value (e.g. -1), so that you can check
984 the validity of the irq number as above.
986 When you requested I/O ports or memory regions via
987 :c:func:`pci_request_region()` or
988 :c:func:`pci_request_regions()` like in this example, release the
989 resource(s) using the corresponding function,
990 :c:func:`pci_release_region()` or
991 :c:func:`pci_release_regions()`.
995 pci_release_regions(chip->pci);
997 When you requested manually via :c:func:`request_region()` or
998 :c:func:`request_mem_region()`, you can release it via
999 :c:func:`release_resource()`. Suppose that you keep the resource
1000 pointer returned from :c:func:`request_region()` in
1001 chip->res_port, the release procedure looks like:
1005 release_and_free_resource(chip->res_port);
1007 Don't forget to call :c:func:`pci_disable_device()` before the
1010 And finally, release the chip-specific record.
1016 We didn't implement the hardware disabling part in the above. If you
1017 need to do this, please note that the destructor may be called even
1018 before the initialization of the chip is completed. It would be better
1019 to have a flag to skip hardware disabling if the hardware was not
1022 When the chip-data is assigned to the card using
1023 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1024 destructor is called at the last. That is, it is assured that all other
1025 components like PCMs and controls have already been released. You don't
1026 have to stop PCMs, etc. explicitly, but just call low-level hardware
1029 The management of a memory-mapped region is almost as same as the
1030 management of an I/O port. You'll need three fields like the
1037 unsigned long iobase_phys;
1038 void __iomem *iobase_virt;
1041 and the allocation would be like below:
1045 err = pci_request_regions(pci, "My Chip");
1050 chip->iobase_phys = pci_resource_start(pci, 0);
1051 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1052 pci_resource_len(pci, 0));
1054 and the corresponding destructor would be:
1058 static int snd_mychip_free(struct mychip *chip)
1061 if (chip->iobase_virt)
1062 iounmap(chip->iobase_virt);
1064 pci_release_regions(chip->pci);
1068 Of course, a modern way with :c:func:`pci_iomap()` will make things a
1073 err = pci_request_regions(pci, "My Chip");
1078 chip->iobase_virt = pci_iomap(pci, 0, 0);
1080 which is paired with :c:func:`pci_iounmap()` at destructor.
1086 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1087 :c:type:`struct pci_device_id <pci_device_id>` table for
1088 this chipset. It's a table of PCI vendor/device ID number, and some
1095 static struct pci_device_id snd_mychip_ids[] = {
1096 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1097 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1101 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1103 The first and second fields of the :c:type:`struct pci_device_id
1104 <pci_device_id>` structure are the vendor and device IDs. If you
1105 have no reason to filter the matching devices, you can leave the
1106 remaining fields as above. The last field of the :c:type:`struct
1107 pci_device_id <pci_device_id>` struct contains private data
1108 for this entry. You can specify any value here, for example, to define
1109 specific operations for supported device IDs. Such an example is found
1110 in the intel8x0 driver.
1112 The last entry of this list is the terminator. You must specify this
1115 Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1120 static struct pci_driver driver = {
1121 .name = KBUILD_MODNAME,
1122 .id_table = snd_mychip_ids,
1123 .probe = snd_mychip_probe,
1124 .remove = snd_mychip_remove,
1127 The ``probe`` and ``remove`` functions have already been defined in
1128 the previous sections. The ``name`` field is the name string of this
1129 device. Note that you must not use a slash “/” in this string.
1131 And at last, the module entries:
1135 static int __init alsa_card_mychip_init(void)
1137 return pci_register_driver(&driver);
1140 static void __exit alsa_card_mychip_exit(void)
1142 pci_unregister_driver(&driver);
1145 module_init(alsa_card_mychip_init)
1146 module_exit(alsa_card_mychip_exit)
1148 Note that these module entries are tagged with ``__init`` and ``__exit``
1159 The PCM middle layer of ALSA is quite powerful and it is only necessary
1160 for each driver to implement the low-level functions to access its
1163 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1164 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1165 access to some functions related with hw_param.
1167 Each card device can have up to four pcm instances. A pcm instance
1168 corresponds to a pcm device file. The limitation of number of instances
1169 comes only from the available bit size of the Linux's device numbers.
1170 Once when 64bit device number is used, we'll have more pcm instances
1173 A pcm instance consists of pcm playback and capture streams, and each
1174 pcm stream consists of one or more pcm substreams. Some soundcards
1175 support multiple playback functions. For example, emu10k1 has a PCM
1176 playback of 32 stereo substreams. In this case, at each open, a free
1177 substream is (usually) automatically chosen and opened. Meanwhile, when
1178 only one substream exists and it was already opened, the successful open
1179 will either block or error with ``EAGAIN`` according to the file open
1180 mode. But you don't have to care about such details in your driver. The
1181 PCM middle layer will take care of such work.
1186 The example code below does not include any hardware access routines but
1187 shows only the skeleton, how to build up the PCM interfaces.
1191 #include <sound/pcm.h>
1194 /* hardware definition */
1195 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1196 .info = (SNDRV_PCM_INFO_MMAP |
1197 SNDRV_PCM_INFO_INTERLEAVED |
1198 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1199 SNDRV_PCM_INFO_MMAP_VALID),
1200 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1201 .rates = SNDRV_PCM_RATE_8000_48000,
1206 .buffer_bytes_max = 32768,
1207 .period_bytes_min = 4096,
1208 .period_bytes_max = 32768,
1210 .periods_max = 1024,
1213 /* hardware definition */
1214 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1215 .info = (SNDRV_PCM_INFO_MMAP |
1216 SNDRV_PCM_INFO_INTERLEAVED |
1217 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1218 SNDRV_PCM_INFO_MMAP_VALID),
1219 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1220 .rates = SNDRV_PCM_RATE_8000_48000,
1225 .buffer_bytes_max = 32768,
1226 .period_bytes_min = 4096,
1227 .period_bytes_max = 32768,
1229 .periods_max = 1024,
1233 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1235 struct mychip *chip = snd_pcm_substream_chip(substream);
1236 struct snd_pcm_runtime *runtime = substream->runtime;
1238 runtime->hw = snd_mychip_playback_hw;
1239 /* more hardware-initialization will be done here */
1244 /* close callback */
1245 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1247 struct mychip *chip = snd_pcm_substream_chip(substream);
1248 /* the hardware-specific codes will be here */
1255 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1257 struct mychip *chip = snd_pcm_substream_chip(substream);
1258 struct snd_pcm_runtime *runtime = substream->runtime;
1260 runtime->hw = snd_mychip_capture_hw;
1261 /* more hardware-initialization will be done here */
1266 /* close callback */
1267 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1269 struct mychip *chip = snd_pcm_substream_chip(substream);
1270 /* the hardware-specific codes will be here */
1275 /* hw_params callback */
1276 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1277 struct snd_pcm_hw_params *hw_params)
1279 /* the hardware-specific codes will be here */
1284 /* hw_free callback */
1285 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1287 /* the hardware-specific codes will be here */
1292 /* prepare callback */
1293 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1295 struct mychip *chip = snd_pcm_substream_chip(substream);
1296 struct snd_pcm_runtime *runtime = substream->runtime;
1298 /* set up the hardware with the current configuration
1301 mychip_set_sample_format(chip, runtime->format);
1302 mychip_set_sample_rate(chip, runtime->rate);
1303 mychip_set_channels(chip, runtime->channels);
1304 mychip_set_dma_setup(chip, runtime->dma_addr,
1310 /* trigger callback */
1311 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1315 case SNDRV_PCM_TRIGGER_START:
1316 /* do something to start the PCM engine */
1319 case SNDRV_PCM_TRIGGER_STOP:
1320 /* do something to stop the PCM engine */
1328 /* pointer callback */
1329 static snd_pcm_uframes_t
1330 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1332 struct mychip *chip = snd_pcm_substream_chip(substream);
1333 unsigned int current_ptr;
1335 /* get the current hardware pointer */
1336 current_ptr = mychip_get_hw_pointer(chip);
1341 static struct snd_pcm_ops snd_mychip_playback_ops = {
1342 .open = snd_mychip_playback_open,
1343 .close = snd_mychip_playback_close,
1344 .ioctl = snd_pcm_lib_ioctl,
1345 .hw_params = snd_mychip_pcm_hw_params,
1346 .hw_free = snd_mychip_pcm_hw_free,
1347 .prepare = snd_mychip_pcm_prepare,
1348 .trigger = snd_mychip_pcm_trigger,
1349 .pointer = snd_mychip_pcm_pointer,
1353 static struct snd_pcm_ops snd_mychip_capture_ops = {
1354 .open = snd_mychip_capture_open,
1355 .close = snd_mychip_capture_close,
1356 .ioctl = snd_pcm_lib_ioctl,
1357 .hw_params = snd_mychip_pcm_hw_params,
1358 .hw_free = snd_mychip_pcm_hw_free,
1359 .prepare = snd_mychip_pcm_prepare,
1360 .trigger = snd_mychip_pcm_trigger,
1361 .pointer = snd_mychip_pcm_pointer,
1365 * definitions of capture are omitted here...
1368 /* create a pcm device */
1369 static int snd_mychip_new_pcm(struct mychip *chip)
1371 struct snd_pcm *pcm;
1374 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1377 pcm->private_data = chip;
1378 strcpy(pcm->name, "My Chip");
1381 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1382 &snd_mychip_playback_ops);
1383 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1384 &snd_mychip_capture_ops);
1385 /* pre-allocation of buffers */
1386 /* NOTE: this may fail */
1387 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1397 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1398 function. It would be better to create a constructor for pcm, namely,
1402 static int snd_mychip_new_pcm(struct mychip *chip)
1404 struct snd_pcm *pcm;
1407 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1410 pcm->private_data = chip;
1411 strcpy(pcm->name, "My Chip");
1417 The :c:func:`snd_pcm_new()` function takes four arguments. The
1418 first argument is the card pointer to which this pcm is assigned, and
1419 the second is the ID string.
1421 The third argument (``index``, 0 in the above) is the index of this new
1422 pcm. It begins from zero. If you create more than one pcm instances,
1423 specify the different numbers in this argument. For example, ``index =
1424 1`` for the second PCM device.
1426 The fourth and fifth arguments are the number of substreams for playback
1427 and capture, respectively. Here 1 is used for both arguments. When no
1428 playback or capture substreams are available, pass 0 to the
1429 corresponding argument.
1431 If a chip supports multiple playbacks or captures, you can specify more
1432 numbers, but they must be handled properly in open/close, etc.
1433 callbacks. When you need to know which substream you are referring to,
1434 then it can be obtained from :c:type:`struct snd_pcm_substream
1435 <snd_pcm_substream>` data passed to each callback as follows:
1439 struct snd_pcm_substream *substream;
1440 int index = substream->number;
1443 After the pcm is created, you need to set operators for each pcm stream.
1447 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1448 &snd_mychip_playback_ops);
1449 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1450 &snd_mychip_capture_ops);
1452 The operators are defined typically like this:
1456 static struct snd_pcm_ops snd_mychip_playback_ops = {
1457 .open = snd_mychip_pcm_open,
1458 .close = snd_mychip_pcm_close,
1459 .ioctl = snd_pcm_lib_ioctl,
1460 .hw_params = snd_mychip_pcm_hw_params,
1461 .hw_free = snd_mychip_pcm_hw_free,
1462 .prepare = snd_mychip_pcm_prepare,
1463 .trigger = snd_mychip_pcm_trigger,
1464 .pointer = snd_mychip_pcm_pointer,
1467 All the callbacks are described in the Operators_ subsection.
1469 After setting the operators, you probably will want to pre-allocate the
1470 buffer and set up the managed allocation mode.
1471 For that, simply call the following:
1475 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1479 It will allocate a buffer up to 64kB as default. Buffer management
1480 details will be described in the later section `Buffer and Memory
1483 Additionally, you can set some extra information for this pcm in
1484 ``pcm->info_flags``. The available values are defined as
1485 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1486 hardware definition (described later). When your soundchip supports only
1487 half-duplex, specify like this:
1491 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1494 ... And the Destructor?
1495 -----------------------
1497 The destructor for a pcm instance is not always necessary. Since the pcm
1498 device will be released by the middle layer code automatically, you
1499 don't have to call the destructor explicitly.
1501 The destructor would be necessary if you created special records
1502 internally and needed to release them. In such a case, set the
1503 destructor function to ``pcm->private_free``:
1507 static void mychip_pcm_free(struct snd_pcm *pcm)
1509 struct mychip *chip = snd_pcm_chip(pcm);
1510 /* free your own data */
1511 kfree(chip->my_private_pcm_data);
1512 /* do what you like else */
1516 static int snd_mychip_new_pcm(struct mychip *chip)
1518 struct snd_pcm *pcm;
1520 /* allocate your own data */
1521 chip->my_private_pcm_data = kmalloc(...);
1522 /* set the destructor */
1523 pcm->private_data = chip;
1524 pcm->private_free = mychip_pcm_free;
1530 Runtime Pointer - The Chest of PCM Information
1531 ----------------------------------------------
1533 When the PCM substream is opened, a PCM runtime instance is allocated
1534 and assigned to the substream. This pointer is accessible via
1535 ``substream->runtime``. This runtime pointer holds most information you
1536 need to control the PCM: the copy of hw_params and sw_params
1537 configurations, the buffer pointers, mmap records, spinlocks, etc.
1539 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1540 are the contents of this file:
1544 struct _snd_pcm_runtime {
1546 struct snd_pcm_substream *trigger_master;
1547 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1549 snd_pcm_uframes_t avail_max;
1550 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1551 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1553 /* -- HW params -- */
1554 snd_pcm_access_t access; /* access mode */
1555 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1556 snd_pcm_subformat_t subformat; /* subformat */
1557 unsigned int rate; /* rate in Hz */
1558 unsigned int channels; /* channels */
1559 snd_pcm_uframes_t period_size; /* period size */
1560 unsigned int periods; /* periods */
1561 snd_pcm_uframes_t buffer_size; /* buffer size */
1562 unsigned int tick_time; /* tick time */
1563 snd_pcm_uframes_t min_align; /* Min alignment for the format */
1565 unsigned int frame_bits;
1566 unsigned int sample_bits;
1568 unsigned int rate_num;
1569 unsigned int rate_den;
1571 /* -- SW params -- */
1572 struct timespec tstamp_mode; /* mmap timestamp is updated */
1573 unsigned int period_step;
1574 unsigned int sleep_min; /* min ticks to sleep */
1575 snd_pcm_uframes_t start_threshold;
1576 snd_pcm_uframes_t stop_threshold;
1577 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1578 noise is nearest than this */
1579 snd_pcm_uframes_t silence_size; /* Silence filling size */
1580 snd_pcm_uframes_t boundary; /* pointers wrap point */
1582 snd_pcm_uframes_t silenced_start;
1583 snd_pcm_uframes_t silenced_size;
1585 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1588 volatile struct snd_pcm_mmap_status *status;
1589 volatile struct snd_pcm_mmap_control *control;
1590 atomic_t mmap_count;
1592 /* -- locking / scheduling -- */
1594 wait_queue_head_t sleep;
1595 struct timer_list tick_timer;
1596 struct fasync_struct *fasync;
1598 /* -- private section -- */
1600 void (*private_free)(struct snd_pcm_runtime *runtime);
1602 /* -- hardware description -- */
1603 struct snd_pcm_hardware hw;
1604 struct snd_pcm_hw_constraints hw_constraints;
1607 unsigned int timer_resolution; /* timer resolution */
1610 unsigned char *dma_area; /* DMA area */
1611 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1612 size_t dma_bytes; /* size of DMA area */
1614 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1616 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1617 /* -- OSS things -- */
1618 struct snd_pcm_oss_runtime oss;
1623 For the operators (callbacks) of each sound driver, most of these
1624 records are supposed to be read-only. Only the PCM middle-layer changes
1625 / updates them. The exceptions are the hardware description (hw) DMA
1626 buffer information and the private data. Besides, if you use the
1627 standard managed buffer allocation mode, you don't need to set the
1628 DMA buffer information by yourself.
1630 In the sections below, important records are explained.
1632 Hardware Description
1633 ~~~~~~~~~~~~~~~~~~~~
1635 The hardware descriptor (:c:type:`struct snd_pcm_hardware
1636 <snd_pcm_hardware>`) contains the definitions of the fundamental
1637 hardware configuration. Above all, you'll need to define this in the
1638 `PCM open callback`_. Note that the runtime instance holds the copy of
1639 the descriptor, not the pointer to the existing descriptor. That is,
1640 in the open callback, you can modify the copied descriptor
1641 (``runtime->hw``) as you need. For example, if the maximum number of
1642 channels is 1 only on some chip models, you can still use the same
1643 hardware descriptor and change the channels_max later:
1647 struct snd_pcm_runtime *runtime = substream->runtime;
1649 runtime->hw = snd_mychip_playback_hw; /* common definition */
1650 if (chip->model == VERY_OLD_ONE)
1651 runtime->hw.channels_max = 1;
1653 Typically, you'll have a hardware descriptor as below:
1657 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1658 .info = (SNDRV_PCM_INFO_MMAP |
1659 SNDRV_PCM_INFO_INTERLEAVED |
1660 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1661 SNDRV_PCM_INFO_MMAP_VALID),
1662 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1663 .rates = SNDRV_PCM_RATE_8000_48000,
1668 .buffer_bytes_max = 32768,
1669 .period_bytes_min = 4096,
1670 .period_bytes_max = 32768,
1672 .periods_max = 1024,
1675 - The ``info`` field contains the type and capabilities of this
1676 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1677 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1678 the mmap is supported and which interleaved format is
1679 supported. When the hardware supports mmap, add the
1680 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1681 interleaved or the non-interleaved formats,
1682 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1683 flag must be set, respectively. If both are supported, you can set
1686 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1687 specified for the OSS mmap mode. Usually both are set. Of course,
1688 ``MMAP_VALID`` is set only if the mmap is really supported.
1690 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1691 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1692 supports the “pause” operation, while the ``RESUME`` bit means that
1693 the pcm supports the full “suspend/resume” operation. If the
1694 ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1695 the corresponding (pause push/release) commands. The suspend/resume
1696 trigger commands can be defined even without the ``RESUME``
1697 flag. See `Power Management`_ section for details.
1699 When the PCM substreams can be synchronized (typically,
1700 synchronized start/stop of a playback and a capture streams), you
1701 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1702 need to check the linked-list of PCM substreams in the trigger
1703 callback. This will be described in the later section.
1705 - ``formats`` field contains the bit-flags of supported formats
1706 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1707 format, give all or'ed bits. In the example above, the signed 16bit
1708 little-endian format is specified.
1710 - ``rates`` field contains the bit-flags of supported rates
1711 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1712 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1713 provided only for typical rates. If your chip supports
1714 unconventional rates, you need to add the ``KNOT`` bit and set up
1715 the hardware constraint manually (explained later).
1717 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1718 rate. This should correspond somehow to ``rates`` bits.
1720 - ``channel_min`` and ``channel_max`` define, as you might already
1721 expected, the minimum and maximum number of channels.
1723 - ``buffer_bytes_max`` defines the maximum buffer size in
1724 bytes. There is no ``buffer_bytes_min`` field, since it can be
1725 calculated from the minimum period size and the minimum number of
1726 periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1727 maximum size of the period in bytes. ``periods_max`` and
1728 ``periods_min`` define the maximum and minimum number of periods in
1731 The “period” is a term that corresponds to a fragment in the OSS
1732 world. The period defines the size at which a PCM interrupt is
1733 generated. This size strongly depends on the hardware. Generally,
1734 the smaller period size will give you more interrupts, that is,
1735 more controls. In the case of capture, this size defines the input
1736 latency. On the other hand, the whole buffer size defines the
1737 output latency for the playback direction.
1739 - There is also a field ``fifo_size``. This specifies the size of the
1740 hardware FIFO, but currently it is neither used in the driver nor
1741 in the alsa-lib. So, you can ignore this field.
1746 Ok, let's go back again to the PCM runtime records. The most
1747 frequently referred records in the runtime instance are the PCM
1748 configurations. The PCM configurations are stored in the runtime
1749 instance after the application sends ``hw_params`` data via
1750 alsa-lib. There are many fields copied from hw_params and sw_params
1751 structs. For example, ``format`` holds the format type chosen by the
1752 application. This field contains the enum value
1753 ``SNDRV_PCM_FORMAT_XXX``.
1755 One thing to be noted is that the configured buffer and period sizes
1756 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1757 channels \* samples-size``. For conversion between frames and bytes,
1758 you can use the :c:func:`frames_to_bytes()` and
1759 :c:func:`bytes_to_frames()` helper functions.
1763 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1765 Also, many software parameters (sw_params) are stored in frames, too.
1766 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1767 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1768 frames as signed integer.
1770 DMA Buffer Information
1771 ~~~~~~~~~~~~~~~~~~~~~~
1773 The DMA buffer is defined by the following four fields, ``dma_area``,
1774 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1775 holds the buffer pointer (the logical address). You can call
1776 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1777 the physical address of the buffer. This field is specified only when
1778 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1779 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1781 If you use either the managed buffer allocation mode or the standard
1782 API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1783 these fields are set by the ALSA middle layer, and you should *not*
1784 change them by yourself. You can read them but not write them. On the
1785 other hand, if you want to allocate the buffer by yourself, you'll
1786 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1787 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1788 your driver doesn't support mmap, this field is not
1789 necessary. ``dma_addr`` is also optional. You can use dma_private as
1795 The running status can be referred via ``runtime->status``. This is
1796 the pointer to the :c:type:`struct snd_pcm_mmap_status
1797 <snd_pcm_mmap_status>` record. For example, you can get the current
1798 DMA hardware pointer via ``runtime->status->hw_ptr``.
1800 The DMA application pointer can be referred via ``runtime->control``,
1801 which points to the :c:type:`struct snd_pcm_mmap_control
1802 <snd_pcm_mmap_control>` record. However, accessing directly to
1803 this value is not recommended.
1808 You can allocate a record for the substream and store it in
1809 ``runtime->private_data``. Usually, this is done in the `PCM open
1810 callback`_. Don't mix this with ``pcm->private_data``. The
1811 ``pcm->private_data`` usually points to the chip instance assigned
1812 statically at the creation of PCM, while the ``runtime->private_data``
1813 points to a dynamic data structure created at the PCM open
1818 static int snd_xxx_open(struct snd_pcm_substream *substream)
1820 struct my_pcm_data *data;
1822 data = kmalloc(sizeof(*data), GFP_KERNEL);
1823 substream->runtime->private_data = data;
1828 The allocated object must be released in the `close callback`_.
1833 OK, now let me give details about each pcm callback (``ops``). In
1834 general, every callback must return 0 if successful, or a negative
1835 error number such as ``-EINVAL``. To choose an appropriate error
1836 number, it is advised to check what value other parts of the kernel
1837 return when the same kind of request fails.
1839 The callback function takes at least the argument with :c:type:`struct
1840 snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1841 record from the given substream instance, you can use the following
1847 struct mychip *chip = snd_pcm_substream_chip(substream);
1851 The macro reads ``substream->private_data``, which is a copy of
1852 ``pcm->private_data``. You can override the former if you need to
1853 assign different data records per PCM substream. For example, the
1854 cmi8330 driver assigns different ``private_data`` for playback and
1855 capture directions, because it uses two different codecs (SB- and
1856 AD-compatible) for different directions.
1863 static int snd_xxx_open(struct snd_pcm_substream *substream);
1865 This is called when a pcm substream is opened.
1867 At least, here you have to initialize the ``runtime->hw``
1868 record. Typically, this is done by like this:
1872 static int snd_xxx_open(struct snd_pcm_substream *substream)
1874 struct mychip *chip = snd_pcm_substream_chip(substream);
1875 struct snd_pcm_runtime *runtime = substream->runtime;
1877 runtime->hw = snd_mychip_playback_hw;
1881 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1884 You can allocate a private data in this callback, as described in
1885 `Private Data`_ section.
1887 If the hardware configuration needs more constraints, set the hardware
1888 constraints here, too. See Constraints_ for more details.
1895 static int snd_xxx_close(struct snd_pcm_substream *substream);
1898 Obviously, this is called when a pcm substream is closed.
1900 Any private instance for a pcm substream allocated in the ``open``
1901 callback will be released here.
1905 static int snd_xxx_close(struct snd_pcm_substream *substream)
1908 kfree(substream->runtime->private_data);
1915 This is used for any special call to pcm ioctls. But usually you can
1916 pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`.
1923 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1924 struct snd_pcm_hw_params *hw_params);
1926 This is called when the hardware parameter (``hw_params``) is set up
1927 by the application, that is, once when the buffer size, the period
1928 size, the format, etc. are defined for the pcm substream.
1930 Many hardware setups should be done in this callback, including the
1931 allocation of buffers.
1933 Parameters to be initialized are retrieved by
1934 :c:func:`params_xxx()` macros.
1936 When you set up the managed buffer allocation mode for the substream,
1937 a buffer is already allocated before this callback gets
1938 called. Alternatively, you can call a helper function below for
1939 allocating the buffer, too.
1943 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1945 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1946 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1949 Note that this and ``prepare`` callbacks may be called multiple times
1950 per initialization. For example, the OSS emulation may call these
1951 callbacks at each change via its ioctl.
1953 Thus, you need to be careful not to allocate the same buffers many
1954 times, which will lead to memory leaks! Calling the helper function
1955 above many times is OK. It will release the previous buffer
1956 automatically when it was already allocated.
1958 Another note is that this callback is non-atomic (schedulable) as
1959 default, i.e. when no ``nonatomic`` flag set. This is important,
1960 because the ``trigger`` callback is atomic (non-schedulable). That is,
1961 mutexes or any schedule-related functions are not available in
1962 ``trigger`` callback. Please see the subsection Atomicity_ for
1970 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1972 This is called to release the resources allocated via
1975 This function is always called before the close callback is called.
1976 Also, the callback may be called multiple times, too. Keep track
1977 whether the resource was already released.
1979 When you have set up the managed buffer allocation mode for the PCM
1980 substream, the allocated PCM buffer will be automatically released
1981 after this callback gets called. Otherwise you'll have to release the
1982 buffer manually. Typically, when the buffer was allocated from the
1983 pre-allocated pool, you can use the standard API function
1984 :c:func:`snd_pcm_lib_malloc_pages()` like:
1988 snd_pcm_lib_free_pages(substream);
1995 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1997 This callback is called when the pcm is “prepared”. You can set the
1998 format type, sample rate, etc. here. The difference from ``hw_params``
1999 is that the ``prepare`` callback will be called each time
2000 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2003 Note that this callback is now non-atomic. You can use
2004 schedule-related functions safely in this callback.
2006 In this and the following callbacks, you can refer to the values via
2007 the runtime record, ``substream->runtime``. For example, to get the
2008 current rate, format or channels, access to ``runtime->rate``,
2009 ``runtime->format`` or ``runtime->channels``, respectively. The
2010 physical address of the allocated buffer is set to
2011 ``runtime->dma_area``. The buffer and period sizes are in
2012 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2014 Be careful that this callback will be called many times at each setup,
2022 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2024 This is called when the pcm is started, stopped or paused.
2026 Which action is specified in the second argument,
2027 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2028 and ``STOP`` commands must be defined in this callback.
2033 case SNDRV_PCM_TRIGGER_START:
2034 /* do something to start the PCM engine */
2036 case SNDRV_PCM_TRIGGER_STOP:
2037 /* do something to stop the PCM engine */
2043 When the pcm supports the pause operation (given in the info field of
2044 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2045 must be handled here, too. The former is the command to pause the pcm,
2046 and the latter to restart the pcm again.
2048 When the pcm supports the suspend/resume operation, regardless of full
2049 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2050 commands must be handled, too. These commands are issued when the
2051 power-management status is changed. Obviously, the ``SUSPEND`` and
2052 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2053 they are identical to the ``STOP`` and ``START`` commands, respectively.
2054 See the `Power Management`_ section for details.
2056 As mentioned, this callback is atomic as default unless ``nonatomic``
2057 flag set, and you cannot call functions which may sleep. The
2058 ``trigger`` callback should be as minimal as possible, just really
2059 triggering the DMA. The other stuff should be initialized
2060 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2067 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2069 This callback is called when the PCM middle layer inquires the current
2070 hardware position on the buffer. The position must be returned in
2071 frames, ranging from 0 to ``buffer_size - 1``.
2073 This is called usually from the buffer-update routine in the pcm
2074 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2075 is called in the interrupt routine. Then the pcm middle layer updates
2076 the position and calculates the available space, and wakes up the
2077 sleeping poll threads, etc.
2079 This callback is also atomic as default.
2081 copy_user, copy_kernel and fill_silence ops
2082 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2084 These callbacks are not mandatory, and can be omitted in most cases.
2085 These callbacks are used when the hardware buffer cannot be in the
2086 normal memory space. Some chips have their own buffer on the hardware
2087 which is not mappable. In such a case, you have to transfer the data
2088 manually from the memory buffer to the hardware buffer. Or, if the
2089 buffer is non-contiguous on both physical and virtual memory spaces,
2090 these callbacks must be defined, too.
2092 If these two callbacks are defined, copy and set-silence operations
2093 are done by them. The detailed will be described in the later section
2094 `Buffer and Memory Management`_.
2099 This callback is also not mandatory. This callback is called when the
2100 ``appl_ptr`` is updated in read or write operations. Some drivers like
2101 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2102 internal buffer, and this callback is useful only for such a purpose.
2104 This callback is atomic as default.
2109 This callback is optional too. The mmap calls this callback to get the
2112 Since the recent changes, you need no special callback any longer for
2113 the standard SG-buffer or vmalloc-buffer. Hence this callback should
2119 This is another optional callback for controlling mmap behavior.
2120 Once when defined, PCM core calls this callback when a page is
2121 memory-mapped instead of dealing via the standard helper.
2122 If you need special handling (due to some architecture or
2123 device-specific issues), implement everything here as you like.
2126 PCM Interrupt Handler
2127 ---------------------
2129 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2130 interrupt handler in the sound driver is to update the buffer position
2131 and to tell the PCM middle layer when the buffer position goes across
2132 the prescribed period size. To inform this, call the
2133 :c:func:`snd_pcm_period_elapsed()` function.
2135 There are several types of sound chips to generate the interrupts.
2137 Interrupts at the period (fragment) boundary
2138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2140 This is the most frequently found type: the hardware generates an
2141 interrupt at each period boundary. In this case, you can call
2142 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2144 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2145 its argument. Thus, you need to keep the substream pointer accessible
2146 from the chip instance. For example, define ``substream`` field in the
2147 chip record to hold the current running substream pointer, and set the
2148 pointer value at ``open`` callback (and reset at ``close`` callback).
2150 If you acquire a spinlock in the interrupt handler, and the lock is used
2151 in other pcm callbacks, too, then you have to release the lock before
2152 calling :c:func:`snd_pcm_period_elapsed()`, because
2153 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2156 Typical code would be like:
2161 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2163 struct mychip *chip = dev_id;
2164 spin_lock(&chip->lock);
2166 if (pcm_irq_invoked(chip)) {
2167 /* call updater, unlock before it */
2168 spin_unlock(&chip->lock);
2169 snd_pcm_period_elapsed(chip->substream);
2170 spin_lock(&chip->lock);
2171 /* acknowledge the interrupt if necessary */
2174 spin_unlock(&chip->lock);
2180 High frequency timer interrupts
2181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2183 This happens when the hardware doesn't generate interrupts at the period
2184 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2185 or ymfpci drivers). In this case, you need to check the current hardware
2186 position and accumulate the processed sample length at each interrupt.
2187 When the accumulated size exceeds the period size, call
2188 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2190 Typical code would be like the following.
2195 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2197 struct mychip *chip = dev_id;
2198 spin_lock(&chip->lock);
2200 if (pcm_irq_invoked(chip)) {
2201 unsigned int last_ptr, size;
2202 /* get the current hardware pointer (in frames) */
2203 last_ptr = get_hw_ptr(chip);
2204 /* calculate the processed frames since the
2207 if (last_ptr < chip->last_ptr)
2208 size = runtime->buffer_size + last_ptr
2211 size = last_ptr - chip->last_ptr;
2212 /* remember the last updated point */
2213 chip->last_ptr = last_ptr;
2214 /* accumulate the size */
2216 /* over the period boundary? */
2217 if (chip->size >= runtime->period_size) {
2218 /* reset the accumulator */
2219 chip->size %= runtime->period_size;
2221 spin_unlock(&chip->lock);
2222 snd_pcm_period_elapsed(substream);
2223 spin_lock(&chip->lock);
2225 /* acknowledge the interrupt if necessary */
2228 spin_unlock(&chip->lock);
2234 On calling :c:func:`snd_pcm_period_elapsed()`
2235 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2237 In both cases, even if more than one period are elapsed, you don't have
2238 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2239 once. And the pcm layer will check the current hardware pointer and
2240 update to the latest status.
2245 One of the most important (and thus difficult to debug) problems in
2246 kernel programming are race conditions. In the Linux kernel, they are
2247 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2248 race condition can happen in an interrupt handler, it has to be managed
2249 atomically, and you have to use a spinlock to protect the critical
2250 session. If the critical section is not in interrupt handler code and if
2251 taking a relatively long time to execute is acceptable, you should use
2252 mutexes or semaphores instead.
2254 As already seen, some pcm callbacks are atomic and some are not. For
2255 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2256 callback is atomic. This means, the latter is called already in a
2257 spinlock held by the PCM middle layer. Please take this atomicity into
2258 account when you choose a locking scheme in the callbacks.
2260 In the atomic callbacks, you cannot use functions which may call
2261 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2262 mutexes can sleep, and hence they cannot be used inside the atomic
2263 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2264 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2266 All three atomic callbacks (trigger, pointer, and ack) are called with
2267 local interrupts disabled.
2269 The recent changes in PCM core code, however, allow all PCM operations
2270 to be non-atomic. This assumes that the all caller sides are in
2271 non-atomic contexts. For example, the function
2272 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2273 interrupt handler. But, if you set up the driver to use a threaded
2274 interrupt handler, this call can be in non-atomic context, too. In such
2275 a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2276 <snd_pcm>` object after creating it. When this flag is set, mutex
2277 and rwsem are used internally in the PCM core instead of spin and
2278 rwlocks, so that you can call all PCM functions safely in a non-atomic
2284 If your chip supports unconventional sample rates, or only the limited
2285 samples, you need to set a constraint for the condition.
2287 For example, in order to restrict the sample rates in the some supported
2288 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2289 call this function in the open callback.
2293 static unsigned int rates[] =
2294 {4000, 10000, 22050, 44100};
2295 static struct snd_pcm_hw_constraint_list constraints_rates = {
2296 .count = ARRAY_SIZE(rates),
2301 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2305 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2306 SNDRV_PCM_HW_PARAM_RATE,
2307 &constraints_rates);
2315 There are many different constraints. Look at ``sound/pcm.h`` for a
2316 complete list. You can even define your own constraint rules. For
2317 example, let's suppose my_chip can manage a substream of 1 channel if
2318 and only if the format is ``S16_LE``, otherwise it supports any format
2319 specified in the :c:type:`struct snd_pcm_hardware
2320 <snd_pcm_hardware>` structure (or in any other
2321 constraint_list). You can build a rule like this:
2325 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2326 struct snd_pcm_hw_rule *rule)
2328 struct snd_interval *c = hw_param_interval(params,
2329 SNDRV_PCM_HW_PARAM_CHANNELS);
2330 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2331 struct snd_interval ch;
2333 snd_interval_any(&ch);
2334 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2335 ch.min = ch.max = 1;
2337 return snd_interval_refine(c, &ch);
2343 Then you need to call this function to add your rule:
2347 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2348 hw_rule_channels_by_format, NULL,
2349 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2351 The rule function is called when an application sets the PCM format, and
2352 it refines the number of channels accordingly. But an application may
2353 set the number of channels before setting the format. Thus you also need
2354 to define the inverse rule:
2358 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2359 struct snd_pcm_hw_rule *rule)
2361 struct snd_interval *c = hw_param_interval(params,
2362 SNDRV_PCM_HW_PARAM_CHANNELS);
2363 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2364 struct snd_mask fmt;
2366 snd_mask_any(&fmt); /* Init the struct */
2368 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2369 return snd_mask_refine(f, &fmt);
2375 ... and in the open callback:
2379 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2380 hw_rule_format_by_channels, NULL,
2381 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2383 One typical usage of the hw constraints is to align the buffer size
2384 with the period size. As default, ALSA PCM core doesn't enforce the
2385 buffer size to be aligned with the period size. For example, it'd be
2386 possible to have a combination like 256 period bytes with 999 buffer
2389 Many device chips, however, require the buffer to be a multiple of
2390 periods. In such a case, call
2391 :c:func:`snd_pcm_hw_constraint_integer()` for
2392 ``SNDRV_PCM_HW_PARAM_PERIODS``.
2396 snd_pcm_hw_constraint_integer(substream->runtime,
2397 SNDRV_PCM_HW_PARAM_PERIODS);
2399 This assures that the number of periods is integer, hence the buffer
2400 size is aligned with the period size.
2402 The hw constraint is a very much powerful mechanism to define the
2403 preferred PCM configuration, and there are relevant helpers.
2404 I won't give more details here, rather I would like to say, “Luke, use
2413 The control interface is used widely for many switches, sliders, etc.
2414 which are accessed from user-space. Its most important use is the mixer
2415 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2416 implemented on the control kernel API.
2418 ALSA has a well-defined AC97 control module. If your chip supports only
2419 the AC97 and nothing else, you can skip this section.
2421 The control API is defined in ``<sound/control.h>``. Include this file
2422 if you want to add your own controls.
2424 Definition of Controls
2425 ----------------------
2427 To create a new control, you need to define the following three
2428 callbacks: ``info``, ``get`` and ``put``. Then, define a
2429 :c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
2434 static struct snd_kcontrol_new my_control = {
2435 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2436 .name = "PCM Playback Switch",
2438 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2439 .private_value = 0xffff,
2440 .info = my_control_info,
2441 .get = my_control_get,
2442 .put = my_control_put
2446 The ``iface`` field specifies the control type,
2447 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2448 for global controls that are not logically part of the mixer. If the
2449 control is closely associated with some specific device on the sound
2450 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2451 and specify the device number with the ``device`` and ``subdevice``
2454 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2455 control name is very important, because its role is classified from
2456 its name. There are pre-defined standard control names. The details
2457 are described in the `Control Names`_ subsection.
2459 The ``index`` field holds the index number of this control. If there
2460 are several different controls with the same name, they can be
2461 distinguished by the index number. This is the case when several
2462 codecs exist on the card. If the index is zero, you can omit the
2465 The ``access`` field contains the access type of this control. Give
2466 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2467 there. The details will be explained in the `Access Flags`_
2470 The ``private_value`` field contains an arbitrary long integer value
2471 for this record. When using the generic ``info``, ``get`` and ``put``
2472 callbacks, you can pass a value through this field. If several small
2473 numbers are necessary, you can combine them in bitwise. Or, it's
2474 possible to give a pointer (casted to unsigned long) of some record to
2477 The ``tlv`` field can be used to provide metadata about the control;
2478 see the `Metadata`_ subsection.
2480 The other three are `Control Callbacks`_.
2485 There are some standards to define the control names. A control is
2486 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2488 The first, ``SOURCE``, specifies the source of the control, and is a
2489 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2490 pre-defined sources.
2492 The second, ``DIRECTION``, is one of the following strings according to
2493 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2494 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2497 The third, ``FUNCTION``, is one of the following strings according to
2498 the function of the control: “Switch”, “Volume” and “Route”.
2500 The example of control names are, thus, “Master Capture Switch” or “PCM
2503 There are some exceptions:
2505 Global capture and playback
2506 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2508 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2509 global capture (input) source, switch and volume. Similarly, “Playback
2510 Switch” and “Playback Volume” are used for the global output gain switch
2516 tone-control switch and volumes are specified like “Tone Control - XXX”,
2517 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2523 3D-control switches and volumes are specified like “3D Control - XXX”,
2524 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2529 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2531 More precise information can be found in
2532 ``Documentation/sound/designs/control-names.rst``.
2537 The access flag is the bitmask which specifies the access type of the
2538 given control. The default access type is
2539 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2540 allowed to this control. When the access flag is omitted (i.e. = 0), it
2541 is considered as ``READWRITE`` access as default.
2543 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2544 instead. In this case, you don't have to define the ``put`` callback.
2545 Similarly, when the control is write-only (although it's a rare case),
2546 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2549 If the control value changes frequently (e.g. the VU meter),
2550 ``VOLATILE`` flag should be given. This means that the control may be
2551 changed without `Change notification`_. Applications should poll such
2552 a control constantly.
2554 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2555 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2563 The ``info`` callback is used to get detailed information on this
2564 control. This must store the values of the given :c:type:`struct
2565 snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2566 for a boolean control with a single element:
2571 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2572 struct snd_ctl_elem_info *uinfo)
2574 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2576 uinfo->value.integer.min = 0;
2577 uinfo->value.integer.max = 1;
2583 The ``type`` field specifies the type of the control. There are
2584 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2585 ``INTEGER64``. The ``count`` field specifies the number of elements in
2586 this control. For example, a stereo volume would have count = 2. The
2587 ``value`` field is a union, and the values stored are depending on the
2588 type. The boolean and integer types are identical.
2590 The enumerated type is a bit different from others. You'll need to set
2591 the string for the currently given item index.
2595 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2596 struct snd_ctl_elem_info *uinfo)
2598 static char *texts[4] = {
2599 "First", "Second", "Third", "Fourth"
2601 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2603 uinfo->value.enumerated.items = 4;
2604 if (uinfo->value.enumerated.item > 3)
2605 uinfo->value.enumerated.item = 3;
2606 strcpy(uinfo->value.enumerated.name,
2607 texts[uinfo->value.enumerated.item]);
2611 The above callback can be simplified with a helper function,
2612 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2613 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2614 it's a matter of taste.)
2618 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2619 struct snd_ctl_elem_info *uinfo)
2621 static char *texts[4] = {
2622 "First", "Second", "Third", "Fourth"
2624 return snd_ctl_enum_info(uinfo, 1, 4, texts);
2628 Some common info callbacks are available for your convenience:
2629 :c:func:`snd_ctl_boolean_mono_info()` and
2630 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2631 is an info callback for a mono channel boolean item, just like
2632 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2633 stereo channel boolean item.
2638 This callback is used to read the current value of the control and to
2639 return to user-space.
2646 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2647 struct snd_ctl_elem_value *ucontrol)
2649 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2650 ucontrol->value.integer.value[0] = get_some_value(chip);
2656 The ``value`` field depends on the type of control as well as on the
2657 info callback. For example, the sb driver uses this field to store the
2658 register offset, the bit-shift and the bit-mask. The ``private_value``
2659 field is set as follows:
2663 .private_value = reg | (shift << 16) | (mask << 24)
2665 and is retrieved in callbacks like
2669 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2670 struct snd_ctl_elem_value *ucontrol)
2672 int reg = kcontrol->private_value & 0xff;
2673 int shift = (kcontrol->private_value >> 16) & 0xff;
2674 int mask = (kcontrol->private_value >> 24) & 0xff;
2678 In the ``get`` callback, you have to fill all the elements if the
2679 control has more than one elements, i.e. ``count > 1``. In the example
2680 above, we filled only one element (``value.integer.value[0]``) since
2681 it's assumed as ``count = 1``.
2686 This callback is used to write a value from user-space.
2693 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2694 struct snd_ctl_elem_value *ucontrol)
2696 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2698 if (chip->current_value !=
2699 ucontrol->value.integer.value[0]) {
2700 change_current_value(chip,
2701 ucontrol->value.integer.value[0]);
2709 As seen above, you have to return 1 if the value is changed. If the
2710 value is not changed, return 0 instead. If any fatal error happens,
2711 return a negative error code as usual.
2713 As in the ``get`` callback, when the control has more than one
2714 elements, all elements must be evaluated in this callback, too.
2716 Callbacks are not atomic
2717 ~~~~~~~~~~~~~~~~~~~~~~~~
2719 All these three callbacks are basically not atomic.
2724 When everything is ready, finally we can create a new control. To create
2725 a control, there are two functions to be called,
2726 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2728 In the simplest way, you can do like this:
2732 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2736 where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2737 <snd_kcontrol_new>` object defined above, and chip is the object
2738 pointer to be passed to kcontrol->private_data which can be referred
2741 :c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2742 snd_kcontrol <snd_kcontrol>` instance, and
2743 :c:func:`snd_ctl_add()` assigns the given control component to the
2749 If you need to change and update a control in the interrupt routine, you
2750 can call :c:func:`snd_ctl_notify()`. For example,
2754 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2756 This function takes the card pointer, the event-mask, and the control id
2757 pointer for the notification. The event-mask specifies the types of
2758 notification, for example, in the above example, the change of control
2759 values is notified. The id pointer is the pointer of :c:type:`struct
2760 snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2761 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2767 To provide information about the dB values of a mixer control, use on of
2768 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2769 variable containing this information, set the ``tlv.p`` field to point to
2770 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2771 in the ``access`` field; like this:
2775 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2777 static struct snd_kcontrol_new my_control = {
2779 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2780 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2782 .tlv.p = db_scale_my_control,
2786 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2787 about a mixer control where each step in the control's value changes the
2788 dB value by a constant dB amount. The first parameter is the name of the
2789 variable to be defined. The second parameter is the minimum value, in
2790 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2791 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2794 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2795 about a mixer control where the control's value affects the output
2796 linearly. The first parameter is the name of the variable to be defined.
2797 The second parameter is the minimum value, in units of 0.01 dB. The
2798 third parameter is the maximum value, in units of 0.01 dB. If the
2799 minimum value mutes the control, set the second parameter to
2800 ``TLV_DB_GAIN_MUTE``.
2808 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2809 write much code to control it. Only low-level control routines are
2810 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2819 struct snd_ac97 *ac97;
2823 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2826 struct mychip *chip = ac97->private_data;
2828 /* read a register value here from the codec */
2829 return the_register_value;
2832 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2833 unsigned short reg, unsigned short val)
2835 struct mychip *chip = ac97->private_data;
2837 /* write the given register value to the codec */
2840 static int snd_mychip_ac97(struct mychip *chip)
2842 struct snd_ac97_bus *bus;
2843 struct snd_ac97_template ac97;
2845 static struct snd_ac97_bus_ops ops = {
2846 .write = snd_mychip_ac97_write,
2847 .read = snd_mychip_ac97_read,
2850 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2853 memset(&ac97, 0, sizeof(ac97));
2854 ac97.private_data = chip;
2855 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2862 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2863 with an ``ac97_bus_ops_t`` record with callback functions.
2867 struct snd_ac97_bus *bus;
2868 static struct snd_ac97_bus_ops ops = {
2869 .write = snd_mychip_ac97_write,
2870 .read = snd_mychip_ac97_read,
2873 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2875 The bus record is shared among all belonging ac97 instances.
2877 And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2878 snd_ac97_template <snd_ac97_template>` record together with
2879 the bus pointer created above.
2883 struct snd_ac97_template ac97;
2886 memset(&ac97, 0, sizeof(ac97));
2887 ac97.private_data = chip;
2888 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2890 where chip->ac97 is a pointer to a newly created ``ac97_t``
2891 instance. In this case, the chip pointer is set as the private data,
2892 so that the read/write callback functions can refer to this chip
2893 instance. This instance is not necessarily stored in the chip
2894 record. If you need to change the register values from the driver, or
2895 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2896 the corresponding functions.
2901 The standard callbacks are ``read`` and ``write``. Obviously they
2902 correspond to the functions for read and write accesses to the
2903 hardware low-level codes.
2905 The ``read`` callback returns the register value specified in the
2910 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2913 struct mychip *chip = ac97->private_data;
2915 return the_register_value;
2918 Here, the chip can be cast from ``ac97->private_data``.
2920 Meanwhile, the ``write`` callback is used to set the register
2925 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2926 unsigned short reg, unsigned short val)
2929 These callbacks are non-atomic like the control API callbacks.
2931 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2933 The ``reset`` callback is used to reset the codec. If the chip
2934 requires a special kind of reset, you can define this callback.
2936 The ``wait`` callback is used to add some waiting time in the standard
2937 initialization of the codec. If the chip requires the extra waiting
2938 time, define this callback.
2940 The ``init`` callback is used for additional initialization of the
2943 Updating Registers in The Driver
2944 --------------------------------
2946 If you need to access to the codec from the driver, you can call the
2947 following functions: :c:func:`snd_ac97_write()`,
2948 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2949 :c:func:`snd_ac97_update_bits()`.
2951 Both :c:func:`snd_ac97_write()` and
2952 :c:func:`snd_ac97_update()` functions are used to set a value to
2953 the given register (``AC97_XXX``). The difference between them is that
2954 :c:func:`snd_ac97_update()` doesn't write a value if the given
2955 value has been already set, while :c:func:`snd_ac97_write()`
2956 always rewrites the value.
2960 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2961 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2963 :c:func:`snd_ac97_read()` is used to read the value of the given
2964 register. For example,
2968 value = snd_ac97_read(ac97, AC97_MASTER);
2970 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2975 snd_ac97_update_bits(ac97, reg, mask, value);
2977 Also, there is a function to change the sample rate (of a given register
2978 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2979 codec: :c:func:`snd_ac97_set_rate()`.
2983 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2986 The following registers are available to set the rate:
2987 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2988 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2989 specified, the register is not really changed but the corresponding
2990 IEC958 status bits will be updated.
2995 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2996 (to save a quartz!). In this case, change the field ``bus->clock`` to
2997 the corresponding value. For example, intel8x0 and es1968 drivers have
2998 their own function to read from the clock.
3003 The ALSA AC97 interface will create a proc file such as
3004 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
3005 can refer to these files to see the current status and registers of
3011 When there are several codecs on the same card, you need to call
3012 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
3013 greater. The ``num`` field specifies the codec number.
3015 If you set up multiple codecs, you either need to write different
3016 callbacks for each codec or check ``ac97->num`` in the callback
3019 MIDI (MPU401-UART) Interface
3020 ============================
3025 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3026 soundcard supports the standard MPU401-UART interface, most likely you
3027 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3028 ``<sound/mpu401.h>``.
3030 Some soundchips have a similar but slightly different implementation of
3031 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3036 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3040 struct snd_rawmidi *rmidi;
3041 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3045 The first argument is the card pointer, and the second is the index of
3046 this component. You can create up to 8 rawmidi devices.
3048 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3049 it's not a special one, you can use ``MPU401_HW_MPU401``.
3051 The 4th argument is the I/O port address. Many backward-compatible
3052 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3053 PCI I/O region. It depends on the chip design.
3055 The 5th argument is a bitflag for additional information. When the I/O
3056 port address above is part of the PCI I/O region, the MPU401 I/O port
3057 might have been already allocated (reserved) by the driver itself. In
3058 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3059 mpu401-uart layer will allocate the I/O ports by itself.
3061 When the controller supports only the input or output MIDI stream, pass
3062 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3063 respectively. Then the rawmidi instance is created as a single stream.
3065 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3066 (via readb and writeb) instead of iob and outb. In this case, you have
3067 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3069 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3070 the default interrupt handler. The driver needs to call
3071 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3072 processing the output stream in the irq handler.
3074 If the MPU-401 interface shares its interrupt with the other logical
3075 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3076 `below <#MIDI-Interrupt-Handler>`__).
3078 Usually, the port address corresponds to the command port and port + 1
3079 corresponds to the data port. If not, you may change the ``cport``
3080 field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3081 However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
3082 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3083 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3084 <snd_mpu401>` explicitly,
3088 struct snd_mpu401 *mpu;
3089 mpu = rmidi->private_data;
3091 and reset the ``cport`` as you like:
3095 mpu->cport = my_own_control_port;
3097 The 6th argument specifies the ISA irq number that will be allocated. If
3098 no interrupt is to be allocated (because your code is already allocating
3099 a shared interrupt, or because the device does not use interrupts), pass
3100 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3101 will be used instead.
3103 MIDI Interrupt Handler
3104 ----------------------
3106 When the interrupt is allocated in
3107 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3108 handler is automatically used, hence you don't have anything else to do
3109 than creating the mpu401 stuff. Otherwise, you have to set
3110 ``MPU401_INFO_IRQ_HOOK``, and call
3111 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3112 interrupt handler when it has determined that a UART interrupt has
3115 In this case, you need to pass the private_data of the returned rawmidi
3116 object from :c:func:`snd_mpu401_uart_new()` as the second
3117 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3121 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3130 The raw MIDI interface is used for hardware MIDI ports that can be
3131 accessed as a byte stream. It is not used for synthesizer chips that do
3132 not directly understand MIDI.
3134 ALSA handles file and buffer management. All you have to do is to write
3135 some code to move data between the buffer and the hardware.
3137 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3142 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3147 struct snd_rawmidi *rmidi;
3148 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3151 rmidi->private_data = chip;
3152 strcpy(rmidi->name, "My MIDI");
3153 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3154 SNDRV_RAWMIDI_INFO_INPUT |
3155 SNDRV_RAWMIDI_INFO_DUPLEX;
3157 The first argument is the card pointer, the second argument is the ID
3160 The third argument is the index of this component. You can create up to
3163 The fourth and fifth arguments are the number of output and input
3164 substreams, respectively, of this device (a substream is the equivalent
3167 Set the ``info_flags`` field to specify the capabilities of the
3168 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3169 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3170 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3171 output and input at the same time.
3173 After the rawmidi device is created, you need to set the operators
3174 (callbacks) for each substream. There are helper functions to set the
3175 operators for all the substreams of a device:
3179 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3180 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3182 The operators are usually defined like this:
3186 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3187 .open = snd_mymidi_output_open,
3188 .close = snd_mymidi_output_close,
3189 .trigger = snd_mymidi_output_trigger,
3192 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3194 If there are more than one substream, you should give a unique name to
3199 struct snd_rawmidi_substream *substream;
3200 list_for_each_entry(substream,
3201 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3203 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3205 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3210 In all the callbacks, the private data that you've set for the rawmidi
3211 device can be accessed as ``substream->rmidi->private_data``.
3213 If there is more than one port, your callbacks can determine the port
3214 index from the struct snd_rawmidi_substream data passed to each
3219 struct snd_rawmidi_substream *substream;
3220 int index = substream->number;
3222 RawMIDI open callback
3223 ~~~~~~~~~~~~~~~~~~~~~
3227 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3230 This is called when a substream is opened. You can initialize the
3231 hardware here, but you shouldn't start transmitting/receiving data yet.
3233 RawMIDI close callback
3234 ~~~~~~~~~~~~~~~~~~~~~~
3238 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3242 The ``open`` and ``close`` callbacks of a rawmidi device are
3243 serialized with a mutex, and can sleep.
3245 Rawmidi trigger callback for output substreams
3246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3250 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3253 This is called with a nonzero ``up`` parameter when there is some data
3254 in the substream buffer that must be transmitted.
3256 To read data from the buffer, call
3257 :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3258 of bytes that have been read; this will be less than the number of bytes
3259 requested when there are no more data in the buffer. After the data have
3260 been transmitted successfully, call
3261 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3267 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3268 if (snd_mychip_try_to_transmit(data))
3269 snd_rawmidi_transmit_ack(substream, 1);
3271 break; /* hardware FIFO full */
3274 If you know beforehand that the hardware will accept data, you can use
3275 the :c:func:`snd_rawmidi_transmit()` function which reads some
3276 data and removes them from the buffer at once:
3280 while (snd_mychip_transmit_possible()) {
3282 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3283 break; /* no more data */
3284 snd_mychip_transmit(data);
3287 If you know beforehand how many bytes you can accept, you can use a
3288 buffer size greater than one with the
3289 :c:func:`snd_rawmidi_transmit\*()` functions.
3291 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3292 before the substream buffer has been emptied, you have to continue
3293 transmitting data later, either in an interrupt handler, or with a
3294 timer if the hardware doesn't have a MIDI transmit interrupt.
3296 The ``trigger`` callback is called with a zero ``up`` parameter when
3297 the transmission of data should be aborted.
3299 RawMIDI trigger callback for input substreams
3300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3304 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3307 This is called with a nonzero ``up`` parameter to enable receiving data,
3308 or with a zero ``up`` parameter do disable receiving data.
3310 The ``trigger`` callback must not sleep; the actual reading of data
3311 from the device is usually done in an interrupt handler.
3313 When data reception is enabled, your interrupt handler should call
3314 :c:func:`snd_rawmidi_receive()` for all received data:
3318 void snd_mychip_midi_interrupt(...)
3320 while (mychip_midi_available()) {
3322 data = mychip_midi_read();
3323 snd_rawmidi_receive(substream, &data, 1);
3333 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3336 This is only used with output substreams. This function should wait
3337 until all data read from the substream buffer have been transmitted.
3338 This ensures that the device can be closed and the driver unloaded
3339 without losing data.
3341 This callback is optional. If you do not set ``drain`` in the struct
3342 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3345 Miscellaneous Devices
3346 =====================
3351 The FM OPL3 is still used in many chips (mainly for backward
3352 compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3353 is defined in ``<sound/opl3.h>``.
3355 FM registers can be directly accessed through the direct-FM API, defined
3356 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3357 accessed through the Hardware-Dependent Device direct-FM extension API,
3358 whereas in OSS compatible mode, FM registers can be accessed with the
3359 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3361 To create the OPL3 component, you have two functions to call. The first
3362 one is a constructor for the ``opl3_t`` instance.
3366 struct snd_opl3 *opl3;
3367 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3370 The first argument is the card pointer, the second one is the left port
3371 address, and the third is the right port address. In most cases, the
3372 right port is placed at the left port + 2.
3374 The fourth argument is the hardware type.
3376 When the left and right ports have been already allocated by the card
3377 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3378 the opl3 module will allocate the specified ports by itself.
3380 When the accessing the hardware requires special method instead of the
3381 standard I/O access, you can create opl3 instance separately with
3382 :c:func:`snd_opl3_new()`.
3386 struct snd_opl3 *opl3;
3387 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3389 Then set ``command``, ``private_data`` and ``private_free`` for the
3390 private access function, the private data and the destructor. The
3391 ``l_port`` and ``r_port`` are not necessarily set. Only the command
3392 must be set properly. You can retrieve the data from the
3393 ``opl3->private_data`` field.
3395 After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3396 call :c:func:`snd_opl3_init()` to initialize the chip to the
3397 proper state. Note that :c:func:`snd_opl3_create()` always calls
3400 If the opl3 instance is created successfully, then create a hwdep device
3405 struct snd_hwdep *opl3hwdep;
3406 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3408 The first argument is the ``opl3_t`` instance you created, and the
3409 second is the index number, usually 0.
3411 The third argument is the index-offset for the sequencer client assigned
3412 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3415 Hardware-Dependent Devices
3416 --------------------------
3418 Some chips need user-space access for special controls or for loading
3419 the micro code. In such a case, you can create a hwdep
3420 (hardware-dependent) device. The hwdep API is defined in
3421 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3422 ``isa/sb/sb16_csp.c``.
3424 The creation of the ``hwdep`` instance is done via
3425 :c:func:`snd_hwdep_new()`.
3429 struct snd_hwdep *hw;
3430 snd_hwdep_new(card, "My HWDEP", 0, &hw);
3432 where the third argument is the index number.
3434 You can then pass any pointer value to the ``private_data``. If you
3435 assign a private data, you should define the destructor, too. The
3436 destructor function is set in the ``private_free`` field.
3440 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3441 hw->private_data = p;
3442 hw->private_free = mydata_free;
3444 and the implementation of the destructor would be:
3448 static void mydata_free(struct snd_hwdep *hw)
3450 struct mydata *p = hw->private_data;
3454 The arbitrary file operations can be defined for this instance. The file
3455 operators are defined in the ``ops`` table. For example, assume that
3456 this chip needs an ioctl.
3460 hw->ops.open = mydata_open;
3461 hw->ops.ioctl = mydata_ioctl;
3462 hw->ops.release = mydata_release;
3464 And implement the callback functions as you like.
3469 Usually the controls for IEC958 devices are implemented via the control
3470 interface. There is a macro to compose a name string for IEC958
3471 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3472 ``<include/asound.h>``.
3474 There are some standard controls for IEC958 status bits. These controls
3475 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3476 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3477 callback, you don't specify the value field for this type (the count
3478 field must be set, though).
3480 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3481 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3482 returns the bitmask for professional mode. They are read-only controls,
3483 and are defined as MIXER controls (iface =
3484 ``SNDRV_CTL_ELEM_IFACE_MIXER``).
3486 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3487 setting the current default IEC958 bits. Note that this one is usually
3488 defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3489 although in some places it's defined as a MIXER control.
3491 In addition, you can define the control switches to enable/disable or to
3492 set the raw bit mode. The implementation will depend on the chip, but
3493 the control should be named as “IEC958 xxx”, preferably using the
3494 :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3496 You can find several cases, for example, ``pci/emu10k1``,
3497 ``pci/ice1712``, or ``pci/cmipci.c``.
3499 Buffer and Memory Management
3500 ============================
3505 ALSA provides several different buffer allocation functions depending on
3506 the bus and the architecture. All these have a consistent API. The
3507 allocation of physically-contiguous pages is done via
3508 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3511 The allocation of pages with fallback is
3512 :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3513 to allocate the specified pages but if the pages are not available, it
3514 tries to reduce the page sizes until enough space is found.
3516 The release the pages, call :c:func:`snd_free_xxx_pages()`
3519 Usually, ALSA drivers try to allocate and reserve a large contiguous
3520 physical space at the time the module is loaded for the later use. This
3521 is called “pre-allocation”. As already written, you can call the
3522 following function at pcm instance construction time (in the case of PCI
3527 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3528 &pci->dev, size, max);
3530 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3531 the maximum size to be changed via the ``prealloc`` proc file. The
3532 allocator will try to get an area as large as possible within the
3535 The second argument (type) and the third argument (device pointer) are
3536 dependent on the bus. For normal devices, pass the device pointer
3537 (typically identical as ``card->dev``) to the third argument with
3538 ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3539 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3540 You can pass NULL to the device pointer in that case, which is the
3541 default mode implying to allocate with ``GFP_KRENEL`` flag.
3542 If you need a different GFP flag, you can pass it by encoding the flag
3543 into the device pointer via a special macro
3544 :c:func:`snd_dma_continuous_data()`.
3545 For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3546 device pointer (see the `Non-Contiguous Buffers`_ section).
3548 Once the buffer is pre-allocated, you can use the allocator in the
3549 ``hw_params`` callback:
3553 snd_pcm_lib_malloc_pages(substream, size);
3555 Note that you have to pre-allocate to use this function.
3557 Most of drivers use, though, rather the newly introduced "managed
3558 buffer allocation mode" instead of the manual allocation or release.
3559 This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3560 instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
3564 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3565 &pci->dev, size, max);
3567 where passed arguments are identical in both functions.
3568 The difference in the managed mode is that PCM core will call
3569 :c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3570 the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3571 after the PCM ``hw_free`` callback automatically. So the driver
3572 doesn't have to call these functions explicitly in its callback any
3573 longer. This made many driver code having NULL ``hw_params`` and
3574 ``hw_free`` entries.
3576 External Hardware Buffers
3577 -------------------------
3579 Some chips have their own hardware buffers and the DMA transfer from the
3580 host memory is not available. In such a case, you need to either 1)
3581 copy/set the audio data directly to the external hardware buffer, or 2)
3582 make an intermediate buffer and copy/set the data from it to the
3583 external hardware buffer in interrupts (or in tasklets, preferably).
3585 The first case works fine if the external hardware buffer is large
3586 enough. This method doesn't need any extra buffers and thus is more
3587 effective. You need to define the ``copy_user`` and ``copy_kernel``
3588 callbacks for the data transfer, in addition to ``fill_silence``
3589 callback for playback. However, there is a drawback: it cannot be
3590 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3592 The second case allows for mmap on the buffer, although you have to
3593 handle an interrupt or a tasklet to transfer the data from the
3594 intermediate buffer to the hardware buffer. You can find an example in
3595 the vxpocket driver.
3597 Another case is when the chip uses a PCI memory-map region for the
3598 buffer instead of the host memory. In this case, mmap is available only
3599 on certain architectures like the Intel one. In non-mmap mode, the data
3600 cannot be transferred as in the normal way. Thus you need to define the
3601 ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3602 as in the cases above. The examples are found in ``rme32.c`` and
3605 The implementation of the ``copy_user``, ``copy_kernel`` and
3606 ``silence`` callbacks depends upon whether the hardware supports
3607 interleaved or non-interleaved samples. The ``copy_user`` callback is
3608 defined like below, a bit differently depending whether the direction
3609 is playback or capture:
3613 static int playback_copy_user(struct snd_pcm_substream *substream,
3614 int channel, unsigned long pos,
3615 void __user *src, unsigned long count);
3616 static int capture_copy_user(struct snd_pcm_substream *substream,
3617 int channel, unsigned long pos,
3618 void __user *dst, unsigned long count);
3620 In the case of interleaved samples, the second argument (``channel``) is
3621 not used. The third argument (``pos``) points the current position
3624 The meaning of the fourth argument is different between playback and
3625 capture. For playback, it holds the source data pointer, and for
3626 capture, it's the destination data pointer.
3628 The last argument is the number of bytes to be copied.
3630 What you have to do in this callback is again different between playback
3631 and capture directions. In the playback case, you copy the given amount
3632 of data (``count``) at the specified pointer (``src``) to the specified
3633 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3634 way, the copy would be like:
3638 my_memcpy_from_user(my_buffer + pos, src, count);
3640 For the capture direction, you copy the given amount of data (``count``)
3641 at the specified offset (``pos``) on the hardware buffer to the
3642 specified pointer (``dst``).
3646 my_memcpy_to_user(dst, my_buffer + pos, count);
3648 Here the functions are named as ``from_user`` and ``to_user`` because
3649 it's the user-space buffer that is passed to these callbacks. That
3650 is, the callback is supposed to copy from/to the user-space data
3651 directly to/from the hardware buffer.
3653 Careful readers might notice that these callbacks receive the
3654 arguments in bytes, not in frames like other callbacks. It's because
3655 it would make coding easier like the examples above, and also it makes
3656 easier to unify both the interleaved and non-interleaved cases, as
3657 explained in the following.
3659 In the case of non-interleaved samples, the implementation will be a bit
3660 more complicated. The callback is called for each channel, passed by
3661 the second argument, so totally it's called for N-channels times per
3664 The meaning of other arguments are almost same as the interleaved
3665 case. The callback is supposed to copy the data from/to the given
3666 user-space buffer, but only for the given channel. For the detailed
3667 implementations, please check ``isa/gus/gus_pcm.c`` or
3668 "pci/rme9652/rme9652.c" as examples.
3670 The above callbacks are the copy from/to the user-space buffer. There
3671 are some cases where we want copy from/to the kernel-space buffer
3672 instead. In such a case, ``copy_kernel`` callback is called. It'd
3677 static int playback_copy_kernel(struct snd_pcm_substream *substream,
3678 int channel, unsigned long pos,
3679 void *src, unsigned long count);
3680 static int capture_copy_kernel(struct snd_pcm_substream *substream,
3681 int channel, unsigned long pos,
3682 void *dst, unsigned long count);
3684 As found easily, the only difference is that the buffer pointer is
3685 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3686 in the fourth argument. Correspondingly, the implementation would be
3687 a version without the user-copy, such as:
3691 my_memcpy(my_buffer + pos, src, count);
3693 Usually for the playback, another callback ``fill_silence`` is
3694 defined. It's implemented in a similar way as the copy callbacks
3699 static int silence(struct snd_pcm_substream *substream, int channel,
3700 unsigned long pos, unsigned long count);
3702 The meanings of arguments are the same as in the ``copy_user`` and
3703 ``copy_kernel`` callbacks, although there is no buffer pointer
3704 argument. In the case of interleaved samples, the channel argument has
3705 no meaning, as well as on ``copy_*`` callbacks.
3707 The role of ``fill_silence`` callback is to set the given amount
3708 (``count``) of silence data at the specified offset (``pos``) on the
3709 hardware buffer. Suppose that the data format is signed (that is, the
3710 silent-data is 0), and the implementation using a memset-like function
3715 my_memset(my_buffer + pos, 0, count);
3717 In the case of non-interleaved samples, again, the implementation
3718 becomes a bit more complicated, as it's called N-times per transfer
3719 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3721 Non-Contiguous Buffers
3722 ----------------------
3724 If your hardware supports the page table as in emu10k1 or the buffer
3725 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3726 provides an interface for handling SG-buffers. The API is provided in
3729 For creating the SG-buffer handler, call
3730 :c:func:`snd_pcm_set_managed_buffer()` or
3731 :c:func:`snd_pcm_set_managed_buffer_all()` with
3732 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3733 pre-allocator. You need to pass ``&pci->dev``, where pci is
3734 the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3739 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3740 &pci->dev, size, max);
3742 The ``struct snd_sg_buf`` instance is created as
3743 ``substream->dma_private`` in turn. You can cast the pointer like:
3747 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3749 Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3750 handler will allocate the non-contiguous kernel pages of the given size
3751 and map them onto the virtually contiguous memory. The virtual pointer
3752 is addressed in runtime->dma_area. The physical address
3753 (``runtime->dma_addr``) is set to zero, because the buffer is
3754 physically non-contiguous. The physical address table is set up in
3755 ``sgbuf->table``. You can get the physical address at a certain offset
3756 via :c:func:`snd_pcm_sgbuf_get_addr()`.
3758 If you need to release the SG-buffer data explicitly, call the
3759 standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3764 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3765 example, for an intermediate buffer. In the recent version of kernel,
3766 you can simply allocate it via standard
3767 :c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
3768 buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
3772 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3775 The NULL is passed to the device pointer argument, which indicates
3776 that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3779 Also, note that zero is passed to both the size and the max size
3780 arguments here. Since each vmalloc call should succeed at any time,
3781 we don't need to pre-allocate the buffers like other continuous
3784 If you need the 32bit DMA allocation, pass the device pointer encoded
3785 by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
3790 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3791 snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
3796 ALSA provides an easy interface for procfs. The proc files are very
3797 useful for debugging. I recommend you set up proc files if you write a
3798 driver and want to get a running status or register dumps. The API is
3799 found in ``<sound/info.h>``.
3801 To create a proc file, call :c:func:`snd_card_proc_new()`.
3805 struct snd_info_entry *entry;
3806 int err = snd_card_proc_new(card, "my-file", &entry);
3808 where the second argument specifies the name of the proc file to be
3809 created. The above example will create a file ``my-file`` under the
3810 card directory, e.g. ``/proc/asound/card0/my-file``.
3812 Like other components, the proc entry created via
3813 :c:func:`snd_card_proc_new()` will be registered and released
3814 automatically in the card registration and release functions.
3816 When the creation is successful, the function stores a new instance in
3817 the pointer given in the third argument. It is initialized as a text
3818 proc file for read only. To use this proc file as a read-only text file
3819 as it is, set the read callback with a private data via
3820 :c:func:`snd_info_set_text_ops()`.
3824 snd_info_set_text_ops(entry, chip, my_proc_read);
3826 where the second argument (``chip``) is the private data to be used in
3827 the callbacks. The third parameter specifies the read buffer size and
3828 the fourth (``my_proc_read``) is the callback function, which is
3833 static void my_proc_read(struct snd_info_entry *entry,
3834 struct snd_info_buffer *buffer);
3836 In the read callback, use :c:func:`snd_iprintf()` for output
3837 strings, which works just like normal :c:func:`printf()`. For
3842 static void my_proc_read(struct snd_info_entry *entry,
3843 struct snd_info_buffer *buffer)
3845 struct my_chip *chip = entry->private_data;
3847 snd_iprintf(buffer, "This is my chip!\n");
3848 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3851 The file permissions can be changed afterwards. As default, it's set as
3852 read only for all users. If you want to add write permission for the
3853 user (root as default), do as follows:
3857 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3859 and set the write buffer size and the callback
3863 entry->c.text.write = my_proc_write;
3865 For the write callback, you can use :c:func:`snd_info_get_line()`
3866 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3867 a string from the line. Some examples are found in
3868 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3870 For a raw-data proc-file, set the attributes as follows:
3874 static struct snd_info_entry_ops my_file_io_ops = {
3875 .read = my_file_io_read,
3878 entry->content = SNDRV_INFO_CONTENT_DATA;
3879 entry->private_data = chip;
3880 entry->c.ops = &my_file_io_ops;
3882 entry->mode = S_IFREG | S_IRUGO;
3884 For the raw data, ``size`` field must be set properly. This specifies
3885 the maximum size of the proc file access.
3887 The read/write callbacks of raw mode are more direct than the text mode.
3888 You need to use a low-level I/O functions such as
3889 :c:func:`copy_from/to_user()` to transfer the data.
3893 static ssize_t my_file_io_read(struct snd_info_entry *entry,
3894 void *file_private_data,
3900 if (copy_to_user(buf, local_data + pos, count))
3905 If the size of the info entry has been set up properly, ``count`` and
3906 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3907 have to check the range in the callbacks unless any other condition is
3913 If the chip is supposed to work with suspend/resume functions, you need
3914 to add power-management code to the driver. The additional code for
3915 power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3916 with __maybe_unused attribute; otherwise the compiler will complain
3919 If the driver *fully* supports suspend/resume that is, the device can be
3920 properly resumed to its state when suspend was called, you can set the
3921 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3922 possible when the registers of the chip can be safely saved and restored
3923 to RAM. If this is set, the trigger callback is called with
3924 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3926 Even if the driver doesn't support PM fully but partial suspend/resume
3927 is still possible, it's still worthy to implement suspend/resume
3928 callbacks. In such a case, applications would reset the status by
3929 calling :c:func:`snd_pcm_prepare()` and restart the stream
3930 appropriately. Hence, you can define suspend/resume callbacks below but
3931 don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3933 Note that the trigger with SUSPEND can always be called when
3934 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3935 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3936 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3937 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3938 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3939 to keep it for compatibility reasons.)
3941 In the earlier version of ALSA drivers, a common power-management layer
3942 was provided, but it has been removed. The driver needs to define the
3943 suspend/resume hooks according to the bus the device is connected to. In
3944 the case of PCI drivers, the callbacks look like below:
3948 static int __maybe_unused snd_my_suspend(struct device *dev)
3950 .... /* do things for suspend */
3953 static int __maybe_unused snd_my_resume(struct device *dev)
3955 .... /* do things for suspend */
3959 The scheme of the real suspend job is as follows.
3961 1. Retrieve the card and the chip data.
3963 2. Call :c:func:`snd_power_change_state()` with
3964 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3966 3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3969 4. Save the register values if necessary.
3971 5. Stop the hardware if necessary.
3973 A typical code would be like:
3977 static int __maybe_unused mychip_suspend(struct device *dev)
3980 struct snd_card *card = dev_get_drvdata(dev);
3981 struct mychip *chip = card->private_data;
3983 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3985 snd_ac97_suspend(chip->ac97);
3987 snd_mychip_save_registers(chip);
3989 snd_mychip_stop_hardware(chip);
3994 The scheme of the real resume job is as follows.
3996 1. Retrieve the card and the chip data.
3998 2. Re-initialize the chip.
4000 3. Restore the saved registers if necessary.
4002 4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
4004 5. Restart the hardware (if any).
4006 6. Call :c:func:`snd_power_change_state()` with
4007 ``SNDRV_CTL_POWER_D0`` to notify the processes.
4009 A typical code would be like:
4013 static int __maybe_unused mychip_resume(struct pci_dev *pci)
4016 struct snd_card *card = dev_get_drvdata(dev);
4017 struct mychip *chip = card->private_data;
4019 snd_mychip_reinit_chip(chip);
4021 snd_mychip_restore_registers(chip);
4023 snd_ac97_resume(chip->ac97);
4025 snd_mychip_restart_chip(chip);
4027 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
4031 Note that, at the time this callback gets called, the PCM stream has
4032 been already suspended via its own PM ops calling
4033 :c:func:`snd_pcm_suspend_all()` internally.
4035 OK, we have all callbacks now. Let's set them up. In the initialization
4036 of the card, make sure that you can get the chip data from the card
4037 instance, typically via ``private_data`` field, in case you created the
4038 chip data individually.
4042 static int snd_mychip_probe(struct pci_dev *pci,
4043 const struct pci_device_id *pci_id)
4046 struct snd_card *card;
4047 struct mychip *chip;
4050 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4053 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
4055 card->private_data = chip;
4059 When you created the chip data with :c:func:`snd_card_new()`, it's
4060 anyway accessible via ``private_data`` field.
4064 static int snd_mychip_probe(struct pci_dev *pci,
4065 const struct pci_device_id *pci_id)
4068 struct snd_card *card;
4069 struct mychip *chip;
4072 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4073 sizeof(struct mychip), &card);
4075 chip = card->private_data;
4079 If you need a space to save the registers, allocate the buffer for it
4080 here, too, since it would be fatal if you cannot allocate a memory in
4081 the suspend phase. The allocated buffer should be released in the
4082 corresponding destructor.
4084 And next, set suspend/resume callbacks to the pci_driver.
4088 static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
4090 static struct pci_driver driver = {
4091 .name = KBUILD_MODNAME,
4092 .id_table = snd_my_ids,
4093 .probe = snd_my_probe,
4094 .remove = snd_my_remove,
4095 .driver.pm = &snd_my_pm_ops,
4101 There are standard module options for ALSA. At least, each module should
4102 have the ``index``, ``id`` and ``enable`` options.
4104 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
4105 cards), they should be arrays. The default initial values are defined
4106 already as constants for easier programming:
4110 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
4111 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
4112 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
4114 If the module supports only a single card, they could be single
4115 variables, instead. ``enable`` option is not always necessary in this
4116 case, but it would be better to have a dummy option for compatibility.
4118 The module parameters must be declared with the standard
4119 ``module_param()``, ``module_param_array()`` and
4120 :c:func:`MODULE_PARM_DESC()` macros.
4122 The typical coding would be like below:
4126 #define CARD_NAME "My Chip"
4128 module_param_array(index, int, NULL, 0444);
4129 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
4130 module_param_array(id, charp, NULL, 0444);
4131 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
4132 module_param_array(enable, bool, NULL, 0444);
4133 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4135 Also, don't forget to define the module description and the license.
4136 Especially, the recent modprobe requires to define the
4137 module license as GPL, etc., otherwise the system is shown as “tainted”.
4141 MODULE_DESCRIPTION("Sound driver for My Chip");
4142 MODULE_LICENSE("GPL");
4145 How To Put Your Driver Into ALSA Tree
4146 =====================================
4151 So far, you've learned how to write the driver codes. And you might have
4152 a question now: how to put my own driver into the ALSA driver tree? Here
4153 (finally :) the standard procedure is described briefly.
4155 Suppose that you create a new PCI driver for the card “xyz”. The card
4156 module name would be snd-xyz. The new driver is usually put into the
4157 alsa-driver tree, ``sound/pci`` directory in the case of PCI
4160 In the following sections, the driver code is supposed to be put into
4161 Linux kernel tree. The two cases are covered: a driver consisting of a
4162 single source file and one consisting of several source files.
4164 Driver with A Single Source File
4165 --------------------------------
4167 1. Modify sound/pci/Makefile
4169 Suppose you have a file xyz.c. Add the following two lines
4173 snd-xyz-objs := xyz.o
4174 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4176 2. Create the Kconfig entry
4178 Add the new entry of Kconfig for your xyz driver. config SND_XYZ
4179 tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
4180 to include support for Foobar XYZ soundcard. To compile this driver
4181 as a module, choose M here: the module will be called snd-xyz. the
4182 line, select SND_PCM, specifies that the driver xyz supports PCM. In
4183 addition to SND_PCM, the following components are supported for
4184 select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
4185 SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
4186 SND_AC97_CODEC. Add the select command for each supported
4189 Note that some selections imply the lowlevel selections. For example,
4190 PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4191 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4192 the lowlevel selections again.
4194 For the details of Kconfig script, refer to the kbuild documentation.
4196 Drivers with Several Source Files
4197 ---------------------------------
4199 Suppose that the driver snd-xyz have several source files. They are
4200 located in the new subdirectory, sound/pci/xyz.
4202 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4207 obj-$(CONFIG_SND) += sound/pci/xyz/
4210 2. Under the directory ``sound/pci/xyz``, create a Makefile
4214 snd-xyz-objs := xyz.o abc.o def.o
4215 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4217 3. Create the Kconfig entry
4219 This procedure is as same as in the last section.
4225 :c:func:`snd_printk()` and friends
4226 ----------------------------------
4228 .. note:: This subsection describes a few helper functions for
4229 decorating a bit more on the standard :c:func:`printk()` & co.
4230 However, in general, the use of such helpers is no longer recommended.
4231 If possible, try to stick with the standard functions like
4232 :c:func:`dev_err()` or :c:func:`pr_err()`.
4234 ALSA provides a verbose version of the :c:func:`printk()` function.
4235 If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4236 prints the given message together with the file name and the line of the
4237 caller. The ``KERN_XXX`` prefix is processed as well as the original
4238 :c:func:`printk()` does, so it's recommended to add this prefix,
4239 e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4241 There are also :c:func:`printk()`'s for debugging.
4242 :c:func:`snd_printd()` can be used for general debugging purposes.
4243 If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4244 just like :c:func:`snd_printk()`. If the ALSA is compiled without
4245 the debugging flag, it's ignored.
4247 :c:func:`snd_printdd()` is compiled in only when
4248 ``CONFIG_SND_DEBUG_VERBOSE`` is set.
4253 It shows the ``BUG?`` message and stack trace as well as
4254 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4255 fatal error happens there.
4257 When no debug flag is set, this macro is ignored.
4259 :c:func:`snd_BUG_ON()`
4260 ----------------------
4262 :c:func:`snd_BUG_ON()` macro is similar with
4263 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4264 it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4267 The macro takes an conditional expression to evaluate. When
4268 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4269 the warning message such as ``BUG? (xxx)`` normally followed by stack
4270 trace. In both cases it returns the evaluated value.
4275 I would like to thank Phil Kerr for his help for improvement and
4276 corrections of this document.
4278 Kevin Conder reformatted the original plain-text to the DocBook format.
4280 Giuliano Pochini corrected typos and contributed the example codes in
4281 the hardware constraints section.