4065 lines · plain
1======================2Writing an ALSA Driver3======================4 5:Author: Takashi Iwai <tiwai@suse.de>6 7Preface8=======9 10This document describes how to write an `ALSA (Advanced Linux Sound11Architecture) <http://www.alsa-project.org/>`__ driver. The document12focuses mainly on PCI soundcards. In the case of other device types, the13API might be different, too. However, at least the ALSA kernel API is14consistent, and therefore it would be still a bit help for writing them.15 16This document targets people who already have enough C language skills17and have basic linux kernel programming knowledge. This document doesn't18explain the general topic of linux kernel coding and doesn't cover19low-level driver implementation details. It only describes the standard20way to write a PCI sound driver on ALSA.21 22File Tree Structure23===================24 25General26-------27 28The file tree structure of ALSA driver is depicted below::29 30 sound31 /core32 /oss33 /seq34 /oss35 /include36 /drivers37 /mpu40138 /opl339 /i2c40 /synth41 /emux42 /pci43 /(cards)44 /isa45 /(cards)46 /arm47 /ppc48 /sparc49 /usb50 /pcmcia /(cards)51 /soc52 /oss53 54 55core directory56--------------57 58This directory contains the middle layer which is the heart of ALSA59drivers. In this directory, the native ALSA modules are stored. The60sub-directories contain different modules and are dependent upon the61kernel config.62 63core/oss64~~~~~~~~65 66The code for OSS PCM and mixer emulation modules is stored in this67directory. The OSS rawmidi emulation is included in the ALSA rawmidi68code since it's quite small. The sequencer code is stored in69``core/seq/oss`` directory (see `below <core/seq/oss_>`__).70 71core/seq72~~~~~~~~73 74This directory and its sub-directories are for the ALSA sequencer. This75directory contains the sequencer core and primary sequencer modules such76as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when77``CONFIG_SND_SEQUENCER`` is set in the kernel config.78 79core/seq/oss80~~~~~~~~~~~~81 82This contains the OSS sequencer emulation code.83 84include directory85-----------------86 87This is the place for the public header files of ALSA drivers, which are88to be exported to user-space, or included by several files in different89directories. Basically, the private header files should not be placed in90this directory, but you may still find files there, due to historical91reasons :)92 93drivers directory94-----------------95 96This directory contains code shared among different drivers on different97architectures. They are hence supposed not to be architecture-specific.98For example, the dummy PCM driver and the serial MIDI driver are found99in this directory. In the sub-directories, there is code for components100which are independent from bus and cpu architectures.101 102drivers/mpu401103~~~~~~~~~~~~~~104 105The MPU401 and MPU401-UART modules are stored here.106 107drivers/opl3 and opl4108~~~~~~~~~~~~~~~~~~~~~109 110The OPL3 and OPL4 FM-synth stuff is found here.111 112i2c directory113-------------114 115This contains the ALSA i2c components.116 117Although there is a standard i2c layer on Linux, ALSA has its own i2c118code for some cards, because the soundcard needs only a simple operation119and the standard i2c API is too complicated for such a purpose.120 121synth directory122---------------123 124This contains the synth middle-level modules.125 126So far, there is only Emu8000/Emu10k1 synth driver under the127``synth/emux`` sub-directory.128 129pci directory130-------------131 132This directory and its sub-directories hold the top-level card modules133for PCI soundcards and the code specific to the PCI BUS.134 135The drivers compiled from a single file are stored directly in the pci136directory, while the drivers with several source files are stored on137their own sub-directory (e.g. emu10k1, ice1712).138 139isa directory140-------------141 142This directory and its sub-directories hold the top-level card modules143for ISA soundcards.144 145arm, ppc, and sparc directories146-------------------------------147 148They are used for top-level card modules which are specific to one of149these architectures.150 151usb directory152-------------153 154This directory contains the USB-audio driver.155The USB MIDI driver is integrated in the usb-audio driver.156 157pcmcia directory158----------------159 160The PCMCIA, especially PCCard drivers will go here. CardBus drivers will161be in the pci directory, because their API is identical to that of162standard PCI cards.163 164soc directory165-------------166 167This directory contains the codes for ASoC (ALSA System on Chip)168layer including ASoC core, codec and machine drivers.169 170oss directory171-------------172 173This contains OSS/Lite code.174At the time of writing, all code has been removed except for dmasound175on m68k.176 177 178Basic Flow for PCI Drivers179==========================180 181Outline182-------183 184The minimum flow for PCI soundcards is as follows:185 186- define the PCI ID table (see the section `PCI Entries`_).187 188- create ``probe`` callback.189 190- create ``remove`` callback.191 192- create a struct pci_driver structure193 containing the three pointers above.194 195- create an ``init`` function just calling the196 :c:func:`pci_register_driver()` to register the pci_driver197 table defined above.198 199- create an ``exit`` function to call the200 :c:func:`pci_unregister_driver()` function.201 202Full Code Example203-----------------204 205The code example is shown below. Some parts are kept unimplemented at206this moment but will be filled in the next sections. The numbers in the207comment lines of the :c:func:`snd_mychip_probe()` function refer208to details explained in the following section.209 210::211 212 #include <linux/init.h>213 #include <linux/pci.h>214 #include <linux/slab.h>215 #include <sound/core.h>216 #include <sound/initval.h>217 218 /* module parameters (see "Module Parameters") */219 /* SNDRV_CARDS: maximum number of cards supported by this module */220 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;221 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;222 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;223 224 /* definition of the chip-specific record */225 struct mychip {226 struct snd_card *card;227 /* the rest of the implementation will be in section228 * "PCI Resource Management"229 */230 };231 232 /* chip-specific destructor233 * (see "PCI Resource Management")234 */235 static int snd_mychip_free(struct mychip *chip)236 {237 .... /* will be implemented later... */238 }239 240 /* component-destructor241 * (see "Management of Cards and Components")242 */243 static int snd_mychip_dev_free(struct snd_device *device)244 {245 return snd_mychip_free(device->device_data);246 }247 248 /* chip-specific constructor249 * (see "Management of Cards and Components")250 */251 static int snd_mychip_create(struct snd_card *card,252 struct pci_dev *pci,253 struct mychip **rchip)254 {255 struct mychip *chip;256 int err;257 static const struct snd_device_ops ops = {258 .dev_free = snd_mychip_dev_free,259 };260 261 *rchip = NULL;262 263 /* check PCI availability here264 * (see "PCI Resource Management")265 */266 ....267 268 /* allocate a chip-specific data with zero filled */269 chip = kzalloc(sizeof(*chip), GFP_KERNEL);270 if (chip == NULL)271 return -ENOMEM;272 273 chip->card = card;274 275 /* rest of initialization here; will be implemented276 * later, see "PCI Resource Management"277 */278 ....279 280 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);281 if (err < 0) {282 snd_mychip_free(chip);283 return err;284 }285 286 *rchip = chip;287 return 0;288 }289 290 /* constructor -- see "Driver Constructor" sub-section */291 static int snd_mychip_probe(struct pci_dev *pci,292 const struct pci_device_id *pci_id)293 {294 static int dev;295 struct snd_card *card;296 struct mychip *chip;297 int err;298 299 /* (1) */300 if (dev >= SNDRV_CARDS)301 return -ENODEV;302 if (!enable[dev]) {303 dev++;304 return -ENOENT;305 }306 307 /* (2) */308 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,309 0, &card);310 if (err < 0)311 return err;312 313 /* (3) */314 err = snd_mychip_create(card, pci, &chip);315 if (err < 0)316 goto error;317 318 /* (4) */319 strcpy(card->driver, "My Chip");320 strcpy(card->shortname, "My Own Chip 123");321 sprintf(card->longname, "%s at 0x%lx irq %i",322 card->shortname, chip->port, chip->irq);323 324 /* (5) */325 .... /* implemented later */326 327 /* (6) */328 err = snd_card_register(card);329 if (err < 0)330 goto error;331 332 /* (7) */333 pci_set_drvdata(pci, card);334 dev++;335 return 0;336 337 error:338 snd_card_free(card);339 return err;340 }341 342 /* destructor -- see the "Destructor" sub-section */343 static void snd_mychip_remove(struct pci_dev *pci)344 {345 snd_card_free(pci_get_drvdata(pci));346 }347 348 349 350Driver Constructor351------------------352 353The real constructor of PCI drivers is the ``probe`` callback. The354``probe`` callback and other component-constructors which are called355from the ``probe`` callback cannot be used with the ``__init`` prefix356because any PCI device could be a hotplug device.357 358In the ``probe`` callback, the following scheme is often used.359 3601) Check and increment the device index.361~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~362 363::364 365 static int dev;366 ....367 if (dev >= SNDRV_CARDS)368 return -ENODEV;369 if (!enable[dev]) {370 dev++;371 return -ENOENT;372 }373 374 375where ``enable[dev]`` is the module option.376 377Each time the ``probe`` callback is called, check the availability of378the device. If not available, simply increment the device index and379return. dev will be incremented also later (`step 7380<7) Set the PCI driver data and return zero._>`__).381 3822) Create a card instance383~~~~~~~~~~~~~~~~~~~~~~~~~384 385::386 387 struct snd_card *card;388 int err;389 ....390 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,391 0, &card);392 393 394The details will be explained in the section `Management of Cards and395Components`_.396 3973) Create a main component398~~~~~~~~~~~~~~~~~~~~~~~~~~399 400In this part, the PCI resources are allocated::401 402 struct mychip *chip;403 ....404 err = snd_mychip_create(card, pci, &chip);405 if (err < 0)406 goto error;407 408The details will be explained in the section `PCI Resource409Management`_.410 411When something goes wrong, the probe function needs to deal with the412error. In this example, we have a single error handling path placed413at the end of the function::414 415 error:416 snd_card_free(card);417 return err;418 419Since each component can be properly freed, the single420:c:func:`snd_card_free()` call should suffice in most cases.421 422 4234) Set the driver ID and name strings.424~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~425 426::427 428 strcpy(card->driver, "My Chip");429 strcpy(card->shortname, "My Own Chip 123");430 sprintf(card->longname, "%s at 0x%lx irq %i",431 card->shortname, chip->port, chip->irq);432 433The driver field holds the minimal ID string of the chip. This is used434by alsa-lib's configurator, so keep it simple but unique. Even the435same driver can have different driver IDs to distinguish the436functionality of each chip type.437 438The shortname field is a string shown as more verbose name. The longname439field contains the information shown in ``/proc/asound/cards``.440 4415) Create other components, such as mixer, MIDI, etc.442~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~443 444Here you define the basic components such as `PCM <PCM Interface_>`__,445mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.446`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.447Also, if you want a `proc file <Proc Interface_>`__, define it here,448too.449 4506) Register the card instance.451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~452 453::454 455 err = snd_card_register(card);456 if (err < 0)457 goto error;458 459Will be explained in the section `Management of Cards and460Components`_, too.461 4627) Set the PCI driver data and return zero.463~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~464 465::466 467 pci_set_drvdata(pci, card);468 dev++;469 return 0;470 471In the above, the card record is stored. This pointer is used in the472remove callback and power-management callbacks, too.473 474Destructor475----------476 477The destructor, the remove callback, simply releases the card instance.478Then the ALSA middle layer will release all the attached components479automatically.480 481It would be typically just calling :c:func:`snd_card_free()`::482 483 static void snd_mychip_remove(struct pci_dev *pci)484 {485 snd_card_free(pci_get_drvdata(pci));486 }487 488 489The above code assumes that the card pointer is set to the PCI driver490data.491 492Header Files493------------494 495For the above example, at least the following include files are496necessary::497 498 #include <linux/init.h>499 #include <linux/pci.h>500 #include <linux/slab.h>501 #include <sound/core.h>502 #include <sound/initval.h>503 504where the last one is necessary only when module options are defined505in the source file. If the code is split into several files, the files506without module options don't need them.507 508In addition to these headers, you'll need ``<linux/interrupt.h>`` for509interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the510:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need511to include ``<linux/delay.h>`` too.512 513The ALSA interfaces like the PCM and control APIs are defined in other514``<sound/xxx.h>`` header files. They have to be included after515``<sound/core.h>``.516 517Management of Cards and Components518==================================519 520Card Instance521-------------522 523For each soundcard, a “card” record must be allocated.524 525A card record is the headquarters of the soundcard. It manages the whole526list of devices (components) on the soundcard, such as PCM, mixers,527MIDI, synthesizer, and so on. Also, the card record holds the ID and the528name strings of the card, manages the root of proc files, and controls529the power-management states and hotplug disconnections. The component530list on the card record is used to manage the correct release of531resources at destruction.532 533As mentioned above, to create a card instance, call534:c:func:`snd_card_new()`::535 536 struct snd_card *card;537 int err;538 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);539 540 541The function takes six arguments: the parent device pointer, the542card-index number, the id string, the module pointer (usually543``THIS_MODULE``), the size of extra-data space, and the pointer to544return the card instance. The extra_size argument is used to allocate545card->private_data for the chip-specific data. Note that these data are546allocated by :c:func:`snd_card_new()`.547 548The first argument, the pointer of struct device, specifies the parent549device. For PCI devices, typically ``&pci->`` is passed there.550 551Components552----------553 554After the card is created, you can attach the components (devices) to555the card instance. In an ALSA driver, a component is represented as a556struct snd_device object. A component557can be a PCM instance, a control interface, a raw MIDI interface, etc.558Each such instance has one component entry.559 560A component can be created via the :c:func:`snd_device_new()`561function::562 563 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);564 565This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the566data pointer, and the callback pointers (``&ops``). The device-level567defines the type of components and the order of registration and568de-registration. For most components, the device-level is already569defined. For a user-defined component, you can use570``SNDRV_DEV_LOWLEVEL``.571 572This function itself doesn't allocate the data space. The data must be573allocated manually beforehand, and its pointer is passed as the574argument. This pointer (``chip`` in the above example) is used as the575identifier for the instance.576 577Each pre-defined ALSA component such as AC97 and PCM calls578:c:func:`snd_device_new()` inside its constructor. The destructor579for each component is defined in the callback pointers. Hence, you don't580need to take care of calling a destructor for such a component.581 582If you wish to create your own component, you need to set the destructor583function to the dev_free callback in the ``ops``, so that it can be584released automatically via :c:func:`snd_card_free()`. The next585example will show an implementation of chip-specific data.586 587Chip-Specific Data588------------------589 590Chip-specific information, e.g. the I/O port address, its resource591pointer, or the irq number, is stored in the chip-specific record::592 593 struct mychip {594 ....595 };596 597 598In general, there are two ways of allocating the chip record.599 6001. Allocating via :c:func:`snd_card_new()`.601~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~602 603As mentioned above, you can pass the extra-data-length to the 5th604argument of :c:func:`snd_card_new()`, e.g.::605 606 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,607 sizeof(struct mychip), &card);608 609struct mychip is the type of the chip record.610 611In return, the allocated record can be accessed as612 613::614 615 struct mychip *chip = card->private_data;616 617With this method, you don't have to allocate twice. The record is618released together with the card instance.619 6202. Allocating an extra device.621~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~622 623After allocating a card instance via :c:func:`snd_card_new()`624(with ``0`` on the 4th arg), call :c:func:`kzalloc()`::625 626 struct snd_card *card;627 struct mychip *chip;628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,629 0, &card);630 .....631 chip = kzalloc(sizeof(*chip), GFP_KERNEL);632 633The chip record should have the field to hold the card pointer at least,634 635::636 637 struct mychip {638 struct snd_card *card;639 ....640 };641 642 643Then, set the card pointer in the returned chip instance::644 645 chip->card = card;646 647Next, initialize the fields, and register this chip record as a648low-level device with a specified ``ops``::649 650 static const struct snd_device_ops ops = {651 .dev_free = snd_mychip_dev_free,652 };653 ....654 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);655 656:c:func:`snd_mychip_dev_free()` is the device-destructor657function, which will call the real destructor::658 659 static int snd_mychip_dev_free(struct snd_device *device)660 {661 return snd_mychip_free(device->device_data);662 }663 664where :c:func:`snd_mychip_free()` is the real destructor.665 666The demerit of this method is the obviously larger amount of code.667The merit is, however, that you can trigger your own callback at668registering and disconnecting the card via a setting in snd_device_ops.669About registering and disconnecting the card, see the subsections670below.671 672 673Registration and Release674------------------------675 676After all components are assigned, register the card instance by calling677:c:func:`snd_card_register()`. Access to the device files is678enabled at this point. That is, before679:c:func:`snd_card_register()` is called, the components are safely680inaccessible from external side. If this call fails, exit the probe681function after releasing the card via :c:func:`snd_card_free()`.682 683For releasing the card instance, you can call simply684:c:func:`snd_card_free()`. As mentioned earlier, all components685are released automatically by this call.686 687For a device which allows hotplugging, you can use688:c:func:`snd_card_free_when_closed()`. This one will postpone689the destruction until all devices are closed.690 691PCI Resource Management692=======================693 694Full Code Example695-----------------696 697In this section, we'll complete the chip-specific constructor,698destructor and PCI entries. Example code is shown first, below::699 700 struct mychip {701 struct snd_card *card;702 struct pci_dev *pci;703 704 unsigned long port;705 int irq;706 };707 708 static int snd_mychip_free(struct mychip *chip)709 {710 /* disable hardware here if any */711 .... /* (not implemented in this document) */712 713 /* release the irq */714 if (chip->irq >= 0)715 free_irq(chip->irq, chip);716 /* release the I/O ports & memory */717 pci_release_regions(chip->pci);718 /* disable the PCI entry */719 pci_disable_device(chip->pci);720 /* release the data */721 kfree(chip);722 return 0;723 }724 725 /* chip-specific constructor */726 static int snd_mychip_create(struct snd_card *card,727 struct pci_dev *pci,728 struct mychip **rchip)729 {730 struct mychip *chip;731 int err;732 static const struct snd_device_ops ops = {733 .dev_free = snd_mychip_dev_free,734 };735 736 *rchip = NULL;737 738 /* initialize the PCI entry */739 err = pci_enable_device(pci);740 if (err < 0)741 return err;742 /* check PCI availability (28bit DMA) */743 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||744 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {745 printk(KERN_ERR "error to set 28bit mask DMA\n");746 pci_disable_device(pci);747 return -ENXIO;748 }749 750 chip = kzalloc(sizeof(*chip), GFP_KERNEL);751 if (chip == NULL) {752 pci_disable_device(pci);753 return -ENOMEM;754 }755 756 /* initialize the stuff */757 chip->card = card;758 chip->pci = pci;759 chip->irq = -1;760 761 /* (1) PCI resource allocation */762 err = pci_request_regions(pci, "My Chip");763 if (err < 0) {764 kfree(chip);765 pci_disable_device(pci);766 return err;767 }768 chip->port = pci_resource_start(pci, 0);769 if (request_irq(pci->irq, snd_mychip_interrupt,770 IRQF_SHARED, KBUILD_MODNAME, chip)) {771 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);772 snd_mychip_free(chip);773 return -EBUSY;774 }775 chip->irq = pci->irq;776 card->sync_irq = chip->irq;777 778 /* (2) initialization of the chip hardware */779 .... /* (not implemented in this document) */780 781 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);782 if (err < 0) {783 snd_mychip_free(chip);784 return err;785 }786 787 *rchip = chip;788 return 0;789 }790 791 /* PCI IDs */792 static struct pci_device_id snd_mychip_ids[] = {793 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,794 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },795 ....796 { 0, }797 };798 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);799 800 /* pci_driver definition */801 static struct pci_driver driver = {802 .name = KBUILD_MODNAME,803 .id_table = snd_mychip_ids,804 .probe = snd_mychip_probe,805 .remove = snd_mychip_remove,806 };807 808 /* module initialization */809 static int __init alsa_card_mychip_init(void)810 {811 return pci_register_driver(&driver);812 }813 814 /* module clean up */815 static void __exit alsa_card_mychip_exit(void)816 {817 pci_unregister_driver(&driver);818 }819 820 module_init(alsa_card_mychip_init)821 module_exit(alsa_card_mychip_exit)822 823 EXPORT_NO_SYMBOLS; /* for old kernels only */824 825Some Hafta's826------------827 828The allocation of PCI resources is done in the ``probe`` function, and829usually an extra :c:func:`xxx_create()` function is written for this830purpose.831 832In the case of PCI devices, you first have to call the833:c:func:`pci_enable_device()` function before allocating834resources. Also, you need to set the proper PCI DMA mask to limit the835accessed I/O range. In some cases, you might need to call836:c:func:`pci_set_master()` function, too.837 838Suppose a 28bit mask, the code to be added would look like::839 840 err = pci_enable_device(pci);841 if (err < 0)842 return err;843 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||844 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {845 printk(KERN_ERR "error to set 28bit mask DMA\n");846 pci_disable_device(pci);847 return -ENXIO;848 }849 850 851Resource Allocation852-------------------853 854The allocation of I/O ports and irqs is done via standard kernel855functions. These resources must be released in the destructor856function (see below).857 858Now assume that the PCI device has an I/O port with 8 bytes and an859interrupt. Then struct mychip will have the860following fields::861 862 struct mychip {863 struct snd_card *card;864 865 unsigned long port;866 int irq;867 };868 869 870For an I/O port (and also a memory region), you need to have the871resource pointer for the standard resource management. For an irq, you872have to keep only the irq number (integer). But you need to initialize873this number to -1 before actual allocation, since irq 0 is valid. The874port address and its resource pointer can be initialized as null by875:c:func:`kzalloc()` automatically, so you don't have to take care of876resetting them.877 878The allocation of an I/O port is done like this::879 880 err = pci_request_regions(pci, "My Chip");881 if (err < 0) { 882 kfree(chip);883 pci_disable_device(pci);884 return err;885 }886 chip->port = pci_resource_start(pci, 0);887 888It will reserve the I/O port region of 8 bytes of the given PCI device.889The returned value, ``chip->res_port``, is allocated via890:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer891must be released via :c:func:`kfree()`, but there is a problem with892this. This issue will be explained later.893 894The allocation of an interrupt source is done like this::895 896 if (request_irq(pci->irq, snd_mychip_interrupt,897 IRQF_SHARED, KBUILD_MODNAME, chip)) {898 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);899 snd_mychip_free(chip);900 return -EBUSY;901 }902 chip->irq = pci->irq;903 904where :c:func:`snd_mychip_interrupt()` is the interrupt handler905defined `later <PCM Interrupt Handler_>`__. Note that906``chip->irq`` should be defined only when :c:func:`request_irq()`907succeeded.908 909On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used910as the interrupt flag of :c:func:`request_irq()`.911 912The last argument of :c:func:`request_irq()` is the data pointer913passed to the interrupt handler. Usually, the chip-specific record is914used for that, but you can use what you like, too.915 916I won't give details about the interrupt handler at this point, but at917least its appearance can be explained now. The interrupt handler looks918usually as follows::919 920 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)921 {922 struct mychip *chip = dev_id;923 ....924 return IRQ_HANDLED;925 }926 927After requesting the IRQ, you can passed it to ``card->sync_irq``928field::929 930 card->irq = chip->irq;931 932This allows the PCM core to automatically call933:c:func:`synchronize_irq()` at the right time, like before ``hw_free``.934See the later section `sync_stop callback`_ for details.935 936Now let's write the corresponding destructor for the resources above.937The role of destructor is simple: disable the hardware (if already938activated) and release the resources. So far, we have no hardware part,939so the disabling code is not written here.940 941To release the resources, the “check-and-release” method is a safer way.942For the interrupt, do like this::943 944 if (chip->irq >= 0)945 free_irq(chip->irq, chip);946 947Since the irq number can start from 0, you should initialize948``chip->irq`` with a negative value (e.g. -1), so that you can check949the validity of the irq number as above.950 951When you requested I/O ports or memory regions via952:c:func:`pci_request_region()` or953:c:func:`pci_request_regions()` like in this example, release the954resource(s) using the corresponding function,955:c:func:`pci_release_region()` or956:c:func:`pci_release_regions()`::957 958 pci_release_regions(chip->pci);959 960When you requested manually via :c:func:`request_region()` or961:c:func:`request_mem_region()`, you can release it via962:c:func:`release_resource()`. Suppose that you keep the resource963pointer returned from :c:func:`request_region()` in964chip->res_port, the release procedure looks like::965 966 release_and_free_resource(chip->res_port);967 968Don't forget to call :c:func:`pci_disable_device()` before the969end.970 971And finally, release the chip-specific record::972 973 kfree(chip);974 975We didn't implement the hardware disabling part above. If you976need to do this, please note that the destructor may be called even977before the initialization of the chip is completed. It would be better978to have a flag to skip hardware disabling if the hardware was not979initialized yet.980 981When the chip-data is assigned to the card using982:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its983destructor is called last. That is, it is assured that all other984components like PCMs and controls have already been released. You don't985have to stop PCMs, etc. explicitly, but just call low-level hardware986stopping.987 988The management of a memory-mapped region is almost as same as the989management of an I/O port. You'll need two fields as follows::990 991 struct mychip {992 ....993 unsigned long iobase_phys;994 void __iomem *iobase_virt;995 };996 997and the allocation would look like below::998 999 err = pci_request_regions(pci, "My Chip");1000 if (err < 0) {1001 kfree(chip);1002 return err;1003 }1004 chip->iobase_phys = pci_resource_start(pci, 0);1005 chip->iobase_virt = ioremap(chip->iobase_phys,1006 pci_resource_len(pci, 0));1007 1008and the corresponding destructor would be::1009 1010 static int snd_mychip_free(struct mychip *chip)1011 {1012 ....1013 if (chip->iobase_virt)1014 iounmap(chip->iobase_virt);1015 ....1016 pci_release_regions(chip->pci);1017 ....1018 }1019 1020Of course, a modern way with :c:func:`pci_iomap()` will make things a1021bit easier, too::1022 1023 err = pci_request_regions(pci, "My Chip");1024 if (err < 0) {1025 kfree(chip);1026 return err;1027 }1028 chip->iobase_virt = pci_iomap(pci, 0, 0);1029 1030which is paired with :c:func:`pci_iounmap()` at destructor.1031 1032 1033PCI Entries1034-----------1035 1036So far, so good. Let's finish the missing PCI stuff. At first, we need a1037struct pci_device_id table for1038this chipset. It's a table of PCI vendor/device ID number, and some1039masks.1040 1041For example::1042 1043 static struct pci_device_id snd_mychip_ids[] = {1044 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,1045 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },1046 ....1047 { 0, }1048 };1049 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);1050 1051The first and second fields of the struct pci_device_id are the vendor1052and device IDs. If you have no reason to filter the matching devices, you can1053leave the remaining fields as above. The last field of the1054struct pci_device_id contains private data for this entry. You can specify1055any value here, for example, to define specific operations for supported1056device IDs. Such an example is found in the intel8x0 driver.1057 1058The last entry of this list is the terminator. You must specify this1059all-zero entry.1060 1061Then, prepare the struct pci_driver1062record::1063 1064 static struct pci_driver driver = {1065 .name = KBUILD_MODNAME,1066 .id_table = snd_mychip_ids,1067 .probe = snd_mychip_probe,1068 .remove = snd_mychip_remove,1069 };1070 1071The ``probe`` and ``remove`` functions have already been defined in1072the previous sections. The ``name`` field is the name string of this1073device. Note that you must not use slashes (“/”) in this string.1074 1075And at last, the module entries::1076 1077 static int __init alsa_card_mychip_init(void)1078 {1079 return pci_register_driver(&driver);1080 }1081 1082 static void __exit alsa_card_mychip_exit(void)1083 {1084 pci_unregister_driver(&driver);1085 }1086 1087 module_init(alsa_card_mychip_init)1088 module_exit(alsa_card_mychip_exit)1089 1090Note that these module entries are tagged with ``__init`` and ``__exit``1091prefixes.1092 1093That's all!1094 1095PCM Interface1096=============1097 1098General1099-------1100 1101The PCM middle layer of ALSA is quite powerful and it is only necessary1102for each driver to implement the low-level functions to access its1103hardware.1104 1105To access the PCM layer, you need to include ``<sound/pcm.h>``1106first. In addition, ``<sound/pcm_params.h>`` might be needed if you1107access some functions related with hw_param.1108 1109Each card device can have up to four PCM instances. A PCM instance1110corresponds to a PCM device file. The limitation of number of instances1111comes only from the available bit size of Linux' device numbers.1112Once 64bit device numbers are used, we'll have more PCM instances1113available.1114 1115A PCM instance consists of PCM playback and capture streams, and each1116PCM stream consists of one or more PCM substreams. Some soundcards1117support multiple playback functions. For example, emu10k1 has a PCM1118playback of 32 stereo substreams. In this case, at each open, a free1119substream is (usually) automatically chosen and opened. Meanwhile, when1120only one substream exists and it was already opened, a subsequent open1121will either block or error with ``EAGAIN`` according to the file open1122mode. But you don't have to care about such details in your driver. The1123PCM middle layer will take care of such work.1124 1125Full Code Example1126-----------------1127 1128The example code below does not include any hardware access routines but1129shows only the skeleton, how to build up the PCM interfaces::1130 1131 #include <sound/pcm.h>1132 ....1133 1134 /* hardware definition */1135 static struct snd_pcm_hardware snd_mychip_playback_hw = {1136 .info = (SNDRV_PCM_INFO_MMAP |1137 SNDRV_PCM_INFO_INTERLEAVED |1138 SNDRV_PCM_INFO_BLOCK_TRANSFER |1139 SNDRV_PCM_INFO_MMAP_VALID),1140 .formats = SNDRV_PCM_FMTBIT_S16_LE,1141 .rates = SNDRV_PCM_RATE_8000_48000,1142 .rate_min = 8000,1143 .rate_max = 48000,1144 .channels_min = 2,1145 .channels_max = 2,1146 .buffer_bytes_max = 32768,1147 .period_bytes_min = 4096,1148 .period_bytes_max = 32768,1149 .periods_min = 1,1150 .periods_max = 1024,1151 };1152 1153 /* hardware definition */1154 static struct snd_pcm_hardware snd_mychip_capture_hw = {1155 .info = (SNDRV_PCM_INFO_MMAP |1156 SNDRV_PCM_INFO_INTERLEAVED |1157 SNDRV_PCM_INFO_BLOCK_TRANSFER |1158 SNDRV_PCM_INFO_MMAP_VALID),1159 .formats = SNDRV_PCM_FMTBIT_S16_LE,1160 .rates = SNDRV_PCM_RATE_8000_48000,1161 .rate_min = 8000,1162 .rate_max = 48000,1163 .channels_min = 2,1164 .channels_max = 2,1165 .buffer_bytes_max = 32768,1166 .period_bytes_min = 4096,1167 .period_bytes_max = 32768,1168 .periods_min = 1,1169 .periods_max = 1024,1170 };1171 1172 /* open callback */1173 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)1174 {1175 struct mychip *chip = snd_pcm_substream_chip(substream);1176 struct snd_pcm_runtime *runtime = substream->runtime;1177 1178 runtime->hw = snd_mychip_playback_hw;1179 /* more hardware-initialization will be done here */1180 ....1181 return 0;1182 }1183 1184 /* close callback */1185 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)1186 {1187 struct mychip *chip = snd_pcm_substream_chip(substream);1188 /* the hardware-specific codes will be here */1189 ....1190 return 0;1191 1192 }1193 1194 /* open callback */1195 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)1196 {1197 struct mychip *chip = snd_pcm_substream_chip(substream);1198 struct snd_pcm_runtime *runtime = substream->runtime;1199 1200 runtime->hw = snd_mychip_capture_hw;1201 /* more hardware-initialization will be done here */1202 ....1203 return 0;1204 }1205 1206 /* close callback */1207 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)1208 {1209 struct mychip *chip = snd_pcm_substream_chip(substream);1210 /* the hardware-specific codes will be here */1211 ....1212 return 0;1213 }1214 1215 /* hw_params callback */1216 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,1217 struct snd_pcm_hw_params *hw_params)1218 {1219 /* the hardware-specific codes will be here */1220 ....1221 return 0;1222 }1223 1224 /* hw_free callback */1225 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)1226 {1227 /* the hardware-specific codes will be here */1228 ....1229 return 0;1230 }1231 1232 /* prepare callback */1233 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)1234 {1235 struct mychip *chip = snd_pcm_substream_chip(substream);1236 struct snd_pcm_runtime *runtime = substream->runtime;1237 1238 /* set up the hardware with the current configuration1239 * for example...1240 */1241 mychip_set_sample_format(chip, runtime->format);1242 mychip_set_sample_rate(chip, runtime->rate);1243 mychip_set_channels(chip, runtime->channels);1244 mychip_set_dma_setup(chip, runtime->dma_addr,1245 chip->buffer_size,1246 chip->period_size);1247 return 0;1248 }1249 1250 /* trigger callback */1251 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,1252 int cmd)1253 {1254 switch (cmd) {1255 case SNDRV_PCM_TRIGGER_START:1256 /* do something to start the PCM engine */1257 ....1258 break;1259 case SNDRV_PCM_TRIGGER_STOP:1260 /* do something to stop the PCM engine */1261 ....1262 break;1263 default:1264 return -EINVAL;1265 }1266 }1267 1268 /* pointer callback */1269 static snd_pcm_uframes_t1270 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)1271 {1272 struct mychip *chip = snd_pcm_substream_chip(substream);1273 unsigned int current_ptr;1274 1275 /* get the current hardware pointer */1276 current_ptr = mychip_get_hw_pointer(chip);1277 return current_ptr;1278 }1279 1280 /* operators */1281 static struct snd_pcm_ops snd_mychip_playback_ops = {1282 .open = snd_mychip_playback_open,1283 .close = snd_mychip_playback_close,1284 .hw_params = snd_mychip_pcm_hw_params,1285 .hw_free = snd_mychip_pcm_hw_free,1286 .prepare = snd_mychip_pcm_prepare,1287 .trigger = snd_mychip_pcm_trigger,1288 .pointer = snd_mychip_pcm_pointer,1289 };1290 1291 /* operators */1292 static struct snd_pcm_ops snd_mychip_capture_ops = {1293 .open = snd_mychip_capture_open,1294 .close = snd_mychip_capture_close,1295 .hw_params = snd_mychip_pcm_hw_params,1296 .hw_free = snd_mychip_pcm_hw_free,1297 .prepare = snd_mychip_pcm_prepare,1298 .trigger = snd_mychip_pcm_trigger,1299 .pointer = snd_mychip_pcm_pointer,1300 };1301 1302 /*1303 * definitions of capture are omitted here...1304 */1305 1306 /* create a pcm device */1307 static int snd_mychip_new_pcm(struct mychip *chip)1308 {1309 struct snd_pcm *pcm;1310 int err;1311 1312 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);1313 if (err < 0)1314 return err;1315 pcm->private_data = chip;1316 strcpy(pcm->name, "My Chip");1317 chip->pcm = pcm;1318 /* set operators */1319 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,1320 &snd_mychip_playback_ops);1321 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,1322 &snd_mychip_capture_ops);1323 /* pre-allocation of buffers */1324 /* NOTE: this may fail */1325 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,1326 &chip->pci->dev,1327 64*1024, 64*1024);1328 return 0;1329 }1330 1331 1332PCM Constructor1333---------------1334 1335A PCM instance is allocated by the :c:func:`snd_pcm_new()`1336function. It would be better to create a constructor for the PCM, namely::1337 1338 static int snd_mychip_new_pcm(struct mychip *chip)1339 {1340 struct snd_pcm *pcm;1341 int err;1342 1343 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);1344 if (err < 0) 1345 return err;1346 pcm->private_data = chip;1347 strcpy(pcm->name, "My Chip");1348 chip->pcm = pcm;1349 ...1350 return 0;1351 }1352 1353The :c:func:`snd_pcm_new()` function takes six arguments. The1354first argument is the card pointer to which this PCM is assigned, and1355the second is the ID string.1356 1357The third argument (``index``, 0 in the above) is the index of this new1358PCM. It begins from zero. If you create more than one PCM instances,1359specify the different numbers in this argument. For example, ``index =13601`` for the second PCM device.1361 1362The fourth and fifth arguments are the number of substreams for playback1363and capture, respectively. Here 1 is used for both arguments. When no1364playback or capture substreams are available, pass 0 to the1365corresponding argument.1366 1367If a chip supports multiple playbacks or captures, you can specify more1368numbers, but they must be handled properly in open/close, etc.1369callbacks. When you need to know which substream you are referring to,1370then it can be obtained from struct snd_pcm_substream data passed to each1371callback as follows::1372 1373 struct snd_pcm_substream *substream;1374 int index = substream->number;1375 1376 1377After the PCM is created, you need to set operators for each PCM stream::1378 1379 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,1380 &snd_mychip_playback_ops);1381 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,1382 &snd_mychip_capture_ops);1383 1384The operators are defined typically like this::1385 1386 static struct snd_pcm_ops snd_mychip_playback_ops = {1387 .open = snd_mychip_pcm_open,1388 .close = snd_mychip_pcm_close,1389 .hw_params = snd_mychip_pcm_hw_params,1390 .hw_free = snd_mychip_pcm_hw_free,1391 .prepare = snd_mychip_pcm_prepare,1392 .trigger = snd_mychip_pcm_trigger,1393 .pointer = snd_mychip_pcm_pointer,1394 };1395 1396All the callbacks are described in the Operators_ subsection.1397 1398After setting the operators, you probably will want to pre-allocate the1399buffer and set up the managed allocation mode.1400For that, simply call the following::1401 1402 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,1403 &chip->pci->dev,1404 64*1024, 64*1024);1405 1406It will allocate a buffer up to 64kB by default. Buffer management1407details will be described in the later section `Buffer and Memory1408Management`_.1409 1410Additionally, you can set some extra information for this PCM in1411``pcm->info_flags``. The available values are defined as1412``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the1413hardware definition (described later). When your soundchip supports only1414half-duplex, specify it like this::1415 1416 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;1417 1418 1419... And the Destructor?1420-----------------------1421 1422The destructor for a PCM instance is not always necessary. Since the PCM1423device will be released by the middle layer code automatically, you1424don't have to call the destructor explicitly.1425 1426The destructor would be necessary if you created special records1427internally and needed to release them. In such a case, set the1428destructor function to ``pcm->private_free``::1429 1430 static void mychip_pcm_free(struct snd_pcm *pcm)1431 {1432 struct mychip *chip = snd_pcm_chip(pcm);1433 /* free your own data */1434 kfree(chip->my_private_pcm_data);1435 /* do what you like else */1436 ....1437 }1438 1439 static int snd_mychip_new_pcm(struct mychip *chip)1440 {1441 struct snd_pcm *pcm;1442 ....1443 /* allocate your own data */1444 chip->my_private_pcm_data = kmalloc(...);1445 /* set the destructor */1446 pcm->private_data = chip;1447 pcm->private_free = mychip_pcm_free;1448 ....1449 }1450 1451 1452 1453Runtime Pointer - The Chest of PCM Information1454----------------------------------------------1455 1456When the PCM substream is opened, a PCM runtime instance is allocated1457and assigned to the substream. This pointer is accessible via1458``substream->runtime``. This runtime pointer holds most information you1459need to control the PCM: a copy of hw_params and sw_params1460configurations, the buffer pointers, mmap records, spinlocks, etc.1461 1462The definition of runtime instance is found in ``<sound/pcm.h>``. Here1463is the relevant part of this file::1464 1465 struct _snd_pcm_runtime {1466 /* -- Status -- */1467 struct snd_pcm_substream *trigger_master;1468 snd_timestamp_t trigger_tstamp; /* trigger timestamp */1469 int overrange;1470 snd_pcm_uframes_t avail_max;1471 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */1472 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/1473 1474 /* -- HW params -- */1475 snd_pcm_access_t access; /* access mode */1476 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */1477 snd_pcm_subformat_t subformat; /* subformat */1478 unsigned int rate; /* rate in Hz */1479 unsigned int channels; /* channels */1480 snd_pcm_uframes_t period_size; /* period size */1481 unsigned int periods; /* periods */1482 snd_pcm_uframes_t buffer_size; /* buffer size */1483 unsigned int tick_time; /* tick time */1484 snd_pcm_uframes_t min_align; /* Min alignment for the format */1485 size_t byte_align;1486 unsigned int frame_bits;1487 unsigned int sample_bits;1488 unsigned int info;1489 unsigned int rate_num;1490 unsigned int rate_den;1491 1492 /* -- SW params -- */1493 struct timespec tstamp_mode; /* mmap timestamp is updated */1494 unsigned int period_step;1495 unsigned int sleep_min; /* min ticks to sleep */1496 snd_pcm_uframes_t start_threshold;1497 /*1498 * The following two thresholds alleviate playback buffer underruns; when1499 * hw_avail drops below the threshold, the respective action is triggered:1500 */1501 snd_pcm_uframes_t stop_threshold; /* - stop playback */1502 snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */1503 snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary,1504 * fill played area with silence immediately */1505 snd_pcm_uframes_t boundary; /* pointers wrap point */1506 1507 /* internal data of auto-silencer */1508 snd_pcm_uframes_t silence_start; /* starting pointer to silence area */1509 snd_pcm_uframes_t silence_filled; /* size filled with silence */1510 1511 snd_pcm_sync_id_t sync; /* hardware synchronization ID */1512 1513 /* -- mmap -- */1514 volatile struct snd_pcm_mmap_status *status;1515 volatile struct snd_pcm_mmap_control *control;1516 atomic_t mmap_count;1517 1518 /* -- locking / scheduling -- */1519 spinlock_t lock;1520 wait_queue_head_t sleep;1521 struct timer_list tick_timer;1522 struct fasync_struct *fasync;1523 1524 /* -- private section -- */1525 void *private_data;1526 void (*private_free)(struct snd_pcm_runtime *runtime);1527 1528 /* -- hardware description -- */1529 struct snd_pcm_hardware hw;1530 struct snd_pcm_hw_constraints hw_constraints;1531 1532 /* -- timer -- */1533 unsigned int timer_resolution; /* timer resolution */1534 1535 /* -- DMA -- */ 1536 unsigned char *dma_area; /* DMA area */1537 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */1538 size_t dma_bytes; /* size of DMA area */1539 1540 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */1541 1542 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)1543 /* -- OSS things -- */1544 struct snd_pcm_oss_runtime oss;1545 #endif1546 };1547 1548 1549For the operators (callbacks) of each sound driver, most of these1550records are supposed to be read-only. Only the PCM middle-layer changes1551/ updates them. The exceptions are the hardware description (hw) DMA1552buffer information and the private data. Besides, if you use the1553standard managed buffer allocation mode, you don't need to set the1554DMA buffer information by yourself.1555 1556In the sections below, important records are explained.1557 1558Hardware Description1559~~~~~~~~~~~~~~~~~~~~1560 1561The hardware descriptor (struct snd_pcm_hardware) contains the definitions of1562the fundamental hardware configuration. Above all, you'll need to define this1563in the `PCM open callback`_. Note that the runtime instance holds a copy of1564the descriptor, not a pointer to the existing descriptor. That is,1565in the open callback, you can modify the copied descriptor1566(``runtime->hw``) as you need. For example, if the maximum number of1567channels is 1 only on some chip models, you can still use the same1568hardware descriptor and change the channels_max later::1569 1570 struct snd_pcm_runtime *runtime = substream->runtime;1571 ...1572 runtime->hw = snd_mychip_playback_hw; /* common definition */1573 if (chip->model == VERY_OLD_ONE)1574 runtime->hw.channels_max = 1;1575 1576Typically, you'll have a hardware descriptor as below::1577 1578 static struct snd_pcm_hardware snd_mychip_playback_hw = {1579 .info = (SNDRV_PCM_INFO_MMAP |1580 SNDRV_PCM_INFO_INTERLEAVED |1581 SNDRV_PCM_INFO_BLOCK_TRANSFER |1582 SNDRV_PCM_INFO_MMAP_VALID),1583 .formats = SNDRV_PCM_FMTBIT_S16_LE,1584 .rates = SNDRV_PCM_RATE_8000_48000,1585 .rate_min = 8000,1586 .rate_max = 48000,1587 .channels_min = 2,1588 .channels_max = 2,1589 .buffer_bytes_max = 32768,1590 .period_bytes_min = 4096,1591 .period_bytes_max = 32768,1592 .periods_min = 1,1593 .periods_max = 1024,1594 };1595 1596- The ``info`` field contains the type and capabilities of this1597 PCM. The bit flags are defined in ``<sound/asound.h>`` as1598 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether1599 mmap is supported and which interleaving formats are1600 supported. When the hardware supports mmap, add the1601 ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the1602 interleaved or the non-interleaved formats, the1603 ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``1604 flag must be set, respectively. If both are supported, you can set1605 both, too.1606 1607 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are1608 specified for the OSS mmap mode. Usually both are set. Of course,1609 ``MMAP_VALID`` is set only if mmap is really supported.1610 1611 The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and1612 ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM1613 supports the “pause” operation, while the ``RESUME`` bit means that1614 the PCM supports the full “suspend/resume” operation. If the1615 ``PAUSE`` flag is set, the ``trigger`` callback below must handle1616 the corresponding (pause push/release) commands. The suspend/resume1617 trigger commands can be defined even without the ``RESUME``1618 flag. See the `Power Management`_ section for details.1619 1620 When the PCM substreams can be synchronized (typically,1621 synchronized start/stop of a playback and a capture stream), you1622 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll1623 need to check the linked-list of PCM substreams in the trigger1624 callback. This will be described in a later section.1625 1626- The ``formats`` field contains the bit-flags of supported formats1627 (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one1628 format, give all or'ed bits. In the example above, the signed 16bit1629 little-endian format is specified.1630 1631- The ``rates`` field contains the bit-flags of supported rates1632 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,1633 pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits1634 are provided only for typical rates. If your chip supports1635 unconventional rates, you need to add the ``KNOT`` bit and set up1636 the hardware constraint manually (explained later).1637 1638- ``rate_min`` and ``rate_max`` define the minimum and maximum sample1639 rate. This should correspond somehow to ``rates`` bits.1640 1641- ``channels_min`` and ``channels_max`` define, as you might have already1642 expected, the minimum and maximum number of channels.1643 1644- ``buffer_bytes_max`` defines the maximum buffer size in1645 bytes. There is no ``buffer_bytes_min`` field, since it can be1646 calculated from the minimum period size and the minimum number of1647 periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max``1648 define the minimum and maximum size of the period in bytes.1649 ``periods_max`` and ``periods_min`` define the maximum and minimum1650 number of periods in the buffer.1651 1652 The “period” is a term that corresponds to a fragment in the OSS1653 world. The period defines the point at which a PCM interrupt is1654 generated. This point strongly depends on the hardware. Generally,1655 a smaller period size will give you more interrupts, which results1656 in being able to fill/drain the buffer more timely. In the case of1657 capture, this size defines the input latency. On the other hand,1658 the whole buffer size defines the output latency for the playback1659 direction.1660 1661- There is also a field ``fifo_size``. This specifies the size of the1662 hardware FIFO, but currently it is neither used by the drivers nor1663 in the alsa-lib. So, you can ignore this field.1664 1665PCM Configurations1666~~~~~~~~~~~~~~~~~~1667 1668Ok, let's go back again to the PCM runtime records. The most1669frequently referred records in the runtime instance are the PCM1670configurations. The PCM configurations are stored in the runtime1671instance after the application sends ``hw_params`` data via1672alsa-lib. There are many fields copied from hw_params and sw_params1673structs. For example, ``format`` holds the format type chosen by the1674application. This field contains the enum value1675``SNDRV_PCM_FORMAT_XXX``.1676 1677One thing to be noted is that the configured buffer and period sizes1678are stored in “frames” in the runtime. In the ALSA world, ``1 frame =1679channels \* samples-size``. For conversion between frames and bytes,1680you can use the :c:func:`frames_to_bytes()` and1681:c:func:`bytes_to_frames()` helper functions::1682 1683 period_bytes = frames_to_bytes(runtime, runtime->period_size);1684 1685Also, many software parameters (sw_params) are stored in frames, too.1686Please check the type of the field. ``snd_pcm_uframes_t`` is for1687frames as unsigned integer while ``snd_pcm_sframes_t`` is for1688frames as signed integer.1689 1690DMA Buffer Information1691~~~~~~~~~~~~~~~~~~~~~~1692 1693The DMA buffer is defined by the following four fields: ``dma_area``,1694``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area``1695holds the buffer pointer (the logical address). You can call1696:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds1697the physical address of the buffer. This field is specified only when1698the buffer is a linear buffer. ``dma_bytes`` holds the size of the1699buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.1700 1701If you use either the managed buffer allocation mode or the standard1702API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,1703these fields are set by the ALSA middle layer, and you should *not*1704change them by yourself. You can read them but not write them. On the1705other hand, if you want to allocate the buffer by yourself, you'll1706need to manage it in the hw_params callback. At least, ``dma_bytes`` is1707mandatory. ``dma_area`` is necessary when the buffer is mmapped. If1708your driver doesn't support mmap, this field is not1709necessary. ``dma_addr`` is also optional. You can use dma_private as1710you like, too.1711 1712Running Status1713~~~~~~~~~~~~~~1714 1715The running status can be referred via ``runtime->status``. This is1716a pointer to a struct snd_pcm_mmap_status record.1717For example, you can get the current1718DMA hardware pointer via ``runtime->status->hw_ptr``.1719 1720The DMA application pointer can be referred via ``runtime->control``,1721which points to a struct snd_pcm_mmap_control record.1722However, accessing this value directly is not recommended.1723 1724Private Data1725~~~~~~~~~~~~1726 1727You can allocate a record for the substream and store it in1728``runtime->private_data``. Usually, this is done in the `PCM open1729callback`_. Don't mix this with ``pcm->private_data``. The1730``pcm->private_data`` usually points to the chip instance assigned1731statically at creation time of the PCM device, while1732``runtime->private_data``1733points to a dynamic data structure created in the PCM open1734callback::1735 1736 static int snd_xxx_open(struct snd_pcm_substream *substream)1737 {1738 struct my_pcm_data *data;1739 ....1740 data = kmalloc(sizeof(*data), GFP_KERNEL);1741 substream->runtime->private_data = data;1742 ....1743 }1744 1745 1746The allocated object must be released in the `close callback`_.1747 1748Operators1749---------1750 1751OK, now let me give details about each PCM callback (``ops``). In1752general, every callback must return 0 if successful, or a negative1753error number such as ``-EINVAL``. To choose an appropriate error1754number, it is advised to check what value other parts of the kernel1755return when the same kind of request fails.1756 1757Each callback function takes at least one argument containing a1758struct snd_pcm_substream pointer. To retrieve the chip1759record from the given substream instance, you can use the following1760macro::1761 1762 int xxx(...) {1763 struct mychip *chip = snd_pcm_substream_chip(substream);1764 ....1765 }1766 1767The macro reads ``substream->private_data``, which is a copy of1768``pcm->private_data``. You can override the former if you need to1769assign different data records per PCM substream. For example, the1770cmi8330 driver assigns different ``private_data`` for playback and1771capture directions, because it uses two different codecs (SB- and1772AD-compatible) for different directions.1773 1774PCM open callback1775~~~~~~~~~~~~~~~~~1776 1777::1778 1779 static int snd_xxx_open(struct snd_pcm_substream *substream);1780 1781This is called when a PCM substream is opened.1782 1783At least, here you have to initialize the ``runtime->hw``1784record. Typically, this is done like this::1785 1786 static int snd_xxx_open(struct snd_pcm_substream *substream)1787 {1788 struct mychip *chip = snd_pcm_substream_chip(substream);1789 struct snd_pcm_runtime *runtime = substream->runtime;1790 1791 runtime->hw = snd_mychip_playback_hw;1792 return 0;1793 }1794 1795where ``snd_mychip_playback_hw`` is the pre-defined hardware1796description.1797 1798You can allocate private data in this callback, as described in the1799`Private Data`_ section.1800 1801If the hardware configuration needs more constraints, set the hardware1802constraints here, too. See Constraints_ for more details.1803 1804close callback1805~~~~~~~~~~~~~~1806 1807::1808 1809 static int snd_xxx_close(struct snd_pcm_substream *substream);1810 1811 1812Obviously, this is called when a PCM substream is closed.1813 1814Any private instance for a PCM substream allocated in the ``open``1815callback will be released here::1816 1817 static int snd_xxx_close(struct snd_pcm_substream *substream)1818 {1819 ....1820 kfree(substream->runtime->private_data);1821 ....1822 }1823 1824ioctl callback1825~~~~~~~~~~~~~~1826 1827This is used for any special call to PCM ioctls. But usually you can1828leave it NULL, then the PCM core calls the generic ioctl callback1829function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a1830unique setup of channel info or reset procedure, you can pass your own1831callback function here.1832 1833hw_params callback1834~~~~~~~~~~~~~~~~~~~1835 1836::1837 1838 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,1839 struct snd_pcm_hw_params *hw_params);1840 1841This is called when the hardware parameters (``hw_params``) are set up1842by the application, that is, once when the buffer size, the period1843size, the format, etc. are defined for the PCM substream.1844 1845Many hardware setups should be done in this callback, including the1846allocation of buffers.1847 1848Parameters to be initialized are retrieved by the1849:c:func:`params_xxx()` macros.1850 1851When you choose managed buffer allocation mode for the substream,1852a buffer is already allocated before this callback gets1853called. Alternatively, you can call a helper function below for1854allocating the buffer::1855 1856 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));1857 1858:c:func:`snd_pcm_lib_malloc_pages()` is available only when the1859DMA buffers have been pre-allocated. See the section `Buffer Types`_1860for more details.1861 1862Note that this one and the ``prepare`` callback may be called multiple1863times per initialization. For example, the OSS emulation may call these1864callbacks at each change via its ioctl.1865 1866Thus, you need to be careful not to allocate the same buffers many1867times, which will lead to memory leaks! Calling the helper function1868above many times is OK. It will release the previous buffer1869automatically when it was already allocated.1870 1871Another note is that this callback is non-atomic (schedulable) by1872default, i.e. when no ``nonatomic`` flag set. This is important,1873because the ``trigger`` callback is atomic (non-schedulable). That is,1874mutexes or any schedule-related functions are not available in the1875``trigger`` callback. Please see the subsection Atomicity_ for1876details.1877 1878hw_free callback1879~~~~~~~~~~~~~~~~~1880 1881::1882 1883 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);1884 1885This is called to release the resources allocated via1886``hw_params``.1887 1888This function is always called before the close callback is called.1889Also, the callback may be called multiple times, too. Keep track1890whether each resource was already released.1891 1892When you have chosen managed buffer allocation mode for the PCM1893substream, the allocated PCM buffer will be automatically released1894after this callback gets called. Otherwise you'll have to release the1895buffer manually. Typically, when the buffer was allocated from the1896pre-allocated pool, you can use the standard API function1897:c:func:`snd_pcm_lib_malloc_pages()` like::1898 1899 snd_pcm_lib_free_pages(substream);1900 1901prepare callback1902~~~~~~~~~~~~~~~~1903 1904::1905 1906 static int snd_xxx_prepare(struct snd_pcm_substream *substream);1907 1908This callback is called when the PCM is “prepared”. You can set the1909format type, sample rate, etc. here. The difference from ``hw_params``1910is that the ``prepare`` callback will be called each time1911:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after1912underruns, etc.1913 1914Note that this callback is non-atomic. You can use1915schedule-related functions safely in this callback.1916 1917In this and the following callbacks, you can refer to the values via1918the runtime record, ``substream->runtime``. For example, to get the1919current rate, format or channels, access to ``runtime->rate``,1920``runtime->format`` or ``runtime->channels``, respectively. The1921physical address of the allocated buffer is set to1922``runtime->dma_area``. The buffer and period sizes are in1923``runtime->buffer_size`` and ``runtime->period_size``, respectively.1924 1925Be careful that this callback will be called many times at each setup,1926too.1927 1928trigger callback1929~~~~~~~~~~~~~~~~1930 1931::1932 1933 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);1934 1935This is called when the PCM is started, stopped or paused.1936 1937The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``1938defined in ``<sound/pcm.h>``. At least, the ``START``1939and ``STOP`` commands must be defined in this callback::1940 1941 switch (cmd) {1942 case SNDRV_PCM_TRIGGER_START:1943 /* do something to start the PCM engine */1944 break;1945 case SNDRV_PCM_TRIGGER_STOP:1946 /* do something to stop the PCM engine */1947 break;1948 default:1949 return -EINVAL;1950 }1951 1952When the PCM supports the pause operation (given in the info field of1953the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands1954must be handled here, too. The former is the command to pause the PCM,1955and the latter to restart the PCM again.1956 1957When the PCM supports the suspend/resume operation, regardless of full1958or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``1959commands must be handled, too. These commands are issued when the1960power-management status is changed. Obviously, the ``SUSPEND`` and1961``RESUME`` commands suspend and resume the PCM substream, and usually,1962they are identical to the ``STOP`` and ``START`` commands, respectively.1963See the `Power Management`_ section for details.1964 1965As mentioned, this callback is atomic by default unless the ``nonatomic``1966flag set, and you cannot call functions which may sleep. The1967``trigger`` callback should be as minimal as possible, just really1968triggering the DMA. The other stuff should be initialized in1969``hw_params`` and ``prepare`` callbacks properly beforehand.1970 1971sync_stop callback1972~~~~~~~~~~~~~~~~~~1973 1974::1975 1976 static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);1977 1978This callback is optional, and NULL can be passed. It's called after1979the PCM core stops the stream, before it changes the stream state via1980``prepare``, ``hw_params`` or ``hw_free``.1981Since the IRQ handler might be still pending, we need to wait until1982the pending task finishes before moving to the next step; otherwise it1983might lead to a crash due to resource conflicts or access to freed1984resources. A typical behavior is to call a synchronization function1985like :c:func:`synchronize_irq()` here.1986 1987For the majority of drivers that need only a call of1988:c:func:`synchronize_irq()`, there is a simpler setup, too.1989While keeping the ``sync_stop`` PCM callback NULL, the driver can set1990the ``card->sync_irq`` field to the returned interrupt number after1991requesting an IRQ, instead. Then PCM core will call1992:c:func:`synchronize_irq()` with the given IRQ appropriately.1993 1994If the IRQ handler is released by the card destructor, you don't need1995to clear ``card->sync_irq``, as the card itself is being released.1996So, usually you'll need to add just a single line for assigning1997``card->sync_irq`` in the driver code unless the driver re-acquires1998the IRQ. When the driver frees and re-acquires the IRQ dynamically1999(e.g. for suspend/resume), it needs to clear and re-set2000``card->sync_irq`` again appropriately.2001 2002pointer callback2003~~~~~~~~~~~~~~~~2004 2005::2006 2007 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)2008 2009This callback is called when the PCM middle layer inquires the current2010hardware position in the buffer. The position must be returned in2011frames, ranging from 0 to ``buffer_size - 1``. 2012 2013This is usually called from the buffer-update routine in the PCM2014middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`2015is called by the interrupt routine. Then the PCM middle layer updates2016the position and calculates the available space, and wakes up the2017sleeping poll threads, etc.2018 2019This callback is also atomic by default.2020 2021copy and fill_silence ops2022~~~~~~~~~~~~~~~~~~~~~~~~~2023 2024These callbacks are not mandatory, and can be omitted in most cases.2025These callbacks are used when the hardware buffer cannot be in the2026normal memory space. Some chips have their own buffer in the hardware2027which is not mappable. In such a case, you have to transfer the data2028manually from the memory buffer to the hardware buffer. Or, if the2029buffer is non-contiguous on both physical and virtual memory spaces,2030these callbacks must be defined, too.2031 2032If these two callbacks are defined, copy and set-silence operations2033are done by them. The details will be described in the later section2034`Buffer and Memory Management`_.2035 2036ack callback2037~~~~~~~~~~~~2038 2039This callback is also not mandatory. This callback is called when the2040``appl_ptr`` is updated in read or write operations. Some drivers like2041emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the2042internal buffer, and this callback is useful only for such a purpose.2043 2044The callback function may return 0 or a negative error. When the2045return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,2046and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.2047 2048This callback is atomic by default.2049 2050page callback2051~~~~~~~~~~~~~2052 2053This callback is optional too. The mmap calls this callback to get the2054page fault address.2055 2056You need no special callback for the standard SG-buffer or vmalloc-2057buffer. Hence this callback should be rarely used.2058 2059mmap callback2060~~~~~~~~~~~~~2061 2062This is another optional callback for controlling mmap behavior.2063When defined, the PCM core calls this callback when a page is2064memory-mapped, instead of using the standard helper.2065If you need special handling (due to some architecture or2066device-specific issues), implement everything here as you like.2067 2068 2069PCM Interrupt Handler2070---------------------2071 2072The remainder of the PCM stuff is the PCM interrupt handler. The role2073of the PCM2074interrupt handler in the sound driver is to update the buffer position2075and to tell the PCM middle layer when the buffer position goes across2076the specified period boundary. To inform about this, call the2077:c:func:`snd_pcm_period_elapsed()` function.2078 2079There are several ways sound chips can generate interrupts.2080 2081Interrupts at the period (fragment) boundary2082~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~2083 2084This is the most frequently found type: the hardware generates an2085interrupt at each period boundary. In this case, you can call2086:c:func:`snd_pcm_period_elapsed()` at each interrupt.2087 2088:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as2089its argument. Thus, you need to keep the substream pointer accessible2090from the chip instance. For example, define ``substream`` field in the2091chip record to hold the current running substream pointer, and set the2092pointer value at ``open`` callback (and reset at ``close`` callback).2093 2094If you acquire a spinlock in the interrupt handler, and the lock is used2095in other PCM callbacks, too, then you have to release the lock before2096calling :c:func:`snd_pcm_period_elapsed()`, because2097:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks2098inside.2099 2100Typical code would look like::2101 2102 2103 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)2104 {2105 struct mychip *chip = dev_id;2106 spin_lock(&chip->lock);2107 ....2108 if (pcm_irq_invoked(chip)) {2109 /* call updater, unlock before it */2110 spin_unlock(&chip->lock);2111 snd_pcm_period_elapsed(chip->substream);2112 spin_lock(&chip->lock);2113 /* acknowledge the interrupt if necessary */2114 }2115 ....2116 spin_unlock(&chip->lock);2117 return IRQ_HANDLED;2118 }2119 2120Also, when the device can detect a buffer underrun/overrun, the driver2121can notify the XRUN status to the PCM core by calling2122:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets2123the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called2124outside the PCM stream lock, hence it can't be called from the atomic2125callback.2126 2127 2128High frequency timer interrupts2129~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~2130 2131This happens when the hardware doesn't generate interrupts at the period2132boundary but issues timer interrupts at a fixed timer rate (e.g. es19682133or ymfpci drivers). In this case, you need to check the current hardware2134position and accumulate the processed sample length at each interrupt.2135When the accumulated size exceeds the period size, call2136:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.2137 2138Typical code would look as follows::2139 2140 2141 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)2142 {2143 struct mychip *chip = dev_id;2144 spin_lock(&chip->lock);2145 ....2146 if (pcm_irq_invoked(chip)) {2147 unsigned int last_ptr, size;2148 /* get the current hardware pointer (in frames) */2149 last_ptr = get_hw_ptr(chip);2150 /* calculate the processed frames since the2151 * last update2152 */2153 if (last_ptr < chip->last_ptr)2154 size = runtime->buffer_size + last_ptr2155 - chip->last_ptr;2156 else2157 size = last_ptr - chip->last_ptr;2158 /* remember the last updated point */2159 chip->last_ptr = last_ptr;2160 /* accumulate the size */2161 chip->size += size;2162 /* over the period boundary? */2163 if (chip->size >= runtime->period_size) {2164 /* reset the accumulator */2165 chip->size %= runtime->period_size;2166 /* call updater */2167 spin_unlock(&chip->lock);2168 snd_pcm_period_elapsed(substream);2169 spin_lock(&chip->lock);2170 }2171 /* acknowledge the interrupt if necessary */2172 }2173 ....2174 spin_unlock(&chip->lock);2175 return IRQ_HANDLED;2176 }2177 2178 2179 2180On calling :c:func:`snd_pcm_period_elapsed()`2181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~2182 2183In both cases, even if more than one period has elapsed, you don't have2184to call :c:func:`snd_pcm_period_elapsed()` many times. Call only2185once. And the PCM layer will check the current hardware pointer and2186update to the latest status.2187 2188Atomicity2189---------2190 2191One of the most important (and thus difficult to debug) problems in2192kernel programming are race conditions. In the Linux kernel, they are2193usually avoided via spin-locks, mutexes or semaphores. In general, if a2194race condition can happen in an interrupt handler, it has to be managed2195atomically, and you have to use a spinlock to protect the critical2196section. If the critical section is not in interrupt handler code and if2197taking a relatively long time to execute is acceptable, you should use2198mutexes or semaphores instead.2199 2200As already seen, some PCM callbacks are atomic and some are not. For2201example, the ``hw_params`` callback is non-atomic, while the ``trigger``2202callback is atomic. This means, the latter is called already in a2203spinlock held by the PCM middle layer, the PCM stream lock. Please2204take this atomicity into account when you choose a locking scheme in2205the callbacks.2206 2207In the atomic callbacks, you cannot use functions which may call2208:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and2209mutexes can sleep, and hence they cannot be used inside the atomic2210callbacks (e.g. ``trigger`` callback). To implement some delay in such a2211callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.2212 2213All three atomic callbacks (trigger, pointer, and ack) are called with2214local interrupts disabled.2215 2216However, it is possible to request all PCM operations to be non-atomic.2217This assumes that all call sites are in2218non-atomic contexts. For example, the function2219:c:func:`snd_pcm_period_elapsed()` is called typically from the2220interrupt handler. But, if you set up the driver to use a threaded2221interrupt handler, this call can be in non-atomic context, too. In such2222a case, you can set the ``nonatomic`` field of the struct snd_pcm object2223after creating it. When this flag is set, mutex and rwsem are used internally2224in the PCM core instead of spin and rwlocks, so that you can call all PCM2225functions safely in a non-atomic2226context.2227 2228Also, in some cases, you might need to call2229:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the2230period gets elapsed during ``ack`` or other callback). There is a2231variant that can be called inside the PCM stream lock2232:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,2233too.2234 2235Constraints2236-----------2237 2238Due to physical limitations, hardware is not infinitely configurable.2239These limitations are expressed by setting constraints.2240 2241For example, in order to restrict the sample rates to some supported2242values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to2243call this function in the open callback::2244 2245 static unsigned int rates[] =2246 {4000, 10000, 22050, 44100};2247 static struct snd_pcm_hw_constraint_list constraints_rates = {2248 .count = ARRAY_SIZE(rates),2249 .list = rates,2250 .mask = 0,2251 };2252 2253 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)2254 {2255 int err;2256 ....2257 err = snd_pcm_hw_constraint_list(substream->runtime, 0,2258 SNDRV_PCM_HW_PARAM_RATE,2259 &constraints_rates);2260 if (err < 0)2261 return err;2262 ....2263 }2264 2265There are many different constraints. Look at ``sound/pcm.h`` for a2266complete list. You can even define your own constraint rules. For2267example, let's suppose my_chip can manage a substream of 1 channel if2268and only if the format is ``S16_LE``, otherwise it supports any format2269specified in struct snd_pcm_hardware (or in any other2270constraint_list). You can build a rule like this::2271 2272 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,2273 struct snd_pcm_hw_rule *rule)2274 {2275 struct snd_interval *c = hw_param_interval(params,2276 SNDRV_PCM_HW_PARAM_CHANNELS);2277 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);2278 struct snd_interval ch;2279 2280 snd_interval_any(&ch);2281 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {2282 ch.min = ch.max = 1;2283 ch.integer = 1;2284 return snd_interval_refine(c, &ch);2285 }2286 return 0;2287 }2288 2289 2290Then you need to call this function to add your rule::2291 2292 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,2293 hw_rule_channels_by_format, NULL,2294 SNDRV_PCM_HW_PARAM_FORMAT, -1);2295 2296The rule function is called when an application sets the PCM format, and2297it refines the number of channels accordingly. But an application may2298set the number of channels before setting the format. Thus you also need2299to define the inverse rule::2300 2301 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,2302 struct snd_pcm_hw_rule *rule)2303 {2304 struct snd_interval *c = hw_param_interval(params,2305 SNDRV_PCM_HW_PARAM_CHANNELS);2306 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);2307 struct snd_mask fmt;2308 2309 snd_mask_any(&fmt); /* Init the struct */2310 if (c->min < 2) {2311 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;2312 return snd_mask_refine(f, &fmt);2313 }2314 return 0;2315 }2316 2317 2318... and in the open callback::2319 2320 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,2321 hw_rule_format_by_channels, NULL,2322 SNDRV_PCM_HW_PARAM_CHANNELS, -1);2323 2324One typical usage of the hw constraints is to align the buffer size2325with the period size. By default, ALSA PCM core doesn't enforce the2326buffer size to be aligned with the period size. For example, it'd be2327possible to have a combination like 256 period bytes with 999 buffer2328bytes.2329 2330Many device chips, however, require the buffer to be a multiple of2331periods. In such a case, call2332:c:func:`snd_pcm_hw_constraint_integer()` for2333``SNDRV_PCM_HW_PARAM_PERIODS``::2334 2335 snd_pcm_hw_constraint_integer(substream->runtime,2336 SNDRV_PCM_HW_PARAM_PERIODS);2337 2338This assures that the number of periods is integer, hence the buffer2339size is aligned with the period size.2340 2341The hw constraint is a very powerful mechanism to define the2342preferred PCM configuration, and there are relevant helpers.2343I won't give more details here, rather I would like to say, “Luke, use2344the source.”2345 2346Control Interface2347=================2348 2349General2350-------2351 2352The control interface is used widely for many switches, sliders, etc.2353which are accessed from user-space. Its most important use is the mixer2354interface. In other words, since ALSA 0.9.x, all the mixer stuff is2355implemented on the control kernel API.2356 2357ALSA has a well-defined AC97 control module. If your chip supports only2358the AC97 and nothing else, you can skip this section.2359 2360The control API is defined in ``<sound/control.h>``. Include this file2361if you want to add your own controls.2362 2363Definition of Controls2364----------------------2365 2366To create a new control, you need to define the following three2367callbacks: ``info``, ``get`` and ``put``. Then, define a2368struct snd_kcontrol_new record, such as::2369 2370 2371 static struct snd_kcontrol_new my_control = {2372 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,2373 .name = "PCM Playback Switch",2374 .index = 0,2375 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,2376 .private_value = 0xffff,2377 .info = my_control_info,2378 .get = my_control_get,2379 .put = my_control_put2380 };2381 2382 2383The ``iface`` field specifies the control type,2384``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``2385for global controls that are not logically part of the mixer. If the2386control is closely associated with some specific device on the sound2387card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,2388and specify the device number with the ``device`` and ``subdevice``2389fields.2390 2391The ``name`` is the name identifier string. Since ALSA 0.9.x, the2392control name is very important, because its role is classified from2393its name. There are pre-defined standard control names. The details2394are described in the `Control Names`_ subsection.2395 2396The ``index`` field holds the index number of this control. If there2397are several different controls with the same name, they can be2398distinguished by the index number. This is the case when several2399codecs exist on the card. If the index is zero, you can omit the2400definition above. 2401 2402The ``access`` field contains the access type of this control. Give2403the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,2404there. The details will be explained in the `Access Flags`_2405subsection.2406 2407The ``private_value`` field contains an arbitrary long integer value2408for this record. When using the generic ``info``, ``get`` and ``put``2409callbacks, you can pass a value through this field. If several small2410numbers are necessary, you can combine them in bitwise. Or, it's2411possible to store a pointer (casted to unsigned long) of some record in2412this field, too. 2413 2414The ``tlv`` field can be used to provide metadata about the control;2415see the `Metadata`_ subsection.2416 2417The other three are `Control Callbacks`_.2418 2419Control Names2420-------------2421 2422There are some standards to define the control names. A control is2423usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.2424 2425The first, ``SOURCE``, specifies the source of the control, and is a2426string such as “Master”, “PCM”, “CD” and “Line”. There are many2427pre-defined sources.2428 2429The second, ``DIRECTION``, is one of the following strings according to2430the direction of the control: “Playback”, “Capture”, “Bypass Playback”2431and “Bypass Capture”. Or, it can be omitted, meaning both playback and2432capture directions.2433 2434The third, ``FUNCTION``, is one of the following strings according to2435the function of the control: “Switch”, “Volume” and “Route”.2436 2437The example of control names are, thus, “Master Capture Switch” or “PCM2438Playback Volume”.2439 2440There are some exceptions:2441 2442Global capture and playback2443~~~~~~~~~~~~~~~~~~~~~~~~~~~2444 2445“Capture Source”, “Capture Switch” and “Capture Volume” are used for the2446global capture (input) source, switch and volume. Similarly, “Playback2447Switch” and “Playback Volume” are used for the global output gain switch2448and volume.2449 2450Tone-controls2451~~~~~~~~~~~~~2452 2453tone-control switch and volumes are specified like “Tone Control - XXX”,2454e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -2455Center”.2456 24573D controls2458~~~~~~~~~~~2459 24603D-control switches and volumes are specified like “3D Control - XXX”,2461e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.2462 2463Mic boost2464~~~~~~~~~2465 2466Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.2467 2468More precise information can be found in2469``Documentation/sound/designs/control-names.rst``.2470 2471Access Flags2472------------2473 2474The access flag is the bitmask which specifies the access type of the2475given control. The default access type is2476``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are2477allowed to this control. When the access flag is omitted (i.e. = 0), it2478is considered as ``READWRITE`` access by default.2479 2480When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``2481instead. In this case, you don't have to define the ``put`` callback.2482Similarly, when the control is write-only (although it's a rare case),2483you can use the ``WRITE`` flag instead, and you don't need the ``get``2484callback.2485 2486If the control value changes frequently (e.g. the VU meter),2487``VOLATILE`` flag should be given. This means that the control may be2488changed without `Change notification`_. Applications should poll such2489a control constantly.2490 2491When the control may be updated, but currently has no effect on anything,2492setting the ``INACTIVE`` flag may be appropriate. For example, PCM2493controls should be inactive while no PCM device is open.2494 2495There are ``LOCK`` and ``OWNER`` flags to change the write permissions.2496 2497Control Callbacks2498-----------------2499 2500info callback2501~~~~~~~~~~~~~2502 2503The ``info`` callback is used to get detailed information on this2504control. This must store the values of the given2505struct snd_ctl_elem_info object. For example,2506for a boolean control with a single element::2507 2508 2509 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,2510 struct snd_ctl_elem_info *uinfo)2511 {2512 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;2513 uinfo->count = 1;2514 uinfo->value.integer.min = 0;2515 uinfo->value.integer.max = 1;2516 return 0;2517 }2518 2519 2520 2521The ``type`` field specifies the type of the control. There are2522``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and2523``INTEGER64``. The ``count`` field specifies the number of elements in2524this control. For example, a stereo volume would have count = 2. The2525``value`` field is a union, and the values stored depend on the2526type. The boolean and integer types are identical.2527 2528The enumerated type is a bit different from the others. You'll need to2529set the string for the selectec item index::2530 2531 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,2532 struct snd_ctl_elem_info *uinfo)2533 {2534 static char *texts[4] = {2535 "First", "Second", "Third", "Fourth"2536 };2537 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;2538 uinfo->count = 1;2539 uinfo->value.enumerated.items = 4;2540 if (uinfo->value.enumerated.item > 3)2541 uinfo->value.enumerated.item = 3;2542 strcpy(uinfo->value.enumerated.name,2543 texts[uinfo->value.enumerated.item]);2544 return 0;2545 }2546 2547The above callback can be simplified with a helper function,2548:c:func:`snd_ctl_enum_info()`. The final code looks like below.2549(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;2550it's a matter of taste.)2551 2552::2553 2554 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,2555 struct snd_ctl_elem_info *uinfo)2556 {2557 static char *texts[4] = {2558 "First", "Second", "Third", "Fourth"2559 };2560 return snd_ctl_enum_info(uinfo, 1, 4, texts);2561 }2562 2563 2564Some common info callbacks are available for your convenience:2565:c:func:`snd_ctl_boolean_mono_info()` and2566:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former2567is an info callback for a mono channel boolean item, just like2568:c:func:`snd_myctl_mono_info()` above, and the latter is for a2569stereo channel boolean item.2570 2571get callback2572~~~~~~~~~~~~2573 2574This callback is used to read the current value of the control, so it2575can be returned to user-space.2576 2577For example::2578 2579 static int snd_myctl_get(struct snd_kcontrol *kcontrol,2580 struct snd_ctl_elem_value *ucontrol)2581 {2582 struct mychip *chip = snd_kcontrol_chip(kcontrol);2583 ucontrol->value.integer.value[0] = get_some_value(chip);2584 return 0;2585 }2586 2587 2588 2589The ``value`` field depends on the type of control as well as on the2590info callback. For example, the sb driver uses this field to store the2591register offset, the bit-shift and the bit-mask. The ``private_value``2592field is set as follows::2593 2594 .private_value = reg | (shift << 16) | (mask << 24)2595 2596and is retrieved in callbacks like::2597 2598 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,2599 struct snd_ctl_elem_value *ucontrol)2600 {2601 int reg = kcontrol->private_value & 0xff;2602 int shift = (kcontrol->private_value >> 16) & 0xff;2603 int mask = (kcontrol->private_value >> 24) & 0xff;2604 ....2605 }2606 2607In the ``get`` callback, you have to fill all the elements if the2608control has more than one element, i.e. ``count > 1``. In the example2609above, we filled only one element (``value.integer.value[0]``) since2610``count = 1`` is assumed.2611 2612put callback2613~~~~~~~~~~~~2614 2615This callback is used to write a value coming from user-space.2616 2617For example::2618 2619 static int snd_myctl_put(struct snd_kcontrol *kcontrol,2620 struct snd_ctl_elem_value *ucontrol)2621 {2622 struct mychip *chip = snd_kcontrol_chip(kcontrol);2623 int changed = 0;2624 if (chip->current_value !=2625 ucontrol->value.integer.value[0]) {2626 change_current_value(chip,2627 ucontrol->value.integer.value[0]);2628 changed = 1;2629 }2630 return changed;2631 }2632 2633 2634 2635As seen above, you have to return 1 if the value is changed. If the2636value is not changed, return 0 instead. If any fatal error happens,2637return a negative error code as usual.2638 2639As in the ``get`` callback, when the control has more than one2640element, all elements must be evaluated in this callback, too.2641 2642Callbacks are not atomic2643~~~~~~~~~~~~~~~~~~~~~~~~2644 2645All these three callbacks are not-atomic.2646 2647Control Constructor2648-------------------2649 2650When everything is ready, finally we can create a new control. To create2651a control, there are two functions to be called,2652:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.2653 2654In the simplest way, you can do it like this::2655 2656 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));2657 if (err < 0)2658 return err;2659 2660where ``my_control`` is the struct snd_kcontrol_new object defined above,2661and chip is the object pointer to be passed to kcontrol->private_data which2662can be referred to in callbacks.2663 2664:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and2665:c:func:`snd_ctl_add()` assigns the given control component to the2666card.2667 2668Change Notification2669-------------------2670 2671If you need to change and update a control in the interrupt routine, you2672can call :c:func:`snd_ctl_notify()`. For example::2673 2674 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);2675 2676This function takes the card pointer, the event-mask, and the control id2677pointer for the notification. The event-mask specifies the types of2678notification, for example, in the above example, the change of control2679values is notified. The id pointer is the pointer of struct snd_ctl_elem_id2680to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``2681for hardware volume interrupts.2682 2683Metadata2684--------2685 2686To provide information about the dB values of a mixer control, use one of2687the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a2688variable containing this information, set the ``tlv.p`` field to point to2689this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag2690in the ``access`` field; like this::2691 2692 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);2693 2694 static struct snd_kcontrol_new my_control = {2695 ...2696 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |2697 SNDRV_CTL_ELEM_ACCESS_TLV_READ,2698 ...2699 .tlv.p = db_scale_my_control,2700 };2701 2702 2703The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information2704about a mixer control where each step in the control's value changes the2705dB value by a constant dB amount. The first parameter is the name of the2706variable to be defined. The second parameter is the minimum value, in2707units of 0.01 dB. The third parameter is the step size, in units of 0.012708dB. Set the fourth parameter to 1 if the minimum value actually mutes2709the control.2710 2711The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information2712about a mixer control where the control's value affects the output2713linearly. The first parameter is the name of the variable to be defined.2714The second parameter is the minimum value, in units of 0.01 dB. The2715third parameter is the maximum value, in units of 0.01 dB. If the2716minimum value mutes the control, set the second parameter to2717``TLV_DB_GAIN_MUTE``.2718 2719API for AC97 Codec2720==================2721 2722General2723-------2724 2725The ALSA AC97 codec layer is a well-defined one, and you don't have to2726write much code to control it. Only low-level control routines are2727necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.2728 2729Full Code Example2730-----------------2731 2732::2733 2734 struct mychip {2735 ....2736 struct snd_ac97 *ac97;2737 ....2738 };2739 2740 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,2741 unsigned short reg)2742 {2743 struct mychip *chip = ac97->private_data;2744 ....2745 /* read a register value here from the codec */2746 return the_register_value;2747 }2748 2749 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,2750 unsigned short reg, unsigned short val)2751 {2752 struct mychip *chip = ac97->private_data;2753 ....2754 /* write the given register value to the codec */2755 }2756 2757 static int snd_mychip_ac97(struct mychip *chip)2758 {2759 struct snd_ac97_bus *bus;2760 struct snd_ac97_template ac97;2761 int err;2762 static struct snd_ac97_bus_ops ops = {2763 .write = snd_mychip_ac97_write,2764 .read = snd_mychip_ac97_read,2765 };2766 2767 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);2768 if (err < 0)2769 return err;2770 memset(&ac97, 0, sizeof(ac97));2771 ac97.private_data = chip;2772 return snd_ac97_mixer(bus, &ac97, &chip->ac97);2773 }2774 2775 2776AC97 Constructor2777----------------2778 2779To create an ac97 instance, first call :c:func:`snd_ac97_bus()`2780with an ``ac97_bus_ops_t`` record with callback functions::2781 2782 struct snd_ac97_bus *bus;2783 static struct snd_ac97_bus_ops ops = {2784 .write = snd_mychip_ac97_write,2785 .read = snd_mychip_ac97_read,2786 };2787 2788 snd_ac97_bus(card, 0, &ops, NULL, &pbus);2789 2790The bus record is shared among all belonging ac97 instances.2791 2792And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template2793record together with the bus pointer created above::2794 2795 struct snd_ac97_template ac97;2796 int err;2797 2798 memset(&ac97, 0, sizeof(ac97));2799 ac97.private_data = chip;2800 snd_ac97_mixer(bus, &ac97, &chip->ac97);2801 2802where chip->ac97 is a pointer to a newly created ``ac97_t``2803instance. In this case, the chip pointer is set as the private data,2804so that the read/write callback functions can refer to this chip2805instance. This instance is not necessarily stored in the chip2806record. If you need to change the register values from the driver, or2807need the suspend/resume of ac97 codecs, keep this pointer to pass to2808the corresponding functions.2809 2810AC97 Callbacks2811--------------2812 2813The standard callbacks are ``read`` and ``write``. Obviously they2814correspond to the functions for read and write accesses to the2815hardware low-level codes.2816 2817The ``read`` callback returns the register value specified in the2818argument::2819 2820 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,2821 unsigned short reg)2822 {2823 struct mychip *chip = ac97->private_data;2824 ....2825 return the_register_value;2826 }2827 2828Here, the chip can be cast from ``ac97->private_data``.2829 2830Meanwhile, the ``write`` callback is used to set the register2831value::2832 2833 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,2834 unsigned short reg, unsigned short val)2835 2836 2837These callbacks are non-atomic like the control API callbacks.2838 2839There are also other callbacks: ``reset``, ``wait`` and ``init``.2840 2841The ``reset`` callback is used to reset the codec. If the chip2842requires a special kind of reset, you can define this callback.2843 2844The ``wait`` callback is used to add some waiting time in the standard2845initialization of the codec. If the chip requires the extra waiting2846time, define this callback.2847 2848The ``init`` callback is used for additional initialization of the2849codec.2850 2851Updating Registers in The Driver2852--------------------------------2853 2854If you need to access to the codec from the driver, you can call the2855following functions: :c:func:`snd_ac97_write()`,2856:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and2857:c:func:`snd_ac97_update_bits()`.2858 2859Both :c:func:`snd_ac97_write()` and2860:c:func:`snd_ac97_update()` functions are used to set a value to2861the given register (``AC97_XXX``). The difference between them is that2862:c:func:`snd_ac97_update()` doesn't write a value if the given2863value has been already set, while :c:func:`snd_ac97_write()`2864always rewrites the value::2865 2866 snd_ac97_write(ac97, AC97_MASTER, 0x8080);2867 snd_ac97_update(ac97, AC97_MASTER, 0x8080);2868 2869:c:func:`snd_ac97_read()` is used to read the value of the given2870register. For example::2871 2872 value = snd_ac97_read(ac97, AC97_MASTER);2873 2874:c:func:`snd_ac97_update_bits()` is used to update some bits in2875the given register::2876 2877 snd_ac97_update_bits(ac97, reg, mask, value);2878 2879Also, there is a function to change the sample rate (of a given register2880such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the2881codec: :c:func:`snd_ac97_set_rate()`::2882 2883 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);2884 2885 2886The following registers are available to set the rate:2887``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,2888``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is2889specified, the register is not really changed but the corresponding2890IEC958 status bits will be updated.2891 2892Clock Adjustment2893----------------2894 2895In some chips, the clock of the codec isn't 48000 but using a PCI clock2896(to save a quartz!). In this case, change the field ``bus->clock`` to2897the corresponding value. For example, intel8x0 and es1968 drivers have2898their own function to read from the clock.2899 2900Proc Files2901----------2902 2903The ALSA AC97 interface will create a proc file such as2904``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You2905can refer to these files to see the current status and registers of2906the codec.2907 2908Multiple Codecs2909---------------2910 2911When there are several codecs on the same card, you need to call2912:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or2913greater. The ``num`` field specifies the codec number.2914 2915If you set up multiple codecs, you either need to write different2916callbacks for each codec or check ``ac97->num`` in the callback2917routines.2918 2919MIDI (MPU401-UART) Interface2920============================2921 2922General2923-------2924 2925Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the2926soundcard supports the standard MPU401-UART interface, most likely you2927can use the ALSA MPU401-UART API. The MPU401-UART API is defined in2928``<sound/mpu401.h>``.2929 2930Some soundchips have a similar but slightly different implementation of2931mpu401 stuff. For example, emu10k1 has its own mpu401 routines.2932 2933MIDI Constructor2934----------------2935 2936To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::2937 2938 struct snd_rawmidi *rmidi;2939 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,2940 irq, &rmidi);2941 2942 2943The first argument is the card pointer, and the second is the index of2944this component. You can create up to 8 rawmidi devices.2945 2946The third argument is the type of the hardware, ``MPU401_HW_XXX``. If2947it's not a special one, you can use ``MPU401_HW_MPU401``.2948 2949The 4th argument is the I/O port address. Many backward-compatible2950MPU401 have an I/O port such as 0x330. Or, it might be a part of its own2951PCI I/O region. It depends on the chip design.2952 2953The 5th argument is a bitflag for additional information. When the I/O2954port address above is part of the PCI I/O region, the MPU401 I/O port2955might have been already allocated (reserved) by the driver itself. In2956such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the2957mpu401-uart layer will allocate the I/O ports by itself.2958 2959When the controller supports only the input or output MIDI stream, pass2960the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,2961respectively. Then the rawmidi instance is created as a single stream.2962 2963``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO2964(via readb and writeb) instead of iob and outb. In this case, you have2965to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.2966 2967When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in2968the default interrupt handler. The driver needs to call2969:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start2970processing the output stream in the irq handler.2971 2972If the MPU-401 interface shares its interrupt with the other logical2973devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see2974`below <MIDI Interrupt Handler_>`__).2975 2976Usually, the port address corresponds to the command port and port + 12977corresponds to the data port. If not, you may change the ``cport``2978field of struct snd_mpu401 manually afterward.2979However, struct snd_mpu401 pointer is2980not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You2981need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::2982 2983 struct snd_mpu401 *mpu;2984 mpu = rmidi->private_data;2985 2986and reset the ``cport`` as you like::2987 2988 mpu->cport = my_own_control_port;2989 2990The 6th argument specifies the ISA irq number that will be allocated. If2991no interrupt is to be allocated (because your code is already allocating2992a shared interrupt, or because the device does not use interrupts), pass2993-1 instead. For a MPU-401 device without an interrupt, a polling timer2994will be used instead.2995 2996MIDI Interrupt Handler2997----------------------2998 2999When the interrupt is allocated in3000:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt3001handler is automatically used, hence you don't have anything else to do3002than creating the mpu401 stuff. Otherwise, you have to set3003``MPU401_INFO_IRQ_HOOK``, and call3004:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own3005interrupt handler when it has determined that a UART interrupt has3006occurred.3007 3008In this case, you need to pass the private_data of the returned rawmidi3009object from :c:func:`snd_mpu401_uart_new()` as the second3010argument of :c:func:`snd_mpu401_uart_interrupt()`::3011 3012 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);3013 3014 3015RawMIDI Interface3016=================3017 3018Overview3019--------3020 3021The raw MIDI interface is used for hardware MIDI ports that can be3022accessed as a byte stream. It is not used for synthesizer chips that do3023not directly understand MIDI.3024 3025ALSA handles file and buffer management. All you have to do is to write3026some code to move data between the buffer and the hardware.3027 3028The rawmidi API is defined in ``<sound/rawmidi.h>``.3029 3030RawMIDI Constructor3031-------------------3032 3033To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`3034function::3035 3036 struct snd_rawmidi *rmidi;3037 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);3038 if (err < 0)3039 return err;3040 rmidi->private_data = chip;3041 strcpy(rmidi->name, "My MIDI");3042 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |3043 SNDRV_RAWMIDI_INFO_INPUT |3044 SNDRV_RAWMIDI_INFO_DUPLEX;3045 3046The first argument is the card pointer, the second argument is the ID3047string.3048 3049The third argument is the index of this component. You can create up to30508 rawmidi devices.3051 3052The fourth and fifth arguments are the number of output and input3053substreams, respectively, of this device (a substream is the equivalent3054of a MIDI port).3055 3056Set the ``info_flags`` field to specify the capabilities of the3057device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one3058output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one3059input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle3060output and input at the same time.3061 3062After the rawmidi device is created, you need to set the operators3063(callbacks) for each substream. There are helper functions to set the3064operators for all the substreams of a device::3065 3066 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);3067 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);3068 3069The operators are usually defined like this::3070 3071 static struct snd_rawmidi_ops snd_mymidi_output_ops = {3072 .open = snd_mymidi_output_open,3073 .close = snd_mymidi_output_close,3074 .trigger = snd_mymidi_output_trigger,3075 };3076 3077These callbacks are explained in the `RawMIDI Callbacks`_ section.3078 3079If there are more than one substream, you should give a unique name to3080each of them::3081 3082 struct snd_rawmidi_substream *substream;3083 list_for_each_entry(substream,3084 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,3085 list {3086 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);3087 }3088 /* same for SNDRV_RAWMIDI_STREAM_INPUT */3089 3090RawMIDI Callbacks3091-----------------3092 3093In all the callbacks, the private data that you've set for the rawmidi3094device can be accessed as ``substream->rmidi->private_data``.3095 3096If there is more than one port, your callbacks can determine the port3097index from the struct snd_rawmidi_substream data passed to each3098callback::3099 3100 struct snd_rawmidi_substream *substream;3101 int index = substream->number;3102 3103RawMIDI open callback3104~~~~~~~~~~~~~~~~~~~~~3105 3106::3107 3108 static int snd_xxx_open(struct snd_rawmidi_substream *substream);3109 3110 3111This is called when a substream is opened. You can initialize the3112hardware here, but you shouldn't start transmitting/receiving data yet.3113 3114RawMIDI close callback3115~~~~~~~~~~~~~~~~~~~~~~3116 3117::3118 3119 static int snd_xxx_close(struct snd_rawmidi_substream *substream);3120 3121Guess what.3122 3123The ``open`` and ``close`` callbacks of a rawmidi device are3124serialized with a mutex, and can sleep.3125 3126Rawmidi trigger callback for output substreams3127~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3128 3129::3130 3131 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);3132 3133 3134This is called with a nonzero ``up`` parameter when there is some data3135in the substream buffer that must be transmitted.3136 3137To read data from the buffer, call3138:c:func:`snd_rawmidi_transmit_peek()`. It will return the number3139of bytes that have been read; this will be less than the number of bytes3140requested when there are no more data in the buffer. After the data have3141been transmitted successfully, call3142:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the3143substream buffer::3144 3145 unsigned char data;3146 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {3147 if (snd_mychip_try_to_transmit(data))3148 snd_rawmidi_transmit_ack(substream, 1);3149 else3150 break; /* hardware FIFO full */3151 }3152 3153If you know beforehand that the hardware will accept data, you can use3154the :c:func:`snd_rawmidi_transmit()` function which reads some3155data and removes them from the buffer at once::3156 3157 while (snd_mychip_transmit_possible()) {3158 unsigned char data;3159 if (snd_rawmidi_transmit(substream, &data, 1) != 1)3160 break; /* no more data */3161 snd_mychip_transmit(data);3162 }3163 3164If you know beforehand how many bytes you can accept, you can use a3165buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.3166 3167The ``trigger`` callback must not sleep. If the hardware FIFO is full3168before the substream buffer has been emptied, you have to continue3169transmitting data later, either in an interrupt handler, or with a3170timer if the hardware doesn't have a MIDI transmit interrupt.3171 3172The ``trigger`` callback is called with a zero ``up`` parameter when3173the transmission of data should be aborted.3174 3175RawMIDI trigger callback for input substreams3176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3177 3178::3179 3180 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);3181 3182 3183This is called with a nonzero ``up`` parameter to enable receiving data,3184or with a zero ``up`` parameter do disable receiving data.3185 3186The ``trigger`` callback must not sleep; the actual reading of data3187from the device is usually done in an interrupt handler.3188 3189When data reception is enabled, your interrupt handler should call3190:c:func:`snd_rawmidi_receive()` for all received data::3191 3192 void snd_mychip_midi_interrupt(...)3193 {3194 while (mychip_midi_available()) {3195 unsigned char data;3196 data = mychip_midi_read();3197 snd_rawmidi_receive(substream, &data, 1);3198 }3199 }3200 3201 3202drain callback3203~~~~~~~~~~~~~~3204 3205::3206 3207 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);3208 3209 3210This is only used with output substreams. This function should wait3211until all data read from the substream buffer have been transmitted.3212This ensures that the device can be closed and the driver unloaded3213without losing data.3214 3215This callback is optional. If you do not set ``drain`` in the struct3216snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds3217instead.3218 3219Miscellaneous Devices3220=====================3221 3222FM OPL33223-------3224 3225The FM OPL3 is still used in many chips (mainly for backward3226compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API3227is defined in ``<sound/opl3.h>``.3228 3229FM registers can be directly accessed through the direct-FM API, defined3230in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are3231accessed through the Hardware-Dependent Device direct-FM extension API,3232whereas in OSS compatible mode, FM registers can be accessed with the3233OSS direct-FM compatible API in ``/dev/dmfmX`` device.3234 3235To create the OPL3 component, you have two functions to call. The first3236one is a constructor for the ``opl3_t`` instance::3237 3238 struct snd_opl3 *opl3;3239 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,3240 integrated, &opl3);3241 3242The first argument is the card pointer, the second one is the left port3243address, and the third is the right port address. In most cases, the3244right port is placed at the left port + 2.3245 3246The fourth argument is the hardware type.3247 3248When the left and right ports have been already allocated by the card3249driver, pass non-zero to the fifth argument (``integrated``). Otherwise,3250the opl3 module will allocate the specified ports by itself.3251 3252When the accessing the hardware requires special method instead of the3253standard I/O access, you can create opl3 instance separately with3254:c:func:`snd_opl3_new()`::3255 3256 struct snd_opl3 *opl3;3257 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);3258 3259Then set ``command``, ``private_data`` and ``private_free`` for the3260private access function, the private data and the destructor. The3261``l_port`` and ``r_port`` are not necessarily set. Only the command3262must be set properly. You can retrieve the data from the3263``opl3->private_data`` field. 3264 3265After creating the opl3 instance via :c:func:`snd_opl3_new()`,3266call :c:func:`snd_opl3_init()` to initialize the chip to the3267proper state. Note that :c:func:`snd_opl3_create()` always calls3268it internally.3269 3270If the opl3 instance is created successfully, then create a hwdep device3271for this opl3::3272 3273 struct snd_hwdep *opl3hwdep;3274 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);3275 3276The first argument is the ``opl3_t`` instance you created, and the3277second is the index number, usually 0.3278 3279The third argument is the index-offset for the sequencer client assigned3280to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART3281always takes 0).3282 3283Hardware-Dependent Devices3284--------------------------3285 3286Some chips need user-space access for special controls or for loading3287the micro code. In such a case, you can create a hwdep3288(hardware-dependent) device. The hwdep API is defined in3289``<sound/hwdep.h>``. You can find examples in opl3 driver or3290``isa/sb/sb16_csp.c``.3291 3292The creation of the ``hwdep`` instance is done via3293:c:func:`snd_hwdep_new()`::3294 3295 struct snd_hwdep *hw;3296 snd_hwdep_new(card, "My HWDEP", 0, &hw);3297 3298where the third argument is the index number.3299 3300You can then pass any pointer value to the ``private_data``. If you3301assign private data, you should define a destructor, too. The3302destructor function is set in the ``private_free`` field::3303 3304 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);3305 hw->private_data = p;3306 hw->private_free = mydata_free;3307 3308and the implementation of the destructor would be::3309 3310 static void mydata_free(struct snd_hwdep *hw)3311 {3312 struct mydata *p = hw->private_data;3313 kfree(p);3314 }3315 3316The arbitrary file operations can be defined for this instance. The file3317operators are defined in the ``ops`` table. For example, assume that3318this chip needs an ioctl::3319 3320 hw->ops.open = mydata_open;3321 hw->ops.ioctl = mydata_ioctl;3322 hw->ops.release = mydata_release;3323 3324And implement the callback functions as you like.3325 3326IEC958 (S/PDIF)3327---------------3328 3329Usually the controls for IEC958 devices are implemented via the control3330interface. There is a macro to compose a name string for IEC9583331controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in3332``<include/asound.h>``.3333 3334There are some standard controls for IEC958 status bits. These controls3335use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is3336fixed as 4 bytes array (value.iec958.status[x]). For the ``info``3337callback, you don't specify the value field for this type (the count3338field must be set, though).3339 3340“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC9583341status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”3342returns the bitmask for professional mode. They are read-only controls.3343 3344Meanwhile, “IEC958 Playback Default” control is defined for getting and3345setting the current default IEC958 bits.3346 3347Due to historical reasons, both variants of the Playback Mask and the3348Playback Default controls can be implemented on either a3349``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.3350Drivers should expose the mask and default on the same iface though.3351 3352In addition, you can define the control switches to enable/disable or to3353set the raw bit mode. The implementation will depend on the chip, but3354the control should be named as “IEC958 xxx”, preferably using the3355:c:func:`SNDRV_CTL_NAME_IEC958()` macro.3356 3357You can find several cases, for example, ``pci/emu10k1``,3358``pci/ice1712``, or ``pci/cmipci.c``.3359 3360Buffer and Memory Management3361============================3362 3363Buffer Types3364------------3365 3366ALSA provides several different buffer allocation functions depending on3367the bus and the architecture. All these have a consistent API. The3368allocation of physically-contiguous pages is done via the3369:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus3370type.3371 3372The allocation of pages with fallback is done via3373:c:func:`snd_dma_alloc_pages_fallback()`. This function tries3374to allocate the specified number of pages, but if not enough pages are3375available, it tries to reduce the request size until enough space3376is found, down to one page.3377 3378To release the pages, call the :c:func:`snd_dma_free_pages()`3379function.3380 3381Usually, ALSA drivers try to allocate and reserve a large contiguous3382physical space at the time the module is loaded for later use. This3383is called “pre-allocation”. As already written, you can call the3384following function at PCM instance construction time (in the case of PCI3385bus)::3386 3387 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,3388 &pci->dev, size, max);3389 3390where ``size`` is the byte size to be pre-allocated and ``max`` is3391the maximum size settable via the ``prealloc`` proc file. The3392allocator will try to get an area as large as possible within the3393given size.3394 3395The second argument (type) and the third argument (device pointer) are3396dependent on the bus. For normal devices, pass the device pointer3397(typically identical as ``card->dev``) to the third argument with3398``SNDRV_DMA_TYPE_DEV`` type.3399 3400A continuous buffer unrelated to the3401bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.3402You can pass NULL to the device pointer in that case, which is the3403default mode implying to allocate with the ``GFP_KERNEL`` flag.3404If you need a restricted (lower) address, set up the coherent DMA mask3405bits for the device, and pass the device pointer, like the normal3406device memory allocations. For this type, it's still allowed to pass3407NULL to the device pointer, too, if no address restriction is needed.3408 3409For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the3410device pointer (see the `Non-Contiguous Buffers`_ section).3411 3412Once the buffer is pre-allocated, you can use the allocator in the3413``hw_params`` callback::3414 3415 snd_pcm_lib_malloc_pages(substream, size);3416 3417Note that you have to pre-allocate to use this function.3418 3419But most drivers use the "managed buffer allocation mode" instead3420of manual allocation and release.3421This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`3422instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`::3423 3424 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,3425 &pci->dev, size, max);3426 3427where the passed arguments are identical for both functions.3428The difference in the managed mode is that PCM core will call3429:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling3430the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`3431after the PCM ``hw_free`` callback automatically. So the driver3432doesn't have to call these functions explicitly in its callback any3433longer. This allows many drivers to have NULL ``hw_params`` and3434``hw_free`` entries.3435 3436External Hardware Buffers3437-------------------------3438 3439Some chips have their own hardware buffers and DMA transfer from the3440host memory is not available. In such a case, you need to either 1)3441copy/set the audio data directly to the external hardware buffer, or 2)3442make an intermediate buffer and copy/set the data from it to the3443external hardware buffer in interrupts (or in tasklets, preferably).3444 3445The first case works fine if the external hardware buffer is large3446enough. This method doesn't need any extra buffers and thus is more3447efficient. You need to define the ``copy`` callback3448for the data transfer, in addition to the ``fill_silence``3449callback for playback. However, there is a drawback: it cannot be3450mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.3451 3452The second case allows for mmap on the buffer, although you have to3453handle an interrupt or a tasklet to transfer the data from the3454intermediate buffer to the hardware buffer. You can find an example in3455the vxpocket driver.3456 3457Another case is when the chip uses a PCI memory-map region for the3458buffer instead of the host memory. In this case, mmap is available only3459on certain architectures like the Intel one. In non-mmap mode, the data3460cannot be transferred as in the normal way. Thus you need to define the3461``copy`` and ``fill_silence`` callbacks as well,3462as in the cases above. Examples are found in ``rme32.c`` and3463``rme96.c``.3464 3465The implementation of the ``copy`` and3466``silence`` callbacks depends upon whether the hardware supports3467interleaved or non-interleaved samples. The ``copy`` callback is3468defined like below, a bit differently depending on whether the direction3469is playback or capture::3470 3471 static int playback_copy(struct snd_pcm_substream *substream,3472 int channel, unsigned long pos,3473 struct iov_iter *src, unsigned long count);3474 static int capture_copy(struct snd_pcm_substream *substream,3475 int channel, unsigned long pos,3476 struct iov_iter *dst, unsigned long count);3477 3478In the case of interleaved samples, the second argument (``channel``) is3479not used. The third argument (``pos``) specifies the position in bytes.3480 3481The meaning of the fourth argument is different between playback and3482capture. For playback, it holds the source data pointer, and for3483capture, it's the destination data pointer.3484 3485The last argument is the number of bytes to be copied.3486 3487What you have to do in this callback is again different between playback3488and capture directions. In the playback case, you copy the given amount3489of data (``count``) at the specified pointer (``src``) to the specified3490offset (``pos``) in the hardware buffer. When coded like memcpy-like3491way, the copy would look like::3492 3493 my_memcpy_from_iter(my_buffer + pos, src, count);3494 3495For the capture direction, you copy the given amount of data (``count``)3496at the specified offset (``pos``) in the hardware buffer to the3497specified pointer (``dst``)::3498 3499 my_memcpy_to_iter(dst, my_buffer + pos, count);3500 3501The given ``src`` or ``dst`` a struct iov_iter pointer containing the3502pointer and the size. Use the existing helpers to copy or access the3503data as defined in ``linux/uio.h``.3504 3505Careful readers might notice that these callbacks receive the3506arguments in bytes, not in frames like other callbacks. It's because3507this makes coding easier like in the examples above, and also it makes3508it easier to unify both the interleaved and non-interleaved cases, as3509explained below.3510 3511In the case of non-interleaved samples, the implementation will be a bit3512more complicated. The callback is called for each channel, passed in3513the second argument, so in total it's called N times per transfer.3514 3515The meaning of the other arguments are almost the same as in the3516interleaved case. The callback is supposed to copy the data from/to3517the given user-space buffer, but only for the given channel. For3518details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c``3519as examples.3520 3521Usually for the playback, another callback ``fill_silence`` is3522defined. It's implemented in a similar way as the copy callbacks3523above::3524 3525 static int silence(struct snd_pcm_substream *substream, int channel,3526 unsigned long pos, unsigned long count);3527 3528The meanings of arguments are the same as in the ``copy`` callback,3529although there is no buffer pointer3530argument. In the case of interleaved samples, the channel argument has3531no meaning, as for the ``copy`` callback.3532 3533The role of the ``fill_silence`` callback is to set the given amount3534(``count``) of silence data at the specified offset (``pos``) in the3535hardware buffer. Suppose that the data format is signed (that is, the3536silent-data is 0), and the implementation using a memset-like function3537would look like::3538 3539 my_memset(my_buffer + pos, 0, count);3540 3541In the case of non-interleaved samples, again, the implementation3542becomes a bit more complicated, as it's called N times per transfer3543for each channel. See, for example, ``isa/gus/gus_pcm.c``.3544 3545Non-Contiguous Buffers3546----------------------3547 3548If your hardware supports a page table as in emu10k1 or buffer3549descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA3550provides an interface for handling SG-buffers. The API is provided in3551``<sound/pcm.h>``.3552 3553For creating the SG-buffer handler, call3554:c:func:`snd_pcm_set_managed_buffer()` or3555:c:func:`snd_pcm_set_managed_buffer_all()` with3556``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI3557pre-allocations. You need to pass ``&pci->dev``, where pci is3558the struct pci_dev pointer of the chip as well::3559 3560 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,3561 &pci->dev, size, max);3562 3563The ``struct snd_sg_buf`` instance is created as3564``substream->dma_private`` in turn. You can cast the pointer like::3565 3566 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;3567 3568Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer3569handler will allocate the non-contiguous kernel pages of the given size3570and map them as virtually contiguous memory. The virtual pointer3571is addressed via runtime->dma_area. The physical address3572(``runtime->dma_addr``) is set to zero, because the buffer is3573physically non-contiguous. The physical address table is set up in3574``sgbuf->table``. You can get the physical address at a certain offset3575via :c:func:`snd_pcm_sgbuf_get_addr()`.3576 3577If you need to release the SG-buffer data explicitly, call the3578standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.3579 3580Vmalloc'ed Buffers3581------------------3582 3583It's possible to use a buffer allocated via :c:func:`vmalloc()`, for3584example, for an intermediate buffer.3585You can simply allocate it via the standard3586:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the3587buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type::3588 3589 snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,3590 NULL, 0, 0);3591 3592NULL is passed as the device pointer argument, which indicates3593that default pages (GFP_KERNEL and GFP_HIGHMEM) will be3594allocated.3595 3596Also, note that zero is passed as both the size and the max size3597argument here. Since each vmalloc call should succeed at any time,3598we don't need to pre-allocate the buffers like other continuous3599pages.3600 3601Proc Interface3602==============3603 3604ALSA provides an easy interface for procfs. The proc files are very3605useful for debugging. I recommend you set up proc files if you write a3606driver and want to get a running status or register dumps. The API is3607found in ``<sound/info.h>``.3608 3609To create a proc file, call :c:func:`snd_card_proc_new()`::3610 3611 struct snd_info_entry *entry;3612 int err = snd_card_proc_new(card, "my-file", &entry);3613 3614where the second argument specifies the name of the proc file to be3615created. The above example will create a file ``my-file`` under the3616card directory, e.g. ``/proc/asound/card0/my-file``.3617 3618Like other components, the proc entry created via3619:c:func:`snd_card_proc_new()` will be registered and released3620automatically in the card registration and release functions.3621 3622When the creation is successful, the function stores a new instance in3623the pointer given in the third argument. It is initialized as a text3624proc file for read only. To use this proc file as a read-only text file3625as-is, set the read callback with private data via3626:c:func:`snd_info_set_text_ops()`::3627 3628 snd_info_set_text_ops(entry, chip, my_proc_read);3629 3630where the second argument (``chip``) is the private data to be used in3631the callback. The third parameter specifies the read buffer size and3632the fourth (``my_proc_read``) is the callback function, which is3633defined like::3634 3635 static void my_proc_read(struct snd_info_entry *entry,3636 struct snd_info_buffer *buffer);3637 3638In the read callback, use :c:func:`snd_iprintf()` for output3639strings, which works just like normal :c:func:`printf()`. For3640example::3641 3642 static void my_proc_read(struct snd_info_entry *entry,3643 struct snd_info_buffer *buffer)3644 {3645 struct my_chip *chip = entry->private_data;3646 3647 snd_iprintf(buffer, "This is my chip!\n");3648 snd_iprintf(buffer, "Port = %ld\n", chip->port);3649 }3650 3651The file permissions can be changed afterwards. By default, they are3652read only for all users. If you want to add write permission for the3653user (root by default), do as follows::3654 3655 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;3656 3657and set the write buffer size and the callback::3658 3659 entry->c.text.write = my_proc_write;3660 3661In the write callback, you can use :c:func:`snd_info_get_line()`3662to get a text line, and :c:func:`snd_info_get_str()` to retrieve3663a string from the line. Some examples are found in3664``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.3665 3666For a raw-data proc-file, set the attributes as follows::3667 3668 static const struct snd_info_entry_ops my_file_io_ops = {3669 .read = my_file_io_read,3670 };3671 3672 entry->content = SNDRV_INFO_CONTENT_DATA;3673 entry->private_data = chip;3674 entry->c.ops = &my_file_io_ops;3675 entry->size = 4096;3676 entry->mode = S_IFREG | S_IRUGO;3677 3678For raw data, ``size`` field must be set properly. This specifies3679the maximum size of the proc file access.3680 3681The read/write callbacks of raw mode are more direct than the text mode.3682You need to use a low-level I/O functions such as3683:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the3684data::3685 3686 static ssize_t my_file_io_read(struct snd_info_entry *entry,3687 void *file_private_data,3688 struct file *file,3689 char *buf,3690 size_t count,3691 loff_t pos)3692 {3693 if (copy_to_user(buf, local_data + pos, count))3694 return -EFAULT;3695 return count;3696 }3697 3698If the size of the info entry has been set up properly, ``count`` and3699``pos`` are guaranteed to fit within 0 and the given size. You don't3700have to check the range in the callbacks unless any other condition is3701required.3702 3703Power Management3704================3705 3706If the chip is supposed to work with suspend/resume functions, you need3707to add power-management code to the driver. The additional code for3708power-management should be ifdef-ed with ``CONFIG_PM``, or annotated3709with __maybe_unused attribute; otherwise the compiler will complain.3710 3711If the driver *fully* supports suspend/resume that is, the device can be3712properly resumed to its state when suspend was called, you can set the3713``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is3714possible when the registers of the chip can be safely saved and restored3715to RAM. If this is set, the trigger callback is called with3716``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.3717 3718Even if the driver doesn't support PM fully but partial suspend/resume3719is still possible, it's still worthy to implement suspend/resume3720callbacks. In such a case, applications would reset the status by3721calling :c:func:`snd_pcm_prepare()` and restart the stream3722appropriately. Hence, you can define suspend/resume callbacks below but3723don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.3724 3725Note that the trigger with SUSPEND can always be called when3726:c:func:`snd_pcm_suspend_all()` is called, regardless of the3727``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the3728behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,3729``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger3730callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better3731to keep it for compatibility reasons.)3732 3733The driver needs to define the3734suspend/resume hooks according to the bus the device is connected to. In3735the case of PCI drivers, the callbacks look like below::3736 3737 static int __maybe_unused snd_my_suspend(struct device *dev)3738 {3739 .... /* do things for suspend */3740 return 0;3741 }3742 static int __maybe_unused snd_my_resume(struct device *dev)3743 {3744 .... /* do things for suspend */3745 return 0;3746 }3747 3748The scheme of the real suspend job is as follows:3749 37501. Retrieve the card and the chip data.3751 37522. Call :c:func:`snd_power_change_state()` with3753 ``SNDRV_CTL_POWER_D3hot`` to change the power status.3754 37553. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for3756 each codec.3757 37584. Save the register values if necessary.3759 37605. Stop the hardware if necessary.3761 3762Typical code would look like::3763 3764 static int __maybe_unused mychip_suspend(struct device *dev)3765 {3766 /* (1) */3767 struct snd_card *card = dev_get_drvdata(dev);3768 struct mychip *chip = card->private_data;3769 /* (2) */3770 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);3771 /* (3) */3772 snd_ac97_suspend(chip->ac97);3773 /* (4) */3774 snd_mychip_save_registers(chip);3775 /* (5) */3776 snd_mychip_stop_hardware(chip);3777 return 0;3778 }3779 3780 3781The scheme of the real resume job is as follows:3782 37831. Retrieve the card and the chip data.3784 37852. Re-initialize the chip.3786 37873. Restore the saved registers if necessary.3788 37894. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`.3790 37915. Restart the hardware (if any).3792 37936. Call :c:func:`snd_power_change_state()` with3794 ``SNDRV_CTL_POWER_D0`` to notify the processes.3795 3796Typical code would look like::3797 3798 static int __maybe_unused mychip_resume(struct pci_dev *pci)3799 {3800 /* (1) */3801 struct snd_card *card = dev_get_drvdata(dev);3802 struct mychip *chip = card->private_data;3803 /* (2) */3804 snd_mychip_reinit_chip(chip);3805 /* (3) */3806 snd_mychip_restore_registers(chip);3807 /* (4) */3808 snd_ac97_resume(chip->ac97);3809 /* (5) */3810 snd_mychip_restart_chip(chip);3811 /* (6) */3812 snd_power_change_state(card, SNDRV_CTL_POWER_D0);3813 return 0;3814 }3815 3816Note that, at the time this callback gets called, the PCM stream has3817been already suspended via its own PM ops calling3818:c:func:`snd_pcm_suspend_all()` internally.3819 3820OK, we have all callbacks now. Let's set them up. In the initialization3821of the card, make sure that you can get the chip data from the card3822instance, typically via ``private_data`` field, in case you created the3823chip data individually::3824 3825 static int snd_mychip_probe(struct pci_dev *pci,3826 const struct pci_device_id *pci_id)3827 {3828 ....3829 struct snd_card *card;3830 struct mychip *chip;3831 int err;3832 ....3833 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,3834 0, &card);3835 ....3836 chip = kzalloc(sizeof(*chip), GFP_KERNEL);3837 ....3838 card->private_data = chip;3839 ....3840 }3841 3842When you created the chip data with :c:func:`snd_card_new()`, it's3843anyway accessible via ``private_data`` field::3844 3845 static int snd_mychip_probe(struct pci_dev *pci,3846 const struct pci_device_id *pci_id)3847 {3848 ....3849 struct snd_card *card;3850 struct mychip *chip;3851 int err;3852 ....3853 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,3854 sizeof(struct mychip), &card);3855 ....3856 chip = card->private_data;3857 ....3858 }3859 3860If you need space to save the registers, allocate the buffer for it3861here, too, since it would be fatal if you cannot allocate a memory in3862the suspend phase. The allocated buffer should be released in the3863corresponding destructor.3864 3865And next, set suspend/resume callbacks to the pci_driver::3866 3867 static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);3868 3869 static struct pci_driver driver = {3870 .name = KBUILD_MODNAME,3871 .id_table = snd_my_ids,3872 .probe = snd_my_probe,3873 .remove = snd_my_remove,3874 .driver = {3875 .pm = &snd_my_pm_ops,3876 },3877 };3878 3879Module Parameters3880=================3881 3882There are standard module options for ALSA. At least, each module should3883have the ``index``, ``id`` and ``enable`` options.3884 3885If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``3886cards), they should be arrays. The default initial values are defined3887already as constants for easier programming::3888 3889 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;3890 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;3891 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;3892 3893If the module supports only a single card, they could be single3894variables, instead. ``enable`` option is not always necessary in this3895case, but it would be better to have a dummy option for compatibility.3896 3897The module parameters must be declared with the standard3898``module_param()``, ``module_param_array()`` and3899:c:func:`MODULE_PARM_DESC()` macros.3900 3901Typical code would look as below::3902 3903 #define CARD_NAME "My Chip"3904 3905 module_param_array(index, int, NULL, 0444);3906 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");3907 module_param_array(id, charp, NULL, 0444);3908 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");3909 module_param_array(enable, bool, NULL, 0444);3910 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");3911 3912Also, don't forget to define the module description and the license.3913Especially, the recent modprobe requires to define the3914module license as GPL, etc., otherwise the system is shown as “tainted”::3915 3916 MODULE_DESCRIPTION("Sound driver for My Chip");3917 MODULE_LICENSE("GPL");3918 3919 3920Device-Managed Resources3921========================3922 3923In the examples above, all resources are allocated and released3924manually. But human beings are lazy in nature, especially developers3925are lazier. So there are some ways to automate the release part; it's3926the (device-)managed resources aka devres or devm family. For3927example, an object allocated via :c:func:`devm_kmalloc()` will be3928freed automatically at unbinding the device.3929 3930ALSA core provides also the device-managed helper, namely,3931:c:func:`snd_devm_card_new()` for creating a card object.3932Call this functions instead of the normal :c:func:`snd_card_new()`,3933and you can forget the explicit :c:func:`snd_card_free()` call, as3934it's called automagically at error and removal paths.3935 3936One caveat is that the call of :c:func:`snd_card_free()` would be put3937at the beginning of the call chain only after you call3938:c:func:`snd_card_register()`.3939 3940Also, the ``private_free`` callback is always called at the card free,3941so be careful to put the hardware clean-up procedure in3942``private_free`` callback. It might be called even before you3943actually set up at an earlier error path. For avoiding such an3944invalid initialization, you can set ``private_free`` callback after3945:c:func:`snd_card_register()` call succeeds.3946 3947Another thing to be remarked is that you should use device-managed3948helpers for each component as much as possible once when you manage3949the card in that way. Mixing up with the normal and the managed3950resources may screw up the release order.3951 3952 3953How To Put Your Driver Into ALSA Tree3954=====================================3955 3956General3957-------3958 3959So far, you've learned how to write the driver codes. And you might have3960a question now: how to put my own driver into the ALSA driver tree? Here3961(finally :) the standard procedure is described briefly.3962 3963Suppose that you create a new PCI driver for the card “xyz”. The card3964module name would be snd-xyz. The new driver is usually put into the3965alsa-driver tree, ``sound/pci`` directory in the case of PCI3966cards.3967 3968In the following sections, the driver code is supposed to be put into3969Linux kernel tree. The two cases are covered: a driver consisting of a3970single source file and one consisting of several source files.3971 3972Driver with A Single Source File3973--------------------------------3974 39751. Modify sound/pci/Makefile3976 3977 Suppose you have a file xyz.c. Add the following two lines::3978 3979 snd-xyz-y := xyz.o3980 obj-$(CONFIG_SND_XYZ) += snd-xyz.o3981 39822. Create the Kconfig entry3983 3984 Add the new entry of Kconfig for your xyz driver::3985 3986 config SND_XYZ3987 tristate "Foobar XYZ"3988 depends on SND3989 select SND_PCM3990 help3991 Say Y here to include support for Foobar XYZ soundcard.3992 To compile this driver as a module, choose M here:3993 the module will be called snd-xyz.3994 3995The line ``select SND_PCM`` specifies that the driver xyz supports PCM.3996In addition to SND_PCM, the following components are supported for3997select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,3998SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.3999Add the select command for each supported component.4000 4001Note that some selections imply the lowlevel selections. For example,4002PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC4003includes PCM, and OPL3_LIB includes HWDEP. You don't need to give4004the lowlevel selections again.4005 4006For the details of Kconfig script, refer to the kbuild documentation.4007 4008Drivers with Several Source Files4009---------------------------------4010 4011Suppose that the driver snd-xyz have several source files. They are4012located in the new subdirectory, sound/pci/xyz.4013 40141. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``4015 as below::4016 4017 obj-$(CONFIG_SND) += sound/pci/xyz/4018 4019 40202. Under the directory ``sound/pci/xyz``, create a Makefile::4021 4022 snd-xyz-y := xyz.o abc.o def.o4023 obj-$(CONFIG_SND_XYZ) += snd-xyz.o4024 40253. Create the Kconfig entry4026 4027 This procedure is as same as in the last section.4028 4029 4030Useful Functions4031================4032 4033:c:func:`snd_BUG()`4034-------------------4035 4036It shows the ``BUG?`` message and stack trace as well as4037:c:func:`snd_BUG_ON()` at the point. It's useful to show that a4038fatal error happens there.4039 4040When no debug flag is set, this macro is ignored.4041 4042:c:func:`snd_BUG_ON()`4043----------------------4044 4045:c:func:`snd_BUG_ON()` macro is similar with4046:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or4047it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))4048return -EINVAL;4049 4050The macro takes an conditional expression to evaluate. When4051``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows4052the warning message such as ``BUG? (xxx)`` normally followed by stack4053trace. In both cases it returns the evaluated value.4054 4055Acknowledgments4056===============4057 4058I would like to thank Phil Kerr for his help for improvement and4059corrections of this document.4060 4061Kevin Conder reformatted the original plain-text to the DocBook format.4062 4063Giuliano Pochini corrected typos and contributed the example codes in4064the hardware constraints section.4065