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 const 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 const 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 const 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;
808 card->sync_irq = chip->irq;
810 /* (2) initialization of the chip hardware */
811 .... /* (not implemented in this document) */
813 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
815 snd_mychip_free(chip);
824 static struct pci_device_id snd_mychip_ids[] = {
825 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
826 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
830 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
832 /* pci_driver definition */
833 static struct pci_driver driver = {
834 .name = KBUILD_MODNAME,
835 .id_table = snd_mychip_ids,
836 .probe = snd_mychip_probe,
837 .remove = snd_mychip_remove,
840 /* module initialization */
841 static int __init alsa_card_mychip_init(void)
843 return pci_register_driver(&driver);
846 /* module clean up */
847 static void __exit alsa_card_mychip_exit(void)
849 pci_unregister_driver(&driver);
852 module_init(alsa_card_mychip_init)
853 module_exit(alsa_card_mychip_exit)
855 EXPORT_NO_SYMBOLS; /* for old kernels only */
860 The allocation of PCI resources is done in the ``probe`` function, and
861 usually an extra :c:func:`xxx_create()` function is written for this
864 In the case of PCI devices, you first have to call the
865 :c:func:`pci_enable_device()` function before allocating
866 resources. Also, you need to set the proper PCI DMA mask to limit the
867 accessed I/O range. In some cases, you might need to call
868 :c:func:`pci_set_master()` function, too.
870 Suppose the 28bit mask, and the code to be added would be like:
874 err = pci_enable_device(pci);
877 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
878 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
879 printk(KERN_ERR "error to set 28bit mask DMA\n");
880 pci_disable_device(pci);
888 The allocation of I/O ports and irqs is done via standard kernel
889 functions. These resources must be released in the destructor
890 function (see below).
892 Now assume that the PCI device has an I/O port with 8 bytes and an
893 interrupt. Then :c:type:`struct mychip <mychip>` will have the
899 struct snd_card *card;
906 For an I/O port (and also a memory region), you need to have the
907 resource pointer for the standard resource management. For an irq, you
908 have to keep only the irq number (integer). But you need to initialize
909 this number as -1 before actual allocation, since irq 0 is valid. The
910 port address and its resource pointer can be initialized as null by
911 :c:func:`kzalloc()` automatically, so you don't have to take care of
914 The allocation of an I/O port is done like this:
918 err = pci_request_regions(pci, "My Chip");
921 pci_disable_device(pci);
924 chip->port = pci_resource_start(pci, 0);
926 It will reserve the I/O port region of 8 bytes of the given PCI device.
927 The returned value, ``chip->res_port``, is allocated via
928 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
929 must be released via :c:func:`kfree()`, but there is a problem with
930 this. This issue will be explained later.
932 The allocation of an interrupt source is done like this:
936 if (request_irq(pci->irq, snd_mychip_interrupt,
937 IRQF_SHARED, KBUILD_MODNAME, chip)) {
938 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
939 snd_mychip_free(chip);
942 chip->irq = pci->irq;
944 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
945 defined `later <#pcm-interface-interrupt-handler>`__. Note that
946 ``chip->irq`` should be defined only when :c:func:`request_irq()`
949 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
950 as the interrupt flag of :c:func:`request_irq()`.
952 The last argument of :c:func:`request_irq()` is the data pointer
953 passed to the interrupt handler. Usually, the chip-specific record is
954 used for that, but you can use what you like, too.
956 I won't give details about the interrupt handler at this point, but at
957 least its appearance can be explained now. The interrupt handler looks
958 usually like the following:
962 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
964 struct mychip *chip = dev_id;
969 After requesting the IRQ, you can passed it to ``card->sync_irq``
973 card->irq = chip->irq;
975 This allows PCM core automatically performing
976 :c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
977 See the later section `sync_stop callback`_ for details.
979 Now let's write the corresponding destructor for the resources above.
980 The role of destructor is simple: disable the hardware (if already
981 activated) and release the resources. So far, we have no hardware part,
982 so the disabling code is not written here.
984 To release the resources, the “check-and-release” method is a safer way.
985 For the interrupt, do like this:
990 free_irq(chip->irq, chip);
992 Since the irq number can start from 0, you should initialize
993 ``chip->irq`` with a negative value (e.g. -1), so that you can check
994 the validity of the irq number as above.
996 When you requested I/O ports or memory regions via
997 :c:func:`pci_request_region()` or
998 :c:func:`pci_request_regions()` like in this example, release the
999 resource(s) using the corresponding function,
1000 :c:func:`pci_release_region()` or
1001 :c:func:`pci_release_regions()`.
1005 pci_release_regions(chip->pci);
1007 When you requested manually via :c:func:`request_region()` or
1008 :c:func:`request_mem_region()`, you can release it via
1009 :c:func:`release_resource()`. Suppose that you keep the resource
1010 pointer returned from :c:func:`request_region()` in
1011 chip->res_port, the release procedure looks like:
1015 release_and_free_resource(chip->res_port);
1017 Don't forget to call :c:func:`pci_disable_device()` before the
1020 And finally, release the chip-specific record.
1026 We didn't implement the hardware disabling part in the above. If you
1027 need to do this, please note that the destructor may be called even
1028 before the initialization of the chip is completed. It would be better
1029 to have a flag to skip hardware disabling if the hardware was not
1032 When the chip-data is assigned to the card using
1033 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1034 destructor is called at the last. That is, it is assured that all other
1035 components like PCMs and controls have already been released. You don't
1036 have to stop PCMs, etc. explicitly, but just call low-level hardware
1039 The management of a memory-mapped region is almost as same as the
1040 management of an I/O port. You'll need three fields like the
1047 unsigned long iobase_phys;
1048 void __iomem *iobase_virt;
1051 and the allocation would be like below:
1055 err = pci_request_regions(pci, "My Chip");
1060 chip->iobase_phys = pci_resource_start(pci, 0);
1061 chip->iobase_virt = ioremap(chip->iobase_phys,
1062 pci_resource_len(pci, 0));
1064 and the corresponding destructor would be:
1068 static int snd_mychip_free(struct mychip *chip)
1071 if (chip->iobase_virt)
1072 iounmap(chip->iobase_virt);
1074 pci_release_regions(chip->pci);
1078 Of course, a modern way with :c:func:`pci_iomap()` will make things a
1083 err = pci_request_regions(pci, "My Chip");
1088 chip->iobase_virt = pci_iomap(pci, 0, 0);
1090 which is paired with :c:func:`pci_iounmap()` at destructor.
1096 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1097 :c:type:`struct pci_device_id <pci_device_id>` table for
1098 this chipset. It's a table of PCI vendor/device ID number, and some
1105 static struct pci_device_id snd_mychip_ids[] = {
1106 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1107 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1111 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1113 The first and second fields of the :c:type:`struct pci_device_id
1114 <pci_device_id>` structure are the vendor and device IDs. If you
1115 have no reason to filter the matching devices, you can leave the
1116 remaining fields as above. The last field of the :c:type:`struct
1117 pci_device_id <pci_device_id>` struct contains private data
1118 for this entry. You can specify any value here, for example, to define
1119 specific operations for supported device IDs. Such an example is found
1120 in the intel8x0 driver.
1122 The last entry of this list is the terminator. You must specify this
1125 Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1130 static struct pci_driver driver = {
1131 .name = KBUILD_MODNAME,
1132 .id_table = snd_mychip_ids,
1133 .probe = snd_mychip_probe,
1134 .remove = snd_mychip_remove,
1137 The ``probe`` and ``remove`` functions have already been defined in
1138 the previous sections. The ``name`` field is the name string of this
1139 device. Note that you must not use a slash “/” in this string.
1141 And at last, the module entries:
1145 static int __init alsa_card_mychip_init(void)
1147 return pci_register_driver(&driver);
1150 static void __exit alsa_card_mychip_exit(void)
1152 pci_unregister_driver(&driver);
1155 module_init(alsa_card_mychip_init)
1156 module_exit(alsa_card_mychip_exit)
1158 Note that these module entries are tagged with ``__init`` and ``__exit``
1169 The PCM middle layer of ALSA is quite powerful and it is only necessary
1170 for each driver to implement the low-level functions to access its
1173 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1174 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1175 access to some functions related with hw_param.
1177 Each card device can have up to four pcm instances. A pcm instance
1178 corresponds to a pcm device file. The limitation of number of instances
1179 comes only from the available bit size of the Linux's device numbers.
1180 Once when 64bit device number is used, we'll have more pcm instances
1183 A pcm instance consists of pcm playback and capture streams, and each
1184 pcm stream consists of one or more pcm substreams. Some soundcards
1185 support multiple playback functions. For example, emu10k1 has a PCM
1186 playback of 32 stereo substreams. In this case, at each open, a free
1187 substream is (usually) automatically chosen and opened. Meanwhile, when
1188 only one substream exists and it was already opened, the successful open
1189 will either block or error with ``EAGAIN`` according to the file open
1190 mode. But you don't have to care about such details in your driver. The
1191 PCM middle layer will take care of such work.
1196 The example code below does not include any hardware access routines but
1197 shows only the skeleton, how to build up the PCM interfaces.
1201 #include <sound/pcm.h>
1204 /* hardware definition */
1205 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1206 .info = (SNDRV_PCM_INFO_MMAP |
1207 SNDRV_PCM_INFO_INTERLEAVED |
1208 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1209 SNDRV_PCM_INFO_MMAP_VALID),
1210 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1211 .rates = SNDRV_PCM_RATE_8000_48000,
1216 .buffer_bytes_max = 32768,
1217 .period_bytes_min = 4096,
1218 .period_bytes_max = 32768,
1220 .periods_max = 1024,
1223 /* hardware definition */
1224 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1225 .info = (SNDRV_PCM_INFO_MMAP |
1226 SNDRV_PCM_INFO_INTERLEAVED |
1227 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1228 SNDRV_PCM_INFO_MMAP_VALID),
1229 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1230 .rates = SNDRV_PCM_RATE_8000_48000,
1235 .buffer_bytes_max = 32768,
1236 .period_bytes_min = 4096,
1237 .period_bytes_max = 32768,
1239 .periods_max = 1024,
1243 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1245 struct mychip *chip = snd_pcm_substream_chip(substream);
1246 struct snd_pcm_runtime *runtime = substream->runtime;
1248 runtime->hw = snd_mychip_playback_hw;
1249 /* more hardware-initialization will be done here */
1254 /* close callback */
1255 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1257 struct mychip *chip = snd_pcm_substream_chip(substream);
1258 /* the hardware-specific codes will be here */
1265 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1267 struct mychip *chip = snd_pcm_substream_chip(substream);
1268 struct snd_pcm_runtime *runtime = substream->runtime;
1270 runtime->hw = snd_mychip_capture_hw;
1271 /* more hardware-initialization will be done here */
1276 /* close callback */
1277 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1279 struct mychip *chip = snd_pcm_substream_chip(substream);
1280 /* the hardware-specific codes will be here */
1285 /* hw_params callback */
1286 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1287 struct snd_pcm_hw_params *hw_params)
1289 /* the hardware-specific codes will be here */
1294 /* hw_free callback */
1295 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1297 /* the hardware-specific codes will be here */
1302 /* prepare callback */
1303 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1305 struct mychip *chip = snd_pcm_substream_chip(substream);
1306 struct snd_pcm_runtime *runtime = substream->runtime;
1308 /* set up the hardware with the current configuration
1311 mychip_set_sample_format(chip, runtime->format);
1312 mychip_set_sample_rate(chip, runtime->rate);
1313 mychip_set_channels(chip, runtime->channels);
1314 mychip_set_dma_setup(chip, runtime->dma_addr,
1320 /* trigger callback */
1321 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1325 case SNDRV_PCM_TRIGGER_START:
1326 /* do something to start the PCM engine */
1329 case SNDRV_PCM_TRIGGER_STOP:
1330 /* do something to stop the PCM engine */
1338 /* pointer callback */
1339 static snd_pcm_uframes_t
1340 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1342 struct mychip *chip = snd_pcm_substream_chip(substream);
1343 unsigned int current_ptr;
1345 /* get the current hardware pointer */
1346 current_ptr = mychip_get_hw_pointer(chip);
1351 static struct snd_pcm_ops snd_mychip_playback_ops = {
1352 .open = snd_mychip_playback_open,
1353 .close = snd_mychip_playback_close,
1354 .hw_params = snd_mychip_pcm_hw_params,
1355 .hw_free = snd_mychip_pcm_hw_free,
1356 .prepare = snd_mychip_pcm_prepare,
1357 .trigger = snd_mychip_pcm_trigger,
1358 .pointer = snd_mychip_pcm_pointer,
1362 static struct snd_pcm_ops snd_mychip_capture_ops = {
1363 .open = snd_mychip_capture_open,
1364 .close = snd_mychip_capture_close,
1365 .hw_params = snd_mychip_pcm_hw_params,
1366 .hw_free = snd_mychip_pcm_hw_free,
1367 .prepare = snd_mychip_pcm_prepare,
1368 .trigger = snd_mychip_pcm_trigger,
1369 .pointer = snd_mychip_pcm_pointer,
1373 * definitions of capture are omitted here...
1376 /* create a pcm device */
1377 static int snd_mychip_new_pcm(struct mychip *chip)
1379 struct snd_pcm *pcm;
1382 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1385 pcm->private_data = chip;
1386 strcpy(pcm->name, "My Chip");
1389 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1390 &snd_mychip_playback_ops);
1391 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1392 &snd_mychip_capture_ops);
1393 /* pre-allocation of buffers */
1394 /* NOTE: this may fail */
1395 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1405 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1406 function. It would be better to create a constructor for pcm, namely,
1410 static int snd_mychip_new_pcm(struct mychip *chip)
1412 struct snd_pcm *pcm;
1415 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1418 pcm->private_data = chip;
1419 strcpy(pcm->name, "My Chip");
1425 The :c:func:`snd_pcm_new()` function takes four arguments. The
1426 first argument is the card pointer to which this pcm is assigned, and
1427 the second is the ID string.
1429 The third argument (``index``, 0 in the above) is the index of this new
1430 pcm. It begins from zero. If you create more than one pcm instances,
1431 specify the different numbers in this argument. For example, ``index =
1432 1`` for the second PCM device.
1434 The fourth and fifth arguments are the number of substreams for playback
1435 and capture, respectively. Here 1 is used for both arguments. When no
1436 playback or capture substreams are available, pass 0 to the
1437 corresponding argument.
1439 If a chip supports multiple playbacks or captures, you can specify more
1440 numbers, but they must be handled properly in open/close, etc.
1441 callbacks. When you need to know which substream you are referring to,
1442 then it can be obtained from :c:type:`struct snd_pcm_substream
1443 <snd_pcm_substream>` data passed to each callback as follows:
1447 struct snd_pcm_substream *substream;
1448 int index = substream->number;
1451 After the pcm is created, you need to set operators for each pcm stream.
1455 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1456 &snd_mychip_playback_ops);
1457 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1458 &snd_mychip_capture_ops);
1460 The operators are defined typically like this:
1464 static struct snd_pcm_ops snd_mychip_playback_ops = {
1465 .open = snd_mychip_pcm_open,
1466 .close = snd_mychip_pcm_close,
1467 .hw_params = snd_mychip_pcm_hw_params,
1468 .hw_free = snd_mychip_pcm_hw_free,
1469 .prepare = snd_mychip_pcm_prepare,
1470 .trigger = snd_mychip_pcm_trigger,
1471 .pointer = snd_mychip_pcm_pointer,
1474 All the callbacks are described in the Operators_ subsection.
1476 After setting the operators, you probably will want to pre-allocate the
1477 buffer and set up the managed allocation mode.
1478 For that, simply call the following:
1482 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1486 It will allocate a buffer up to 64kB as default. Buffer management
1487 details will be described in the later section `Buffer and Memory
1490 Additionally, you can set some extra information for this pcm in
1491 ``pcm->info_flags``. The available values are defined as
1492 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1493 hardware definition (described later). When your soundchip supports only
1494 half-duplex, specify like this:
1498 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1501 ... And the Destructor?
1502 -----------------------
1504 The destructor for a pcm instance is not always necessary. Since the pcm
1505 device will be released by the middle layer code automatically, you
1506 don't have to call the destructor explicitly.
1508 The destructor would be necessary if you created special records
1509 internally and needed to release them. In such a case, set the
1510 destructor function to ``pcm->private_free``:
1514 static void mychip_pcm_free(struct snd_pcm *pcm)
1516 struct mychip *chip = snd_pcm_chip(pcm);
1517 /* free your own data */
1518 kfree(chip->my_private_pcm_data);
1519 /* do what you like else */
1523 static int snd_mychip_new_pcm(struct mychip *chip)
1525 struct snd_pcm *pcm;
1527 /* allocate your own data */
1528 chip->my_private_pcm_data = kmalloc(...);
1529 /* set the destructor */
1530 pcm->private_data = chip;
1531 pcm->private_free = mychip_pcm_free;
1537 Runtime Pointer - The Chest of PCM Information
1538 ----------------------------------------------
1540 When the PCM substream is opened, a PCM runtime instance is allocated
1541 and assigned to the substream. This pointer is accessible via
1542 ``substream->runtime``. This runtime pointer holds most information you
1543 need to control the PCM: the copy of hw_params and sw_params
1544 configurations, the buffer pointers, mmap records, spinlocks, etc.
1546 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1547 are the contents of this file:
1551 struct _snd_pcm_runtime {
1553 struct snd_pcm_substream *trigger_master;
1554 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1556 snd_pcm_uframes_t avail_max;
1557 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1558 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1560 /* -- HW params -- */
1561 snd_pcm_access_t access; /* access mode */
1562 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1563 snd_pcm_subformat_t subformat; /* subformat */
1564 unsigned int rate; /* rate in Hz */
1565 unsigned int channels; /* channels */
1566 snd_pcm_uframes_t period_size; /* period size */
1567 unsigned int periods; /* periods */
1568 snd_pcm_uframes_t buffer_size; /* buffer size */
1569 unsigned int tick_time; /* tick time */
1570 snd_pcm_uframes_t min_align; /* Min alignment for the format */
1572 unsigned int frame_bits;
1573 unsigned int sample_bits;
1575 unsigned int rate_num;
1576 unsigned int rate_den;
1578 /* -- SW params -- */
1579 struct timespec tstamp_mode; /* mmap timestamp is updated */
1580 unsigned int period_step;
1581 unsigned int sleep_min; /* min ticks to sleep */
1582 snd_pcm_uframes_t start_threshold;
1583 snd_pcm_uframes_t stop_threshold;
1584 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1585 noise is nearest than this */
1586 snd_pcm_uframes_t silence_size; /* Silence filling size */
1587 snd_pcm_uframes_t boundary; /* pointers wrap point */
1589 snd_pcm_uframes_t silenced_start;
1590 snd_pcm_uframes_t silenced_size;
1592 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1595 volatile struct snd_pcm_mmap_status *status;
1596 volatile struct snd_pcm_mmap_control *control;
1597 atomic_t mmap_count;
1599 /* -- locking / scheduling -- */
1601 wait_queue_head_t sleep;
1602 struct timer_list tick_timer;
1603 struct fasync_struct *fasync;
1605 /* -- private section -- */
1607 void (*private_free)(struct snd_pcm_runtime *runtime);
1609 /* -- hardware description -- */
1610 struct snd_pcm_hardware hw;
1611 struct snd_pcm_hw_constraints hw_constraints;
1614 unsigned int timer_resolution; /* timer resolution */
1617 unsigned char *dma_area; /* DMA area */
1618 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1619 size_t dma_bytes; /* size of DMA area */
1621 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1623 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1624 /* -- OSS things -- */
1625 struct snd_pcm_oss_runtime oss;
1630 For the operators (callbacks) of each sound driver, most of these
1631 records are supposed to be read-only. Only the PCM middle-layer changes
1632 / updates them. The exceptions are the hardware description (hw) DMA
1633 buffer information and the private data. Besides, if you use the
1634 standard managed buffer allocation mode, you don't need to set the
1635 DMA buffer information by yourself.
1637 In the sections below, important records are explained.
1639 Hardware Description
1640 ~~~~~~~~~~~~~~~~~~~~
1642 The hardware descriptor (:c:type:`struct snd_pcm_hardware
1643 <snd_pcm_hardware>`) contains the definitions of the fundamental
1644 hardware configuration. Above all, you'll need to define this in the
1645 `PCM open callback`_. Note that the runtime instance holds the copy of
1646 the descriptor, not the pointer to the existing descriptor. That is,
1647 in the open callback, you can modify the copied descriptor
1648 (``runtime->hw``) as you need. For example, if the maximum number of
1649 channels is 1 only on some chip models, you can still use the same
1650 hardware descriptor and change the channels_max later:
1654 struct snd_pcm_runtime *runtime = substream->runtime;
1656 runtime->hw = snd_mychip_playback_hw; /* common definition */
1657 if (chip->model == VERY_OLD_ONE)
1658 runtime->hw.channels_max = 1;
1660 Typically, you'll have a hardware descriptor as below:
1664 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1665 .info = (SNDRV_PCM_INFO_MMAP |
1666 SNDRV_PCM_INFO_INTERLEAVED |
1667 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1668 SNDRV_PCM_INFO_MMAP_VALID),
1669 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1670 .rates = SNDRV_PCM_RATE_8000_48000,
1675 .buffer_bytes_max = 32768,
1676 .period_bytes_min = 4096,
1677 .period_bytes_max = 32768,
1679 .periods_max = 1024,
1682 - The ``info`` field contains the type and capabilities of this
1683 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1684 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1685 the mmap is supported and which interleaved format is
1686 supported. When the hardware supports mmap, add the
1687 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1688 interleaved or the non-interleaved formats,
1689 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1690 flag must be set, respectively. If both are supported, you can set
1693 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1694 specified for the OSS mmap mode. Usually both are set. Of course,
1695 ``MMAP_VALID`` is set only if the mmap is really supported.
1697 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1698 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1699 supports the “pause” operation, while the ``RESUME`` bit means that
1700 the pcm supports the full “suspend/resume” operation. If the
1701 ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1702 the corresponding (pause push/release) commands. The suspend/resume
1703 trigger commands can be defined even without the ``RESUME``
1704 flag. See `Power Management`_ section for details.
1706 When the PCM substreams can be synchronized (typically,
1707 synchronized start/stop of a playback and a capture streams), you
1708 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1709 need to check the linked-list of PCM substreams in the trigger
1710 callback. This will be described in the later section.
1712 - ``formats`` field contains the bit-flags of supported formats
1713 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1714 format, give all or'ed bits. In the example above, the signed 16bit
1715 little-endian format is specified.
1717 - ``rates`` field contains the bit-flags of supported rates
1718 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1719 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1720 provided only for typical rates. If your chip supports
1721 unconventional rates, you need to add the ``KNOT`` bit and set up
1722 the hardware constraint manually (explained later).
1724 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1725 rate. This should correspond somehow to ``rates`` bits.
1727 - ``channel_min`` and ``channel_max`` define, as you might already
1728 expected, the minimum and maximum number of channels.
1730 - ``buffer_bytes_max`` defines the maximum buffer size in
1731 bytes. There is no ``buffer_bytes_min`` field, since it can be
1732 calculated from the minimum period size and the minimum number of
1733 periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1734 maximum size of the period in bytes. ``periods_max`` and
1735 ``periods_min`` define the maximum and minimum number of periods in
1738 The “period” is a term that corresponds to a fragment in the OSS
1739 world. The period defines the size at which a PCM interrupt is
1740 generated. This size strongly depends on the hardware. Generally,
1741 the smaller period size will give you more interrupts, that is,
1742 more controls. In the case of capture, this size defines the input
1743 latency. On the other hand, the whole buffer size defines the
1744 output latency for the playback direction.
1746 - There is also a field ``fifo_size``. This specifies the size of the
1747 hardware FIFO, but currently it is neither used in the driver nor
1748 in the alsa-lib. So, you can ignore this field.
1753 Ok, let's go back again to the PCM runtime records. The most
1754 frequently referred records in the runtime instance are the PCM
1755 configurations. The PCM configurations are stored in the runtime
1756 instance after the application sends ``hw_params`` data via
1757 alsa-lib. There are many fields copied from hw_params and sw_params
1758 structs. For example, ``format`` holds the format type chosen by the
1759 application. This field contains the enum value
1760 ``SNDRV_PCM_FORMAT_XXX``.
1762 One thing to be noted is that the configured buffer and period sizes
1763 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1764 channels \* samples-size``. For conversion between frames and bytes,
1765 you can use the :c:func:`frames_to_bytes()` and
1766 :c:func:`bytes_to_frames()` helper functions.
1770 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1772 Also, many software parameters (sw_params) are stored in frames, too.
1773 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1774 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1775 frames as signed integer.
1777 DMA Buffer Information
1778 ~~~~~~~~~~~~~~~~~~~~~~
1780 The DMA buffer is defined by the following four fields, ``dma_area``,
1781 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1782 holds the buffer pointer (the logical address). You can call
1783 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1784 the physical address of the buffer. This field is specified only when
1785 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1786 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1788 If you use either the managed buffer allocation mode or the standard
1789 API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1790 these fields are set by the ALSA middle layer, and you should *not*
1791 change them by yourself. You can read them but not write them. On the
1792 other hand, if you want to allocate the buffer by yourself, you'll
1793 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1794 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1795 your driver doesn't support mmap, this field is not
1796 necessary. ``dma_addr`` is also optional. You can use dma_private as
1802 The running status can be referred via ``runtime->status``. This is
1803 the pointer to the :c:type:`struct snd_pcm_mmap_status
1804 <snd_pcm_mmap_status>` record. For example, you can get the current
1805 DMA hardware pointer via ``runtime->status->hw_ptr``.
1807 The DMA application pointer can be referred via ``runtime->control``,
1808 which points to the :c:type:`struct snd_pcm_mmap_control
1809 <snd_pcm_mmap_control>` record. However, accessing directly to
1810 this value is not recommended.
1815 You can allocate a record for the substream and store it in
1816 ``runtime->private_data``. Usually, this is done in the `PCM open
1817 callback`_. Don't mix this with ``pcm->private_data``. The
1818 ``pcm->private_data`` usually points to the chip instance assigned
1819 statically at the creation of PCM, while the ``runtime->private_data``
1820 points to a dynamic data structure created at the PCM open
1825 static int snd_xxx_open(struct snd_pcm_substream *substream)
1827 struct my_pcm_data *data;
1829 data = kmalloc(sizeof(*data), GFP_KERNEL);
1830 substream->runtime->private_data = data;
1835 The allocated object must be released in the `close callback`_.
1840 OK, now let me give details about each pcm callback (``ops``). In
1841 general, every callback must return 0 if successful, or a negative
1842 error number such as ``-EINVAL``. To choose an appropriate error
1843 number, it is advised to check what value other parts of the kernel
1844 return when the same kind of request fails.
1846 The callback function takes at least the argument with :c:type:`struct
1847 snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1848 record from the given substream instance, you can use the following
1854 struct mychip *chip = snd_pcm_substream_chip(substream);
1858 The macro reads ``substream->private_data``, which is a copy of
1859 ``pcm->private_data``. You can override the former if you need to
1860 assign different data records per PCM substream. For example, the
1861 cmi8330 driver assigns different ``private_data`` for playback and
1862 capture directions, because it uses two different codecs (SB- and
1863 AD-compatible) for different directions.
1870 static int snd_xxx_open(struct snd_pcm_substream *substream);
1872 This is called when a pcm substream is opened.
1874 At least, here you have to initialize the ``runtime->hw``
1875 record. Typically, this is done by like this:
1879 static int snd_xxx_open(struct snd_pcm_substream *substream)
1881 struct mychip *chip = snd_pcm_substream_chip(substream);
1882 struct snd_pcm_runtime *runtime = substream->runtime;
1884 runtime->hw = snd_mychip_playback_hw;
1888 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1891 You can allocate a private data in this callback, as described in
1892 `Private Data`_ section.
1894 If the hardware configuration needs more constraints, set the hardware
1895 constraints here, too. See Constraints_ for more details.
1902 static int snd_xxx_close(struct snd_pcm_substream *substream);
1905 Obviously, this is called when a pcm substream is closed.
1907 Any private instance for a pcm substream allocated in the ``open``
1908 callback will be released here.
1912 static int snd_xxx_close(struct snd_pcm_substream *substream)
1915 kfree(substream->runtime->private_data);
1922 This is used for any special call to pcm ioctls. But usually you can
1923 leave it as NULL, then PCM core calls the generic ioctl callback
1924 function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the
1925 unique setup of channel info or reset procedure, you can pass your own
1926 callback function here.
1933 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1934 struct snd_pcm_hw_params *hw_params);
1936 This is called when the hardware parameter (``hw_params``) is set up
1937 by the application, that is, once when the buffer size, the period
1938 size, the format, etc. are defined for the pcm substream.
1940 Many hardware setups should be done in this callback, including the
1941 allocation of buffers.
1943 Parameters to be initialized are retrieved by
1944 :c:func:`params_xxx()` macros.
1946 When you set up the managed buffer allocation mode for the substream,
1947 a buffer is already allocated before this callback gets
1948 called. Alternatively, you can call a helper function below for
1949 allocating the buffer, too.
1953 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1955 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1956 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1959 Note that this and ``prepare`` callbacks may be called multiple times
1960 per initialization. For example, the OSS emulation may call these
1961 callbacks at each change via its ioctl.
1963 Thus, you need to be careful not to allocate the same buffers many
1964 times, which will lead to memory leaks! Calling the helper function
1965 above many times is OK. It will release the previous buffer
1966 automatically when it was already allocated.
1968 Another note is that this callback is non-atomic (schedulable) as
1969 default, i.e. when no ``nonatomic`` flag set. This is important,
1970 because the ``trigger`` callback is atomic (non-schedulable). That is,
1971 mutexes or any schedule-related functions are not available in
1972 ``trigger`` callback. Please see the subsection Atomicity_ for
1980 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1982 This is called to release the resources allocated via
1985 This function is always called before the close callback is called.
1986 Also, the callback may be called multiple times, too. Keep track
1987 whether the resource was already released.
1989 When you have set up the managed buffer allocation mode for the PCM
1990 substream, the allocated PCM buffer will be automatically released
1991 after this callback gets called. Otherwise you'll have to release the
1992 buffer manually. Typically, when the buffer was allocated from the
1993 pre-allocated pool, you can use the standard API function
1994 :c:func:`snd_pcm_lib_malloc_pages()` like:
1998 snd_pcm_lib_free_pages(substream);
2005 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2007 This callback is called when the pcm is “prepared”. You can set the
2008 format type, sample rate, etc. here. The difference from ``hw_params``
2009 is that the ``prepare`` callback will be called each time
2010 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2013 Note that this callback is now non-atomic. You can use
2014 schedule-related functions safely in this callback.
2016 In this and the following callbacks, you can refer to the values via
2017 the runtime record, ``substream->runtime``. For example, to get the
2018 current rate, format or channels, access to ``runtime->rate``,
2019 ``runtime->format`` or ``runtime->channels``, respectively. The
2020 physical address of the allocated buffer is set to
2021 ``runtime->dma_area``. The buffer and period sizes are in
2022 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2024 Be careful that this callback will be called many times at each setup,
2032 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2034 This is called when the pcm is started, stopped or paused.
2036 Which action is specified in the second argument,
2037 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2038 and ``STOP`` commands must be defined in this callback.
2043 case SNDRV_PCM_TRIGGER_START:
2044 /* do something to start the PCM engine */
2046 case SNDRV_PCM_TRIGGER_STOP:
2047 /* do something to stop the PCM engine */
2053 When the pcm supports the pause operation (given in the info field of
2054 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2055 must be handled here, too. The former is the command to pause the pcm,
2056 and the latter to restart the pcm again.
2058 When the pcm supports the suspend/resume operation, regardless of full
2059 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2060 commands must be handled, too. These commands are issued when the
2061 power-management status is changed. Obviously, the ``SUSPEND`` and
2062 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2063 they are identical to the ``STOP`` and ``START`` commands, respectively.
2064 See the `Power Management`_ section for details.
2066 As mentioned, this callback is atomic as default unless ``nonatomic``
2067 flag set, and you cannot call functions which may sleep. The
2068 ``trigger`` callback should be as minimal as possible, just really
2069 triggering the DMA. The other stuff should be initialized
2070 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2077 static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
2079 This callback is optional, and NULL can be passed. It's called after
2080 the PCM core stops the stream and changes the stream state
2081 ``prepare``, ``hw_params`` or ``hw_free``.
2082 Since the IRQ handler might be still pending, we need to wait until
2083 the pending task finishes before moving to the next step; otherwise it
2084 might lead to a crash due to resource conflicts or access to the freed
2085 resources. A typical behavior is to call a synchronization function
2086 like :c:func:`synchronize_irq()` here.
2088 For majority of drivers that need only a call of
2089 :c:func:`synchronize_irq()`, there is a simpler setup, too.
2090 While keeping NULL to ``sync_stop`` PCM callback, the driver can set
2091 ``card->sync_irq`` field to store the valid interrupt number after
2092 requesting an IRQ, instead. Then PCM core will look call
2093 :c:func:`synchronize_irq()` with the given IRQ appropriately.
2095 If the IRQ handler is released at the card destructor, you don't need
2096 to clear ``card->sync_irq``, as the card itself is being released.
2097 So, usually you'll need to add just a single line for assigning
2098 ``card->sync_irq`` in the driver code unless the driver re-acquires
2099 the IRQ. When the driver frees and re-acquires the IRQ dynamically
2100 (e.g. for suspend/resume), it needs to clear and re-set
2101 ``card->sync_irq`` again appropriately.
2108 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2110 This callback is called when the PCM middle layer inquires the current
2111 hardware position on the buffer. The position must be returned in
2112 frames, ranging from 0 to ``buffer_size - 1``.
2114 This is called usually from the buffer-update routine in the pcm
2115 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2116 is called in the interrupt routine. Then the pcm middle layer updates
2117 the position and calculates the available space, and wakes up the
2118 sleeping poll threads, etc.
2120 This callback is also atomic as default.
2122 copy_user, copy_kernel and fill_silence ops
2123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2125 These callbacks are not mandatory, and can be omitted in most cases.
2126 These callbacks are used when the hardware buffer cannot be in the
2127 normal memory space. Some chips have their own buffer on the hardware
2128 which is not mappable. In such a case, you have to transfer the data
2129 manually from the memory buffer to the hardware buffer. Or, if the
2130 buffer is non-contiguous on both physical and virtual memory spaces,
2131 these callbacks must be defined, too.
2133 If these two callbacks are defined, copy and set-silence operations
2134 are done by them. The detailed will be described in the later section
2135 `Buffer and Memory Management`_.
2140 This callback is also not mandatory. This callback is called when the
2141 ``appl_ptr`` is updated in read or write operations. Some drivers like
2142 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2143 internal buffer, and this callback is useful only for such a purpose.
2145 This callback is atomic as default.
2150 This callback is optional too. The mmap calls this callback to get the
2153 Since the recent changes, you need no special callback any longer for
2154 the standard SG-buffer or vmalloc-buffer. Hence this callback should
2160 This is another optional callback for controlling mmap behavior.
2161 Once when defined, PCM core calls this callback when a page is
2162 memory-mapped instead of dealing via the standard helper.
2163 If you need special handling (due to some architecture or
2164 device-specific issues), implement everything here as you like.
2167 PCM Interrupt Handler
2168 ---------------------
2170 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2171 interrupt handler in the sound driver is to update the buffer position
2172 and to tell the PCM middle layer when the buffer position goes across
2173 the prescribed period size. To inform this, call the
2174 :c:func:`snd_pcm_period_elapsed()` function.
2176 There are several types of sound chips to generate the interrupts.
2178 Interrupts at the period (fragment) boundary
2179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2181 This is the most frequently found type: the hardware generates an
2182 interrupt at each period boundary. In this case, you can call
2183 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2185 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2186 its argument. Thus, you need to keep the substream pointer accessible
2187 from the chip instance. For example, define ``substream`` field in the
2188 chip record to hold the current running substream pointer, and set the
2189 pointer value at ``open`` callback (and reset at ``close`` callback).
2191 If you acquire a spinlock in the interrupt handler, and the lock is used
2192 in other pcm callbacks, too, then you have to release the lock before
2193 calling :c:func:`snd_pcm_period_elapsed()`, because
2194 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2197 Typical code would be like:
2202 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2204 struct mychip *chip = dev_id;
2205 spin_lock(&chip->lock);
2207 if (pcm_irq_invoked(chip)) {
2208 /* call updater, unlock before it */
2209 spin_unlock(&chip->lock);
2210 snd_pcm_period_elapsed(chip->substream);
2211 spin_lock(&chip->lock);
2212 /* acknowledge the interrupt if necessary */
2215 spin_unlock(&chip->lock);
2221 High frequency timer interrupts
2222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2224 This happens when the hardware doesn't generate interrupts at the period
2225 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2226 or ymfpci drivers). In this case, you need to check the current hardware
2227 position and accumulate the processed sample length at each interrupt.
2228 When the accumulated size exceeds the period size, call
2229 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2231 Typical code would be like the following.
2236 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2238 struct mychip *chip = dev_id;
2239 spin_lock(&chip->lock);
2241 if (pcm_irq_invoked(chip)) {
2242 unsigned int last_ptr, size;
2243 /* get the current hardware pointer (in frames) */
2244 last_ptr = get_hw_ptr(chip);
2245 /* calculate the processed frames since the
2248 if (last_ptr < chip->last_ptr)
2249 size = runtime->buffer_size + last_ptr
2252 size = last_ptr - chip->last_ptr;
2253 /* remember the last updated point */
2254 chip->last_ptr = last_ptr;
2255 /* accumulate the size */
2257 /* over the period boundary? */
2258 if (chip->size >= runtime->period_size) {
2259 /* reset the accumulator */
2260 chip->size %= runtime->period_size;
2262 spin_unlock(&chip->lock);
2263 snd_pcm_period_elapsed(substream);
2264 spin_lock(&chip->lock);
2266 /* acknowledge the interrupt if necessary */
2269 spin_unlock(&chip->lock);
2275 On calling :c:func:`snd_pcm_period_elapsed()`
2276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2278 In both cases, even if more than one period are elapsed, you don't have
2279 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2280 once. And the pcm layer will check the current hardware pointer and
2281 update to the latest status.
2286 One of the most important (and thus difficult to debug) problems in
2287 kernel programming are race conditions. In the Linux kernel, they are
2288 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2289 race condition can happen in an interrupt handler, it has to be managed
2290 atomically, and you have to use a spinlock to protect the critical
2291 session. If the critical section is not in interrupt handler code and if
2292 taking a relatively long time to execute is acceptable, you should use
2293 mutexes or semaphores instead.
2295 As already seen, some pcm callbacks are atomic and some are not. For
2296 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2297 callback is atomic. This means, the latter is called already in a
2298 spinlock held by the PCM middle layer. Please take this atomicity into
2299 account when you choose a locking scheme in the callbacks.
2301 In the atomic callbacks, you cannot use functions which may call
2302 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2303 mutexes can sleep, and hence they cannot be used inside the atomic
2304 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2305 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2307 All three atomic callbacks (trigger, pointer, and ack) are called with
2308 local interrupts disabled.
2310 The recent changes in PCM core code, however, allow all PCM operations
2311 to be non-atomic. This assumes that the all caller sides are in
2312 non-atomic contexts. For example, the function
2313 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2314 interrupt handler. But, if you set up the driver to use a threaded
2315 interrupt handler, this call can be in non-atomic context, too. In such
2316 a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2317 <snd_pcm>` object after creating it. When this flag is set, mutex
2318 and rwsem are used internally in the PCM core instead of spin and
2319 rwlocks, so that you can call all PCM functions safely in a non-atomic
2325 If your chip supports unconventional sample rates, or only the limited
2326 samples, you need to set a constraint for the condition.
2328 For example, in order to restrict the sample rates in the some supported
2329 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2330 call this function in the open callback.
2334 static unsigned int rates[] =
2335 {4000, 10000, 22050, 44100};
2336 static struct snd_pcm_hw_constraint_list constraints_rates = {
2337 .count = ARRAY_SIZE(rates),
2342 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2346 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2347 SNDRV_PCM_HW_PARAM_RATE,
2348 &constraints_rates);
2356 There are many different constraints. Look at ``sound/pcm.h`` for a
2357 complete list. You can even define your own constraint rules. For
2358 example, let's suppose my_chip can manage a substream of 1 channel if
2359 and only if the format is ``S16_LE``, otherwise it supports any format
2360 specified in the :c:type:`struct snd_pcm_hardware
2361 <snd_pcm_hardware>` structure (or in any other
2362 constraint_list). You can build a rule like this:
2366 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2367 struct snd_pcm_hw_rule *rule)
2369 struct snd_interval *c = hw_param_interval(params,
2370 SNDRV_PCM_HW_PARAM_CHANNELS);
2371 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2372 struct snd_interval ch;
2374 snd_interval_any(&ch);
2375 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2376 ch.min = ch.max = 1;
2378 return snd_interval_refine(c, &ch);
2384 Then you need to call this function to add your rule:
2388 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2389 hw_rule_channels_by_format, NULL,
2390 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2392 The rule function is called when an application sets the PCM format, and
2393 it refines the number of channels accordingly. But an application may
2394 set the number of channels before setting the format. Thus you also need
2395 to define the inverse rule:
2399 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2400 struct snd_pcm_hw_rule *rule)
2402 struct snd_interval *c = hw_param_interval(params,
2403 SNDRV_PCM_HW_PARAM_CHANNELS);
2404 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2405 struct snd_mask fmt;
2407 snd_mask_any(&fmt); /* Init the struct */
2409 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2410 return snd_mask_refine(f, &fmt);
2416 ... and in the open callback:
2420 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2421 hw_rule_format_by_channels, NULL,
2422 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2424 One typical usage of the hw constraints is to align the buffer size
2425 with the period size. As default, ALSA PCM core doesn't enforce the
2426 buffer size to be aligned with the period size. For example, it'd be
2427 possible to have a combination like 256 period bytes with 999 buffer
2430 Many device chips, however, require the buffer to be a multiple of
2431 periods. In such a case, call
2432 :c:func:`snd_pcm_hw_constraint_integer()` for
2433 ``SNDRV_PCM_HW_PARAM_PERIODS``.
2437 snd_pcm_hw_constraint_integer(substream->runtime,
2438 SNDRV_PCM_HW_PARAM_PERIODS);
2440 This assures that the number of periods is integer, hence the buffer
2441 size is aligned with the period size.
2443 The hw constraint is a very much powerful mechanism to define the
2444 preferred PCM configuration, and there are relevant helpers.
2445 I won't give more details here, rather I would like to say, “Luke, use
2454 The control interface is used widely for many switches, sliders, etc.
2455 which are accessed from user-space. Its most important use is the mixer
2456 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2457 implemented on the control kernel API.
2459 ALSA has a well-defined AC97 control module. If your chip supports only
2460 the AC97 and nothing else, you can skip this section.
2462 The control API is defined in ``<sound/control.h>``. Include this file
2463 if you want to add your own controls.
2465 Definition of Controls
2466 ----------------------
2468 To create a new control, you need to define the following three
2469 callbacks: ``info``, ``get`` and ``put``. Then, define a
2470 :c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
2475 static struct snd_kcontrol_new my_control = {
2476 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2477 .name = "PCM Playback Switch",
2479 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2480 .private_value = 0xffff,
2481 .info = my_control_info,
2482 .get = my_control_get,
2483 .put = my_control_put
2487 The ``iface`` field specifies the control type,
2488 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2489 for global controls that are not logically part of the mixer. If the
2490 control is closely associated with some specific device on the sound
2491 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2492 and specify the device number with the ``device`` and ``subdevice``
2495 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2496 control name is very important, because its role is classified from
2497 its name. There are pre-defined standard control names. The details
2498 are described in the `Control Names`_ subsection.
2500 The ``index`` field holds the index number of this control. If there
2501 are several different controls with the same name, they can be
2502 distinguished by the index number. This is the case when several
2503 codecs exist on the card. If the index is zero, you can omit the
2506 The ``access`` field contains the access type of this control. Give
2507 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2508 there. The details will be explained in the `Access Flags`_
2511 The ``private_value`` field contains an arbitrary long integer value
2512 for this record. When using the generic ``info``, ``get`` and ``put``
2513 callbacks, you can pass a value through this field. If several small
2514 numbers are necessary, you can combine them in bitwise. Or, it's
2515 possible to give a pointer (casted to unsigned long) of some record to
2518 The ``tlv`` field can be used to provide metadata about the control;
2519 see the `Metadata`_ subsection.
2521 The other three are `Control Callbacks`_.
2526 There are some standards to define the control names. A control is
2527 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2529 The first, ``SOURCE``, specifies the source of the control, and is a
2530 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2531 pre-defined sources.
2533 The second, ``DIRECTION``, is one of the following strings according to
2534 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2535 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2538 The third, ``FUNCTION``, is one of the following strings according to
2539 the function of the control: “Switch”, “Volume” and “Route”.
2541 The example of control names are, thus, “Master Capture Switch” or “PCM
2544 There are some exceptions:
2546 Global capture and playback
2547 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2549 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2550 global capture (input) source, switch and volume. Similarly, “Playback
2551 Switch” and “Playback Volume” are used for the global output gain switch
2557 tone-control switch and volumes are specified like “Tone Control - XXX”,
2558 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2564 3D-control switches and volumes are specified like “3D Control - XXX”,
2565 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2570 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2572 More precise information can be found in
2573 ``Documentation/sound/designs/control-names.rst``.
2578 The access flag is the bitmask which specifies the access type of the
2579 given control. The default access type is
2580 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2581 allowed to this control. When the access flag is omitted (i.e. = 0), it
2582 is considered as ``READWRITE`` access as default.
2584 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2585 instead. In this case, you don't have to define the ``put`` callback.
2586 Similarly, when the control is write-only (although it's a rare case),
2587 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2590 If the control value changes frequently (e.g. the VU meter),
2591 ``VOLATILE`` flag should be given. This means that the control may be
2592 changed without `Change notification`_. Applications should poll such
2593 a control constantly.
2595 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2596 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2604 The ``info`` callback is used to get detailed information on this
2605 control. This must store the values of the given :c:type:`struct
2606 snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2607 for a boolean control with a single element:
2612 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2613 struct snd_ctl_elem_info *uinfo)
2615 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2617 uinfo->value.integer.min = 0;
2618 uinfo->value.integer.max = 1;
2624 The ``type`` field specifies the type of the control. There are
2625 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2626 ``INTEGER64``. The ``count`` field specifies the number of elements in
2627 this control. For example, a stereo volume would have count = 2. The
2628 ``value`` field is a union, and the values stored are depending on the
2629 type. The boolean and integer types are identical.
2631 The enumerated type is a bit different from others. You'll need to set
2632 the string for the currently given item index.
2636 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2637 struct snd_ctl_elem_info *uinfo)
2639 static char *texts[4] = {
2640 "First", "Second", "Third", "Fourth"
2642 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2644 uinfo->value.enumerated.items = 4;
2645 if (uinfo->value.enumerated.item > 3)
2646 uinfo->value.enumerated.item = 3;
2647 strcpy(uinfo->value.enumerated.name,
2648 texts[uinfo->value.enumerated.item]);
2652 The above callback can be simplified with a helper function,
2653 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2654 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2655 it's a matter of taste.)
2659 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2660 struct snd_ctl_elem_info *uinfo)
2662 static char *texts[4] = {
2663 "First", "Second", "Third", "Fourth"
2665 return snd_ctl_enum_info(uinfo, 1, 4, texts);
2669 Some common info callbacks are available for your convenience:
2670 :c:func:`snd_ctl_boolean_mono_info()` and
2671 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2672 is an info callback for a mono channel boolean item, just like
2673 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2674 stereo channel boolean item.
2679 This callback is used to read the current value of the control and to
2680 return to user-space.
2687 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2688 struct snd_ctl_elem_value *ucontrol)
2690 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2691 ucontrol->value.integer.value[0] = get_some_value(chip);
2697 The ``value`` field depends on the type of control as well as on the
2698 info callback. For example, the sb driver uses this field to store the
2699 register offset, the bit-shift and the bit-mask. The ``private_value``
2700 field is set as follows:
2704 .private_value = reg | (shift << 16) | (mask << 24)
2706 and is retrieved in callbacks like
2710 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2711 struct snd_ctl_elem_value *ucontrol)
2713 int reg = kcontrol->private_value & 0xff;
2714 int shift = (kcontrol->private_value >> 16) & 0xff;
2715 int mask = (kcontrol->private_value >> 24) & 0xff;
2719 In the ``get`` callback, you have to fill all the elements if the
2720 control has more than one elements, i.e. ``count > 1``. In the example
2721 above, we filled only one element (``value.integer.value[0]``) since
2722 it's assumed as ``count = 1``.
2727 This callback is used to write a value from user-space.
2734 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2735 struct snd_ctl_elem_value *ucontrol)
2737 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2739 if (chip->current_value !=
2740 ucontrol->value.integer.value[0]) {
2741 change_current_value(chip,
2742 ucontrol->value.integer.value[0]);
2750 As seen above, you have to return 1 if the value is changed. If the
2751 value is not changed, return 0 instead. If any fatal error happens,
2752 return a negative error code as usual.
2754 As in the ``get`` callback, when the control has more than one
2755 elements, all elements must be evaluated in this callback, too.
2757 Callbacks are not atomic
2758 ~~~~~~~~~~~~~~~~~~~~~~~~
2760 All these three callbacks are basically not atomic.
2765 When everything is ready, finally we can create a new control. To create
2766 a control, there are two functions to be called,
2767 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2769 In the simplest way, you can do like this:
2773 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2777 where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2778 <snd_kcontrol_new>` object defined above, and chip is the object
2779 pointer to be passed to kcontrol->private_data which can be referred
2782 :c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2783 snd_kcontrol <snd_kcontrol>` instance, and
2784 :c:func:`snd_ctl_add()` assigns the given control component to the
2790 If you need to change and update a control in the interrupt routine, you
2791 can call :c:func:`snd_ctl_notify()`. For example,
2795 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2797 This function takes the card pointer, the event-mask, and the control id
2798 pointer for the notification. The event-mask specifies the types of
2799 notification, for example, in the above example, the change of control
2800 values is notified. The id pointer is the pointer of :c:type:`struct
2801 snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2802 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2808 To provide information about the dB values of a mixer control, use on of
2809 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2810 variable containing this information, set the ``tlv.p`` field to point to
2811 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2812 in the ``access`` field; like this:
2816 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2818 static struct snd_kcontrol_new my_control = {
2820 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2821 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2823 .tlv.p = db_scale_my_control,
2827 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2828 about a mixer control where each step in the control's value changes the
2829 dB value by a constant dB amount. The first parameter is the name of the
2830 variable to be defined. The second parameter is the minimum value, in
2831 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2832 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2835 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2836 about a mixer control where the control's value affects the output
2837 linearly. The first parameter is the name of the variable to be defined.
2838 The second parameter is the minimum value, in units of 0.01 dB. The
2839 third parameter is the maximum value, in units of 0.01 dB. If the
2840 minimum value mutes the control, set the second parameter to
2841 ``TLV_DB_GAIN_MUTE``.
2849 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2850 write much code to control it. Only low-level control routines are
2851 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2860 struct snd_ac97 *ac97;
2864 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2867 struct mychip *chip = ac97->private_data;
2869 /* read a register value here from the codec */
2870 return the_register_value;
2873 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2874 unsigned short reg, unsigned short val)
2876 struct mychip *chip = ac97->private_data;
2878 /* write the given register value to the codec */
2881 static int snd_mychip_ac97(struct mychip *chip)
2883 struct snd_ac97_bus *bus;
2884 struct snd_ac97_template ac97;
2886 static struct snd_ac97_bus_ops ops = {
2887 .write = snd_mychip_ac97_write,
2888 .read = snd_mychip_ac97_read,
2891 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2894 memset(&ac97, 0, sizeof(ac97));
2895 ac97.private_data = chip;
2896 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2903 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2904 with an ``ac97_bus_ops_t`` record with callback functions.
2908 struct snd_ac97_bus *bus;
2909 static struct snd_ac97_bus_ops ops = {
2910 .write = snd_mychip_ac97_write,
2911 .read = snd_mychip_ac97_read,
2914 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2916 The bus record is shared among all belonging ac97 instances.
2918 And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2919 snd_ac97_template <snd_ac97_template>` record together with
2920 the bus pointer created above.
2924 struct snd_ac97_template ac97;
2927 memset(&ac97, 0, sizeof(ac97));
2928 ac97.private_data = chip;
2929 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2931 where chip->ac97 is a pointer to a newly created ``ac97_t``
2932 instance. In this case, the chip pointer is set as the private data,
2933 so that the read/write callback functions can refer to this chip
2934 instance. This instance is not necessarily stored in the chip
2935 record. If you need to change the register values from the driver, or
2936 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2937 the corresponding functions.
2942 The standard callbacks are ``read`` and ``write``. Obviously they
2943 correspond to the functions for read and write accesses to the
2944 hardware low-level codes.
2946 The ``read`` callback returns the register value specified in the
2951 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2954 struct mychip *chip = ac97->private_data;
2956 return the_register_value;
2959 Here, the chip can be cast from ``ac97->private_data``.
2961 Meanwhile, the ``write`` callback is used to set the register
2966 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2967 unsigned short reg, unsigned short val)
2970 These callbacks are non-atomic like the control API callbacks.
2972 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2974 The ``reset`` callback is used to reset the codec. If the chip
2975 requires a special kind of reset, you can define this callback.
2977 The ``wait`` callback is used to add some waiting time in the standard
2978 initialization of the codec. If the chip requires the extra waiting
2979 time, define this callback.
2981 The ``init`` callback is used for additional initialization of the
2984 Updating Registers in The Driver
2985 --------------------------------
2987 If you need to access to the codec from the driver, you can call the
2988 following functions: :c:func:`snd_ac97_write()`,
2989 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2990 :c:func:`snd_ac97_update_bits()`.
2992 Both :c:func:`snd_ac97_write()` and
2993 :c:func:`snd_ac97_update()` functions are used to set a value to
2994 the given register (``AC97_XXX``). The difference between them is that
2995 :c:func:`snd_ac97_update()` doesn't write a value if the given
2996 value has been already set, while :c:func:`snd_ac97_write()`
2997 always rewrites the value.
3001 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
3002 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
3004 :c:func:`snd_ac97_read()` is used to read the value of the given
3005 register. For example,
3009 value = snd_ac97_read(ac97, AC97_MASTER);
3011 :c:func:`snd_ac97_update_bits()` is used to update some bits in
3016 snd_ac97_update_bits(ac97, reg, mask, value);
3018 Also, there is a function to change the sample rate (of a given register
3019 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
3020 codec: :c:func:`snd_ac97_set_rate()`.
3024 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
3027 The following registers are available to set the rate:
3028 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
3029 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
3030 specified, the register is not really changed but the corresponding
3031 IEC958 status bits will be updated.
3036 In some chips, the clock of the codec isn't 48000 but using a PCI clock
3037 (to save a quartz!). In this case, change the field ``bus->clock`` to
3038 the corresponding value. For example, intel8x0 and es1968 drivers have
3039 their own function to read from the clock.
3044 The ALSA AC97 interface will create a proc file such as
3045 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
3046 can refer to these files to see the current status and registers of
3052 When there are several codecs on the same card, you need to call
3053 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
3054 greater. The ``num`` field specifies the codec number.
3056 If you set up multiple codecs, you either need to write different
3057 callbacks for each codec or check ``ac97->num`` in the callback
3060 MIDI (MPU401-UART) Interface
3061 ============================
3066 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3067 soundcard supports the standard MPU401-UART interface, most likely you
3068 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3069 ``<sound/mpu401.h>``.
3071 Some soundchips have a similar but slightly different implementation of
3072 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3077 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3081 struct snd_rawmidi *rmidi;
3082 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3086 The first argument is the card pointer, and the second is the index of
3087 this component. You can create up to 8 rawmidi devices.
3089 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3090 it's not a special one, you can use ``MPU401_HW_MPU401``.
3092 The 4th argument is the I/O port address. Many backward-compatible
3093 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3094 PCI I/O region. It depends on the chip design.
3096 The 5th argument is a bitflag for additional information. When the I/O
3097 port address above is part of the PCI I/O region, the MPU401 I/O port
3098 might have been already allocated (reserved) by the driver itself. In
3099 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3100 mpu401-uart layer will allocate the I/O ports by itself.
3102 When the controller supports only the input or output MIDI stream, pass
3103 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3104 respectively. Then the rawmidi instance is created as a single stream.
3106 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3107 (via readb and writeb) instead of iob and outb. In this case, you have
3108 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3110 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3111 the default interrupt handler. The driver needs to call
3112 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3113 processing the output stream in the irq handler.
3115 If the MPU-401 interface shares its interrupt with the other logical
3116 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3117 `below <#MIDI-Interrupt-Handler>`__).
3119 Usually, the port address corresponds to the command port and port + 1
3120 corresponds to the data port. If not, you may change the ``cport``
3121 field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3122 However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
3123 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3124 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3125 <snd_mpu401>` explicitly,
3129 struct snd_mpu401 *mpu;
3130 mpu = rmidi->private_data;
3132 and reset the ``cport`` as you like:
3136 mpu->cport = my_own_control_port;
3138 The 6th argument specifies the ISA irq number that will be allocated. If
3139 no interrupt is to be allocated (because your code is already allocating
3140 a shared interrupt, or because the device does not use interrupts), pass
3141 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3142 will be used instead.
3144 MIDI Interrupt Handler
3145 ----------------------
3147 When the interrupt is allocated in
3148 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3149 handler is automatically used, hence you don't have anything else to do
3150 than creating the mpu401 stuff. Otherwise, you have to set
3151 ``MPU401_INFO_IRQ_HOOK``, and call
3152 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3153 interrupt handler when it has determined that a UART interrupt has
3156 In this case, you need to pass the private_data of the returned rawmidi
3157 object from :c:func:`snd_mpu401_uart_new()` as the second
3158 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3162 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3171 The raw MIDI interface is used for hardware MIDI ports that can be
3172 accessed as a byte stream. It is not used for synthesizer chips that do
3173 not directly understand MIDI.
3175 ALSA handles file and buffer management. All you have to do is to write
3176 some code to move data between the buffer and the hardware.
3178 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3183 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3188 struct snd_rawmidi *rmidi;
3189 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3192 rmidi->private_data = chip;
3193 strcpy(rmidi->name, "My MIDI");
3194 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3195 SNDRV_RAWMIDI_INFO_INPUT |
3196 SNDRV_RAWMIDI_INFO_DUPLEX;
3198 The first argument is the card pointer, the second argument is the ID
3201 The third argument is the index of this component. You can create up to
3204 The fourth and fifth arguments are the number of output and input
3205 substreams, respectively, of this device (a substream is the equivalent
3208 Set the ``info_flags`` field to specify the capabilities of the
3209 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3210 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3211 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3212 output and input at the same time.
3214 After the rawmidi device is created, you need to set the operators
3215 (callbacks) for each substream. There are helper functions to set the
3216 operators for all the substreams of a device:
3220 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3221 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3223 The operators are usually defined like this:
3227 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3228 .open = snd_mymidi_output_open,
3229 .close = snd_mymidi_output_close,
3230 .trigger = snd_mymidi_output_trigger,
3233 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3235 If there are more than one substream, you should give a unique name to
3240 struct snd_rawmidi_substream *substream;
3241 list_for_each_entry(substream,
3242 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3244 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3246 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3251 In all the callbacks, the private data that you've set for the rawmidi
3252 device can be accessed as ``substream->rmidi->private_data``.
3254 If there is more than one port, your callbacks can determine the port
3255 index from the struct snd_rawmidi_substream data passed to each
3260 struct snd_rawmidi_substream *substream;
3261 int index = substream->number;
3263 RawMIDI open callback
3264 ~~~~~~~~~~~~~~~~~~~~~
3268 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3271 This is called when a substream is opened. You can initialize the
3272 hardware here, but you shouldn't start transmitting/receiving data yet.
3274 RawMIDI close callback
3275 ~~~~~~~~~~~~~~~~~~~~~~
3279 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3283 The ``open`` and ``close`` callbacks of a rawmidi device are
3284 serialized with a mutex, and can sleep.
3286 Rawmidi trigger callback for output substreams
3287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3291 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3294 This is called with a nonzero ``up`` parameter when there is some data
3295 in the substream buffer that must be transmitted.
3297 To read data from the buffer, call
3298 :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3299 of bytes that have been read; this will be less than the number of bytes
3300 requested when there are no more data in the buffer. After the data have
3301 been transmitted successfully, call
3302 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3308 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3309 if (snd_mychip_try_to_transmit(data))
3310 snd_rawmidi_transmit_ack(substream, 1);
3312 break; /* hardware FIFO full */
3315 If you know beforehand that the hardware will accept data, you can use
3316 the :c:func:`snd_rawmidi_transmit()` function which reads some
3317 data and removes them from the buffer at once:
3321 while (snd_mychip_transmit_possible()) {
3323 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3324 break; /* no more data */
3325 snd_mychip_transmit(data);
3328 If you know beforehand how many bytes you can accept, you can use a
3329 buffer size greater than one with the
3330 :c:func:`snd_rawmidi_transmit\*()` functions.
3332 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3333 before the substream buffer has been emptied, you have to continue
3334 transmitting data later, either in an interrupt handler, or with a
3335 timer if the hardware doesn't have a MIDI transmit interrupt.
3337 The ``trigger`` callback is called with a zero ``up`` parameter when
3338 the transmission of data should be aborted.
3340 RawMIDI trigger callback for input substreams
3341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3345 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3348 This is called with a nonzero ``up`` parameter to enable receiving data,
3349 or with a zero ``up`` parameter do disable receiving data.
3351 The ``trigger`` callback must not sleep; the actual reading of data
3352 from the device is usually done in an interrupt handler.
3354 When data reception is enabled, your interrupt handler should call
3355 :c:func:`snd_rawmidi_receive()` for all received data:
3359 void snd_mychip_midi_interrupt(...)
3361 while (mychip_midi_available()) {
3363 data = mychip_midi_read();
3364 snd_rawmidi_receive(substream, &data, 1);
3374 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3377 This is only used with output substreams. This function should wait
3378 until all data read from the substream buffer have been transmitted.
3379 This ensures that the device can be closed and the driver unloaded
3380 without losing data.
3382 This callback is optional. If you do not set ``drain`` in the struct
3383 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3386 Miscellaneous Devices
3387 =====================
3392 The FM OPL3 is still used in many chips (mainly for backward
3393 compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3394 is defined in ``<sound/opl3.h>``.
3396 FM registers can be directly accessed through the direct-FM API, defined
3397 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3398 accessed through the Hardware-Dependent Device direct-FM extension API,
3399 whereas in OSS compatible mode, FM registers can be accessed with the
3400 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3402 To create the OPL3 component, you have two functions to call. The first
3403 one is a constructor for the ``opl3_t`` instance.
3407 struct snd_opl3 *opl3;
3408 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3411 The first argument is the card pointer, the second one is the left port
3412 address, and the third is the right port address. In most cases, the
3413 right port is placed at the left port + 2.
3415 The fourth argument is the hardware type.
3417 When the left and right ports have been already allocated by the card
3418 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3419 the opl3 module will allocate the specified ports by itself.
3421 When the accessing the hardware requires special method instead of the
3422 standard I/O access, you can create opl3 instance separately with
3423 :c:func:`snd_opl3_new()`.
3427 struct snd_opl3 *opl3;
3428 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3430 Then set ``command``, ``private_data`` and ``private_free`` for the
3431 private access function, the private data and the destructor. The
3432 ``l_port`` and ``r_port`` are not necessarily set. Only the command
3433 must be set properly. You can retrieve the data from the
3434 ``opl3->private_data`` field.
3436 After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3437 call :c:func:`snd_opl3_init()` to initialize the chip to the
3438 proper state. Note that :c:func:`snd_opl3_create()` always calls
3441 If the opl3 instance is created successfully, then create a hwdep device
3446 struct snd_hwdep *opl3hwdep;
3447 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3449 The first argument is the ``opl3_t`` instance you created, and the
3450 second is the index number, usually 0.
3452 The third argument is the index-offset for the sequencer client assigned
3453 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3456 Hardware-Dependent Devices
3457 --------------------------
3459 Some chips need user-space access for special controls or for loading
3460 the micro code. In such a case, you can create a hwdep
3461 (hardware-dependent) device. The hwdep API is defined in
3462 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3463 ``isa/sb/sb16_csp.c``.
3465 The creation of the ``hwdep`` instance is done via
3466 :c:func:`snd_hwdep_new()`.
3470 struct snd_hwdep *hw;
3471 snd_hwdep_new(card, "My HWDEP", 0, &hw);
3473 where the third argument is the index number.
3475 You can then pass any pointer value to the ``private_data``. If you
3476 assign a private data, you should define the destructor, too. The
3477 destructor function is set in the ``private_free`` field.
3481 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3482 hw->private_data = p;
3483 hw->private_free = mydata_free;
3485 and the implementation of the destructor would be:
3489 static void mydata_free(struct snd_hwdep *hw)
3491 struct mydata *p = hw->private_data;
3495 The arbitrary file operations can be defined for this instance. The file
3496 operators are defined in the ``ops`` table. For example, assume that
3497 this chip needs an ioctl.
3501 hw->ops.open = mydata_open;
3502 hw->ops.ioctl = mydata_ioctl;
3503 hw->ops.release = mydata_release;
3505 And implement the callback functions as you like.
3510 Usually the controls for IEC958 devices are implemented via the control
3511 interface. There is a macro to compose a name string for IEC958
3512 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3513 ``<include/asound.h>``.
3515 There are some standard controls for IEC958 status bits. These controls
3516 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3517 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3518 callback, you don't specify the value field for this type (the count
3519 field must be set, though).
3521 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3522 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3523 returns the bitmask for professional mode. They are read-only controls,
3524 and are defined as MIXER controls (iface =
3525 ``SNDRV_CTL_ELEM_IFACE_MIXER``).
3527 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3528 setting the current default IEC958 bits. Note that this one is usually
3529 defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3530 although in some places it's defined as a MIXER control.
3532 In addition, you can define the control switches to enable/disable or to
3533 set the raw bit mode. The implementation will depend on the chip, but
3534 the control should be named as “IEC958 xxx”, preferably using the
3535 :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3537 You can find several cases, for example, ``pci/emu10k1``,
3538 ``pci/ice1712``, or ``pci/cmipci.c``.
3540 Buffer and Memory Management
3541 ============================
3546 ALSA provides several different buffer allocation functions depending on
3547 the bus and the architecture. All these have a consistent API. The
3548 allocation of physically-contiguous pages is done via
3549 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3552 The allocation of pages with fallback is
3553 :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3554 to allocate the specified pages but if the pages are not available, it
3555 tries to reduce the page sizes until enough space is found.
3557 The release the pages, call :c:func:`snd_free_xxx_pages()`
3560 Usually, ALSA drivers try to allocate and reserve a large contiguous
3561 physical space at the time the module is loaded for the later use. This
3562 is called “pre-allocation”. As already written, you can call the
3563 following function at pcm instance construction time (in the case of PCI
3568 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3569 &pci->dev, size, max);
3571 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3572 the maximum size to be changed via the ``prealloc`` proc file. The
3573 allocator will try to get an area as large as possible within the
3576 The second argument (type) and the third argument (device pointer) are
3577 dependent on the bus. For normal devices, pass the device pointer
3578 (typically identical as ``card->dev``) to the third argument with
3579 ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3580 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3581 You can pass NULL to the device pointer in that case, which is the
3582 default mode implying to allocate with ``GFP_KRENEL`` flag.
3583 If you need a different GFP flag, you can pass it by encoding the flag
3584 into the device pointer via a special macro
3585 :c:func:`snd_dma_continuous_data()`.
3586 For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3587 device pointer (see the `Non-Contiguous Buffers`_ section).
3589 Once the buffer is pre-allocated, you can use the allocator in the
3590 ``hw_params`` callback:
3594 snd_pcm_lib_malloc_pages(substream, size);
3596 Note that you have to pre-allocate to use this function.
3598 Most of drivers use, though, rather the newly introduced "managed
3599 buffer allocation mode" instead of the manual allocation or release.
3600 This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3601 instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
3605 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3606 &pci->dev, size, max);
3608 where passed arguments are identical in both functions.
3609 The difference in the managed mode is that PCM core will call
3610 :c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3611 the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3612 after the PCM ``hw_free`` callback automatically. So the driver
3613 doesn't have to call these functions explicitly in its callback any
3614 longer. This made many driver code having NULL ``hw_params`` and
3615 ``hw_free`` entries.
3617 External Hardware Buffers
3618 -------------------------
3620 Some chips have their own hardware buffers and the DMA transfer from the
3621 host memory is not available. In such a case, you need to either 1)
3622 copy/set the audio data directly to the external hardware buffer, or 2)
3623 make an intermediate buffer and copy/set the data from it to the
3624 external hardware buffer in interrupts (or in tasklets, preferably).
3626 The first case works fine if the external hardware buffer is large
3627 enough. This method doesn't need any extra buffers and thus is more
3628 effective. You need to define the ``copy_user`` and ``copy_kernel``
3629 callbacks for the data transfer, in addition to ``fill_silence``
3630 callback for playback. However, there is a drawback: it cannot be
3631 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3633 The second case allows for mmap on the buffer, although you have to
3634 handle an interrupt or a tasklet to transfer the data from the
3635 intermediate buffer to the hardware buffer. You can find an example in
3636 the vxpocket driver.
3638 Another case is when the chip uses a PCI memory-map region for the
3639 buffer instead of the host memory. In this case, mmap is available only
3640 on certain architectures like the Intel one. In non-mmap mode, the data
3641 cannot be transferred as in the normal way. Thus you need to define the
3642 ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3643 as in the cases above. The examples are found in ``rme32.c`` and
3646 The implementation of the ``copy_user``, ``copy_kernel`` and
3647 ``silence`` callbacks depends upon whether the hardware supports
3648 interleaved or non-interleaved samples. The ``copy_user`` callback is
3649 defined like below, a bit differently depending whether the direction
3650 is playback or capture:
3654 static int playback_copy_user(struct snd_pcm_substream *substream,
3655 int channel, unsigned long pos,
3656 void __user *src, unsigned long count);
3657 static int capture_copy_user(struct snd_pcm_substream *substream,
3658 int channel, unsigned long pos,
3659 void __user *dst, unsigned long count);
3661 In the case of interleaved samples, the second argument (``channel``) is
3662 not used. The third argument (``pos``) points the current position
3665 The meaning of the fourth argument is different between playback and
3666 capture. For playback, it holds the source data pointer, and for
3667 capture, it's the destination data pointer.
3669 The last argument is the number of bytes to be copied.
3671 What you have to do in this callback is again different between playback
3672 and capture directions. In the playback case, you copy the given amount
3673 of data (``count``) at the specified pointer (``src``) to the specified
3674 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3675 way, the copy would be like:
3679 my_memcpy_from_user(my_buffer + pos, src, count);
3681 For the capture direction, you copy the given amount of data (``count``)
3682 at the specified offset (``pos``) on the hardware buffer to the
3683 specified pointer (``dst``).
3687 my_memcpy_to_user(dst, my_buffer + pos, count);
3689 Here the functions are named as ``from_user`` and ``to_user`` because
3690 it's the user-space buffer that is passed to these callbacks. That
3691 is, the callback is supposed to copy from/to the user-space data
3692 directly to/from the hardware buffer.
3694 Careful readers might notice that these callbacks receive the
3695 arguments in bytes, not in frames like other callbacks. It's because
3696 it would make coding easier like the examples above, and also it makes
3697 easier to unify both the interleaved and non-interleaved cases, as
3698 explained in the following.
3700 In the case of non-interleaved samples, the implementation will be a bit
3701 more complicated. The callback is called for each channel, passed by
3702 the second argument, so totally it's called for N-channels times per
3705 The meaning of other arguments are almost same as the interleaved
3706 case. The callback is supposed to copy the data from/to the given
3707 user-space buffer, but only for the given channel. For the detailed
3708 implementations, please check ``isa/gus/gus_pcm.c`` or
3709 "pci/rme9652/rme9652.c" as examples.
3711 The above callbacks are the copy from/to the user-space buffer. There
3712 are some cases where we want copy from/to the kernel-space buffer
3713 instead. In such a case, ``copy_kernel`` callback is called. It'd
3718 static int playback_copy_kernel(struct snd_pcm_substream *substream,
3719 int channel, unsigned long pos,
3720 void *src, unsigned long count);
3721 static int capture_copy_kernel(struct snd_pcm_substream *substream,
3722 int channel, unsigned long pos,
3723 void *dst, unsigned long count);
3725 As found easily, the only difference is that the buffer pointer is
3726 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3727 in the fourth argument. Correspondingly, the implementation would be
3728 a version without the user-copy, such as:
3732 my_memcpy(my_buffer + pos, src, count);
3734 Usually for the playback, another callback ``fill_silence`` is
3735 defined. It's implemented in a similar way as the copy callbacks
3740 static int silence(struct snd_pcm_substream *substream, int channel,
3741 unsigned long pos, unsigned long count);
3743 The meanings of arguments are the same as in the ``copy_user`` and
3744 ``copy_kernel`` callbacks, although there is no buffer pointer
3745 argument. In the case of interleaved samples, the channel argument has
3746 no meaning, as well as on ``copy_*`` callbacks.
3748 The role of ``fill_silence`` callback is to set the given amount
3749 (``count``) of silence data at the specified offset (``pos``) on the
3750 hardware buffer. Suppose that the data format is signed (that is, the
3751 silent-data is 0), and the implementation using a memset-like function
3756 my_memset(my_buffer + pos, 0, count);
3758 In the case of non-interleaved samples, again, the implementation
3759 becomes a bit more complicated, as it's called N-times per transfer
3760 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3762 Non-Contiguous Buffers
3763 ----------------------
3765 If your hardware supports the page table as in emu10k1 or the buffer
3766 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3767 provides an interface for handling SG-buffers. The API is provided in
3770 For creating the SG-buffer handler, call
3771 :c:func:`snd_pcm_set_managed_buffer()` or
3772 :c:func:`snd_pcm_set_managed_buffer_all()` with
3773 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3774 pre-allocator. You need to pass ``&pci->dev``, where pci is
3775 the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3780 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3781 &pci->dev, size, max);
3783 The ``struct snd_sg_buf`` instance is created as
3784 ``substream->dma_private`` in turn. You can cast the pointer like:
3788 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3790 Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3791 handler will allocate the non-contiguous kernel pages of the given size
3792 and map them onto the virtually contiguous memory. The virtual pointer
3793 is addressed in runtime->dma_area. The physical address
3794 (``runtime->dma_addr``) is set to zero, because the buffer is
3795 physically non-contiguous. The physical address table is set up in
3796 ``sgbuf->table``. You can get the physical address at a certain offset
3797 via :c:func:`snd_pcm_sgbuf_get_addr()`.
3799 If you need to release the SG-buffer data explicitly, call the
3800 standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3805 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3806 example, for an intermediate buffer. In the recent version of kernel,
3807 you can simply allocate it via standard
3808 :c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
3809 buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
3813 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3816 The NULL is passed to the device pointer argument, which indicates
3817 that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3820 Also, note that zero is passed to both the size and the max size
3821 arguments here. Since each vmalloc call should succeed at any time,
3822 we don't need to pre-allocate the buffers like other continuous
3825 If you need the 32bit DMA allocation, pass the device pointer encoded
3826 by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
3831 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3832 snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
3837 ALSA provides an easy interface for procfs. The proc files are very
3838 useful for debugging. I recommend you set up proc files if you write a
3839 driver and want to get a running status or register dumps. The API is
3840 found in ``<sound/info.h>``.
3842 To create a proc file, call :c:func:`snd_card_proc_new()`.
3846 struct snd_info_entry *entry;
3847 int err = snd_card_proc_new(card, "my-file", &entry);
3849 where the second argument specifies the name of the proc file to be
3850 created. The above example will create a file ``my-file`` under the
3851 card directory, e.g. ``/proc/asound/card0/my-file``.
3853 Like other components, the proc entry created via
3854 :c:func:`snd_card_proc_new()` will be registered and released
3855 automatically in the card registration and release functions.
3857 When the creation is successful, the function stores a new instance in
3858 the pointer given in the third argument. It is initialized as a text
3859 proc file for read only. To use this proc file as a read-only text file
3860 as it is, set the read callback with a private data via
3861 :c:func:`snd_info_set_text_ops()`.
3865 snd_info_set_text_ops(entry, chip, my_proc_read);
3867 where the second argument (``chip``) is the private data to be used in
3868 the callbacks. The third parameter specifies the read buffer size and
3869 the fourth (``my_proc_read``) is the callback function, which is
3874 static void my_proc_read(struct snd_info_entry *entry,
3875 struct snd_info_buffer *buffer);
3877 In the read callback, use :c:func:`snd_iprintf()` for output
3878 strings, which works just like normal :c:func:`printf()`. For
3883 static void my_proc_read(struct snd_info_entry *entry,
3884 struct snd_info_buffer *buffer)
3886 struct my_chip *chip = entry->private_data;
3888 snd_iprintf(buffer, "This is my chip!\n");
3889 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3892 The file permissions can be changed afterwards. As default, it's set as
3893 read only for all users. If you want to add write permission for the
3894 user (root as default), do as follows:
3898 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3900 and set the write buffer size and the callback
3904 entry->c.text.write = my_proc_write;
3906 For the write callback, you can use :c:func:`snd_info_get_line()`
3907 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3908 a string from the line. Some examples are found in
3909 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3911 For a raw-data proc-file, set the attributes as follows:
3915 static const struct snd_info_entry_ops my_file_io_ops = {
3916 .read = my_file_io_read,
3919 entry->content = SNDRV_INFO_CONTENT_DATA;
3920 entry->private_data = chip;
3921 entry->c.ops = &my_file_io_ops;
3923 entry->mode = S_IFREG | S_IRUGO;
3925 For the raw data, ``size`` field must be set properly. This specifies
3926 the maximum size of the proc file access.
3928 The read/write callbacks of raw mode are more direct than the text mode.
3929 You need to use a low-level I/O functions such as
3930 :c:func:`copy_from/to_user()` to transfer the data.
3934 static ssize_t my_file_io_read(struct snd_info_entry *entry,
3935 void *file_private_data,
3941 if (copy_to_user(buf, local_data + pos, count))
3946 If the size of the info entry has been set up properly, ``count`` and
3947 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3948 have to check the range in the callbacks unless any other condition is
3954 If the chip is supposed to work with suspend/resume functions, you need
3955 to add power-management code to the driver. The additional code for
3956 power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3957 with __maybe_unused attribute; otherwise the compiler will complain
3960 If the driver *fully* supports suspend/resume that is, the device can be
3961 properly resumed to its state when suspend was called, you can set the
3962 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3963 possible when the registers of the chip can be safely saved and restored
3964 to RAM. If this is set, the trigger callback is called with
3965 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3967 Even if the driver doesn't support PM fully but partial suspend/resume
3968 is still possible, it's still worthy to implement suspend/resume
3969 callbacks. In such a case, applications would reset the status by
3970 calling :c:func:`snd_pcm_prepare()` and restart the stream
3971 appropriately. Hence, you can define suspend/resume callbacks below but
3972 don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3974 Note that the trigger with SUSPEND can always be called when
3975 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3976 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3977 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3978 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3979 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3980 to keep it for compatibility reasons.)
3982 In the earlier version of ALSA drivers, a common power-management layer
3983 was provided, but it has been removed. The driver needs to define the
3984 suspend/resume hooks according to the bus the device is connected to. In
3985 the case of PCI drivers, the callbacks look like below:
3989 static int __maybe_unused snd_my_suspend(struct device *dev)
3991 .... /* do things for suspend */
3994 static int __maybe_unused snd_my_resume(struct device *dev)
3996 .... /* do things for suspend */
4000 The scheme of the real suspend job is as follows.
4002 1. Retrieve the card and the chip data.
4004 2. Call :c:func:`snd_power_change_state()` with
4005 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
4007 3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
4010 4. Save the register values if necessary.
4012 5. Stop the hardware if necessary.
4014 A typical code would be like:
4018 static int __maybe_unused mychip_suspend(struct device *dev)
4021 struct snd_card *card = dev_get_drvdata(dev);
4022 struct mychip *chip = card->private_data;
4024 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
4026 snd_ac97_suspend(chip->ac97);
4028 snd_mychip_save_registers(chip);
4030 snd_mychip_stop_hardware(chip);
4035 The scheme of the real resume job is as follows.
4037 1. Retrieve the card and the chip data.
4039 2. Re-initialize the chip.
4041 3. Restore the saved registers if necessary.
4043 4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
4045 5. Restart the hardware (if any).
4047 6. Call :c:func:`snd_power_change_state()` with
4048 ``SNDRV_CTL_POWER_D0`` to notify the processes.
4050 A typical code would be like:
4054 static int __maybe_unused mychip_resume(struct pci_dev *pci)
4057 struct snd_card *card = dev_get_drvdata(dev);
4058 struct mychip *chip = card->private_data;
4060 snd_mychip_reinit_chip(chip);
4062 snd_mychip_restore_registers(chip);
4064 snd_ac97_resume(chip->ac97);
4066 snd_mychip_restart_chip(chip);
4068 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
4072 Note that, at the time this callback gets called, the PCM stream has
4073 been already suspended via its own PM ops calling
4074 :c:func:`snd_pcm_suspend_all()` internally.
4076 OK, we have all callbacks now. Let's set them up. In the initialization
4077 of the card, make sure that you can get the chip data from the card
4078 instance, typically via ``private_data`` field, in case you created the
4079 chip data individually.
4083 static int snd_mychip_probe(struct pci_dev *pci,
4084 const struct pci_device_id *pci_id)
4087 struct snd_card *card;
4088 struct mychip *chip;
4091 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4094 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
4096 card->private_data = chip;
4100 When you created the chip data with :c:func:`snd_card_new()`, it's
4101 anyway accessible via ``private_data`` field.
4105 static int snd_mychip_probe(struct pci_dev *pci,
4106 const struct pci_device_id *pci_id)
4109 struct snd_card *card;
4110 struct mychip *chip;
4113 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4114 sizeof(struct mychip), &card);
4116 chip = card->private_data;
4120 If you need a space to save the registers, allocate the buffer for it
4121 here, too, since it would be fatal if you cannot allocate a memory in
4122 the suspend phase. The allocated buffer should be released in the
4123 corresponding destructor.
4125 And next, set suspend/resume callbacks to the pci_driver.
4129 static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
4131 static struct pci_driver driver = {
4132 .name = KBUILD_MODNAME,
4133 .id_table = snd_my_ids,
4134 .probe = snd_my_probe,
4135 .remove = snd_my_remove,
4136 .driver.pm = &snd_my_pm_ops,
4142 There are standard module options for ALSA. At least, each module should
4143 have the ``index``, ``id`` and ``enable`` options.
4145 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
4146 cards), they should be arrays. The default initial values are defined
4147 already as constants for easier programming:
4151 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
4152 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
4153 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
4155 If the module supports only a single card, they could be single
4156 variables, instead. ``enable`` option is not always necessary in this
4157 case, but it would be better to have a dummy option for compatibility.
4159 The module parameters must be declared with the standard
4160 ``module_param()``, ``module_param_array()`` and
4161 :c:func:`MODULE_PARM_DESC()` macros.
4163 The typical coding would be like below:
4167 #define CARD_NAME "My Chip"
4169 module_param_array(index, int, NULL, 0444);
4170 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
4171 module_param_array(id, charp, NULL, 0444);
4172 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
4173 module_param_array(enable, bool, NULL, 0444);
4174 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4176 Also, don't forget to define the module description and the license.
4177 Especially, the recent modprobe requires to define the
4178 module license as GPL, etc., otherwise the system is shown as “tainted”.
4182 MODULE_DESCRIPTION("Sound driver for My Chip");
4183 MODULE_LICENSE("GPL");
4186 How To Put Your Driver Into ALSA Tree
4187 =====================================
4192 So far, you've learned how to write the driver codes. And you might have
4193 a question now: how to put my own driver into the ALSA driver tree? Here
4194 (finally :) the standard procedure is described briefly.
4196 Suppose that you create a new PCI driver for the card “xyz”. The card
4197 module name would be snd-xyz. The new driver is usually put into the
4198 alsa-driver tree, ``sound/pci`` directory in the case of PCI
4201 In the following sections, the driver code is supposed to be put into
4202 Linux kernel tree. The two cases are covered: a driver consisting of a
4203 single source file and one consisting of several source files.
4205 Driver with A Single Source File
4206 --------------------------------
4208 1. Modify sound/pci/Makefile
4210 Suppose you have a file xyz.c. Add the following two lines
4214 snd-xyz-objs := xyz.o
4215 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4217 2. Create the Kconfig entry
4219 Add the new entry of Kconfig for your xyz driver. config SND_XYZ
4220 tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
4221 to include support for Foobar XYZ soundcard. To compile this driver
4222 as a module, choose M here: the module will be called snd-xyz. the
4223 line, select SND_PCM, specifies that the driver xyz supports PCM. In
4224 addition to SND_PCM, the following components are supported for
4225 select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
4226 SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
4227 SND_AC97_CODEC. Add the select command for each supported
4230 Note that some selections imply the lowlevel selections. For example,
4231 PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4232 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4233 the lowlevel selections again.
4235 For the details of Kconfig script, refer to the kbuild documentation.
4237 Drivers with Several Source Files
4238 ---------------------------------
4240 Suppose that the driver snd-xyz have several source files. They are
4241 located in the new subdirectory, sound/pci/xyz.
4243 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4248 obj-$(CONFIG_SND) += sound/pci/xyz/
4251 2. Under the directory ``sound/pci/xyz``, create a Makefile
4255 snd-xyz-objs := xyz.o abc.o def.o
4256 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4258 3. Create the Kconfig entry
4260 This procedure is as same as in the last section.
4266 :c:func:`snd_printk()` and friends
4267 ----------------------------------
4269 .. note:: This subsection describes a few helper functions for
4270 decorating a bit more on the standard :c:func:`printk()` & co.
4271 However, in general, the use of such helpers is no longer recommended.
4272 If possible, try to stick with the standard functions like
4273 :c:func:`dev_err()` or :c:func:`pr_err()`.
4275 ALSA provides a verbose version of the :c:func:`printk()` function.
4276 If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4277 prints the given message together with the file name and the line of the
4278 caller. The ``KERN_XXX`` prefix is processed as well as the original
4279 :c:func:`printk()` does, so it's recommended to add this prefix,
4280 e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4282 There are also :c:func:`printk()`'s for debugging.
4283 :c:func:`snd_printd()` can be used for general debugging purposes.
4284 If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4285 just like :c:func:`snd_printk()`. If the ALSA is compiled without
4286 the debugging flag, it's ignored.
4288 :c:func:`snd_printdd()` is compiled in only when
4289 ``CONFIG_SND_DEBUG_VERBOSE`` is set.
4294 It shows the ``BUG?`` message and stack trace as well as
4295 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4296 fatal error happens there.
4298 When no debug flag is set, this macro is ignored.
4300 :c:func:`snd_BUG_ON()`
4301 ----------------------
4303 :c:func:`snd_BUG_ON()` macro is similar with
4304 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4305 it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4308 The macro takes an conditional expression to evaluate. When
4309 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4310 the warning message such as ``BUG? (xxx)`` normally followed by stack
4311 trace. In both cases it returns the evaluated value.
4316 I would like to thank Phil Kerr for his help for improvement and
4317 corrections of this document.
4319 Kevin Conder reformatted the original plain-text to the DocBook format.
4321 Giuliano Pochini corrected typos and contributed the example codes in
4322 the hardware constraints section.
git.samba.org / sfrench / cifs-2.6.git / blob