Lines Matching +full:chip +full:- +full:to +full:- +full:chip
10 This document describes how to write an `ALSA (Advanced Linux Sound
11 Architecture) <http://www.alsa-project.org/>`__ driver. The document
19 low-level driver implementation details. It only describes the standard
20 way to write a PCI sound driver on ALSA.
26 -------
56 --------------
60 sub-directories contain different modules and are dependent upon the
74 This directory and its sub-directories are for the ALSA sequencer. This
76 as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
85 -----------------
88 to be exported to user-space, or included by several files in different
90 this directory, but you may still find files there, due to historical
94 -----------------
97 architectures. They are hence supposed not to be architecture-specific.
99 in this directory. In the sub-directories, there is code for components
105 The MPU401 and MPU401-UART modules are stored here.
110 The OPL3 and OPL4 FM-synth stuff is found here.
113 -------------
122 ---------------
124 This contains the synth middle-level modules.
127 ``synth/emux`` sub-directory.
130 -------------
132 This directory and its sub-directories hold the top-level card modules
133 for PCI soundcards and the code specific to the PCI BUS.
137 their own sub-directory (e.g. emu10k1, ice1712).
140 -------------
142 This directory and its sub-directories hold the top-level card modules
146 -------------------------------
148 They are used for top-level card modules which are specific to one of
152 -------------
154 This directory contains the USB-audio driver.
155 The USB MIDI driver is integrated in the usb-audio driver.
158 ----------------
161 be in the pci directory, because their API is identical to that of
165 -------------
167 This directory contains the codes for ASoC (ALSA System on Chip)
171 -------------
182 -------
186 - define the PCI ID table (see the section `PCI Entries`_).
188 - create ``probe`` callback.
190 - create ``remove`` callback.
192 - create a struct pci_driver structure
195 - create an ``init`` function just calling the
196 :c:func:`pci_register_driver()` to register the pci_driver
199 - create an ``exit`` function to call the
203 -----------------
208 to details explained in the following section.
224 /* definition of the chip-specific record */
232 /* chip-specific destructor
235 static int snd_mychip_free(struct mychip *chip)
240 /* component-destructor
245 return snd_mychip_free(device->device_data);
248 /* chip-specific constructor
255 struct mychip *chip;
268 /* allocate a chip-specific data with zero filled */
269 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
270 if (chip == NULL)
271 return -ENOMEM;
273 chip->card = card;
280 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
282 snd_mychip_free(chip);
286 *rchip = chip;
290 /* constructor -- see "Driver Constructor" sub-section */
296 struct mychip *chip;
301 return -ENODEV;
304 return -ENOENT;
308 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
314 err = snd_mychip_create(card, pci, &chip);
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);
342 /* destructor -- see the "Destructor" sub-section */
351 ------------------
354 ``probe`` callback and other component-constructors which are called
368 return -ENODEV;
371 return -ENOENT;
390 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
402 struct mychip *chip;
404 err = snd_mychip_create(card, pci, &chip);
411 When something goes wrong, the probe function needs to deal with the
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);
433 The driver field holds the minimal ID string of the chip. This is used
434 by alsa-lib's configurator, so keep it simple but unique. Even the
435 same driver can have different driver IDs to distinguish the
436 functionality of each chip type.
446 `MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
472 remove callback and power-management callbacks, too.
475 ----------
489 The above code assumes that the card pointer is set to the PCI driver
493 ------------
508 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
511 to include ``<linux/delay.h>`` too.
514 ``<sound/xxx.h>`` header files. They have to be included after
521 -------------
529 the power-management states and hotplug disconnections. The component
530 list on the card record is used to manage the correct release of
533 As mentioned above, to create a card instance, call
538 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
542 card-index number, the id string, the module pointer (usually
543 ``THIS_MODULE``), the size of extra-data space, and the pointer to
544 return the card instance. The extra_size argument is used to allocate
545 card->private_data for the chip-specific data. Note that these data are
549 device. For PCI devices, typically ``&pci->`` is passed there.
552 ----------
554 After the card is created, you can attach the components (devices) to
563 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
565 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
566 data pointer, and the callback pointers (``&ops``). The device-level
568 de-registration. For most components, the device-level is already
569 defined. For a user-defined component, you can use
574 argument. This pointer (``chip`` in the above example) is used as the
577 Each pre-defined ALSA component such as AC97 and PCM calls
580 need to take care of calling a destructor for such a component.
582 If you wish to create your own component, you need to set the destructor
583 function to the dev_free callback in the ``ops``, so that it can be
585 example will show an implementation of chip-specific data.
587 Chip-Specific Data
588 ------------------
590 Chip-specific information, e.g. the I/O port address, its resource
591 pointer, or the irq number, is stored in the chip-specific record::
598 In general, there are two ways of allocating the chip record.
603 As mentioned above, you can pass the extra-data-length to the 5th
606 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
609 struct mychip is the type of the chip record.
615 struct mychip *chip = card->private_data;
617 With this method, you don't have to allocate twice. The record is
627 struct mychip *chip;
628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
631 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
633 The chip record should have the field to hold the card pointer at least,
643 Then, set the card pointer in the returned chip instance::
645 chip->card = card;
647 Next, initialize the fields, and register this chip record as a
648 low-level device with a specified ``ops``::
654 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
656 :c:func:`snd_mychip_dev_free()` is the device-destructor
661 return snd_mychip_free(device->device_data);
674 ------------------------
677 :c:func:`snd_card_register()`. Access to the device files is
695 -----------------
697 In this section, we'll complete the chip-specific constructor,
708 static int snd_mychip_free(struct mychip *chip)
714 if (chip->irq >= 0)
715 free_irq(chip->irq, chip);
717 pci_release_regions(chip->pci);
719 pci_disable_device(chip->pci);
721 kfree(chip);
725 /* chip-specific constructor */
730 struct mychip *chip;
745 printk(KERN_ERR "error to set 28bit mask DMA\n");
747 return -ENXIO;
750 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
751 if (chip == NULL) {
753 return -ENOMEM;
757 chip->card = card;
758 chip->pci = pci;
759 chip->irq = -1;
762 err = pci_request_regions(pci, "My Chip");
764 kfree(chip);
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;
775 chip->irq = pci->irq;
776 card->sync_irq = chip->irq;
778 /* (2) initialization of the chip hardware */
781 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
783 snd_mychip_free(chip);
787 *rchip = chip;
826 ------------
832 In the case of PCI devices, you first have to call the
834 resources. Also, you need to set the proper PCI DMA mask to limit the
835 accessed I/O range. In some cases, you might need to call
838 Suppose a 28bit mask, the code to be added would look like::
845 printk(KERN_ERR "error to set 28bit mask DMA\n");
847 return -ENXIO;
852 -------------------
870 For an I/O port (and also a memory region), you need to have the
872 have to keep only the irq number (integer). But you need to initialize
873 this number to -1 before actual allocation, since irq 0 is valid. The
875 :c:func:`kzalloc()` automatically, so you don't have to take care of
880 err = pci_request_regions(pci, "My Chip");
882 kfree(chip);
886 chip->port = pci_resource_start(pci, 0);
889 The returned value, ``chip->res_port``, is allocated via
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;
902 chip->irq = pci->irq;
906 ``chip->irq`` should be defined only when :c:func:`request_irq()`
913 passed to the interrupt handler. Usually, the chip-specific record is
922 struct mychip *chip = dev_id;
927 After requesting the IRQ, you can passed it to ``card->sync_irq``
930 card->irq = chip->irq;
932 This allows the PCM core to automatically call
941 To release the resources, the “check-and-release” method is a safer way.
944 if (chip->irq >= 0)
945 free_irq(chip->irq, chip);
948 ``chip->irq`` with a negative value (e.g. -1), so that you can check
958 pci_release_regions(chip->pci);
964 chip->res_port, the release procedure looks like::
966 release_and_free_resource(chip->res_port);
968 Don't forget to call :c:func:`pci_disable_device()` before the
971 And finally, release the chip-specific record::
973 kfree(chip);
976 need to do this, please note that the destructor may be called even
977 before the initialization of the chip is completed. It would be better
978 to have a flag to skip hardware disabling if the hardware was not
981 When the chip-data is assigned to the card using
985 have to stop PCMs, etc. explicitly, but just call low-level hardware
988 The management of a memory-mapped region is almost as same as the
999 err = pci_request_regions(pci, "My Chip");
1001 kfree(chip);
1004 chip->iobase_phys = pci_resource_start(pci, 0);
1005 chip->iobase_virt = ioremap(chip->iobase_phys,
1010 static int snd_mychip_free(struct mychip *chip)
1013 if (chip->iobase_virt)
1014 iounmap(chip->iobase_virt);
1016 pci_release_regions(chip->pci);
1023 err = pci_request_regions(pci, "My Chip");
1025 kfree(chip);
1028 chip->iobase_virt = pci_iomap(pci, 0, 0);
1034 -----------
1052 and device IDs. If you have no reason to filter the matching devices, you can
1055 any value here, for example, to define specific operations for supported
1059 all-zero entry.
1099 -------
1102 for each driver to implement the low-level functions to access its
1105 To access the PCM layer, you need to include ``<sound/pcm.h>``
1109 Each card device can have up to four PCM instances. A PCM instance
1110 corresponds to a PCM device file. The limitation of number of instances
1121 will either block or error with ``EAGAIN`` according to the file open
1122 mode. But you don't have to care about such details in your driver. The
1126 -----------------
1129 shows only the skeleton, how to build up the PCM interfaces::
1175 struct mychip *chip = snd_pcm_substream_chip(substream);
1176 struct snd_pcm_runtime *runtime = substream->runtime;
1178 runtime->hw = snd_mychip_playback_hw;
1179 /* more hardware-initialization will be done here */
1187 struct mychip *chip = snd_pcm_substream_chip(substream);
1188 /* the hardware-specific codes will be here */
1197 struct mychip *chip = snd_pcm_substream_chip(substream);
1198 struct snd_pcm_runtime *runtime = substream->runtime;
1200 runtime->hw = snd_mychip_capture_hw;
1201 /* more hardware-initialization will be done here */
1209 struct mychip *chip = snd_pcm_substream_chip(substream);
1210 /* the hardware-specific codes will be here */
1219 /* the hardware-specific codes will be here */
1227 /* the hardware-specific codes will be here */
1235 struct mychip *chip = snd_pcm_substream_chip(substream);
1236 struct snd_pcm_runtime *runtime = substream->runtime;
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);
1256 /* do something to start the PCM engine */
1260 /* do something to stop the PCM engine */
1264 return -EINVAL;
1272 struct mychip *chip = snd_pcm_substream_chip(substream);
1276 current_ptr = mychip_get_hw_pointer(chip);
1307 static int snd_mychip_new_pcm(struct mychip *chip)
1312 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1315 pcm->private_data = chip;
1316 strcpy(pcm->name, "My Chip");
1317 chip->pcm = pcm;
1323 /* pre-allocation of buffers */
1326 &chip->pci->dev,
1333 ---------------
1336 function. It would be better to create a constructor for the PCM, namely::
1338 static int snd_mychip_new_pcm(struct mychip *chip)
1343 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1346 pcm->private_data = chip;
1347 strcpy(pcm->name, "My Chip");
1348 chip->pcm = pcm;
1354 first argument is the card pointer to which this PCM is assigned, and
1364 playback or capture substreams are available, pass 0 to the
1367 If a chip supports multiple playbacks or captures, you can specify more
1369 callbacks. When you need to know which substream you are referring to,
1370 then it can be obtained from struct snd_pcm_substream data passed to each
1374 int index = substream->number;
1377 After the PCM is created, you need to set operators for each PCM stream::
1398 After setting the operators, you probably will want to pre-allocate the
1403 &chip->pci->dev,
1406 It will allocate a buffer up to 64kB by default. Buffer management
1411 ``pcm->info_flags``. The available values are defined as
1414 half-duplex, specify it like this::
1416 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1420 -----------------------
1424 don't have to call the destructor explicitly.
1427 internally and needed to release them. In such a case, set the
1428 destructor function to ``pcm->private_free``::
1432 struct mychip *chip = snd_pcm_chip(pcm);
1434 kfree(chip->my_private_pcm_data);
1439 static int snd_mychip_new_pcm(struct mychip *chip)
1444 chip->my_private_pcm_data = kmalloc(...);
1446 pcm->private_data = chip;
1447 pcm->private_free = mychip_pcm_free;
1453 Runtime Pointer - The Chest of PCM Information
1454 ----------------------------------------------
1457 and assigned to the substream. This pointer is accessible via
1458 ``substream->runtime``. This runtime pointer holds most information you
1459 need to control the PCM: a copy of hw_params and sw_params
1466 /* -- Status -- */
1474 /* -- HW params -- */
1492 /* -- SW params -- */
1495 unsigned int sleep_min; /* min ticks to sleep */
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,
1507 /* internal data of auto-silencer */
1508 snd_pcm_uframes_t silence_start; /* starting pointer to silence area */
1513 /* -- mmap -- */
1518 /* -- locking / scheduling -- */
1524 /* -- private section -- */
1528 /* -- hardware description -- */
1532 /* -- timer -- */
1535 /* -- DMA -- */
1543 /* -- OSS things -- */
1550 records are supposed to be read-only. Only the PCM middle-layer changes
1553 standard managed buffer allocation mode, you don't need to set the
1562 the fundamental hardware configuration. Above all, you'll need to define this
1564 the descriptor, not a pointer to the existing descriptor. That is,
1566 (``runtime->hw``) as you need. For example, if the maximum number of
1567 channels is 1 only on some chip models, you can still use the same
1570 struct snd_pcm_runtime *runtime = substream->runtime;
1572 runtime->hw = snd_mychip_playback_hw; /* common definition */
1573 if (chip->model == VERY_OLD_ONE)
1574 runtime->hw.channels_max = 1;
1596 - The ``info`` field contains the type and capabilities of this
1598 ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1602 interleaved or the non-interleaved formats, the
1623 need to check the linked-list of PCM substreams in the trigger
1626 - The ``formats`` field contains the bit-flags of supported formats
1629 little-endian format is specified.
1631 - The ``rates`` field contains the bit-flags of supported rates
1632 (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1633 pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
1634 are provided only for typical rates. If your chip supports
1635 unconventional rates, you need to add the ``KNOT`` bit and set up
1638 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1639 rate. This should correspond somehow to ``rates`` bits.
1641 - ``channels_min`` and ``channels_max`` define, as you might have already
1644 - ``buffer_bytes_max`` defines the maximum buffer size in
1652 The “period” is a term that corresponds to a fragment in the OSS
1656 in being able to fill/drain the buffer more timely. In the case of
1661 - There is also a field ``fifo_size``. This specifies the size of the
1663 in the alsa-lib. So, you can ignore this field.
1668 Ok, let's go back again to the PCM runtime records. The most
1672 alsa-lib. There are many fields copied from hw_params and sw_params
1677 One thing to be noted is that the configured buffer and period sizes
1679 channels \* samples-size``. For conversion between frames and bytes,
1683 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1696 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1705 other hand, if you want to allocate the buffer by yourself, you'll
1706 need to manage it in the hw_params callback. At least, ``dma_bytes`` is
1715 The running status can be referred via ``runtime->status``. This is
1716 a pointer to a struct snd_pcm_mmap_status record.
1718 DMA hardware pointer via ``runtime->status->hw_ptr``.
1720 The DMA application pointer can be referred via ``runtime->control``,
1721 which points to a struct snd_pcm_mmap_control record.
1728 ``runtime->private_data``. Usually, this is done in the `PCM open
1729 callback`_. Don't mix this with ``pcm->private_data``. The
1730 ``pcm->private_data`` usually points to the chip instance assigned
1732 ``runtime->private_data``
1733 points to a dynamic data structure created in the PCM open
1741 substream->runtime->private_data = data;
1749 ---------
1753 error number such as ``-EINVAL``. To choose an appropriate error
1754 number, it is advised to check what value other parts of the kernel
1758 struct snd_pcm_substream pointer. To retrieve the chip
1763 struct mychip *chip = snd_pcm_substream_chip(substream);
1767 The macro reads ``substream->private_data``, which is a copy of
1768 ``pcm->private_data``. You can override the former if you need to
1771 capture directions, because it uses two different codecs (SB- and
1772 AD-compatible) for different directions.
1783 At least, here you have to initialize the ``runtime->hw``
1788 struct mychip *chip = snd_pcm_substream_chip(substream);
1789 struct snd_pcm_runtime *runtime = substream->runtime;
1791 runtime->hw = snd_mychip_playback_hw;
1795 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1820 kfree(substream->runtime->private_data);
1827 This is used for any special call to PCM ioctls. But usually you can
1829 function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a
1848 Parameters to be initialized are retrieved by the
1859 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1866 Thus, you need to be careful not to allocate the same buffers many
1867 times, which will lead to memory leaks! Calling the helper function
1871 Another note is that this callback is non-atomic (schedulable) by
1873 because the ``trigger`` callback is atomic (non-schedulable). That is,
1874 mutexes or any schedule-related functions are not available in the
1885 This is called to release the resources allocated via
1894 after this callback gets called. Otherwise you'll have to release the
1896 pre-allocated pool, you can use the standard API function
1914 Note that this callback is non-atomic. You can use
1915 schedule-related functions safely in this callback.
1917 In this and the following callbacks, you can refer to the values via
1918 the runtime record, ``substream->runtime``. For example, to get the
1919 current rate, format or channels, access to ``runtime->rate``,
1920 ``runtime->format`` or ``runtime->channels``, respectively. The
1921 physical address of the allocated buffer is set to
1922 ``runtime->dma_area``. The buffer and period sizes are in
1923 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
1943 /* do something to start the PCM engine */
1946 /* do something to stop the PCM engine */
1949 return -EINVAL;
1954 must be handled here, too. The former is the command to pause the PCM,
1955 and the latter to restart the PCM again.
1960 power-management status is changed. Obviously, the ``SUSPEND`` and
1962 they are identical to the ``STOP`` and ``START`` commands, respectively.
1981 Since the IRQ handler might be still pending, we need to wait until
1982 the pending task finishes before moving to the next step; otherwise it
1983 might lead to a crash due to resource conflicts or access to freed
1984 resources. A typical behavior is to call a synchronization function
1990 the ``card->sync_irq`` field to the returned interrupt number after
1995 to clear ``card->sync_irq``, as the card itself is being released.
1996 So, usually you'll need to add just a single line for assigning
1997 ``card->sync_irq`` in the driver code unless the driver re-acquires
1998 the IRQ. When the driver frees and re-acquires the IRQ dynamically
1999 (e.g. for suspend/resume), it needs to clear and re-set
2000 ``card->sync_irq`` again appropriately.
2011 frames, ranging from 0 to ``buffer_size - 1``.
2013 This is usually called from the buffer-update routine in the PCM
2027 which is not mappable. In such a case, you have to transfer the data
2028 manually from the memory buffer to the hardware buffer. Or, if the
2029 buffer is non-contiguous on both physical and virtual memory spaces,
2032 If these two callbacks are defined, copy and set-silence operations
2041 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2045 return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
2046 and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.
2053 This callback is optional too. The mmap calls this callback to get the
2056 You need no special callback for the standard SG-buffer or vmalloc-
2064 memory-mapped, instead of using the standard helper.
2065 If you need special handling (due to some architecture or
2066 device-specific issues), implement everything here as you like.
2070 ---------------------
2074 interrupt handler in the sound driver is to update the buffer position
2075 and to tell the PCM middle layer when the buffer position goes across
2076 the specified period boundary. To inform about this, call the
2089 its argument. Thus, you need to keep the substream pointer accessible
2090 from the chip instance. For example, define ``substream`` field in the
2091 chip record to hold the current running substream pointer, and set the
2095 in other PCM callbacks, too, then you have to release the lock before
2105 struct mychip *chip = dev_id;
2106 spin_lock(&chip->lock);
2108 if (pcm_irq_invoked(chip)) {
2110 spin_unlock(&chip->lock);
2111 snd_pcm_period_elapsed(chip->substream);
2112 spin_lock(&chip->lock);
2116 spin_unlock(&chip->lock);
2121 can notify the XRUN status to the PCM core by calling
2123 the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
2133 or ymfpci drivers). In this case, you need to check the current hardware
2143 struct mychip *chip = dev_id;
2144 spin_lock(&chip->lock);
2146 if (pcm_irq_invoked(chip)) {
2149 last_ptr = get_hw_ptr(chip);
2153 if (last_ptr < chip->last_ptr)
2154 size = runtime->buffer_size + last_ptr
2155 - chip->last_ptr;
2157 size = last_ptr - chip->last_ptr;
2159 chip->last_ptr = last_ptr;
2161 chip->size += size;
2163 if (chip->size >= runtime->period_size) {
2165 chip->size %= runtime->period_size;
2167 spin_unlock(&chip->lock);
2169 spin_lock(&chip->lock);
2174 spin_unlock(&chip->lock);
2184 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2186 update to the latest status.
2189 ---------
2191 One of the most important (and thus difficult to debug) problems in
2193 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2194 race condition can happen in an interrupt handler, it has to be managed
2195 atomically, and you have to use a spinlock to protect the critical
2197 taking a relatively long time to execute is acceptable, you should use
2201 example, the ``hw_params`` callback is non-atomic, while the ``trigger``
2208 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2210 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2216 However, it is possible to request all PCM operations to be non-atomic.
2218 non-atomic contexts. For example, the function
2220 interrupt handler. But, if you set up the driver to use a threaded
2221 interrupt handler, this call can be in non-atomic context, too. In such
2225 functions safely in a non-atomic
2228 Also, in some cases, you might need to call
2236 -----------
2238 Due to physical limitations, hardware is not infinitely configurable.
2241 For example, in order to restrict the sample rates to some supported
2242 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2257 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2281 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2290 Then you need to call this function to add your rule::
2292 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2294 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2299 to define the inverse rule::
2310 if (c->min < 2) {
2320 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2322 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2324 One typical usage of the hw constraints is to align the buffer size
2326 buffer size to be aligned with the period size. For example, it'd be
2327 possible to have a combination like 256 period bytes with 999 buffer
2330 Many device chips, however, require the buffer to be a multiple of
2335 snd_pcm_hw_constraint_integer(substream->runtime,
2341 The hw constraint is a very powerful mechanism to define the
2343 I won't give more details here, rather I would like to say, “Luke, use
2350 -------
2353 which are accessed from user-space. Its most important use is the mixer
2357 ALSA has a well-defined AC97 control module. If your chip supports only
2361 if you want to add your own controls.
2364 ----------------------
2366 To create a new control, you need to define the following three
2393 its name. There are pre-defined standard control names. The details
2411 possible to store a pointer (casted to unsigned long) of some record in
2414 The ``tlv`` field can be used to provide metadata about the control;
2420 -------------
2422 There are some standards to define the control names. A control is
2427 pre-defined sources.
2429 The second, ``DIRECTION``, is one of the following strings according to
2434 The third, ``FUNCTION``, is one of the following strings according to
2450 Tone-controls
2453 tone-control switch and volumes are specified like “Tone Control - XXX”,
2454 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2460 3D-control switches and volumes are specified like “3D Control - XXX”,
2461 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2466 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2469 ``Documentation/sound/designs/control-names.rst``.
2472 ------------
2477 allowed to this control. When the access flag is omitted (i.e. = 0), it
2480 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2481 instead. In this case, you don't have to define the ``put`` callback.
2482 Similarly, when the control is write-only (although it's a rare case),
2495 There are ``LOCK`` and ``OWNER`` flags to change the write permissions.
2498 -----------------
2503 The ``info`` callback is used to get detailed information on this
2512 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513 uinfo->count = 1;
2514 uinfo->value.integer.min = 0;
2515 uinfo->value.integer.max = 1;
2528 The enumerated type is a bit different from the others. You'll need to
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]);
2574 This callback is used to read the current value of the control, so it
2575 can be returned to user-space.
2582 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2583 ucontrol->value.integer.value[0] = get_some_value(chip);
2590 info callback. For example, the sb driver uses this field to store the
2591 register offset, the bit-shift and the bit-mask. The ``private_value``
2601 int reg = kcontrol->private_value & 0xff;
2602 int shift = (kcontrol->private_value >> 16) & 0xff;
2603 int mask = (kcontrol->private_value >> 24) & 0xff;
2607 In the ``get`` callback, you have to fill all the elements if the
2615 This callback is used to write a value coming from user-space.
2622 struct mychip *chip = snd_kcontrol_chip(kcontrol);
2624 if (chip->current_value !=
2625 ucontrol->value.integer.value[0]) {
2626 change_current_value(chip,
2627 ucontrol->value.integer.value[0]);
2635 As seen above, you have to return 1 if the value is changed. If the
2645 All these three callbacks are not-atomic.
2648 -------------------
2650 When everything is ready, finally we can create a new control. To create
2651 a control, there are two functions to be called,
2656 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2661 and chip is the object pointer to be passed to kcontrol->private_data which
2662 can be referred to in callbacks.
2665 :c:func:`snd_ctl_add()` assigns the given control component to the
2669 -------------------
2671 If you need to change and update a control in the interrupt routine, you
2676 This function takes the card pointer, the event-mask, and the control id
2677 pointer for the notification. The event-mask specifies the types of
2680 to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2684 --------
2686 To provide information about the dB values of a mixer control, use one of
2687 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2688 variable containing this information, set the ``tlv.p`` field to point to
2692 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2706 variable to be defined. The second parameter is the minimum value, in
2708 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2713 linearly. The first parameter is the name of the variable to be defined.
2716 minimum value mutes the control, set the second parameter to
2723 -------
2725 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2726 write much code to control it. Only low-level control routines are
2730 -----------------
2743 struct mychip *chip = ac97->private_data;
2752 struct mychip *chip = ac97->private_data;
2754 /* write the given register value to the codec */
2757 static int snd_mychip_ac97(struct mychip *chip)
2767 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2771 ac97.private_data = chip;
2772 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2777 ----------------
2779 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2799 ac97.private_data = chip;
2800 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2802 where chip->ac97 is a pointer to a newly created ``ac97_t``
2803 instance. In this case, the chip pointer is set as the private data,
2804 so that the read/write callback functions can refer to this chip
2805 instance. This instance is not necessarily stored in the chip
2806 record. If you need to change the register values from the driver, or
2807 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2811 --------------
2814 correspond to the functions for read and write accesses to the
2815 hardware low-level codes.
2823 struct mychip *chip = ac97->private_data;
2828 Here, the chip can be cast from ``ac97->private_data``.
2830 Meanwhile, the ``write`` callback is used to set the register
2837 These callbacks are non-atomic like the control API callbacks.
2841 The ``reset`` callback is used to reset the codec. If the chip
2844 The ``wait`` callback is used to add some waiting time in the standard
2845 initialization of the codec. If the chip requires the extra waiting
2852 --------------------------------
2854 If you need to access to the codec from the driver, you can call the
2860 :c:func:`snd_ac97_update()` functions are used to set a value to
2869 :c:func:`snd_ac97_read()` is used to read the value of the given
2874 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2879 Also, there is a function to change the sample rate (of a given register
2886 The following registers are available to set the rate:
2893 ----------------
2896 (to save a quartz!). In this case, change the field ``bus->clock`` to
2898 their own function to read from the clock.
2901 ----------
2904 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2905 can refer to these files to see the current status and registers of
2909 ---------------
2911 When there are several codecs on the same card, you need to call
2915 If you set up multiple codecs, you either need to write different
2916 callbacks for each codec or check ``ac97->num`` in the callback
2919 MIDI (MPU401-UART) Interface
2923 -------
2925 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
2926 soundcard supports the standard MPU401-UART interface, most likely you
2927 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2934 ----------------
2936 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::
2944 this component. You can create up to 8 rawmidi devices.
2949 The 4th argument is the I/O port address. Many backward-compatible
2951 PCI I/O region. It depends on the chip design.
2957 mpu401-uart layer will allocate the I/O ports by itself.
2963 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
2965 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
2968 the default interrupt handler. The driver needs to call
2969 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
2972 If the MPU-401 interface shares its interrupt with the other logical
2976 Usually, the port address corresponds to the command port and port + 1
2977 corresponds to the data port. If not, you may change the ``cport``
2981 need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
2984 mpu = rmidi->private_data;
2988 mpu->cport = my_own_control_port;
2991 no interrupt is to be allocated (because your code is already allocating
2993 -1 instead. For a MPU-401 device without an interrupt, a polling timer
2997 ----------------------
3001 handler is automatically used, hence you don't have anything else to do
3002 than creating the mpu401 stuff. Otherwise, you have to set
3008 In this case, you need to pass the private_data of the returned rawmidi
3012 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3019 --------
3025 ALSA handles file and buffer management. All you have to do is to write
3026 some code to move data between the buffer and the hardware.
3031 -------------------
3033 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3037 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3040 rmidi->private_data = chip;
3041 strcpy(rmidi->name, "My MIDI");
3042 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3049 The third argument is the index of this component. You can create up to
3056 Set the ``info_flags`` field to specify the capabilities of the
3062 After the rawmidi device is created, you need to set the operators
3063 (callbacks) for each substream. There are helper functions to set the
3079 If there are more than one substream, you should give a unique name to
3084 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3086 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3091 -----------------
3094 device can be accessed as ``substream->rmidi->private_data``.
3097 index from the struct snd_rawmidi_substream data passed to each
3101 int index = substream->number;
3137 To read data from the buffer, call
3142 :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3168 before the substream buffer has been emptied, you have to continue
3183 This is called with a nonzero ``up`` parameter to enable receiving data,
3223 -------
3229 FM registers can be directly accessed through the direct-FM API, defined
3231 accessed through the Hardware-Dependent Device direct-FM extension API,
3233 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3235 To create the OPL3 component, you have two functions to call. The first
3249 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3263 ``opl3->private_data`` field.
3266 call :c:func:`snd_opl3_init()` to initialize the chip to the
3279 The third argument is the index-offset for the sequencer client assigned
3280 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3283 Hardware-Dependent Devices
3284 --------------------------
3286 Some chips need user-space access for special controls or for loading
3288 (hardware-dependent) device. The hwdep API is defined in
3300 You can then pass any pointer value to the ``private_data``. If you
3305 hw->private_data = p;
3306 hw->private_free = mydata_free;
3312 struct mydata *p = hw->private_data;
3318 this chip needs an ioctl::
3320 hw->ops.open = mydata_open;
3321 hw->ops.ioctl = mydata_ioctl;
3322 hw->ops.release = mydata_release;
3327 ---------------
3330 interface. There is a macro to compose a name string for IEC958
3340 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3342 returns the bitmask for professional mode. They are read-only controls.
3347 Due to historical reasons, both variants of the Playback Mask and the
3352 In addition, you can define the control switches to enable/disable or to
3353 set the raw bit mode. The implementation will depend on the chip, but
3364 ------------
3368 allocation of physically-contiguous pages is done via the
3374 to allocate the specified number of pages, but if not enough pages are
3375 available, it tries to reduce the request size until enough space
3376 is found, down to one page.
3378 To release the pages, call the :c:func:`snd_dma_free_pages()`
3381 Usually, ALSA drivers try to allocate and reserve a large contiguous
3383 is called “pre-allocation”. As already written, you can call the
3388 &pci->dev, size, max);
3390 where ``size`` is the byte size to be pre-allocated and ``max`` is
3392 allocator will try to get an area as large as possible within the
3397 (typically identical as ``card->dev``) to the third argument with
3400 A continuous buffer unrelated to the
3401 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3402 You can pass NULL to the device pointer in that case, which is the
3403 default mode implying to allocate with the ``GFP_KERNEL`` flag.
3406 device memory allocations. For this type, it's still allowed to pass
3407 NULL to the device pointer, too, if no address restriction is needed.
3409 For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3410 device pointer (see the `Non-Contiguous Buffers`_ section).
3412 Once the buffer is pre-allocated, you can use the allocator in the
3417 Note that you have to pre-allocate to use this function.
3425 &pci->dev, size, max);
3432 doesn't have to call these functions explicitly in its callback any
3433 longer. This allows many drivers to have NULL ``hw_params`` and
3437 -------------------------
3440 host memory is not available. In such a case, you need to either 1)
3441 copy/set the audio data directly to the external hardware buffer, or 2)
3442 make an intermediate buffer and copy/set the data from it to the
3447 efficient. You need to define the ``copy`` callback
3448 for the data transfer, in addition to the ``fill_silence``
3452 The second case allows for mmap on the buffer, although you have to
3453 handle an interrupt or a tasklet to transfer the data from the
3454 intermediate buffer to the hardware buffer. You can find an example in
3457 Another case is when the chip uses a PCI memory-map region for the
3459 on certain architectures like the Intel one. In non-mmap mode, the data
3460 cannot be transferred as in the normal way. Thus you need to define the
3467 interleaved or non-interleaved samples. The ``copy`` callback is
3485 The last argument is the number of bytes to be copied.
3487 What you have to do in this callback is again different between playback
3489 of data (``count``) at the specified pointer (``src``) to the specified
3490 offset (``pos``) in the hardware buffer. When coded like memcpy-like
3496 at the specified offset (``pos``) in the hardware buffer to the
3502 pointer and the size. Use the existing helpers to copy or access the
3508 it easier to unify both the interleaved and non-interleaved cases, as
3511 In the case of non-interleaved samples, the implementation will be a bit
3516 interleaved case. The callback is supposed to copy the data from/to
3517 the given user-space buffer, but only for the given channel. For
3533 The role of the ``fill_silence`` callback is to set the given amount
3536 silent-data is 0), and the implementation using a memset-like function
3541 In the case of non-interleaved samples, again, the implementation
3545 Non-Contiguous Buffers
3546 ----------------------
3549 descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
3550 provides an interface for handling SG-buffers. The API is provided in
3553 For creating the SG-buffer handler, call
3557 pre-allocations. You need to pass ``&pci->dev``, where pci is
3558 the struct pci_dev pointer of the chip as well::
3561 &pci->dev, size, max);
3564 ``substream->dma_private`` in turn. You can cast the pointer like::
3566 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3568 Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3569 handler will allocate the non-contiguous kernel pages of the given size
3571 is addressed via runtime->dma_area. The physical address
3572 (``runtime->dma_addr``) is set to zero, because the buffer is
3573 physically non-contiguous. The physical address table is set up in
3574 ``sgbuf->table``. You can get the physical address at a certain offset
3577 If you need to release the SG-buffer data explicitly, call the
3581 ------------------
3583 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3598 we don't need to pre-allocate the buffers like other continuous
3606 driver and want to get a running status or register dumps. The API is
3609 To create a proc file, call :c:func:`snd_card_proc_new()`::
3612 int err = snd_card_proc_new(card, "my-file", &entry);
3614 where the second argument specifies the name of the proc file to be
3615 created. The above example will create a file ``my-file`` under the
3616 card directory, e.g. ``/proc/asound/card0/my-file``.
3624 proc file for read only. To use this proc file as a read-only text file
3625 as-is, set the read callback with private data via
3628 snd_info_set_text_ops(entry, chip, my_proc_read);
3630 where the second argument (``chip``) is the private data to be used in
3645 struct my_chip *chip = entry->private_data;
3647 snd_iprintf(buffer, "This is my chip!\n");
3648 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3652 read only for all users. If you want to add write permission for the
3655 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3659 entry->c.text.write = my_proc_write;
3662 to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3666 For a raw-data proc-file, set the attributes as follows::
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;
3682 You need to use a low-level I/O functions such as
3683 :c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the
3694 return -EFAULT;
3699 ``pos`` are guaranteed to fit within 0 and the given size. You don't
3700 have to check the range in the callbacks unless any other condition is
3706 If the chip is supposed to work with suspend/resume functions, you need
3707 to add power-management code to the driver. The additional code for
3708 power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3712 properly resumed to its state when suspend was called, you can set the
3714 possible when the registers of the chip can be safely saved and restored
3715 to RAM. If this is set, the trigger callback is called with
3719 is still possible, it's still worthy to implement suspend/resume
3723 don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3729 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3731 to keep it for compatibility reasons.)
3733 The driver needs to define the
3734 suspend/resume hooks according to the bus the device is connected to. In
3750 1. Retrieve the card and the chip data.
3753 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3768 struct mychip *chip = card->private_data;
3772 snd_ac97_suspend(chip->ac97);
3774 snd_mychip_save_registers(chip);
3776 snd_mychip_stop_hardware(chip);
3783 1. Retrieve the card and the chip data.
3785 2. Re-initialize the chip.
3794 ``SNDRV_CTL_POWER_D0`` to notify the processes.
3802 struct mychip *chip = card->private_data;
3804 snd_mychip_reinit_chip(chip);
3806 snd_mychip_restore_registers(chip);
3808 snd_ac97_resume(chip->ac97);
3810 snd_mychip_restart_chip(chip);
3821 of the card, make sure that you can get the chip data from the card
3823 chip data individually::
3830 struct mychip *chip;
3833 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3836 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
3838 card->private_data = chip;
3842 When you created the chip data with :c:func:`snd_card_new()`, it's
3850 struct mychip *chip;
3853 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3856 chip = card->private_data;
3860 If you need space to save the registers, allocate the buffer for it
3865 And next, set suspend/resume callbacks to the pci_driver::
3885 If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
3895 case, but it would be better to have a dummy option for compatibility.
3903 #define CARD_NAME "My Chip"
3912 Also, don't forget to define the module description and the license.
3913 Especially, the recent modprobe requires to define the
3916 MODULE_DESCRIPTION("Sound driver for My Chip");
3920 Device-Managed Resources
3925 are lazier. So there are some ways to automate the release part; it's
3926 the (device-)managed resources aka devres or devm family. For
3930 ALSA core provides also the device-managed helper, namely,
3941 so be careful to put the hardware clean-up procedure in
3947 Another thing to be remarked is that you should use device-managed
3953 How To Put Your Driver Into ALSA Tree
3957 -------
3959 So far, you've learned how to write the driver codes. And you might have
3960 a question now: how to put my own driver into the ALSA driver tree? Here
3964 module name would be snd-xyz. The new driver is usually put into the
3965 alsa-driver tree, ``sound/pci`` directory in the case of PCI
3968 In the following sections, the driver code is supposed to be put into
3973 --------------------------------
3979 snd-xyz-y := xyz.o
3980 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3991 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.
3996 In addition to SND_PCM, the following components are supported for
4003 includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4006 For the details of Kconfig script, refer to the kbuild documentation.
4009 ---------------------------------
4011 Suppose that the driver snd-xyz have several source files. They are
4017 obj-$(CONFIG_SND) += sound/pci/xyz/
4022 snd-xyz-y := xyz.o abc.o def.o
4023 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4034 -------------------
4037 :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4043 ----------------------
4048 return -EINVAL;
4050 The macro takes an conditional expression to evaluate. When
4051 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4058 I would like to thank Phil Kerr for his help for improvement and
4061 Kevin Conder reformatted the original plain-text to the DocBook format.