Lines Matching +full:keep +full:- +full:power +full:- +full:in +full:- +full:suspend
11 Architecture) <http://www.alsa-project.org/>`__ driver. The document
12 focuses mainly on PCI soundcards. In the case of other device types, the
19 low-level driver implementation details. It only describes the standard
26 -------
56 --------------
59 drivers. In this directory, the native ALSA modules are stored. The
60 sub-directories contain different modules and are dependent upon the
66 The code for OSS PCM and mixer emulation modules is stored in this
67 directory. The OSS rawmidi emulation is included in the ALSA rawmidi
68 code since it's quite small. The sequencer code is stored in
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
77 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
85 -----------------
88 to be exported to user-space, or included by several files in different
89 directories. Basically, the private header files should not be placed in
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
135 The drivers compiled from a single file are stored directly in the pci
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 -------------
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
199 - create an ``exit`` function to call the
203 -----------------
206 this moment but will be filled in the next sections. The numbers in the
208 to details explained in the following section.
224 /* definition of the chip-specific record */
227 /* the rest of the implementation will be in section
232 /* chip-specific destructor
240 /* component-destructor
245 return snd_mychip_free(device->device_data);
248 /* chip-specific constructor
268 /* allocate a chip-specific data with zero filled */
271 return -ENOMEM;
273 chip->card = card;
290 /* constructor -- see "Driver Constructor" sub-section */
301 return -ENODEV;
304 return -ENOENT;
308 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
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
358 In the ``probe`` callback, the following scheme is often used.
368 return -ENODEV;
371 return -ENOENT;
390 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
394 The details will be explained in the section `Management of Cards and
400 In this part, the PCI resources are allocated::
408 The details will be explained in the section `PCI Resource
412 error. In this example, we have a single error handling path placed
420 :c:func:`snd_card_free()` call should suffice in most cases.
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);
434 by alsa-lib's configurator, so keep it simple but unique. Even the
439 field contains the information shown in ``/proc/asound/cards``.
446 `MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
459 Will be explained in the section `Management of Cards and
471 In the above, the card record is stored. This pointer is used in the
472 remove callback and power-management callbacks, too.
475 ----------
493 ------------
505 in the source file. If the code is split into several files, the files
508 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
513 The ALSA interfaces like the PCM and control APIs are defined in other
521 -------------
529 the power-management states and hotplug disconnections. The component
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
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 ----------
555 the card instance. In an ALSA driver, a component is represented as a
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
579 for each component is defined in the callback pointers. Hence, you don't
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,
611 In return, the allocated record can be accessed as
615 struct mychip *chip = card->private_data;
628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
643 Then, set the card pointer in the returned chip instance::
645 chip->card = card;
648 low-level device with a specified ``ops``::
656 :c:func:`snd_mychip_dev_free()` is the device-destructor
661 return snd_mychip_free(device->device_data);
668 registering and disconnecting the card via a setting in snd_device_ops.
674 ------------------------
695 -----------------
697 In this section, we'll complete the chip-specific constructor,
711 .... /* (not implemented in this document) */
714 if (chip->irq >= 0)
715 free_irq(chip->irq, chip);
717 pci_release_regions(chip->pci);
719 pci_disable_device(chip->pci);
725 /* chip-specific constructor */
747 return -ENXIO;
753 return -ENOMEM;
757 chip->card = card;
758 chip->pci = pci;
759 chip->irq = -1;
768 chip->port = pci_resource_start(pci, 0);
769 if (request_irq(pci->irq, snd_mychip_interrupt,
771 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
773 return -EBUSY;
775 chip->irq = pci->irq;
776 card->sync_irq = chip->irq;
779 .... /* (not implemented in this document) */
826 ------------
828 The allocation of PCI resources is done in the ``probe`` function, and
832 In the case of PCI devices, you first have to call the
835 accessed I/O range. In some cases, you might need to call
847 return -ENXIO;
852 -------------------
855 functions. These resources must be released in the destructor
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
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,
898 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
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
927 After requesting the IRQ, you can passed it to ``card->sync_irq``
930 card->irq = chip->irq;
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
953 :c:func:`pci_request_regions()` like in this example, release the
958 pci_release_regions(chip->pci);
962 :c:func:`release_resource()`. Suppose that you keep the resource
963 pointer returned from :c:func:`request_region()` in
964 chip->res_port, the release procedure looks like::
966 release_and_free_resource(chip->res_port);
971 And finally, release the chip-specific record::
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
1004 chip->iobase_phys = pci_resource_start(pci, 0);
1005 chip->iobase_virt = ioremap(chip->iobase_phys,
1013 if (chip->iobase_virt)
1014 iounmap(chip->iobase_virt);
1016 pci_release_regions(chip->pci);
1028 chip->iobase_virt = pci_iomap(pci, 0, 0);
1034 -----------
1056 device IDs. Such an example is found in the intel8x0 driver.
1059 all-zero entry.
1071 The ``probe`` and ``remove`` functions have already been defined in
1073 device. Note that you must not use slashes (“/”) in this string.
1099 -------
1102 for each driver to implement the low-level functions to access its
1106 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1118 playback of 32 stereo substreams. In this case, at each open, a free
1122 mode. But you don't have to care about such details in your driver. The
1126 -----------------
1176 struct snd_pcm_runtime *runtime = substream->runtime;
1178 runtime->hw = snd_mychip_playback_hw;
1179 /* more hardware-initialization will be done here */
1188 /* the hardware-specific codes will be here */
1198 struct snd_pcm_runtime *runtime = substream->runtime;
1200 runtime->hw = snd_mychip_capture_hw;
1201 /* more hardware-initialization will be done here */
1210 /* the hardware-specific codes will be here */
1219 /* the hardware-specific codes will be here */
1227 /* the hardware-specific codes will be here */
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);
1264 return -EINVAL;
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 ---------------
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;
1357 The third argument (``index``, 0 in the above) is the index of this new
1359 specify the different numbers in this argument. For example, ``index =
1368 numbers, but they must be handled properly in open/close, etc.
1374 int index = substream->number;
1396 All the callbacks are described in the Operators_ subsection.
1398 After setting the operators, you probably will want to pre-allocate the
1403 &chip->pci->dev,
1407 details will be described in the later section `Buffer and Memory
1410 Additionally, you can set some extra information for this PCM in
1411 ``pcm->info_flags``. The available values are defined as
1412 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1414 half-duplex, specify it like this::
1416 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1420 -----------------------
1427 internally and needed to release them. In such a case, set the
1428 destructor function to ``pcm->private_free``::
1434 kfree(chip->my_private_pcm_data);
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 ----------------------------------------------
1458 ``substream->runtime``. This runtime pointer holds most information you
1462 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1466 /* -- Status -- */
1474 /* -- HW params -- */
1478 unsigned int rate; /* rate in Hz */
1492 /* -- SW params -- */
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 */
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
1556 In the sections below, important records are explained.
1563 in the `PCM open callback`_. Note that the runtime instance holds a copy of
1565 in the open callback, you can modify the copied descriptor
1566 (``runtime->hw``) as you need. For example, if the maximum number of
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
1597 PCM. The bit flags are defined in ``<sound/asound.h>`` as
1602 interleaved or the non-interleaved formats, the
1607 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1614 the PCM supports the full “suspend/resume” operation. If the
1616 the corresponding (pause push/release) commands. The suspend/resume
1618 flag. See the `Power Management`_ section for details.
1622 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1623 need to check the linked-list of PCM substreams in the trigger
1624 callback. This will be described in a later section.
1626 - The ``formats`` field contains the bit-flags of supported formats
1628 format, give all or'ed bits. In the example above, the signed 16bit
1629 little-endian format is specified.
1631 - The ``rates`` field contains the bit-flags of supported rates
1633 pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
1638 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1641 - ``channels_min`` and ``channels_max`` define, as you might have already
1644 - ``buffer_bytes_max`` defines the maximum buffer size in
1648 define the minimum and maximum size of the period in bytes.
1650 number of periods in the buffer.
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.
1669 frequently referred records in the runtime instance are the PCM
1670 configurations. The PCM configurations are stored in the runtime
1672 alsa-lib. There are many fields copied from hw_params and sw_params
1678 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1679 channels \* samples-size``. For conversion between frames and bytes,
1683 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1685 Also, many software parameters (sw_params) are stored in frames, too.
1699 buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
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
1718 DMA hardware pointer via ``runtime->status->hw_ptr``.
1720 The DMA application pointer can be referred via ``runtime->control``,
1727 You can allocate a record for the substream and store it in
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;
1746 The allocated object must be released in the `close callback`_.
1749 ---------
1751 OK, now let me give details about each PCM callback (``ops``). In
1753 error number such as ``-EINVAL``. To choose an appropriate error
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``
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
1798 You can allocate private data in this callback, as described in the
1814 Any private instance for a PCM substream allocated in the ``open``
1820 kfree(substream->runtime->private_data);
1845 Many hardware setups should be done in this callback, including the
1859 DMA buffers have been pre-allocated. See the section `Buffer Types`_
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
1889 Also, the callback may be called multiple times, too. Keep track
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
1922 ``runtime->dma_area``. The buffer and period sizes are in
1923 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
1937 The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
1938 defined in ``<sound/pcm.h>``. At least, the ``START``
1939 and ``STOP`` commands must be defined in this callback::
1949 return -EINVAL;
1952 When the PCM supports the pause operation (given in the info field of
1957 When the PCM supports the suspend/resume operation, regardless of full
1958 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
1960 power-management status is changed. Obviously, the ``SUSPEND`` and
1961 ``RESUME`` commands suspend and resume the PCM substream, and usually,
1963 See the `Power Management`_ section for details.
1968 triggering the DMA. The other stuff should be initialized in
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.
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.
2010 hardware position in the buffer. The position must be returned in
2011 frames, ranging from 0 to ``buffer_size - 1``.
2013 This is usually called from the buffer-update routine in the PCM
2024 These callbacks are not mandatory, and can be omitted in most cases.
2025 These callbacks are used when the hardware buffer cannot be in the
2026 normal memory space. Some chips have their own buffer in the hardware
2027 which is not mappable. In such a case, you have to transfer the data
2029 buffer is non-contiguous on both physical and virtual memory spaces,
2032 If these two callbacks are defined, copy and set-silence operations
2033 are done by them. The details will be described in the later section
2040 ``appl_ptr`` is updated in read or write operations. Some drivers like
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,
2056 You need no special callback for the standard SG-buffer or vmalloc-
2064 memory-mapped, instead of using the standard helper.
2066 device-specific issues), implement everything here as you like.
2070 ---------------------
2074 interrupt handler in the sound driver is to update the buffer position
2085 interrupt at each period boundary. In this case, you can call
2089 its argument. Thus, you need to keep the substream pointer accessible
2090 from the chip instance. For example, define ``substream`` field in the
2094 If you acquire a spinlock in the interrupt handler, and the lock is used
2095 in other PCM callbacks, too, then you have to release the lock before
2106 spin_lock(&chip->lock);
2110 spin_unlock(&chip->lock);
2111 snd_pcm_period_elapsed(chip->substream);
2112 spin_lock(&chip->lock);
2116 spin_unlock(&chip->lock);
2133 or ymfpci drivers). In this case, you need to check the current hardware
2144 spin_lock(&chip->lock);
2148 /* get the current hardware pointer (in frames) */
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);
2183 In both cases, even if more than one period has elapsed, you don't have
2189 ---------
2191 One of the most important (and thus difficult to debug) problems in
2192 kernel programming are race conditions. In the Linux kernel, they are
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
2196 section. If the critical section is not in interrupt handler code and if
2201 example, the ``hw_params`` callback is non-atomic, while the ``trigger``
2202 callback is atomic. This means, the latter is called already in a
2204 take this atomicity into account when you choose a locking scheme in
2207 In the atomic callbacks, you cannot use functions which may call
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.
2217 This assumes that all call sites are in
2218 non-atomic contexts. For example, the function
2221 interrupt handler, this call can be in non-atomic context, too. In such
2224 in the PCM core instead of spin and rwlocks, so that you can call all PCM
2225 functions safely in a non-atomic
2228 Also, in some cases, you might need to call
2229 :c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
2236 -----------
2241 For example, in order to restrict the sample rates to some supported
2243 call this function in the open callback::
2257 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2269 specified in struct snd_pcm_hardware (or in any other
2281 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2292 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2294 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2310 if (c->min < 2) {
2318 ... and in the open callback::
2320 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2322 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2331 periods. In such a case, call
2335 snd_pcm_hw_constraint_integer(substream->runtime,
2350 -------
2353 which are accessed from user-space. Its most important use is the mixer
2354 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2357 ALSA has a well-defined AC97 control module. If your chip supports only
2360 The control API is defined in ``<sound/control.h>``. Include this file
2364 ----------------------
2393 its name. There are pre-defined standard control names. The details
2394 are described in the `Control Names`_ subsection.
2404 there. The details will be explained in the `Access Flags`_
2410 numbers are necessary, you can combine them in bitwise. Or, it's
2411 possible to store a pointer (casted to unsigned long) of some record in
2420 -------------
2427 pre-defined sources.
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)”.
2468 More precise information can be found in
2469 ``Documentation/sound/designs/control-names.rst``.
2472 ------------
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),
2498 -----------------
2512 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513 uinfo->count = 1;
2514 uinfo->value.integer.min = 0;
2515 uinfo->value.integer.max = 1;
2523 ``INTEGER64``. The ``count`` field specifies the number of elements in
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]);
2549 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2575 can be returned to user-space.
2583 ucontrol->value.integer.value[0] = get_some_value(chip);
2591 register offset, the bit-shift and the bit-mask. The ``private_value``
2596 and is retrieved in callbacks like::
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
2608 control has more than one element, i.e. ``count > 1``. In the example
2615 This callback is used to write a value coming from user-space.
2624 if (chip->current_value !=
2625 ucontrol->value.integer.value[0]) {
2627 ucontrol->value.integer.value[0]);
2639 As in the ``get`` callback, when the control has more than one
2640 element, all elements must be evaluated in this callback, too.
2645 All these three callbacks are not-atomic.
2648 -------------------
2654 In the simplest way, you can do it like this::
2661 and chip is the object pointer to be passed to kcontrol->private_data which
2662 can be referred to in callbacks.
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
2678 notification, for example, in the above example, the change of control
2680 to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2684 --------
2690 in the ``access`` field; like this::
2692 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2704 about a mixer control where each step in the control's value changes the
2706 variable to be defined. The second parameter is the minimum value, in
2707 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2714 The second parameter is the minimum value, in units of 0.01 dB. The
2715 third parameter is the maximum value, in units of 0.01 dB. If the
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
2727 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2730 -----------------
2743 struct mychip *chip = ac97->private_data;
2752 struct mychip *chip = ac97->private_data;
2767 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2772 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2777 ----------------
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,
2805 instance. This instance is not necessarily stored in the chip
2807 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2811 --------------
2815 hardware low-level codes.
2817 The ``read`` callback returns the register value specified in the
2823 struct mychip *chip = ac97->private_data;
2828 Here, the chip can be cast from ``ac97->private_data``.
2837 These callbacks are non-atomic like the control API callbacks.
2844 The ``wait`` callback is used to add some waiting time in the standard
2851 Updating Registers in The Driver
2852 --------------------------------
2874 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2893 ----------------
2895 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2896 (to save a quartz!). In this case, change the field ``bus->clock`` to
2901 ----------
2904 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2909 ---------------
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 ----------------
2949 The 4th argument is the I/O port address. Many backward-compatible
2955 might have been already allocated (reserved) by the driver itself. In
2957 mpu401-uart layer will allocate the I/O ports by itself.
2964 (via readb and writeb) instead of iob and outb. In this case, you have
2967 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
2970 processing the output stream in the irq handler.
2972 If the MPU-401 interface shares its interrupt with the other logical
2981 need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
2984 mpu = rmidi->private_data;
2988 mpu->cport = my_own_control_port;
2993 -1 instead. For a MPU-401 device without an interrupt, a polling timer
2997 ----------------------
2999 When the interrupt is allocated in
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 --------
3028 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3031 -------------------
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 |
3077 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3084 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3086 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3091 -----------------
3093 In all the callbacks, the private data that you've set for the rawmidi
3094 device can be accessed as ``substream->rmidi->private_data``.
3101 int index = substream->number;
3135 in the substream buffer that must be transmitted.
3140 requested when there are no more data in the buffer. After the data have
3169 transmitting data later, either in an interrupt handler, or with a
3187 from the device is usually done in an interrupt handler.
3215 This callback is optional. If you do not set ``drain`` in the struct
3223 -------
3225 The FM OPL3 is still used in many chips (mainly for backward
3227 is defined in ``<sound/opl3.h>``.
3229 FM registers can be directly accessed through the direct-FM API, defined
3230 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3231 accessed through the Hardware-Dependent Device direct-FM extension API,
3232 whereas in OSS compatible mode, FM registers can be accessed with the
3233 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3243 address, and the third is the right port address. In most cases, the
3249 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3263 ``opl3->private_data`` field.
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
3287 the micro code. In such a case, you can create a hwdep
3288 (hardware-dependent) device. The hwdep API is defined in
3289 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3302 destructor function is set in the ``private_free`` field::
3305 hw->private_data = p;
3306 hw->private_free = mydata_free;
3312 struct mydata *p = hw->private_data;
3317 operators are defined in the ``ops`` table. For example, assume that
3320 hw->ops.open = mydata_open;
3321 hw->ops.ioctl = mydata_ioctl;
3322 hw->ops.release = mydata_release;
3327 ---------------
3331 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
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.
3352 In addition, you can define the control switches to enable/disable or to
3364 ------------
3368 allocation of physically-contiguous pages is done via the
3383 is called “pre-allocation”. As already written, you can call the
3384 following function at PCM instance construction time (in the case of PCI
3388 &pci->dev, size, max);
3390 where ``size`` is the byte size to be pre-allocated and ``max`` is
3397 (typically identical as ``card->dev``) to the third argument with
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
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);
3428 The difference in the managed mode is that PCM core will call
3432 doesn't have to call these functions explicitly in its callback any
3437 -------------------------
3440 host memory is not available. In such a case, you need to either 1)
3443 external hardware buffer in interrupts (or in tasklets, preferably).
3448 for the data transfer, in addition to the ``fill_silence``
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
3458 buffer instead of the host memory. In this case, mmap is available only
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
3462 as in the cases above. Examples are found in ``rme32.c`` and
3467 interleaved or non-interleaved samples. The ``copy`` callback is
3478 In the case of interleaved samples, the second argument (``channel``) is
3479 not used. The third argument (``pos``) specifies the position in bytes.
3487 What you have to do in this callback is again different between playback
3488 and capture directions. In the playback case, you copy the given amount
3490 offset (``pos``) in the hardware buffer. When coded like memcpy-like
3496 at the specified offset (``pos``) in the hardware buffer to the
3503 data as defined in ``linux/uio.h``.
3506 arguments in bytes, not in frames like other callbacks. It's because
3507 this makes coding easier like in the examples above, and also it makes
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
3512 more complicated. The callback is called for each channel, passed in
3513 the second argument, so in total it's called N times per transfer.
3515 The meaning of the other arguments are almost the same as in the
3517 the given user-space buffer, but only for the given channel. For
3522 defined. It's implemented in a similar way as the copy callbacks
3528 The meanings of arguments are the same as in the ``copy`` callback,
3530 argument. In the case of interleaved samples, the channel argument has
3534 (``count``) of silence data at the specified offset (``pos``) in the
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 ----------------------
3548 If your hardware supports a page table as in emu10k1 or buffer
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
3556 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI
3557 pre-allocations. You need to pass ``&pci->dev``, where pci is
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 ------------------
3598 we don't need to pre-allocate the buffers like other continuous
3607 found in ``<sound/info.h>``.
3612 int err = snd_card_proc_new(card, "my-file", &entry);
3615 created. The above example will create a file ``my-file`` under the
3616 card directory, e.g. ``/proc/asound/card0/my-file``.
3620 automatically in the card registration and release functions.
3622 When the creation is successful, the function stores a new instance in
3623 the pointer given in the third argument. It is initialized as a text
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
3630 where the second argument (``chip``) is the private data to be used in
3638 In the read callback, use :c:func:`snd_iprintf()` for output
3645 struct my_chip *chip = entry->private_data;
3648 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3655 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3659 entry->c.text.write = my_proc_write;
3661 In the write callback, you can use :c:func:`snd_info_get_line()`
3663 a string from the line. Some examples are found in
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
3694 return -EFAULT;
3700 have to check the range in the callbacks unless any other condition is
3703 Power Management
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
3711 If the driver *fully* supports suspend/resume that is, the device can be
3712 properly resumed to its state when suspend was called, you can set the
3713 ``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
3718 Even if the driver doesn't support PM fully but partial suspend/resume
3719 is still possible, it's still worthy to implement suspend/resume
3720 callbacks. In such a case, applications would reset the status by
3722 appropriately. Hence, you can define suspend/resume callbacks below but
3725 Note that the trigger with SUSPEND can always be called when
3728 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3729 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3731 to keep it for compatibility reasons.)
3734 suspend/resume hooks according to the bus the device is connected to. In
3739 .... /* do things for suspend */
3744 .... /* do things for suspend */
3748 The scheme of the real suspend job is as follows:
3753 ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3768 struct mychip *chip = card->private_data;
3772 snd_ac97_suspend(chip->ac97);
3785 2. Re-initialize the chip.
3802 struct mychip *chip = card->private_data;
3808 snd_ac97_resume(chip->ac97);
3820 OK, we have all callbacks now. Let's set them up. In the initialization
3822 instance, typically via ``private_data`` field, in case you created the
3833 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3838 card->private_data = chip;
3853 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3856 chip = card->private_data;
3861 here, too, since it would be fatal if you cannot allocate a memory in
3862 the suspend phase. The allocated buffer should be released in the
3865 And next, set suspend/resume callbacks to the pci_driver::
3894 variables, instead. ``enable`` option is not always necessary in this
3920 Device-Managed Resources
3923 In the examples above, all resources are allocated and released
3924 manually. But human beings are lazy in nature, especially developers
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
3949 the card in that way. Mixing up with the normal and the managed
3957 -------
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
3993 the module will be called snd-xyz.
3996 In addition to SND_PCM, the following components are supported for
4009 ---------------------------------
4011 Suppose that the driver snd-xyz have several source files. They are
4012 located in the new subdirectory, sound/pci/xyz.
4014 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
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
4027 This procedure is as same as in the last section.
4034 -------------------
4043 ----------------------
4048 return -EINVAL;
4051 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4053 trace. In both cases it returns the evaluated value.
4061 Kevin Conder reformatted the original plain-text to the DocBook format.
4063 Giuliano Pochini corrected typos and contributed the example codes in