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 struct 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 <7) 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 calling :c:func:`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 device, specifies the parent
564 device. For PCI devices, typically ``&pci->`` is passed there.
569 After the card is created, you can attach the components (devices) to
570 the card instance. In an ALSA driver, a component is represented as a
571 struct snd_device object. A component
572 can be a PCM instance, a control interface, a raw MIDI interface, etc.
573 Each such instance has one component entry.
575 A component can be created via :c:func:`snd_device_new()`
580 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
582 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
583 data pointer, and the callback pointers (``&ops``). The device-level
584 defines the type of components and the order of registration and
585 de-registration. For most components, the device-level is already
586 defined. For a user-defined component, you can use
587 ``SNDRV_DEV_LOWLEVEL``.
589 This function itself doesn't allocate the data space. The data must be
590 allocated manually beforehand, and its pointer is passed as the
591 argument. This pointer (``chip`` in the above example) is used as the
592 identifier for the instance.
594 Each pre-defined ALSA component such as ac97 and pcm calls
595 :c:func:`snd_device_new()` inside its constructor. The destructor
596 for each component is defined in the callback pointers. Hence, you don't
597 need to take care of calling a destructor for such a component.
599 If you wish to create your own component, you need to set the destructor
600 function to the dev_free callback in the ``ops``, so that it can be
601 released automatically via :c:func:`snd_card_free()`. The next
602 example will show an implementation of chip-specific data.
607 Chip-specific information, e.g. the I/O port address, its resource
608 pointer, or the irq number, is stored in the chip-specific record.
617 In general, there are two ways of allocating the chip record.
619 1. Allocating via :c:func:`snd_card_new()`.
620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622 As mentioned above, you can pass the extra-data-length to the 5th
623 argument of :c:func:`snd_card_new()`, i.e.
627 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
628 sizeof(struct mychip), &card);
630 struct mychip is the type of the chip record.
632 In return, the allocated record can be accessed as
636 struct mychip *chip = card->private_data;
638 With this method, you don't have to allocate twice. The record is
639 released together with the card instance.
641 2. Allocating an extra device.
642 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
644 After allocating a card instance via :c:func:`snd_card_new()`
645 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
649 struct snd_card *card;
651 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
654 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
656 The chip record should have the field to hold the card pointer at least,
661 struct snd_card *card;
666 Then, set the card pointer in the returned chip instance.
672 Next, initialize the fields, and register this chip record as a
673 low-level device with a specified ``ops``,
677 static const struct snd_device_ops ops = {
678 .dev_free = snd_mychip_dev_free,
681 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
683 :c:func:`snd_mychip_dev_free()` is the device-destructor
684 function, which will call the real destructor.
688 static int snd_mychip_dev_free(struct snd_device *device)
690 return snd_mychip_free(device->device_data);
693 where :c:func:`snd_mychip_free()` is the real destructor.
695 The demerit of this method is the obviously more amount of codes.
696 The merit is, however, you can trigger the own callback at registering
697 and disconnecting the card via setting in snd_device_ops.
698 About the registering and disconnecting the card, see the subsections
702 Registration and Release
703 ------------------------
705 After all components are assigned, register the card instance by calling
706 :c:func:`snd_card_register()`. Access to the device files is
707 enabled at this point. That is, before
708 :c:func:`snd_card_register()` is called, the components are safely
709 inaccessible from external side. If this call fails, exit the probe
710 function after releasing the card via :c:func:`snd_card_free()`.
712 For releasing the card instance, you can call simply
713 :c:func:`snd_card_free()`. As mentioned earlier, all components
714 are released automatically by this call.
716 For a device which allows hotplugging, you can use
717 :c:func:`snd_card_free_when_closed()`. This one will postpone
718 the destruction until all devices are closed.
720 PCI Resource Management
721 =======================
726 In this section, we'll complete the chip-specific constructor,
727 destructor and PCI entries. Example code is shown first, below.
732 struct snd_card *card;
739 static int snd_mychip_free(struct mychip *chip)
741 /* disable hardware here if any */
742 .... /* (not implemented in this document) */
744 /* release the irq */
746 free_irq(chip->irq, chip);
747 /* release the I/O ports & memory */
748 pci_release_regions(chip->pci);
749 /* disable the PCI entry */
750 pci_disable_device(chip->pci);
751 /* release the data */
756 /* chip-specific constructor */
757 static int snd_mychip_create(struct snd_card *card,
759 struct mychip **rchip)
763 static const struct snd_device_ops ops = {
764 .dev_free = snd_mychip_dev_free,
769 /* initialize the PCI entry */
770 err = pci_enable_device(pci);
773 /* check PCI availability (28bit DMA) */
774 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
775 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
776 printk(KERN_ERR "error to set 28bit mask DMA\n");
777 pci_disable_device(pci);
781 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
783 pci_disable_device(pci);
787 /* initialize the stuff */
792 /* (1) PCI resource allocation */
793 err = pci_request_regions(pci, "My Chip");
796 pci_disable_device(pci);
799 chip->port = pci_resource_start(pci, 0);
800 if (request_irq(pci->irq, snd_mychip_interrupt,
801 IRQF_SHARED, KBUILD_MODNAME, chip)) {
802 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
803 snd_mychip_free(chip);
806 chip->irq = pci->irq;
807 card->sync_irq = chip->irq;
809 /* (2) initialization of the chip hardware */
810 .... /* (not implemented in this document) */
812 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
814 snd_mychip_free(chip);
823 static struct pci_device_id snd_mychip_ids[] = {
824 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
825 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
829 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
831 /* pci_driver definition */
832 static struct pci_driver driver = {
833 .name = KBUILD_MODNAME,
834 .id_table = snd_mychip_ids,
835 .probe = snd_mychip_probe,
836 .remove = snd_mychip_remove,
839 /* module initialization */
840 static int __init alsa_card_mychip_init(void)
842 return pci_register_driver(&driver);
845 /* module clean up */
846 static void __exit alsa_card_mychip_exit(void)
848 pci_unregister_driver(&driver);
851 module_init(alsa_card_mychip_init)
852 module_exit(alsa_card_mychip_exit)
854 EXPORT_NO_SYMBOLS; /* for old kernels only */
859 The allocation of PCI resources is done in the ``probe`` function, and
860 usually an extra :c:func:`xxx_create()` function is written for this
863 In the case of PCI devices, you first have to call the
864 :c:func:`pci_enable_device()` function before allocating
865 resources. Also, you need to set the proper PCI DMA mask to limit the
866 accessed I/O range. In some cases, you might need to call
867 :c:func:`pci_set_master()` function, too.
869 Suppose the 28bit mask, and the code to be added would be like:
873 err = pci_enable_device(pci);
876 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
877 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
878 printk(KERN_ERR "error to set 28bit mask DMA\n");
879 pci_disable_device(pci);
887 The allocation of I/O ports and irqs is done via standard kernel
888 functions. These resources must be released in the destructor
889 function (see below).
891 Now assume that the PCI device has an I/O port with 8 bytes and an
892 interrupt. Then struct mychip will have the
898 struct snd_card *card;
905 For an I/O port (and also a memory region), you need to have the
906 resource pointer for the standard resource management. For an irq, you
907 have to keep only the irq number (integer). But you need to initialize
908 this number as -1 before actual allocation, since irq 0 is valid. The
909 port address and its resource pointer can be initialized as null by
910 :c:func:`kzalloc()` automatically, so you don't have to take care of
913 The allocation of an I/O port is done like this:
917 err = pci_request_regions(pci, "My Chip");
920 pci_disable_device(pci);
923 chip->port = pci_resource_start(pci, 0);
925 It will reserve the I/O port region of 8 bytes of the given PCI device.
926 The returned value, ``chip->res_port``, is allocated via
927 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
928 must be released via :c:func:`kfree()`, but there is a problem with
929 this. This issue will be explained later.
931 The allocation of an interrupt source is done like this:
935 if (request_irq(pci->irq, snd_mychip_interrupt,
936 IRQF_SHARED, KBUILD_MODNAME, chip)) {
937 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
938 snd_mychip_free(chip);
941 chip->irq = pci->irq;
943 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
944 defined `later <PCM Interrupt Handler_>`__. Note that
945 ``chip->irq`` should be defined only when :c:func:`request_irq()`
948 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
949 as the interrupt flag of :c:func:`request_irq()`.
951 The last argument of :c:func:`request_irq()` is the data pointer
952 passed to the interrupt handler. Usually, the chip-specific record is
953 used for that, but you can use what you like, too.
955 I won't give details about the interrupt handler at this point, but at
956 least its appearance can be explained now. The interrupt handler looks
957 usually like the following:
961 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
963 struct mychip *chip = dev_id;
968 After requesting the IRQ, you can passed it to ``card->sync_irq``
972 card->irq = chip->irq;
974 This allows PCM core automatically performing
975 :c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
976 See the later section `sync_stop callback`_ for details.
978 Now let's write the corresponding destructor for the resources above.
979 The role of destructor is simple: disable the hardware (if already
980 activated) and release the resources. So far, we have no hardware part,
981 so the disabling code is not written here.
983 To release the resources, the “check-and-release” method is a safer way.
984 For the interrupt, do like this:
989 free_irq(chip->irq, chip);
991 Since the irq number can start from 0, you should initialize
992 ``chip->irq`` with a negative value (e.g. -1), so that you can check
993 the validity of the irq number as above.
995 When you requested I/O ports or memory regions via
996 :c:func:`pci_request_region()` or
997 :c:func:`pci_request_regions()` like in this example, release the
998 resource(s) using the corresponding function,
999 :c:func:`pci_release_region()` or
1000 :c:func:`pci_release_regions()`.
1004 pci_release_regions(chip->pci);
1006 When you requested manually via :c:func:`request_region()` or
1007 :c:func:`request_mem_region()`, you can release it via
1008 :c:func:`release_resource()`. Suppose that you keep the resource
1009 pointer returned from :c:func:`request_region()` in
1010 chip->res_port, the release procedure looks like:
1014 release_and_free_resource(chip->res_port);
1016 Don't forget to call :c:func:`pci_disable_device()` before the
1019 And finally, release the chip-specific record.
1025 We didn't implement the hardware disabling part in the above. If you
1026 need to do this, please note that the destructor may be called even
1027 before the initialization of the chip is completed. It would be better
1028 to have a flag to skip hardware disabling if the hardware was not
1031 When the chip-data is assigned to the card using
1032 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1033 destructor is called at the last. That is, it is assured that all other
1034 components like PCMs and controls have already been released. You don't
1035 have to stop PCMs, etc. explicitly, but just call low-level hardware
1038 The management of a memory-mapped region is almost as same as the
1039 management of an I/O port. You'll need three fields like the
1046 unsigned long iobase_phys;
1047 void __iomem *iobase_virt;
1050 and the allocation would be like below:
1054 err = pci_request_regions(pci, "My Chip");
1059 chip->iobase_phys = pci_resource_start(pci, 0);
1060 chip->iobase_virt = ioremap(chip->iobase_phys,
1061 pci_resource_len(pci, 0));
1063 and the corresponding destructor would be:
1067 static int snd_mychip_free(struct mychip *chip)
1070 if (chip->iobase_virt)
1071 iounmap(chip->iobase_virt);
1073 pci_release_regions(chip->pci);
1077 Of course, a modern way with :c:func:`pci_iomap()` will make things a
1082 err = pci_request_regions(pci, "My Chip");
1087 chip->iobase_virt = pci_iomap(pci, 0, 0);
1089 which is paired with :c:func:`pci_iounmap()` at destructor.
1095 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1096 struct pci_device_id table for
1097 this chipset. It's a table of PCI vendor/device ID number, and some
1104 static struct pci_device_id snd_mychip_ids[] = {
1105 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1106 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1110 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1112 The first and second fields of the struct pci_device_id are the vendor
1113 and device IDs. If you have no reason to filter the matching devices, you can
1114 leave the remaining fields as above. The last field of the
1115 struct pci_device_id contains private data for this entry. You can specify
1116 any value here, for example, to define specific operations for supported
1117 device IDs. Such an example is found in the intel8x0 driver.
1119 The last entry of this list is the terminator. You must specify this
1122 Then, prepare the struct pci_driver
1127 static struct pci_driver driver = {
1128 .name = KBUILD_MODNAME,
1129 .id_table = snd_mychip_ids,
1130 .probe = snd_mychip_probe,
1131 .remove = snd_mychip_remove,
1134 The ``probe`` and ``remove`` functions have already been defined in
1135 the previous sections. The ``name`` field is the name string of this
1136 device. Note that you must not use a slash “/” in this string.
1138 And at last, the module entries:
1142 static int __init alsa_card_mychip_init(void)
1144 return pci_register_driver(&driver);
1147 static void __exit alsa_card_mychip_exit(void)
1149 pci_unregister_driver(&driver);
1152 module_init(alsa_card_mychip_init)
1153 module_exit(alsa_card_mychip_exit)
1155 Note that these module entries are tagged with ``__init`` and ``__exit``
1166 The PCM middle layer of ALSA is quite powerful and it is only necessary
1167 for each driver to implement the low-level functions to access its
1170 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1171 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1172 access to some functions related with hw_param.
1174 Each card device can have up to four pcm instances. A pcm instance
1175 corresponds to a pcm device file. The limitation of number of instances
1176 comes only from the available bit size of the Linux's device numbers.
1177 Once when 64bit device number is used, we'll have more pcm instances
1180 A pcm instance consists of pcm playback and capture streams, and each
1181 pcm stream consists of one or more pcm substreams. Some soundcards
1182 support multiple playback functions. For example, emu10k1 has a PCM
1183 playback of 32 stereo substreams. In this case, at each open, a free
1184 substream is (usually) automatically chosen and opened. Meanwhile, when
1185 only one substream exists and it was already opened, the successful open
1186 will either block or error with ``EAGAIN`` according to the file open
1187 mode. But you don't have to care about such details in your driver. The
1188 PCM middle layer will take care of such work.
1193 The example code below does not include any hardware access routines but
1194 shows only the skeleton, how to build up the PCM interfaces.
1198 #include <sound/pcm.h>
1201 /* hardware definition */
1202 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1203 .info = (SNDRV_PCM_INFO_MMAP |
1204 SNDRV_PCM_INFO_INTERLEAVED |
1205 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1206 SNDRV_PCM_INFO_MMAP_VALID),
1207 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1208 .rates = SNDRV_PCM_RATE_8000_48000,
1213 .buffer_bytes_max = 32768,
1214 .period_bytes_min = 4096,
1215 .period_bytes_max = 32768,
1217 .periods_max = 1024,
1220 /* hardware definition */
1221 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1222 .info = (SNDRV_PCM_INFO_MMAP |
1223 SNDRV_PCM_INFO_INTERLEAVED |
1224 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1225 SNDRV_PCM_INFO_MMAP_VALID),
1226 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1227 .rates = SNDRV_PCM_RATE_8000_48000,
1232 .buffer_bytes_max = 32768,
1233 .period_bytes_min = 4096,
1234 .period_bytes_max = 32768,
1236 .periods_max = 1024,
1240 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1242 struct mychip *chip = snd_pcm_substream_chip(substream);
1243 struct snd_pcm_runtime *runtime = substream->runtime;
1245 runtime->hw = snd_mychip_playback_hw;
1246 /* more hardware-initialization will be done here */
1251 /* close callback */
1252 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1254 struct mychip *chip = snd_pcm_substream_chip(substream);
1255 /* the hardware-specific codes will be here */
1262 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1264 struct mychip *chip = snd_pcm_substream_chip(substream);
1265 struct snd_pcm_runtime *runtime = substream->runtime;
1267 runtime->hw = snd_mychip_capture_hw;
1268 /* more hardware-initialization will be done here */
1273 /* close callback */
1274 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1276 struct mychip *chip = snd_pcm_substream_chip(substream);
1277 /* the hardware-specific codes will be here */
1282 /* hw_params callback */
1283 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1284 struct snd_pcm_hw_params *hw_params)
1286 /* the hardware-specific codes will be here */
1291 /* hw_free callback */
1292 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1294 /* the hardware-specific codes will be here */
1299 /* prepare callback */
1300 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1302 struct mychip *chip = snd_pcm_substream_chip(substream);
1303 struct snd_pcm_runtime *runtime = substream->runtime;
1305 /* set up the hardware with the current configuration
1308 mychip_set_sample_format(chip, runtime->format);
1309 mychip_set_sample_rate(chip, runtime->rate);
1310 mychip_set_channels(chip, runtime->channels);
1311 mychip_set_dma_setup(chip, runtime->dma_addr,
1317 /* trigger callback */
1318 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1322 case SNDRV_PCM_TRIGGER_START:
1323 /* do something to start the PCM engine */
1326 case SNDRV_PCM_TRIGGER_STOP:
1327 /* do something to stop the PCM engine */
1335 /* pointer callback */
1336 static snd_pcm_uframes_t
1337 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1339 struct mychip *chip = snd_pcm_substream_chip(substream);
1340 unsigned int current_ptr;
1342 /* get the current hardware pointer */
1343 current_ptr = mychip_get_hw_pointer(chip);
1348 static struct snd_pcm_ops snd_mychip_playback_ops = {
1349 .open = snd_mychip_playback_open,
1350 .close = snd_mychip_playback_close,
1351 .hw_params = snd_mychip_pcm_hw_params,
1352 .hw_free = snd_mychip_pcm_hw_free,
1353 .prepare = snd_mychip_pcm_prepare,
1354 .trigger = snd_mychip_pcm_trigger,
1355 .pointer = snd_mychip_pcm_pointer,
1359 static struct snd_pcm_ops snd_mychip_capture_ops = {
1360 .open = snd_mychip_capture_open,
1361 .close = snd_mychip_capture_close,
1362 .hw_params = snd_mychip_pcm_hw_params,
1363 .hw_free = snd_mychip_pcm_hw_free,
1364 .prepare = snd_mychip_pcm_prepare,
1365 .trigger = snd_mychip_pcm_trigger,
1366 .pointer = snd_mychip_pcm_pointer,
1370 * definitions of capture are omitted here...
1373 /* create a pcm device */
1374 static int snd_mychip_new_pcm(struct mychip *chip)
1376 struct snd_pcm *pcm;
1379 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1382 pcm->private_data = chip;
1383 strcpy(pcm->name, "My Chip");
1386 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1387 &snd_mychip_playback_ops);
1388 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1389 &snd_mychip_capture_ops);
1390 /* pre-allocation of buffers */
1391 /* NOTE: this may fail */
1392 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1402 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1403 function. It would be better to create a constructor for pcm, namely,
1407 static int snd_mychip_new_pcm(struct mychip *chip)
1409 struct snd_pcm *pcm;
1412 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1415 pcm->private_data = chip;
1416 strcpy(pcm->name, "My Chip");
1422 The :c:func:`snd_pcm_new()` function takes four arguments. The
1423 first argument is the card pointer to which this pcm is assigned, and
1424 the second is the ID string.
1426 The third argument (``index``, 0 in the above) is the index of this new
1427 pcm. It begins from zero. If you create more than one pcm instances,
1428 specify the different numbers in this argument. For example, ``index =
1429 1`` for the second PCM device.
1431 The fourth and fifth arguments are the number of substreams for playback
1432 and capture, respectively. Here 1 is used for both arguments. When no
1433 playback or capture substreams are available, pass 0 to the
1434 corresponding argument.
1436 If a chip supports multiple playbacks or captures, you can specify more
1437 numbers, but they must be handled properly in open/close, etc.
1438 callbacks. When you need to know which substream you are referring to,
1439 then it can be obtained from struct snd_pcm_substream data passed to each
1440 callback as follows:
1444 struct snd_pcm_substream *substream;
1445 int index = substream->number;
1448 After the pcm is created, you need to set operators for each pcm stream.
1452 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1453 &snd_mychip_playback_ops);
1454 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1455 &snd_mychip_capture_ops);
1457 The operators are defined typically like this:
1461 static struct snd_pcm_ops snd_mychip_playback_ops = {
1462 .open = snd_mychip_pcm_open,
1463 .close = snd_mychip_pcm_close,
1464 .hw_params = snd_mychip_pcm_hw_params,
1465 .hw_free = snd_mychip_pcm_hw_free,
1466 .prepare = snd_mychip_pcm_prepare,
1467 .trigger = snd_mychip_pcm_trigger,
1468 .pointer = snd_mychip_pcm_pointer,
1471 All the callbacks are described in the Operators_ subsection.
1473 After setting the operators, you probably will want to pre-allocate the
1474 buffer and set up the managed allocation mode.
1475 For that, simply call the following:
1479 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1483 It will allocate a buffer up to 64kB as default. Buffer management
1484 details will be described in the later section `Buffer and Memory
1487 Additionally, you can set some extra information for this pcm in
1488 ``pcm->info_flags``. The available values are defined as
1489 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1490 hardware definition (described later). When your soundchip supports only
1491 half-duplex, specify like this:
1495 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1498 ... And the Destructor?
1499 -----------------------
1501 The destructor for a pcm instance is not always necessary. Since the pcm
1502 device will be released by the middle layer code automatically, you
1503 don't have to call the destructor explicitly.
1505 The destructor would be necessary if you created special records
1506 internally and needed to release them. In such a case, set the
1507 destructor function to ``pcm->private_free``:
1511 static void mychip_pcm_free(struct snd_pcm *pcm)
1513 struct mychip *chip = snd_pcm_chip(pcm);
1514 /* free your own data */
1515 kfree(chip->my_private_pcm_data);
1516 /* do what you like else */
1520 static int snd_mychip_new_pcm(struct mychip *chip)
1522 struct snd_pcm *pcm;
1524 /* allocate your own data */
1525 chip->my_private_pcm_data = kmalloc(...);
1526 /* set the destructor */
1527 pcm->private_data = chip;
1528 pcm->private_free = mychip_pcm_free;
1534 Runtime Pointer - The Chest of PCM Information
1535 ----------------------------------------------
1537 When the PCM substream is opened, a PCM runtime instance is allocated
1538 and assigned to the substream. This pointer is accessible via
1539 ``substream->runtime``. This runtime pointer holds most information you
1540 need to control the PCM: the copy of hw_params and sw_params
1541 configurations, the buffer pointers, mmap records, spinlocks, etc.
1543 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1544 are the contents of this file:
1548 struct _snd_pcm_runtime {
1550 struct snd_pcm_substream *trigger_master;
1551 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
1553 snd_pcm_uframes_t avail_max;
1554 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
1555 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1557 /* -- HW params -- */
1558 snd_pcm_access_t access; /* access mode */
1559 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
1560 snd_pcm_subformat_t subformat; /* subformat */
1561 unsigned int rate; /* rate in Hz */
1562 unsigned int channels; /* channels */
1563 snd_pcm_uframes_t period_size; /* period size */
1564 unsigned int periods; /* periods */
1565 snd_pcm_uframes_t buffer_size; /* buffer size */
1566 unsigned int tick_time; /* tick time */
1567 snd_pcm_uframes_t min_align; /* Min alignment for the format */
1569 unsigned int frame_bits;
1570 unsigned int sample_bits;
1572 unsigned int rate_num;
1573 unsigned int rate_den;
1575 /* -- SW params -- */
1576 struct timespec tstamp_mode; /* mmap timestamp is updated */
1577 unsigned int period_step;
1578 unsigned int sleep_min; /* min ticks to sleep */
1579 snd_pcm_uframes_t start_threshold;
1580 snd_pcm_uframes_t stop_threshold;
1581 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1582 noise is nearest than this */
1583 snd_pcm_uframes_t silence_size; /* Silence filling size */
1584 snd_pcm_uframes_t boundary; /* pointers wrap point */
1586 snd_pcm_uframes_t silenced_start;
1587 snd_pcm_uframes_t silenced_size;
1589 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
1592 volatile struct snd_pcm_mmap_status *status;
1593 volatile struct snd_pcm_mmap_control *control;
1594 atomic_t mmap_count;
1596 /* -- locking / scheduling -- */
1598 wait_queue_head_t sleep;
1599 struct timer_list tick_timer;
1600 struct fasync_struct *fasync;
1602 /* -- private section -- */
1604 void (*private_free)(struct snd_pcm_runtime *runtime);
1606 /* -- hardware description -- */
1607 struct snd_pcm_hardware hw;
1608 struct snd_pcm_hw_constraints hw_constraints;
1611 unsigned int timer_resolution; /* timer resolution */
1614 unsigned char *dma_area; /* DMA area */
1615 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
1616 size_t dma_bytes; /* size of DMA area */
1618 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
1620 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1621 /* -- OSS things -- */
1622 struct snd_pcm_oss_runtime oss;
1627 For the operators (callbacks) of each sound driver, most of these
1628 records are supposed to be read-only. Only the PCM middle-layer changes
1629 / updates them. The exceptions are the hardware description (hw) DMA
1630 buffer information and the private data. Besides, if you use the
1631 standard managed buffer allocation mode, you don't need to set the
1632 DMA buffer information by yourself.
1634 In the sections below, important records are explained.
1636 Hardware Description
1637 ~~~~~~~~~~~~~~~~~~~~
1639 The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
1640 the fundamental hardware configuration. Above all, you'll need to define this
1641 in the `PCM open callback`_. Note that the runtime instance holds the copy of
1642 the descriptor, not the pointer to the existing descriptor. That is,
1643 in the open callback, you can modify the copied descriptor
1644 (``runtime->hw``) as you need. For example, if the maximum number of
1645 channels is 1 only on some chip models, you can still use the same
1646 hardware descriptor and change the channels_max later:
1650 struct snd_pcm_runtime *runtime = substream->runtime;
1652 runtime->hw = snd_mychip_playback_hw; /* common definition */
1653 if (chip->model == VERY_OLD_ONE)
1654 runtime->hw.channels_max = 1;
1656 Typically, you'll have a hardware descriptor as below:
1660 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1661 .info = (SNDRV_PCM_INFO_MMAP |
1662 SNDRV_PCM_INFO_INTERLEAVED |
1663 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1664 SNDRV_PCM_INFO_MMAP_VALID),
1665 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1666 .rates = SNDRV_PCM_RATE_8000_48000,
1671 .buffer_bytes_max = 32768,
1672 .period_bytes_min = 4096,
1673 .period_bytes_max = 32768,
1675 .periods_max = 1024,
1678 - The ``info`` field contains the type and capabilities of this
1679 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1680 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1681 the mmap is supported and which interleaved format is
1682 supported. When the hardware supports mmap, add the
1683 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1684 interleaved or the non-interleaved formats,
1685 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1686 flag must be set, respectively. If both are supported, you can set
1689 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1690 specified for the OSS mmap mode. Usually both are set. Of course,
1691 ``MMAP_VALID`` is set only if the mmap is really supported.
1693 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1694 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1695 supports the “pause” operation, while the ``RESUME`` bit means that
1696 the pcm supports the full “suspend/resume” operation. If the
1697 ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1698 the corresponding (pause push/release) commands. The suspend/resume
1699 trigger commands can be defined even without the ``RESUME``
1700 flag. See `Power Management`_ section for details.
1702 When the PCM substreams can be synchronized (typically,
1703 synchronized start/stop of a playback and a capture streams), you
1704 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1705 need to check the linked-list of PCM substreams in the trigger
1706 callback. This will be described in the later section.
1708 - ``formats`` field contains the bit-flags of supported formats
1709 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1710 format, give all or'ed bits. In the example above, the signed 16bit
1711 little-endian format is specified.
1713 - ``rates`` field contains the bit-flags of supported rates
1714 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1715 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1716 provided only for typical rates. If your chip supports
1717 unconventional rates, you need to add the ``KNOT`` bit and set up
1718 the hardware constraint manually (explained later).
1720 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1721 rate. This should correspond somehow to ``rates`` bits.
1723 - ``channel_min`` and ``channel_max`` define, as you might already
1724 expected, the minimum and maximum number of channels.
1726 - ``buffer_bytes_max`` defines the maximum buffer size in
1727 bytes. There is no ``buffer_bytes_min`` field, since it can be
1728 calculated from the minimum period size and the minimum number of
1729 periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1730 maximum size of the period in bytes. ``periods_max`` and
1731 ``periods_min`` define the maximum and minimum number of periods in
1734 The “period” is a term that corresponds to a fragment in the OSS
1735 world. The period defines the size at which a PCM interrupt is
1736 generated. This size strongly depends on the hardware. Generally,
1737 the smaller period size will give you more interrupts, that is,
1738 more controls. In the case of capture, this size defines the input
1739 latency. On the other hand, the whole buffer size defines the
1740 output latency for the playback direction.
1742 - There is also a field ``fifo_size``. This specifies the size of the
1743 hardware FIFO, but currently it is neither used in the driver nor
1744 in the alsa-lib. So, you can ignore this field.
1749 Ok, let's go back again to the PCM runtime records. The most
1750 frequently referred records in the runtime instance are the PCM
1751 configurations. The PCM configurations are stored in the runtime
1752 instance after the application sends ``hw_params`` data via
1753 alsa-lib. There are many fields copied from hw_params and sw_params
1754 structs. For example, ``format`` holds the format type chosen by the
1755 application. This field contains the enum value
1756 ``SNDRV_PCM_FORMAT_XXX``.
1758 One thing to be noted is that the configured buffer and period sizes
1759 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1760 channels \* samples-size``. For conversion between frames and bytes,
1761 you can use the :c:func:`frames_to_bytes()` and
1762 :c:func:`bytes_to_frames()` helper functions.
1766 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1768 Also, many software parameters (sw_params) are stored in frames, too.
1769 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1770 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1771 frames as signed integer.
1773 DMA Buffer Information
1774 ~~~~~~~~~~~~~~~~~~~~~~
1776 The DMA buffer is defined by the following four fields, ``dma_area``,
1777 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1778 holds the buffer pointer (the logical address). You can call
1779 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1780 the physical address of the buffer. This field is specified only when
1781 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1782 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1784 If you use either the managed buffer allocation mode or the standard
1785 API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1786 these fields are set by the ALSA middle layer, and you should *not*
1787 change them by yourself. You can read them but not write them. On the
1788 other hand, if you want to allocate the buffer by yourself, you'll
1789 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1790 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1791 your driver doesn't support mmap, this field is not
1792 necessary. ``dma_addr`` is also optional. You can use dma_private as
1798 The running status can be referred via ``runtime->status``. This is
1799 the pointer to the struct snd_pcm_mmap_status record.
1800 For example, you can get the current
1801 DMA hardware pointer via ``runtime->status->hw_ptr``.
1803 The DMA application pointer can be referred via ``runtime->control``,
1804 which points to the struct snd_pcm_mmap_control record.
1805 However, accessing directly to this value is not recommended.
1810 You can allocate a record for the substream and store it in
1811 ``runtime->private_data``. Usually, this is done in the `PCM open
1812 callback`_. Don't mix this with ``pcm->private_data``. The
1813 ``pcm->private_data`` usually points to the chip instance assigned
1814 statically at the creation of PCM, while the ``runtime->private_data``
1815 points to a dynamic data structure created at the PCM open
1820 static int snd_xxx_open(struct snd_pcm_substream *substream)
1822 struct my_pcm_data *data;
1824 data = kmalloc(sizeof(*data), GFP_KERNEL);
1825 substream->runtime->private_data = data;
1830 The allocated object must be released in the `close callback`_.
1835 OK, now let me give details about each pcm callback (``ops``). In
1836 general, every callback must return 0 if successful, or a negative
1837 error number such as ``-EINVAL``. To choose an appropriate error
1838 number, it is advised to check what value other parts of the kernel
1839 return when the same kind of request fails.
1841 The callback function takes at least the argument with
1842 struct snd_pcm_substream pointer. To retrieve the chip
1843 record from the given substream instance, you can use the following
1849 struct mychip *chip = snd_pcm_substream_chip(substream);
1853 The macro reads ``substream->private_data``, which is a copy of
1854 ``pcm->private_data``. You can override the former if you need to
1855 assign different data records per PCM substream. For example, the
1856 cmi8330 driver assigns different ``private_data`` for playback and
1857 capture directions, because it uses two different codecs (SB- and
1858 AD-compatible) for different directions.
1865 static int snd_xxx_open(struct snd_pcm_substream *substream);
1867 This is called when a pcm substream is opened.
1869 At least, here you have to initialize the ``runtime->hw``
1870 record. Typically, this is done by like this:
1874 static int snd_xxx_open(struct snd_pcm_substream *substream)
1876 struct mychip *chip = snd_pcm_substream_chip(substream);
1877 struct snd_pcm_runtime *runtime = substream->runtime;
1879 runtime->hw = snd_mychip_playback_hw;
1883 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1886 You can allocate a private data in this callback, as described in
1887 `Private Data`_ section.
1889 If the hardware configuration needs more constraints, set the hardware
1890 constraints here, too. See Constraints_ for more details.
1897 static int snd_xxx_close(struct snd_pcm_substream *substream);
1900 Obviously, this is called when a pcm substream is closed.
1902 Any private instance for a pcm substream allocated in the ``open``
1903 callback will be released here.
1907 static int snd_xxx_close(struct snd_pcm_substream *substream)
1910 kfree(substream->runtime->private_data);
1917 This is used for any special call to pcm ioctls. But usually you can
1918 leave it as NULL, then PCM core calls the generic ioctl callback
1919 function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the
1920 unique setup of channel info or reset procedure, you can pass your own
1921 callback function here.
1928 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1929 struct snd_pcm_hw_params *hw_params);
1931 This is called when the hardware parameter (``hw_params``) is set up
1932 by the application, that is, once when the buffer size, the period
1933 size, the format, etc. are defined for the pcm substream.
1935 Many hardware setups should be done in this callback, including the
1936 allocation of buffers.
1938 Parameters to be initialized are retrieved by
1939 :c:func:`params_xxx()` macros.
1941 When you set up the managed buffer allocation mode for the substream,
1942 a buffer is already allocated before this callback gets
1943 called. Alternatively, you can call a helper function below for
1944 allocating the buffer, too.
1948 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1950 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1951 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1954 Note that this and ``prepare`` callbacks may be called multiple times
1955 per initialization. For example, the OSS emulation may call these
1956 callbacks at each change via its ioctl.
1958 Thus, you need to be careful not to allocate the same buffers many
1959 times, which will lead to memory leaks! Calling the helper function
1960 above many times is OK. It will release the previous buffer
1961 automatically when it was already allocated.
1963 Another note is that this callback is non-atomic (schedulable) as
1964 default, i.e. when no ``nonatomic`` flag set. This is important,
1965 because the ``trigger`` callback is atomic (non-schedulable). That is,
1966 mutexes or any schedule-related functions are not available in
1967 ``trigger`` callback. Please see the subsection Atomicity_ for
1975 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1977 This is called to release the resources allocated via
1980 This function is always called before the close callback is called.
1981 Also, the callback may be called multiple times, too. Keep track
1982 whether the resource was already released.
1984 When you have set up the managed buffer allocation mode for the PCM
1985 substream, the allocated PCM buffer will be automatically released
1986 after this callback gets called. Otherwise you'll have to release the
1987 buffer manually. Typically, when the buffer was allocated from the
1988 pre-allocated pool, you can use the standard API function
1989 :c:func:`snd_pcm_lib_malloc_pages()` like:
1993 snd_pcm_lib_free_pages(substream);
2000 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2002 This callback is called when the pcm is “prepared”. You can set the
2003 format type, sample rate, etc. here. The difference from ``hw_params``
2004 is that the ``prepare`` callback will be called each time
2005 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2008 Note that this callback is now non-atomic. You can use
2009 schedule-related functions safely in this callback.
2011 In this and the following callbacks, you can refer to the values via
2012 the runtime record, ``substream->runtime``. For example, to get the
2013 current rate, format or channels, access to ``runtime->rate``,
2014 ``runtime->format`` or ``runtime->channels``, respectively. The
2015 physical address of the allocated buffer is set to
2016 ``runtime->dma_area``. The buffer and period sizes are in
2017 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2019 Be careful that this callback will be called many times at each setup,
2027 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2029 This is called when the pcm is started, stopped or paused.
2031 Which action is specified in the second argument,
2032 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2033 and ``STOP`` commands must be defined in this callback.
2038 case SNDRV_PCM_TRIGGER_START:
2039 /* do something to start the PCM engine */
2041 case SNDRV_PCM_TRIGGER_STOP:
2042 /* do something to stop the PCM engine */
2048 When the pcm supports the pause operation (given in the info field of
2049 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2050 must be handled here, too. The former is the command to pause the pcm,
2051 and the latter to restart the pcm again.
2053 When the pcm supports the suspend/resume operation, regardless of full
2054 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2055 commands must be handled, too. These commands are issued when the
2056 power-management status is changed. Obviously, the ``SUSPEND`` and
2057 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2058 they are identical to the ``STOP`` and ``START`` commands, respectively.
2059 See the `Power Management`_ section for details.
2061 As mentioned, this callback is atomic as default unless ``nonatomic``
2062 flag set, and you cannot call functions which may sleep. The
2063 ``trigger`` callback should be as minimal as possible, just really
2064 triggering the DMA. The other stuff should be initialized
2065 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2072 static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
2074 This callback is optional, and NULL can be passed. It's called after
2075 the PCM core stops the stream and changes the stream state
2076 ``prepare``, ``hw_params`` or ``hw_free``.
2077 Since the IRQ handler might be still pending, we need to wait until
2078 the pending task finishes before moving to the next step; otherwise it
2079 might lead to a crash due to resource conflicts or access to the freed
2080 resources. A typical behavior is to call a synchronization function
2081 like :c:func:`synchronize_irq()` here.
2083 For majority of drivers that need only a call of
2084 :c:func:`synchronize_irq()`, there is a simpler setup, too.
2085 While keeping NULL to ``sync_stop`` PCM callback, the driver can set
2086 ``card->sync_irq`` field to store the valid interrupt number after
2087 requesting an IRQ, instead. Then PCM core will look call
2088 :c:func:`synchronize_irq()` with the given IRQ appropriately.
2090 If the IRQ handler is released at the card destructor, you don't need
2091 to clear ``card->sync_irq``, as the card itself is being released.
2092 So, usually you'll need to add just a single line for assigning
2093 ``card->sync_irq`` in the driver code unless the driver re-acquires
2094 the IRQ. When the driver frees and re-acquires the IRQ dynamically
2095 (e.g. for suspend/resume), it needs to clear and re-set
2096 ``card->sync_irq`` again appropriately.
2103 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2105 This callback is called when the PCM middle layer inquires the current
2106 hardware position on the buffer. The position must be returned in
2107 frames, ranging from 0 to ``buffer_size - 1``.
2109 This is called usually from the buffer-update routine in the pcm
2110 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2111 is called in the interrupt routine. Then the pcm middle layer updates
2112 the position and calculates the available space, and wakes up the
2113 sleeping poll threads, etc.
2115 This callback is also atomic as default.
2117 copy_user, copy_kernel and fill_silence ops
2118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2120 These callbacks are not mandatory, and can be omitted in most cases.
2121 These callbacks are used when the hardware buffer cannot be in the
2122 normal memory space. Some chips have their own buffer on the hardware
2123 which is not mappable. In such a case, you have to transfer the data
2124 manually from the memory buffer to the hardware buffer. Or, if the
2125 buffer is non-contiguous on both physical and virtual memory spaces,
2126 these callbacks must be defined, too.
2128 If these two callbacks are defined, copy and set-silence operations
2129 are done by them. The detailed will be described in the later section
2130 `Buffer and Memory Management`_.
2135 This callback is also not mandatory. This callback is called when the
2136 ``appl_ptr`` is updated in read or write operations. Some drivers like
2137 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2138 internal buffer, and this callback is useful only for such a purpose.
2140 This callback is atomic as default.
2145 This callback is optional too. The mmap calls this callback to get the
2148 Since the recent changes, you need no special callback any longer for
2149 the standard SG-buffer or vmalloc-buffer. Hence this callback should
2155 This is another optional callback for controlling mmap behavior.
2156 Once when defined, PCM core calls this callback when a page is
2157 memory-mapped instead of dealing via the standard helper.
2158 If you need special handling (due to some architecture or
2159 device-specific issues), implement everything here as you like.
2162 PCM Interrupt Handler
2163 ---------------------
2165 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2166 interrupt handler in the sound driver is to update the buffer position
2167 and to tell the PCM middle layer when the buffer position goes across
2168 the prescribed period size. To inform this, call the
2169 :c:func:`snd_pcm_period_elapsed()` function.
2171 There are several types of sound chips to generate the interrupts.
2173 Interrupts at the period (fragment) boundary
2174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2176 This is the most frequently found type: the hardware generates an
2177 interrupt at each period boundary. In this case, you can call
2178 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2180 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2181 its argument. Thus, you need to keep the substream pointer accessible
2182 from the chip instance. For example, define ``substream`` field in the
2183 chip record to hold the current running substream pointer, and set the
2184 pointer value at ``open`` callback (and reset at ``close`` callback).
2186 If you acquire a spinlock in the interrupt handler, and the lock is used
2187 in other pcm callbacks, too, then you have to release the lock before
2188 calling :c:func:`snd_pcm_period_elapsed()`, because
2189 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2192 Typical code would be like:
2197 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2199 struct mychip *chip = dev_id;
2200 spin_lock(&chip->lock);
2202 if (pcm_irq_invoked(chip)) {
2203 /* call updater, unlock before it */
2204 spin_unlock(&chip->lock);
2205 snd_pcm_period_elapsed(chip->substream);
2206 spin_lock(&chip->lock);
2207 /* acknowledge the interrupt if necessary */
2210 spin_unlock(&chip->lock);
2216 High frequency timer interrupts
2217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2219 This happens when the hardware doesn't generate interrupts at the period
2220 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2221 or ymfpci drivers). In this case, you need to check the current hardware
2222 position and accumulate the processed sample length at each interrupt.
2223 When the accumulated size exceeds the period size, call
2224 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2226 Typical code would be like the following.
2231 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2233 struct mychip *chip = dev_id;
2234 spin_lock(&chip->lock);
2236 if (pcm_irq_invoked(chip)) {
2237 unsigned int last_ptr, size;
2238 /* get the current hardware pointer (in frames) */
2239 last_ptr = get_hw_ptr(chip);
2240 /* calculate the processed frames since the
2243 if (last_ptr < chip->last_ptr)
2244 size = runtime->buffer_size + last_ptr
2247 size = last_ptr - chip->last_ptr;
2248 /* remember the last updated point */
2249 chip->last_ptr = last_ptr;
2250 /* accumulate the size */
2252 /* over the period boundary? */
2253 if (chip->size >= runtime->period_size) {
2254 /* reset the accumulator */
2255 chip->size %= runtime->period_size;
2257 spin_unlock(&chip->lock);
2258 snd_pcm_period_elapsed(substream);
2259 spin_lock(&chip->lock);
2261 /* acknowledge the interrupt if necessary */
2264 spin_unlock(&chip->lock);
2270 On calling :c:func:`snd_pcm_period_elapsed()`
2271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2273 In both cases, even if more than one period are elapsed, you don't have
2274 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2275 once. And the pcm layer will check the current hardware pointer and
2276 update to the latest status.
2281 One of the most important (and thus difficult to debug) problems in
2282 kernel programming are race conditions. In the Linux kernel, they are
2283 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2284 race condition can happen in an interrupt handler, it has to be managed
2285 atomically, and you have to use a spinlock to protect the critical
2286 session. If the critical section is not in interrupt handler code and if
2287 taking a relatively long time to execute is acceptable, you should use
2288 mutexes or semaphores instead.
2290 As already seen, some pcm callbacks are atomic and some are not. For
2291 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2292 callback is atomic. This means, the latter is called already in a
2293 spinlock held by the PCM middle layer. Please take this atomicity into
2294 account when you choose a locking scheme in the callbacks.
2296 In the atomic callbacks, you cannot use functions which may call
2297 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2298 mutexes can sleep, and hence they cannot be used inside the atomic
2299 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2300 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2302 All three atomic callbacks (trigger, pointer, and ack) are called with
2303 local interrupts disabled.
2305 The recent changes in PCM core code, however, allow all PCM operations
2306 to be non-atomic. This assumes that the all caller sides are in
2307 non-atomic contexts. For example, the function
2308 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2309 interrupt handler. But, if you set up the driver to use a threaded
2310 interrupt handler, this call can be in non-atomic context, too. In such
2311 a case, you can set ``nonatomic`` filed of struct snd_pcm object
2312 after creating it. When this flag is set, mutex and rwsem are used internally
2313 in the PCM core instead of spin and rwlocks, so that you can call all PCM
2314 functions safely in a non-atomic
2320 If your chip supports unconventional sample rates, or only the limited
2321 samples, you need to set a constraint for the condition.
2323 For example, in order to restrict the sample rates in the some supported
2324 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2325 call this function in the open callback.
2329 static unsigned int rates[] =
2330 {4000, 10000, 22050, 44100};
2331 static struct snd_pcm_hw_constraint_list constraints_rates = {
2332 .count = ARRAY_SIZE(rates),
2337 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2341 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2342 SNDRV_PCM_HW_PARAM_RATE,
2343 &constraints_rates);
2351 There are many different constraints. Look at ``sound/pcm.h`` for a
2352 complete list. You can even define your own constraint rules. For
2353 example, let's suppose my_chip can manage a substream of 1 channel if
2354 and only if the format is ``S16_LE``, otherwise it supports any format
2355 specified in struct snd_pcm_hardware> (or in any other
2356 constraint_list). You can build a rule like this:
2360 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2361 struct snd_pcm_hw_rule *rule)
2363 struct snd_interval *c = hw_param_interval(params,
2364 SNDRV_PCM_HW_PARAM_CHANNELS);
2365 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2366 struct snd_interval ch;
2368 snd_interval_any(&ch);
2369 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2370 ch.min = ch.max = 1;
2372 return snd_interval_refine(c, &ch);
2378 Then you need to call this function to add your rule:
2382 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2383 hw_rule_channels_by_format, NULL,
2384 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2386 The rule function is called when an application sets the PCM format, and
2387 it refines the number of channels accordingly. But an application may
2388 set the number of channels before setting the format. Thus you also need
2389 to define the inverse rule:
2393 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2394 struct snd_pcm_hw_rule *rule)
2396 struct snd_interval *c = hw_param_interval(params,
2397 SNDRV_PCM_HW_PARAM_CHANNELS);
2398 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2399 struct snd_mask fmt;
2401 snd_mask_any(&fmt); /* Init the struct */
2403 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2404 return snd_mask_refine(f, &fmt);
2410 ... and in the open callback:
2414 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2415 hw_rule_format_by_channels, NULL,
2416 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2418 One typical usage of the hw constraints is to align the buffer size
2419 with the period size. As default, ALSA PCM core doesn't enforce the
2420 buffer size to be aligned with the period size. For example, it'd be
2421 possible to have a combination like 256 period bytes with 999 buffer
2424 Many device chips, however, require the buffer to be a multiple of
2425 periods. In such a case, call
2426 :c:func:`snd_pcm_hw_constraint_integer()` for
2427 ``SNDRV_PCM_HW_PARAM_PERIODS``.
2431 snd_pcm_hw_constraint_integer(substream->runtime,
2432 SNDRV_PCM_HW_PARAM_PERIODS);
2434 This assures that the number of periods is integer, hence the buffer
2435 size is aligned with the period size.
2437 The hw constraint is a very much powerful mechanism to define the
2438 preferred PCM configuration, and there are relevant helpers.
2439 I won't give more details here, rather I would like to say, “Luke, use
2448 The control interface is used widely for many switches, sliders, etc.
2449 which are accessed from user-space. Its most important use is the mixer
2450 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2451 implemented on the control kernel API.
2453 ALSA has a well-defined AC97 control module. If your chip supports only
2454 the AC97 and nothing else, you can skip this section.
2456 The control API is defined in ``<sound/control.h>``. Include this file
2457 if you want to add your own controls.
2459 Definition of Controls
2460 ----------------------
2462 To create a new control, you need to define the following three
2463 callbacks: ``info``, ``get`` and ``put``. Then, define a
2464 struct snd_kcontrol_new record, such as:
2469 static struct snd_kcontrol_new my_control = {
2470 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2471 .name = "PCM Playback Switch",
2473 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2474 .private_value = 0xffff,
2475 .info = my_control_info,
2476 .get = my_control_get,
2477 .put = my_control_put
2481 The ``iface`` field specifies the control type,
2482 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2483 for global controls that are not logically part of the mixer. If the
2484 control is closely associated with some specific device on the sound
2485 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2486 and specify the device number with the ``device`` and ``subdevice``
2489 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2490 control name is very important, because its role is classified from
2491 its name. There are pre-defined standard control names. The details
2492 are described in the `Control Names`_ subsection.
2494 The ``index`` field holds the index number of this control. If there
2495 are several different controls with the same name, they can be
2496 distinguished by the index number. This is the case when several
2497 codecs exist on the card. If the index is zero, you can omit the
2500 The ``access`` field contains the access type of this control. Give
2501 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2502 there. The details will be explained in the `Access Flags`_
2505 The ``private_value`` field contains an arbitrary long integer value
2506 for this record. When using the generic ``info``, ``get`` and ``put``
2507 callbacks, you can pass a value through this field. If several small
2508 numbers are necessary, you can combine them in bitwise. Or, it's
2509 possible to give a pointer (casted to unsigned long) of some record to
2512 The ``tlv`` field can be used to provide metadata about the control;
2513 see the `Metadata`_ subsection.
2515 The other three are `Control Callbacks`_.
2520 There are some standards to define the control names. A control is
2521 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2523 The first, ``SOURCE``, specifies the source of the control, and is a
2524 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2525 pre-defined sources.
2527 The second, ``DIRECTION``, is one of the following strings according to
2528 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2529 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2532 The third, ``FUNCTION``, is one of the following strings according to
2533 the function of the control: “Switch”, “Volume” and “Route”.
2535 The example of control names are, thus, “Master Capture Switch” or “PCM
2538 There are some exceptions:
2540 Global capture and playback
2541 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2543 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2544 global capture (input) source, switch and volume. Similarly, “Playback
2545 Switch” and “Playback Volume” are used for the global output gain switch
2551 tone-control switch and volumes are specified like “Tone Control - XXX”,
2552 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2558 3D-control switches and volumes are specified like “3D Control - XXX”,
2559 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2564 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2566 More precise information can be found in
2567 ``Documentation/sound/designs/control-names.rst``.
2572 The access flag is the bitmask which specifies the access type of the
2573 given control. The default access type is
2574 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2575 allowed to this control. When the access flag is omitted (i.e. = 0), it
2576 is considered as ``READWRITE`` access as default.
2578 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2579 instead. In this case, you don't have to define the ``put`` callback.
2580 Similarly, when the control is write-only (although it's a rare case),
2581 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2584 If the control value changes frequently (e.g. the VU meter),
2585 ``VOLATILE`` flag should be given. This means that the control may be
2586 changed without `Change notification`_. Applications should poll such
2587 a control constantly.
2589 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2590 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2598 The ``info`` callback is used to get detailed information on this
2599 control. This must store the values of the given
2600 struct snd_ctl_elem_info object. For example,
2601 for a boolean control with a single element:
2606 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2607 struct snd_ctl_elem_info *uinfo)
2609 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2611 uinfo->value.integer.min = 0;
2612 uinfo->value.integer.max = 1;
2618 The ``type`` field specifies the type of the control. There are
2619 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2620 ``INTEGER64``. The ``count`` field specifies the number of elements in
2621 this control. For example, a stereo volume would have count = 2. The
2622 ``value`` field is a union, and the values stored are depending on the
2623 type. The boolean and integer types are identical.
2625 The enumerated type is a bit different from others. You'll need to set
2626 the string for the currently given item index.
2630 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2631 struct snd_ctl_elem_info *uinfo)
2633 static char *texts[4] = {
2634 "First", "Second", "Third", "Fourth"
2636 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2638 uinfo->value.enumerated.items = 4;
2639 if (uinfo->value.enumerated.item > 3)
2640 uinfo->value.enumerated.item = 3;
2641 strcpy(uinfo->value.enumerated.name,
2642 texts[uinfo->value.enumerated.item]);
2646 The above callback can be simplified with a helper function,
2647 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2648 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2649 it's a matter of taste.)
2653 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2654 struct snd_ctl_elem_info *uinfo)
2656 static char *texts[4] = {
2657 "First", "Second", "Third", "Fourth"
2659 return snd_ctl_enum_info(uinfo, 1, 4, texts);
2663 Some common info callbacks are available for your convenience:
2664 :c:func:`snd_ctl_boolean_mono_info()` and
2665 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2666 is an info callback for a mono channel boolean item, just like
2667 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2668 stereo channel boolean item.
2673 This callback is used to read the current value of the control and to
2674 return to user-space.
2681 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2682 struct snd_ctl_elem_value *ucontrol)
2684 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2685 ucontrol->value.integer.value[0] = get_some_value(chip);
2691 The ``value`` field depends on the type of control as well as on the
2692 info callback. For example, the sb driver uses this field to store the
2693 register offset, the bit-shift and the bit-mask. The ``private_value``
2694 field is set as follows:
2698 .private_value = reg | (shift << 16) | (mask << 24)
2700 and is retrieved in callbacks like
2704 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2705 struct snd_ctl_elem_value *ucontrol)
2707 int reg = kcontrol->private_value & 0xff;
2708 int shift = (kcontrol->private_value >> 16) & 0xff;
2709 int mask = (kcontrol->private_value >> 24) & 0xff;
2713 In the ``get`` callback, you have to fill all the elements if the
2714 control has more than one elements, i.e. ``count > 1``. In the example
2715 above, we filled only one element (``value.integer.value[0]``) since
2716 it's assumed as ``count = 1``.
2721 This callback is used to write a value from user-space.
2728 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2729 struct snd_ctl_elem_value *ucontrol)
2731 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2733 if (chip->current_value !=
2734 ucontrol->value.integer.value[0]) {
2735 change_current_value(chip,
2736 ucontrol->value.integer.value[0]);
2744 As seen above, you have to return 1 if the value is changed. If the
2745 value is not changed, return 0 instead. If any fatal error happens,
2746 return a negative error code as usual.
2748 As in the ``get`` callback, when the control has more than one
2749 elements, all elements must be evaluated in this callback, too.
2751 Callbacks are not atomic
2752 ~~~~~~~~~~~~~~~~~~~~~~~~
2754 All these three callbacks are basically not atomic.
2759 When everything is ready, finally we can create a new control. To create
2760 a control, there are two functions to be called,
2761 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2763 In the simplest way, you can do like this:
2767 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2771 where ``my_control`` is the struct snd_kcontrol_new object defined above,
2772 and chip is the object pointer to be passed to kcontrol->private_data which
2773 can be referred to in callbacks.
2775 :c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
2776 :c:func:`snd_ctl_add()` assigns the given control component to the
2782 If you need to change and update a control in the interrupt routine, you
2783 can call :c:func:`snd_ctl_notify()`. For example,
2787 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2789 This function takes the card pointer, the event-mask, and the control id
2790 pointer for the notification. The event-mask specifies the types of
2791 notification, for example, in the above example, the change of control
2792 values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
2793 to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2794 for hardware volume interrupts.
2799 To provide information about the dB values of a mixer control, use on of
2800 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2801 variable containing this information, set the ``tlv.p`` field to point to
2802 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2803 in the ``access`` field; like this:
2807 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2809 static struct snd_kcontrol_new my_control = {
2811 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2812 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2814 .tlv.p = db_scale_my_control,
2818 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2819 about a mixer control where each step in the control's value changes the
2820 dB value by a constant dB amount. The first parameter is the name of the
2821 variable to be defined. The second parameter is the minimum value, in
2822 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2823 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2826 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2827 about a mixer control where the control's value affects the output
2828 linearly. The first parameter is the name of the variable to be defined.
2829 The second parameter is the minimum value, in units of 0.01 dB. The
2830 third parameter is the maximum value, in units of 0.01 dB. If the
2831 minimum value mutes the control, set the second parameter to
2832 ``TLV_DB_GAIN_MUTE``.
2840 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2841 write much code to control it. Only low-level control routines are
2842 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2851 struct snd_ac97 *ac97;
2855 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2858 struct mychip *chip = ac97->private_data;
2860 /* read a register value here from the codec */
2861 return the_register_value;
2864 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2865 unsigned short reg, unsigned short val)
2867 struct mychip *chip = ac97->private_data;
2869 /* write the given register value to the codec */
2872 static int snd_mychip_ac97(struct mychip *chip)
2874 struct snd_ac97_bus *bus;
2875 struct snd_ac97_template ac97;
2877 static struct snd_ac97_bus_ops ops = {
2878 .write = snd_mychip_ac97_write,
2879 .read = snd_mychip_ac97_read,
2882 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2885 memset(&ac97, 0, sizeof(ac97));
2886 ac97.private_data = chip;
2887 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2894 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2895 with an ``ac97_bus_ops_t`` record with callback functions.
2899 struct snd_ac97_bus *bus;
2900 static struct snd_ac97_bus_ops ops = {
2901 .write = snd_mychip_ac97_write,
2902 .read = snd_mychip_ac97_read,
2905 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2907 The bus record is shared among all belonging ac97 instances.
2909 And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
2910 record together with the bus pointer created above.
2914 struct snd_ac97_template ac97;
2917 memset(&ac97, 0, sizeof(ac97));
2918 ac97.private_data = chip;
2919 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2921 where chip->ac97 is a pointer to a newly created ``ac97_t``
2922 instance. In this case, the chip pointer is set as the private data,
2923 so that the read/write callback functions can refer to this chip
2924 instance. This instance is not necessarily stored in the chip
2925 record. If you need to change the register values from the driver, or
2926 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2927 the corresponding functions.
2932 The standard callbacks are ``read`` and ``write``. Obviously they
2933 correspond to the functions for read and write accesses to the
2934 hardware low-level codes.
2936 The ``read`` callback returns the register value specified in the
2941 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2944 struct mychip *chip = ac97->private_data;
2946 return the_register_value;
2949 Here, the chip can be cast from ``ac97->private_data``.
2951 Meanwhile, the ``write`` callback is used to set the register
2956 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2957 unsigned short reg, unsigned short val)
2960 These callbacks are non-atomic like the control API callbacks.
2962 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2964 The ``reset`` callback is used to reset the codec. If the chip
2965 requires a special kind of reset, you can define this callback.
2967 The ``wait`` callback is used to add some waiting time in the standard
2968 initialization of the codec. If the chip requires the extra waiting
2969 time, define this callback.
2971 The ``init`` callback is used for additional initialization of the
2974 Updating Registers in The Driver
2975 --------------------------------
2977 If you need to access to the codec from the driver, you can call the
2978 following functions: :c:func:`snd_ac97_write()`,
2979 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2980 :c:func:`snd_ac97_update_bits()`.
2982 Both :c:func:`snd_ac97_write()` and
2983 :c:func:`snd_ac97_update()` functions are used to set a value to
2984 the given register (``AC97_XXX``). The difference between them is that
2985 :c:func:`snd_ac97_update()` doesn't write a value if the given
2986 value has been already set, while :c:func:`snd_ac97_write()`
2987 always rewrites the value.
2991 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2992 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2994 :c:func:`snd_ac97_read()` is used to read the value of the given
2995 register. For example,
2999 value = snd_ac97_read(ac97, AC97_MASTER);
3001 :c:func:`snd_ac97_update_bits()` is used to update some bits in
3006 snd_ac97_update_bits(ac97, reg, mask, value);
3008 Also, there is a function to change the sample rate (of a given register
3009 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
3010 codec: :c:func:`snd_ac97_set_rate()`.
3014 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
3017 The following registers are available to set the rate:
3018 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
3019 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
3020 specified, the register is not really changed but the corresponding
3021 IEC958 status bits will be updated.
3026 In some chips, the clock of the codec isn't 48000 but using a PCI clock
3027 (to save a quartz!). In this case, change the field ``bus->clock`` to
3028 the corresponding value. For example, intel8x0 and es1968 drivers have
3029 their own function to read from the clock.
3034 The ALSA AC97 interface will create a proc file such as
3035 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
3036 can refer to these files to see the current status and registers of
3042 When there are several codecs on the same card, you need to call
3043 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
3044 greater. The ``num`` field specifies the codec number.
3046 If you set up multiple codecs, you either need to write different
3047 callbacks for each codec or check ``ac97->num`` in the callback
3050 MIDI (MPU401-UART) Interface
3051 ============================
3056 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3057 soundcard supports the standard MPU401-UART interface, most likely you
3058 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3059 ``<sound/mpu401.h>``.
3061 Some soundchips have a similar but slightly different implementation of
3062 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3067 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3071 struct snd_rawmidi *rmidi;
3072 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3076 The first argument is the card pointer, and the second is the index of
3077 this component. You can create up to 8 rawmidi devices.
3079 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3080 it's not a special one, you can use ``MPU401_HW_MPU401``.
3082 The 4th argument is the I/O port address. Many backward-compatible
3083 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3084 PCI I/O region. It depends on the chip design.
3086 The 5th argument is a bitflag for additional information. When the I/O
3087 port address above is part of the PCI I/O region, the MPU401 I/O port
3088 might have been already allocated (reserved) by the driver itself. In
3089 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3090 mpu401-uart layer will allocate the I/O ports by itself.
3092 When the controller supports only the input or output MIDI stream, pass
3093 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3094 respectively. Then the rawmidi instance is created as a single stream.
3096 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3097 (via readb and writeb) instead of iob and outb. In this case, you have
3098 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3100 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3101 the default interrupt handler. The driver needs to call
3102 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3103 processing the output stream in the irq handler.
3105 If the MPU-401 interface shares its interrupt with the other logical
3106 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3107 `below <MIDI Interrupt Handler_>`__).
3109 Usually, the port address corresponds to the command port and port + 1
3110 corresponds to the data port. If not, you may change the ``cport``
3111 field of struct snd_mpu401 manually afterward.
3112 However, struct snd_mpu401 pointer is
3113 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3114 need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
3118 struct snd_mpu401 *mpu;
3119 mpu = rmidi->private_data;
3121 and reset the ``cport`` as you like:
3125 mpu->cport = my_own_control_port;
3127 The 6th argument specifies the ISA irq number that will be allocated. If
3128 no interrupt is to be allocated (because your code is already allocating
3129 a shared interrupt, or because the device does not use interrupts), pass
3130 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3131 will be used instead.
3133 MIDI Interrupt Handler
3134 ----------------------
3136 When the interrupt is allocated in
3137 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3138 handler is automatically used, hence you don't have anything else to do
3139 than creating the mpu401 stuff. Otherwise, you have to set
3140 ``MPU401_INFO_IRQ_HOOK``, and call
3141 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3142 interrupt handler when it has determined that a UART interrupt has
3145 In this case, you need to pass the private_data of the returned rawmidi
3146 object from :c:func:`snd_mpu401_uart_new()` as the second
3147 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3151 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3160 The raw MIDI interface is used for hardware MIDI ports that can be
3161 accessed as a byte stream. It is not used for synthesizer chips that do
3162 not directly understand MIDI.
3164 ALSA handles file and buffer management. All you have to do is to write
3165 some code to move data between the buffer and the hardware.
3167 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3172 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3177 struct snd_rawmidi *rmidi;
3178 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3181 rmidi->private_data = chip;
3182 strcpy(rmidi->name, "My MIDI");
3183 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3184 SNDRV_RAWMIDI_INFO_INPUT |
3185 SNDRV_RAWMIDI_INFO_DUPLEX;
3187 The first argument is the card pointer, the second argument is the ID
3190 The third argument is the index of this component. You can create up to
3193 The fourth and fifth arguments are the number of output and input
3194 substreams, respectively, of this device (a substream is the equivalent
3197 Set the ``info_flags`` field to specify the capabilities of the
3198 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3199 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3200 input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3201 output and input at the same time.
3203 After the rawmidi device is created, you need to set the operators
3204 (callbacks) for each substream. There are helper functions to set the
3205 operators for all the substreams of a device:
3209 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3210 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3212 The operators are usually defined like this:
3216 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3217 .open = snd_mymidi_output_open,
3218 .close = snd_mymidi_output_close,
3219 .trigger = snd_mymidi_output_trigger,
3222 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3224 If there are more than one substream, you should give a unique name to
3229 struct snd_rawmidi_substream *substream;
3230 list_for_each_entry(substream,
3231 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3233 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3235 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3240 In all the callbacks, the private data that you've set for the rawmidi
3241 device can be accessed as ``substream->rmidi->private_data``.
3243 If there is more than one port, your callbacks can determine the port
3244 index from the struct snd_rawmidi_substream data passed to each
3249 struct snd_rawmidi_substream *substream;
3250 int index = substream->number;
3252 RawMIDI open callback
3253 ~~~~~~~~~~~~~~~~~~~~~
3257 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3260 This is called when a substream is opened. You can initialize the
3261 hardware here, but you shouldn't start transmitting/receiving data yet.
3263 RawMIDI close callback
3264 ~~~~~~~~~~~~~~~~~~~~~~
3268 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3272 The ``open`` and ``close`` callbacks of a rawmidi device are
3273 serialized with a mutex, and can sleep.
3275 Rawmidi trigger callback for output substreams
3276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3280 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3283 This is called with a nonzero ``up`` parameter when there is some data
3284 in the substream buffer that must be transmitted.
3286 To read data from the buffer, call
3287 :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3288 of bytes that have been read; this will be less than the number of bytes
3289 requested when there are no more data in the buffer. After the data have
3290 been transmitted successfully, call
3291 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3297 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3298 if (snd_mychip_try_to_transmit(data))
3299 snd_rawmidi_transmit_ack(substream, 1);
3301 break; /* hardware FIFO full */
3304 If you know beforehand that the hardware will accept data, you can use
3305 the :c:func:`snd_rawmidi_transmit()` function which reads some
3306 data and removes them from the buffer at once:
3310 while (snd_mychip_transmit_possible()) {
3312 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3313 break; /* no more data */
3314 snd_mychip_transmit(data);
3317 If you know beforehand how many bytes you can accept, you can use a
3318 buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
3320 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3321 before the substream buffer has been emptied, you have to continue
3322 transmitting data later, either in an interrupt handler, or with a
3323 timer if the hardware doesn't have a MIDI transmit interrupt.
3325 The ``trigger`` callback is called with a zero ``up`` parameter when
3326 the transmission of data should be aborted.
3328 RawMIDI trigger callback for input substreams
3329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3333 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3336 This is called with a nonzero ``up`` parameter to enable receiving data,
3337 or with a zero ``up`` parameter do disable receiving data.
3339 The ``trigger`` callback must not sleep; the actual reading of data
3340 from the device is usually done in an interrupt handler.
3342 When data reception is enabled, your interrupt handler should call
3343 :c:func:`snd_rawmidi_receive()` for all received data:
3347 void snd_mychip_midi_interrupt(...)
3349 while (mychip_midi_available()) {
3351 data = mychip_midi_read();
3352 snd_rawmidi_receive(substream, &data, 1);
3362 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3365 This is only used with output substreams. This function should wait
3366 until all data read from the substream buffer have been transmitted.
3367 This ensures that the device can be closed and the driver unloaded
3368 without losing data.
3370 This callback is optional. If you do not set ``drain`` in the struct
3371 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3374 Miscellaneous Devices
3375 =====================
3380 The FM OPL3 is still used in many chips (mainly for backward
3381 compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3382 is defined in ``<sound/opl3.h>``.
3384 FM registers can be directly accessed through the direct-FM API, defined
3385 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3386 accessed through the Hardware-Dependent Device direct-FM extension API,
3387 whereas in OSS compatible mode, FM registers can be accessed with the
3388 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3390 To create the OPL3 component, you have two functions to call. The first
3391 one is a constructor for the ``opl3_t`` instance.
3395 struct snd_opl3 *opl3;
3396 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3399 The first argument is the card pointer, the second one is the left port
3400 address, and the third is the right port address. In most cases, the
3401 right port is placed at the left port + 2.
3403 The fourth argument is the hardware type.
3405 When the left and right ports have been already allocated by the card
3406 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3407 the opl3 module will allocate the specified ports by itself.
3409 When the accessing the hardware requires special method instead of the
3410 standard I/O access, you can create opl3 instance separately with
3411 :c:func:`snd_opl3_new()`.
3415 struct snd_opl3 *opl3;
3416 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3418 Then set ``command``, ``private_data`` and ``private_free`` for the
3419 private access function, the private data and the destructor. The
3420 ``l_port`` and ``r_port`` are not necessarily set. Only the command
3421 must be set properly. You can retrieve the data from the
3422 ``opl3->private_data`` field.
3424 After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3425 call :c:func:`snd_opl3_init()` to initialize the chip to the
3426 proper state. Note that :c:func:`snd_opl3_create()` always calls
3429 If the opl3 instance is created successfully, then create a hwdep device
3434 struct snd_hwdep *opl3hwdep;
3435 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3437 The first argument is the ``opl3_t`` instance you created, and the
3438 second is the index number, usually 0.
3440 The third argument is the index-offset for the sequencer client assigned
3441 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3444 Hardware-Dependent Devices
3445 --------------------------
3447 Some chips need user-space access for special controls or for loading
3448 the micro code. In such a case, you can create a hwdep
3449 (hardware-dependent) device. The hwdep API is defined in
3450 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3451 ``isa/sb/sb16_csp.c``.
3453 The creation of the ``hwdep`` instance is done via
3454 :c:func:`snd_hwdep_new()`.
3458 struct snd_hwdep *hw;
3459 snd_hwdep_new(card, "My HWDEP", 0, &hw);
3461 where the third argument is the index number.
3463 You can then pass any pointer value to the ``private_data``. If you
3464 assign a private data, you should define the destructor, too. The
3465 destructor function is set in the ``private_free`` field.
3469 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3470 hw->private_data = p;
3471 hw->private_free = mydata_free;
3473 and the implementation of the destructor would be:
3477 static void mydata_free(struct snd_hwdep *hw)
3479 struct mydata *p = hw->private_data;
3483 The arbitrary file operations can be defined for this instance. The file
3484 operators are defined in the ``ops`` table. For example, assume that
3485 this chip needs an ioctl.
3489 hw->ops.open = mydata_open;
3490 hw->ops.ioctl = mydata_ioctl;
3491 hw->ops.release = mydata_release;
3493 And implement the callback functions as you like.
3498 Usually the controls for IEC958 devices are implemented via the control
3499 interface. There is a macro to compose a name string for IEC958
3500 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3501 ``<include/asound.h>``.
3503 There are some standard controls for IEC958 status bits. These controls
3504 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3505 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3506 callback, you don't specify the value field for this type (the count
3507 field must be set, though).
3509 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3510 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3511 returns the bitmask for professional mode. They are read-only controls.
3513 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3514 setting the current default IEC958 bits.
3516 Due to historical reasons, both variants of the Playback Mask and the
3517 Playback Default controls can be implemented on either a
3518 ``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
3519 Drivers should expose the mask and default on the same iface though.
3521 In addition, you can define the control switches to enable/disable or to
3522 set the raw bit mode. The implementation will depend on the chip, but
3523 the control should be named as “IEC958 xxx”, preferably using the
3524 :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3526 You can find several cases, for example, ``pci/emu10k1``,
3527 ``pci/ice1712``, or ``pci/cmipci.c``.
3529 Buffer and Memory Management
3530 ============================
3535 ALSA provides several different buffer allocation functions depending on
3536 the bus and the architecture. All these have a consistent API. The
3537 allocation of physically-contiguous pages is done via
3538 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3541 The allocation of pages with fallback is
3542 :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3543 to allocate the specified pages but if the pages are not available, it
3544 tries to reduce the page sizes until enough space is found.
3546 The release the pages, call :c:func:`snd_free_xxx_pages()`
3549 Usually, ALSA drivers try to allocate and reserve a large contiguous
3550 physical space at the time the module is loaded for the later use. This
3551 is called “pre-allocation”. As already written, you can call the
3552 following function at pcm instance construction time (in the case of PCI
3557 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3558 &pci->dev, size, max);
3560 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3561 the maximum size to be changed via the ``prealloc`` proc file. The
3562 allocator will try to get an area as large as possible within the
3565 The second argument (type) and the third argument (device pointer) are
3566 dependent on the bus. For normal devices, pass the device pointer
3567 (typically identical as ``card->dev``) to the third argument with
3568 ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3569 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3570 You can pass NULL to the device pointer in that case, which is the
3571 default mode implying to allocate with ``GFP_KERNEL`` flag.
3572 If you need a different GFP flag, you can pass it by encoding the flag
3573 into the device pointer via a special macro
3574 :c:func:`snd_dma_continuous_data()`.
3575 For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3576 device pointer (see the `Non-Contiguous Buffers`_ section).
3578 Once the buffer is pre-allocated, you can use the allocator in the
3579 ``hw_params`` callback:
3583 snd_pcm_lib_malloc_pages(substream, size);
3585 Note that you have to pre-allocate to use this function.
3587 Most of drivers use, though, rather the newly introduced "managed
3588 buffer allocation mode" instead of the manual allocation or release.
3589 This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3590 instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
3594 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3595 &pci->dev, size, max);
3597 where passed arguments are identical in both functions.
3598 The difference in the managed mode is that PCM core will call
3599 :c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3600 the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3601 after the PCM ``hw_free`` callback automatically. So the driver
3602 doesn't have to call these functions explicitly in its callback any
3603 longer. This made many driver code having NULL ``hw_params`` and
3604 ``hw_free`` entries.
3606 External Hardware Buffers
3607 -------------------------
3609 Some chips have their own hardware buffers and the DMA transfer from the
3610 host memory is not available. In such a case, you need to either 1)
3611 copy/set the audio data directly to the external hardware buffer, or 2)
3612 make an intermediate buffer and copy/set the data from it to the
3613 external hardware buffer in interrupts (or in tasklets, preferably).
3615 The first case works fine if the external hardware buffer is large
3616 enough. This method doesn't need any extra buffers and thus is more
3617 effective. You need to define the ``copy_user`` and ``copy_kernel``
3618 callbacks for the data transfer, in addition to ``fill_silence``
3619 callback for playback. However, there is a drawback: it cannot be
3620 mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3622 The second case allows for mmap on the buffer, although you have to
3623 handle an interrupt or a tasklet to transfer the data from the
3624 intermediate buffer to the hardware buffer. You can find an example in
3625 the vxpocket driver.
3627 Another case is when the chip uses a PCI memory-map region for the
3628 buffer instead of the host memory. In this case, mmap is available only
3629 on certain architectures like the Intel one. In non-mmap mode, the data
3630 cannot be transferred as in the normal way. Thus you need to define the
3631 ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3632 as in the cases above. The examples are found in ``rme32.c`` and
3635 The implementation of the ``copy_user``, ``copy_kernel`` and
3636 ``silence`` callbacks depends upon whether the hardware supports
3637 interleaved or non-interleaved samples. The ``copy_user`` callback is
3638 defined like below, a bit differently depending whether the direction
3639 is playback or capture:
3643 static int playback_copy_user(struct snd_pcm_substream *substream,
3644 int channel, unsigned long pos,
3645 void __user *src, unsigned long count);
3646 static int capture_copy_user(struct snd_pcm_substream *substream,
3647 int channel, unsigned long pos,
3648 void __user *dst, unsigned long count);
3650 In the case of interleaved samples, the second argument (``channel``) is
3651 not used. The third argument (``pos``) points the current position
3654 The meaning of the fourth argument is different between playback and
3655 capture. For playback, it holds the source data pointer, and for
3656 capture, it's the destination data pointer.
3658 The last argument is the number of bytes to be copied.
3660 What you have to do in this callback is again different between playback
3661 and capture directions. In the playback case, you copy the given amount
3662 of data (``count``) at the specified pointer (``src``) to the specified
3663 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3664 way, the copy would be like:
3668 my_memcpy_from_user(my_buffer + pos, src, count);
3670 For the capture direction, you copy the given amount of data (``count``)
3671 at the specified offset (``pos``) on the hardware buffer to the
3672 specified pointer (``dst``).
3676 my_memcpy_to_user(dst, my_buffer + pos, count);
3678 Here the functions are named as ``from_user`` and ``to_user`` because
3679 it's the user-space buffer that is passed to these callbacks. That
3680 is, the callback is supposed to copy from/to the user-space data
3681 directly to/from the hardware buffer.
3683 Careful readers might notice that these callbacks receive the
3684 arguments in bytes, not in frames like other callbacks. It's because
3685 it would make coding easier like the examples above, and also it makes
3686 easier to unify both the interleaved and non-interleaved cases, as
3687 explained in the following.
3689 In the case of non-interleaved samples, the implementation will be a bit
3690 more complicated. The callback is called for each channel, passed by
3691 the second argument, so totally it's called for N-channels times per
3694 The meaning of other arguments are almost same as the interleaved
3695 case. The callback is supposed to copy the data from/to the given
3696 user-space buffer, but only for the given channel. For the detailed
3697 implementations, please check ``isa/gus/gus_pcm.c`` or
3698 "pci/rme9652/rme9652.c" as examples.
3700 The above callbacks are the copy from/to the user-space buffer. There
3701 are some cases where we want copy from/to the kernel-space buffer
3702 instead. In such a case, ``copy_kernel`` callback is called. It'd
3707 static int playback_copy_kernel(struct snd_pcm_substream *substream,
3708 int channel, unsigned long pos,
3709 void *src, unsigned long count);
3710 static int capture_copy_kernel(struct snd_pcm_substream *substream,
3711 int channel, unsigned long pos,
3712 void *dst, unsigned long count);
3714 As found easily, the only difference is that the buffer pointer is
3715 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3716 in the fourth argument. Correspondingly, the implementation would be
3717 a version without the user-copy, such as:
3721 my_memcpy(my_buffer + pos, src, count);
3723 Usually for the playback, another callback ``fill_silence`` is
3724 defined. It's implemented in a similar way as the copy callbacks
3729 static int silence(struct snd_pcm_substream *substream, int channel,
3730 unsigned long pos, unsigned long count);
3732 The meanings of arguments are the same as in the ``copy_user`` and
3733 ``copy_kernel`` callbacks, although there is no buffer pointer
3734 argument. In the case of interleaved samples, the channel argument has
3735 no meaning, as well as on ``copy_*`` callbacks.
3737 The role of ``fill_silence`` callback is to set the given amount
3738 (``count``) of silence data at the specified offset (``pos``) on the
3739 hardware buffer. Suppose that the data format is signed (that is, the
3740 silent-data is 0), and the implementation using a memset-like function
3745 my_memset(my_buffer + pos, 0, count);
3747 In the case of non-interleaved samples, again, the implementation
3748 becomes a bit more complicated, as it's called N-times per transfer
3749 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3751 Non-Contiguous Buffers
3752 ----------------------
3754 If your hardware supports the page table as in emu10k1 or the buffer
3755 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3756 provides an interface for handling SG-buffers. The API is provided in
3759 For creating the SG-buffer handler, call
3760 :c:func:`snd_pcm_set_managed_buffer()` or
3761 :c:func:`snd_pcm_set_managed_buffer_all()` with
3762 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3763 pre-allocator. You need to pass ``&pci->dev``, where pci is
3764 the struct pci_dev pointer of the chip as
3769 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3770 &pci->dev, size, max);
3772 The ``struct snd_sg_buf`` instance is created as
3773 ``substream->dma_private`` in turn. You can cast the pointer like:
3777 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3779 Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3780 handler will allocate the non-contiguous kernel pages of the given size
3781 and map them onto the virtually contiguous memory. The virtual pointer
3782 is addressed in runtime->dma_area. The physical address
3783 (``runtime->dma_addr``) is set to zero, because the buffer is
3784 physically non-contiguous. The physical address table is set up in
3785 ``sgbuf->table``. You can get the physical address at a certain offset
3786 via :c:func:`snd_pcm_sgbuf_get_addr()`.
3788 If you need to release the SG-buffer data explicitly, call the
3789 standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3794 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3795 example, for an intermediate buffer. In the recent version of kernel,
3796 you can simply allocate it via standard
3797 :c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
3798 buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
3802 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3805 The NULL is passed to the device pointer argument, which indicates
3806 that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3809 Also, note that zero is passed to both the size and the max size
3810 arguments here. Since each vmalloc call should succeed at any time,
3811 we don't need to pre-allocate the buffers like other continuous
3814 If you need the 32bit DMA allocation, pass the device pointer encoded
3815 by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
3820 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3821 snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
3826 ALSA provides an easy interface for procfs. The proc files are very
3827 useful for debugging. I recommend you set up proc files if you write a
3828 driver and want to get a running status or register dumps. The API is
3829 found in ``<sound/info.h>``.
3831 To create a proc file, call :c:func:`snd_card_proc_new()`.
3835 struct snd_info_entry *entry;
3836 int err = snd_card_proc_new(card, "my-file", &entry);
3838 where the second argument specifies the name of the proc file to be
3839 created. The above example will create a file ``my-file`` under the
3840 card directory, e.g. ``/proc/asound/card0/my-file``.
3842 Like other components, the proc entry created via
3843 :c:func:`snd_card_proc_new()` will be registered and released
3844 automatically in the card registration and release functions.
3846 When the creation is successful, the function stores a new instance in
3847 the pointer given in the third argument. It is initialized as a text
3848 proc file for read only. To use this proc file as a read-only text file
3849 as it is, set the read callback with a private data via
3850 :c:func:`snd_info_set_text_ops()`.
3854 snd_info_set_text_ops(entry, chip, my_proc_read);
3856 where the second argument (``chip``) is the private data to be used in
3857 the callbacks. The third parameter specifies the read buffer size and
3858 the fourth (``my_proc_read``) is the callback function, which is
3863 static void my_proc_read(struct snd_info_entry *entry,
3864 struct snd_info_buffer *buffer);
3866 In the read callback, use :c:func:`snd_iprintf()` for output
3867 strings, which works just like normal :c:func:`printf()`. For
3872 static void my_proc_read(struct snd_info_entry *entry,
3873 struct snd_info_buffer *buffer)
3875 struct my_chip *chip = entry->private_data;
3877 snd_iprintf(buffer, "This is my chip!\n");
3878 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3881 The file permissions can be changed afterwards. As default, it's set as
3882 read only for all users. If you want to add write permission for the
3883 user (root as default), do as follows:
3887 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3889 and set the write buffer size and the callback
3893 entry->c.text.write = my_proc_write;
3895 For the write callback, you can use :c:func:`snd_info_get_line()`
3896 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3897 a string from the line. Some examples are found in
3898 ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3900 For a raw-data proc-file, set the attributes as follows:
3904 static const struct snd_info_entry_ops my_file_io_ops = {
3905 .read = my_file_io_read,
3908 entry->content = SNDRV_INFO_CONTENT_DATA;
3909 entry->private_data = chip;
3910 entry->c.ops = &my_file_io_ops;
3912 entry->mode = S_IFREG | S_IRUGO;
3914 For the raw data, ``size`` field must be set properly. This specifies
3915 the maximum size of the proc file access.
3917 The read/write callbacks of raw mode are more direct than the text mode.
3918 You need to use a low-level I/O functions such as
3919 :c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
3923 static ssize_t my_file_io_read(struct snd_info_entry *entry,
3924 void *file_private_data,
3930 if (copy_to_user(buf, local_data + pos, count))
3935 If the size of the info entry has been set up properly, ``count`` and
3936 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3937 have to check the range in the callbacks unless any other condition is
3943 If the chip is supposed to work with suspend/resume functions, you need
3944 to add power-management code to the driver. The additional code for
3945 power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3946 with __maybe_unused attribute; otherwise the compiler will complain
3949 If the driver *fully* supports suspend/resume that is, the device can be
3950 properly resumed to its state when suspend was called, you can set the
3951 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3952 possible when the registers of the chip can be safely saved and restored
3953 to RAM. If this is set, the trigger callback is called with
3954 ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3956 Even if the driver doesn't support PM fully but partial suspend/resume
3957 is still possible, it's still worthy to implement suspend/resume
3958 callbacks. In such a case, applications would reset the status by
3959 calling :c:func:`snd_pcm_prepare()` and restart the stream
3960 appropriately. Hence, you can define suspend/resume callbacks below but
3961 don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3963 Note that the trigger with SUSPEND can always be called when
3964 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3965 ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3966 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3967 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3968 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3969 to keep it for compatibility reasons.)
3971 In the earlier version of ALSA drivers, a common power-management layer
3972 was provided, but it has been removed. The driver needs to define the
3973 suspend/resume hooks according to the bus the device is connected to. In
3974 the case of PCI drivers, the callbacks look like below:
3978 static int __maybe_unused snd_my_suspend(struct device *dev)
3980 .... /* do things for suspend */
3983 static int __maybe_unused snd_my_resume(struct device *dev)
3985 .... /* do things for suspend */
3989 The scheme of the real suspend job is as follows.
3991 1. Retrieve the card and the chip data.
3993 2. Call :c:func:`snd_power_change_state()` with
3994 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3996 3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3999 4. Save the register values if necessary.
4001 5. Stop the hardware if necessary.
4003 A typical code would be like:
4007 static int __maybe_unused mychip_suspend(struct device *dev)
4010 struct snd_card *card = dev_get_drvdata(dev);
4011 struct mychip *chip = card->private_data;
4013 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
4015 snd_ac97_suspend(chip->ac97);
4017 snd_mychip_save_registers(chip);
4019 snd_mychip_stop_hardware(chip);
4024 The scheme of the real resume job is as follows.
4026 1. Retrieve the card and the chip data.
4028 2. Re-initialize the chip.
4030 3. Restore the saved registers if necessary.
4032 4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
4034 5. Restart the hardware (if any).
4036 6. Call :c:func:`snd_power_change_state()` with
4037 ``SNDRV_CTL_POWER_D0`` to notify the processes.
4039 A typical code would be like:
4043 static int __maybe_unused mychip_resume(struct pci_dev *pci)
4046 struct snd_card *card = dev_get_drvdata(dev);
4047 struct mychip *chip = card->private_data;
4049 snd_mychip_reinit_chip(chip);
4051 snd_mychip_restore_registers(chip);
4053 snd_ac97_resume(chip->ac97);
4055 snd_mychip_restart_chip(chip);
4057 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
4061 Note that, at the time this callback gets called, the PCM stream has
4062 been already suspended via its own PM ops calling
4063 :c:func:`snd_pcm_suspend_all()` internally.
4065 OK, we have all callbacks now. Let's set them up. In the initialization
4066 of the card, make sure that you can get the chip data from the card
4067 instance, typically via ``private_data`` field, in case you created the
4068 chip data individually.
4072 static int snd_mychip_probe(struct pci_dev *pci,
4073 const struct pci_device_id *pci_id)
4076 struct snd_card *card;
4077 struct mychip *chip;
4080 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4083 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
4085 card->private_data = chip;
4089 When you created the chip data with :c:func:`snd_card_new()`, it's
4090 anyway accessible via ``private_data`` field.
4094 static int snd_mychip_probe(struct pci_dev *pci,
4095 const struct pci_device_id *pci_id)
4098 struct snd_card *card;
4099 struct mychip *chip;
4102 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4103 sizeof(struct mychip), &card);
4105 chip = card->private_data;
4109 If you need a space to save the registers, allocate the buffer for it
4110 here, too, since it would be fatal if you cannot allocate a memory in
4111 the suspend phase. The allocated buffer should be released in the
4112 corresponding destructor.
4114 And next, set suspend/resume callbacks to the pci_driver.
4118 static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
4120 static struct pci_driver driver = {
4121 .name = KBUILD_MODNAME,
4122 .id_table = snd_my_ids,
4123 .probe = snd_my_probe,
4124 .remove = snd_my_remove,
4125 .driver.pm = &snd_my_pm_ops,
4131 There are standard module options for ALSA. At least, each module should
4132 have the ``index``, ``id`` and ``enable`` options.
4134 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
4135 cards), they should be arrays. The default initial values are defined
4136 already as constants for easier programming:
4140 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
4141 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
4142 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
4144 If the module supports only a single card, they could be single
4145 variables, instead. ``enable`` option is not always necessary in this
4146 case, but it would be better to have a dummy option for compatibility.
4148 The module parameters must be declared with the standard
4149 ``module_param()``, ``module_param_array()`` and
4150 :c:func:`MODULE_PARM_DESC()` macros.
4152 The typical coding would be like below:
4156 #define CARD_NAME "My Chip"
4158 module_param_array(index, int, NULL, 0444);
4159 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
4160 module_param_array(id, charp, NULL, 0444);
4161 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
4162 module_param_array(enable, bool, NULL, 0444);
4163 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4165 Also, don't forget to define the module description and the license.
4166 Especially, the recent modprobe requires to define the
4167 module license as GPL, etc., otherwise the system is shown as “tainted”.
4171 MODULE_DESCRIPTION("Sound driver for My Chip");
4172 MODULE_LICENSE("GPL");
4175 How To Put Your Driver Into ALSA Tree
4176 =====================================
4181 So far, you've learned how to write the driver codes. And you might have
4182 a question now: how to put my own driver into the ALSA driver tree? Here
4183 (finally :) the standard procedure is described briefly.
4185 Suppose that you create a new PCI driver for the card “xyz”. The card
4186 module name would be snd-xyz. The new driver is usually put into the
4187 alsa-driver tree, ``sound/pci`` directory in the case of PCI
4190 In the following sections, the driver code is supposed to be put into
4191 Linux kernel tree. The two cases are covered: a driver consisting of a
4192 single source file and one consisting of several source files.
4194 Driver with A Single Source File
4195 --------------------------------
4197 1. Modify sound/pci/Makefile
4199 Suppose you have a file xyz.c. Add the following two lines
4203 snd-xyz-objs := xyz.o
4204 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4206 2. Create the Kconfig entry
4208 Add the new entry of Kconfig for your xyz driver. config SND_XYZ
4209 tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
4210 to include support for Foobar XYZ soundcard. To compile this driver
4211 as a module, choose M here: the module will be called snd-xyz. the
4212 line, select SND_PCM, specifies that the driver xyz supports PCM. In
4213 addition to SND_PCM, the following components are supported for
4214 select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
4215 SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
4216 SND_AC97_CODEC. Add the select command for each supported
4219 Note that some selections imply the lowlevel selections. For example,
4220 PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4221 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4222 the lowlevel selections again.
4224 For the details of Kconfig script, refer to the kbuild documentation.
4226 Drivers with Several Source Files
4227 ---------------------------------
4229 Suppose that the driver snd-xyz have several source files. They are
4230 located in the new subdirectory, sound/pci/xyz.
4232 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4237 obj-$(CONFIG_SND) += sound/pci/xyz/
4240 2. Under the directory ``sound/pci/xyz``, create a Makefile
4244 snd-xyz-objs := xyz.o abc.o def.o
4245 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4247 3. Create the Kconfig entry
4249 This procedure is as same as in the last section.
4255 :c:func:`snd_printk()` and friends
4256 ----------------------------------
4258 .. note:: This subsection describes a few helper functions for
4259 decorating a bit more on the standard :c:func:`printk()` & co.
4260 However, in general, the use of such helpers is no longer recommended.
4261 If possible, try to stick with the standard functions like
4262 :c:func:`dev_err()` or :c:func:`pr_err()`.
4264 ALSA provides a verbose version of the :c:func:`printk()` function.
4265 If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4266 prints the given message together with the file name and the line of the
4267 caller. The ``KERN_XXX`` prefix is processed as well as the original
4268 :c:func:`printk()` does, so it's recommended to add this prefix,
4269 e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4271 There are also :c:func:`printk()`'s for debugging.
4272 :c:func:`snd_printd()` can be used for general debugging purposes.
4273 If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4274 just like :c:func:`snd_printk()`. If the ALSA is compiled without
4275 the debugging flag, it's ignored.
4277 :c:func:`snd_printdd()` is compiled in only when
4278 ``CONFIG_SND_DEBUG_VERBOSE`` is set.
4283 It shows the ``BUG?`` message and stack trace as well as
4284 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4285 fatal error happens there.
4287 When no debug flag is set, this macro is ignored.
4289 :c:func:`snd_BUG_ON()`
4290 ----------------------
4292 :c:func:`snd_BUG_ON()` macro is similar with
4293 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4294 it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4297 The macro takes an conditional expression to evaluate. When
4298 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4299 the warning message such as ``BUG? (xxx)`` normally followed by stack
4300 trace. In both cases it returns the evaluated value.
4305 I would like to thank Phil Kerr for his help for improvement and
4306 corrections of this document.
4308 Kevin Conder reformatted the original plain-text to the DocBook format.
4310 Giuliano Pochini corrected typos and contributed the example codes in
4311 the hardware constraints section.
projects / platform / kernel / linux-rpi.git / blob