Lines Matching +full:no +full:- +full:tick +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
29 -------
61 --------------
64 drivers. In this directory, the native ALSA modules are stored. The
65 sub-directories contain different modules and are dependent upon the
71 The codes for PCM and mixer OSS emulation modules are stored in this
72 directory. The rawmidi OSS emulation is included in the ALSA rawmidi
73 code since it's quite small. The sequencer code is stored in
74 ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
79 This directory and its sub-directories are for the ALSA sequencer. This
81 like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
82 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
90 -----------------
93 to be exported to user-space, or included by several files at different
94 directories. Basically, the private header files should not be placed in
99 -----------------
102 architectures. They are hence supposed not to be architecture-specific.
104 in this directory. In the sub-directories, there is code for components
110 The MPU401 and MPU401-UART modules are stored here.
115 The OPL3 and OPL4 FM-synth stuff is found here.
118 -------------
127 ---------------
129 This contains the synth middle-level modules.
132 ``synth/emux`` sub-directory.
135 -------------
137 This directory and its sub-directories hold the top-level card modules
140 The drivers compiled from a single file are stored directly in the pci
142 their own sub-directory (e.g. emu10k1, ice1712).
145 -------------
147 This directory and its sub-directories hold the top-level card modules
151 -------------------------------
153 They are used for top-level card modules which are specific to one of
157 -------------
159 This directory contains the USB-audio driver. In the latest version, the
160 USB MIDI driver is integrated in the usb-audio driver.
163 ----------------
166 be in the pci directory, because their API is identical to that of
170 -------------
176 -------------
187 -------
191 - define the PCI ID table (see the section `PCI Entries`_).
193 - create ``probe`` callback.
195 - create ``remove`` callback.
197 - create a :c:type:`struct pci_driver <pci_driver>` structure
200 - create an ``init`` function just calling the
204 - create an ``exit`` function to call the
208 -----------------
211 this moment but will be filled in the next sections. The numbers in the
213 to details explained in the following section.
229 /* definition of the chip-specific record */
232 /* the rest of the implementation will be in section
237 /* chip-specific destructor
245 /* component-destructor
250 return snd_mychip_free(device->device_data);
253 /* chip-specific constructor
273 /* allocate a chip-specific data with zero filled */
276 return -ENOMEM;
278 chip->card = card;
295 /* constructor -- see "Driver Constructor" sub-section */
306 return -ENODEV;
309 return -ENOENT;
313 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
324 strcpy(card->driver, "My Chip");
325 strcpy(card->shortname, "My Own Chip 123");
326 sprintf(card->longname, "%s at 0x%lx irq %i",
327 card->shortname, chip->port, chip->irq);
347 /* destructor -- see the "Destructor" sub-section */
356 ------------------
359 ``probe`` callback and other component-constructors which are called
363 In the ``probe`` callback, the following scheme is often used.
373 return -ENODEV;
376 return -ENOENT;
385 <#set-the-pci-driver-data-and-return-zero>`__).
395 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
399 The details will be explained in the section `Management of Cards and
405 In this part, the PCI resources are allocated.
415 The details will be explained in the section `PCI Resource
419 error. In this example, we have a single error handling path placed
429 :c:func:`snd_card_free()` call should suffice in most cases.
437 strcpy(card->driver, "My Chip");
438 strcpy(card->shortname, "My Own Chip 123");
439 sprintf(card->longname, "%s at 0x%lx irq %i",
440 card->shortname, chip->port, chip->irq);
443 by alsa-lib's configurator, so keep it simple but unique. Even the
448 field contains the information shown in ``/proc/asound/cards``.
453 Here you define the basic components such as `PCM <#PCM-Interface>`__,
454 mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
455 `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
456 Also, if you want a `proc file <#Proc-Interface>`__, define it here,
468 Will be explained in the section `Management of Cards and
480 In the above, the card record is stored. This pointer is used in the
481 remove callback and power-management callbacks, too.
484 ----------
504 ------------
518 in the source file. If the code is split into several files, the files
521 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
526 The ALSA interfaces like the PCM and control APIs are defined in other
534 -------------
542 the power-management states and hotplug disconnections. The component
553 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
557 card-index number, the id string, the module pointer (usually
558 ``THIS_MODULE``), the size of extra-data space, and the pointer to
560 card->private_data for the chip-specific data. Note that these data are
565 ``&pci->`` is passed there.
568 ----------
571 the card instance. In an ALSA driver, a component is represented as a
583 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
584 data pointer, and the callback pointers (``&ops``). The device-level
586 de-registration. For most components, the device-level is already
587 defined. For a user-defined component, you can use
592 argument. This pointer (``chip`` in the above example) is used as the
595 Each pre-defined ALSA component such as ac97 and pcm calls
597 for each component is defined in the callback pointers. Hence, you don't
601 function to the dev_free callback in the ``ops``, so that it can be
603 example will show an implementation of chip-specific data.
605 Chip-Specific Data
606 ------------------
608 Chip-specific information, e.g. the I/O port address, its resource
609 pointer, or the irq number, is stored in the chip-specific record.
618 In general, there are two ways of allocating the chip record.
623 As mentioned above, you can pass the extra-data-length to the 5th
628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
633 In return, the allocated record can be accessed as
637 struct mychip *chip = card->private_data;
652 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
667 Then, set the card pointer in the returned chip instance.
671 chip->card = card;
674 low-level device with a specified ``ops``,
684 :c:func:`snd_mychip_dev_free()` is the device-destructor
691 return snd_mychip_free(device->device_data);
698 and disconnecting the card via setting in snd_device_ops.
704 ------------------------
725 -----------------
727 In this section, we'll complete the chip-specific constructor,
743 .... /* (not implemented in this document) */
746 if (chip->irq >= 0)
747 free_irq(chip->irq, chip);
749 pci_release_regions(chip->pci);
751 pci_disable_device(chip->pci);
757 /* chip-specific constructor */
779 return -ENXIO;
785 return -ENOMEM;
789 chip->card = card;
790 chip->pci = pci;
791 chip->irq = -1;
800 chip->port = pci_resource_start(pci, 0);
801 if (request_irq(pci->irq, snd_mychip_interrupt,
803 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
805 return -EBUSY;
807 chip->irq = pci->irq;
810 .... /* (not implemented in this document) */
857 ------------
859 The allocation of PCI resources is done in the ``probe`` function, and
863 In the case of PCI devices, you first have to call the
866 accessed I/O range. In some cases, you might need to call
880 return -ENXIO;
885 -------------------
888 functions. These resources must be released in the destructor
908 this number as -1 before actual allocation, since irq 0 is valid. The
923 chip->port = pci_resource_start(pci, 0);
926 The returned value, ``chip->res_port``, is allocated via
935 if (request_irq(pci->irq, snd_mychip_interrupt,
937 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
939 return -EBUSY;
941 chip->irq = pci->irq;
944 defined `later <#pcm-interface-interrupt-handler>`__. Note that
945 ``chip->irq`` should be defined only when :c:func:`request_irq()`
952 passed to the interrupt handler. Usually, the chip-specific record is
971 activated) and release the resources. So far, we have no hardware part,
974 To release the resources, the “check-and-release” method is a safer way.
979 if (chip->irq >= 0)
980 free_irq(chip->irq, chip);
983 ``chip->irq`` with a negative value (e.g. -1), so that you can check
988 :c:func:`pci_request_regions()` like in this example, release the
995 pci_release_regions(chip->pci);
1000 pointer returned from :c:func:`request_region()` in
1001 chip->res_port, the release procedure looks like:
1005 release_and_free_resource(chip->res_port);
1010 And finally, release the chip-specific record.
1016 We didn't implement the hardware disabling part in the above. If you
1022 When the chip-data is assigned to the card using
1026 have to stop PCMs, etc. explicitly, but just call low-level hardware
1029 The management of a memory-mapped region is almost as same as the
1050 chip->iobase_phys = pci_resource_start(pci, 0);
1051 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1061 if (chip->iobase_virt)
1062 iounmap(chip->iobase_virt);
1064 pci_release_regions(chip->pci);
1078 chip->iobase_virt = pci_iomap(pci, 0, 0);
1084 -----------
1105 have no reason to filter the matching devices, you can leave the
1110 in the intel8x0 driver.
1113 all-zero entry.
1127 The ``probe`` and ``remove`` functions have already been defined in
1129 device. Note that you must not use a slash “/” in this string.
1157 -------
1160 for each driver to implement the low-level functions to access its
1164 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1176 playback of 32 stereo substreams. In this case, at each open, a free
1180 mode. But you don't have to care about such details in your driver. The
1184 -----------------
1236 struct snd_pcm_runtime *runtime = substream->runtime;
1238 runtime->hw = snd_mychip_playback_hw;
1239 /* more hardware-initialization will be done here */
1248 /* the hardware-specific codes will be here */
1258 struct snd_pcm_runtime *runtime = substream->runtime;
1260 runtime->hw = snd_mychip_capture_hw;
1261 /* more hardware-initialization will be done here */
1270 /* the hardware-specific codes will be here */
1294 struct snd_pcm_runtime *runtime = substream->runtime;
1299 mychip_set_sample_format(chip, runtime->format);
1300 mychip_set_sample_rate(chip, runtime->rate);
1301 mychip_set_channels(chip, runtime->channels);
1302 mychip_set_dma_setup(chip, runtime->dma_addr,
1303 chip->buffer_size,
1304 chip->period_size);
1322 return -EINVAL;
1372 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1375 pcm->private_data = chip;
1376 strcpy(pcm->name, "My Chip");
1377 chip->pcm = pcm;
1383 /* pre-allocation of buffers */
1386 snd_dma_pci_data(chip->pci),
1393 ---------------
1405 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1408 pcm->private_data = chip;
1409 strcpy(pcm->name, "My Chip");
1410 chip->pcm = pcm;
1419 The third argument (``index``, 0 in the above) is the index of this new
1421 specify the different numbers in this argument. For example, ``index =
1425 and capture, respectively. Here 1 is used for both arguments. When no
1430 numbers, but they must be handled properly in open/close, etc.
1438 int index = substream->number;
1465 All the callbacks are described in the Operators_ subsection.
1467 After setting the operators, you probably will want to pre-allocate the
1468 buffer. For the pre-allocation, simply call the following:
1473 snd_dma_pci_data(chip->pci),
1477 details will be described in the later section `Buffer and Memory
1480 Additionally, you can set some extra information for this pcm in
1481 ``pcm->info_flags``. The available values are defined as
1482 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1484 half-duplex, specify like this:
1488 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1492 -----------------------
1499 internally and needed to release them. In such a case, set the
1500 destructor function to ``pcm->private_free``:
1508 kfree(chip->my_private_pcm_data);
1518 chip->my_private_pcm_data = kmalloc(...);
1520 pcm->private_data = chip;
1521 pcm->private_free = mychip_pcm_free;
1527 Runtime Pointer - The Chest of PCM Information
1528 ----------------------------------------------
1532 ``substream->runtime``. This runtime pointer holds most information you
1536 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1542 /* -- Status -- */
1550 /* -- HW params -- */
1554 unsigned int rate; /* rate in Hz */
1559 unsigned int tick_time; /* tick time */
1568 /* -- SW params -- */
1584 /* -- mmap -- */
1589 /* -- locking / scheduling -- */
1595 /* -- private section -- */
1599 /* -- hardware description -- */
1603 /* -- timer -- */
1606 /* -- DMA -- */
1614 /* -- OSS things -- */
1621 records are supposed to be read-only. Only the PCM middle-layer changes
1628 In the sections below, important records are explained.
1635 hardware configuration. Above all, you'll need to define this in the
1638 in the open callback, you can modify the copied descriptor
1639 (``runtime->hw``) as you need. For example, if the maximum number of
1645 struct snd_pcm_runtime *runtime = substream->runtime;
1647 runtime->hw = snd_mychip_playback_hw; /* common definition */
1648 if (chip->model == VERY_OLD_ONE)
1649 runtime->hw.channels_max = 1;
1673 - The ``info`` field contains the type and capabilities of this
1674 pcm. The bit flags are defined in ``<sound/asound.h>`` as
1679 interleaved or the non-interleaved formats,
1684 In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1691 the pcm supports the full “suspend/resume” operation. If the
1693 the corresponding (pause push/release) commands. The suspend/resume
1699 can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1700 need to check the linked-list of PCM substreams in the trigger
1701 callback. This will be described in the later section.
1703 - ``formats`` field contains the bit-flags of supported formats
1705 format, give all or'ed bits. In the example above, the signed 16bit
1706 little-endian format is specified.
1708 - ``rates`` field contains the bit-flags of supported rates
1710 pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1715 - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1718 - ``channel_min`` and ``channel_max`` define, as you might already
1721 - ``buffer_bytes_max`` defines the maximum buffer size in
1722 bytes. There is no ``buffer_bytes_min`` field, since it can be
1725 maximum size of the period in bytes. ``periods_max`` and
1726 ``periods_min`` define the maximum and minimum number of periods in
1729 The “period” is a term that corresponds to a fragment in the OSS
1733 more controls. In the case of capture, this size defines the input
1737 - There is also a field ``fifo_size``. This specifies the size of the
1738 hardware FIFO, but currently it is neither used in the driver nor
1739 in the alsa-lib. So, you can ignore this field.
1745 frequently referred records in the runtime instance are the PCM
1746 configurations. The PCM configurations are stored in the runtime
1748 alsa-lib. There are many fields copied from hw_params and sw_params
1754 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1755 channels \* samples-size``. For conversion between frames and bytes,
1761 period_bytes = frames_to_bytes(runtime, runtime->period_size);
1763 Also, many software parameters (sw_params) are stored in frames, too.
1777 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1784 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1793 The running status can be referred via ``runtime->status``. This is
1796 DMA hardware pointer via ``runtime->status->hw_ptr``.
1798 The DMA application pointer can be referred via ``runtime->control``,
1806 You can allocate a record for the substream and store it in
1807 ``runtime->private_data``. Usually, this is done in the `PCM open
1808 callback`_. Don't mix this with ``pcm->private_data``. The
1809 ``pcm->private_data`` usually points to the chip instance assigned
1810 statically at the creation of PCM, while the ``runtime->private_data``
1821 substream->runtime->private_data = data;
1826 The allocated object must be released in the `close callback`_.
1829 ---------
1831 OK, now let me give details about each pcm callback (``ops``). In
1833 error number such as ``-EINVAL``. To choose an appropriate error
1849 The macro reads ``substream->private_data``, which is a copy of
1850 ``pcm->private_data``. You can override the former if you need to
1853 capture directions, because it uses two different codecs (SB- and
1854 AD-compatible) for different directions.
1865 At least, here you have to initialize the ``runtime->hw``
1873 struct snd_pcm_runtime *runtime = substream->runtime;
1875 runtime->hw = snd_mychip_playback_hw;
1879 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1882 You can allocate a private data in this callback, as described in
1898 Any private instance for a pcm substream allocated in the ``open``
1906 kfree(substream->runtime->private_data);
1928 Many hardware setups should be done in this callback, including the
1940 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1952 Another note is that this callback is non-atomic (schedulable) as
1953 default, i.e. when no ``nonatomic`` flag set. This is important,
1954 because the ``trigger`` callback is atomic (non-schedulable). That is,
1955 mutexes or any schedule-related functions are not available in
1992 Note that this callback is now non-atomic. You can use
1993 schedule-related functions safely in this callback.
1995 In this and the following callbacks, you can refer to the values via
1996 the runtime record, ``substream->runtime``. For example, to get the
1997 current rate, format or channels, access to ``runtime->rate``,
1998 ``runtime->format`` or ``runtime->channels``, respectively. The
2000 ``runtime->dma_area``. The buffer and period sizes are in
2001 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2015 Which action is specified in the second argument,
2016 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2017 and ``STOP`` commands must be defined in this callback.
2029 return -EINVAL;
2032 When the pcm supports the pause operation (given in the info field of
2037 When the pcm supports the suspend/resume operation, regardless of full
2038 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2040 power-management status is changed. Obviously, the ``SUSPEND`` and
2041 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2059 hardware position on the buffer. The position must be returned in
2060 frames, ranging from 0 to ``buffer_size - 1``.
2062 This is called usually from the buffer-update routine in the pcm
2064 is called in the interrupt routine. Then the pcm middle layer updates
2073 These callbacks are not mandatory, and can be omitted in most cases.
2074 These callbacks are used when the hardware buffer cannot be in the
2076 which is not mappable. In such a case, you have to transfer the data
2078 buffer is non-contiguous on both physical and virtual memory spaces,
2081 If these two callbacks are defined, copy and set-silence operations
2082 are done by them. The detailed will be described in the later section
2089 ``appl_ptr`` is updated in read or write operations. Some drivers like
2090 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2099 non-contiguous buffers. The mmap calls this callback to get the page
2100 address. Some examples will be explained in the later section `Buffer
2108 memory-mapped instead of dealing via the standard helper.
2110 device-specific issues), implement everything here as you like.
2114 ---------------------
2117 interrupt handler in the sound driver is to update the buffer position
2128 interrupt at each period boundary. In this case, you can call
2133 from the chip instance. For example, define ``substream`` field in the
2137 If you acquire a spinlock in the interrupt handler, and the lock is used
2138 in other pcm callbacks, too, then you have to release the lock before
2151 spin_lock(&chip->lock);
2155 spin_unlock(&chip->lock);
2156 snd_pcm_period_elapsed(chip->substream);
2157 spin_lock(&chip->lock);
2161 spin_unlock(&chip->lock);
2172 or ymfpci drivers). In this case, you need to check the current hardware
2185 spin_lock(&chip->lock);
2189 /* get the current hardware pointer (in frames) */
2194 if (last_ptr < chip->last_ptr)
2195 size = runtime->buffer_size + last_ptr
2196 - chip->last_ptr;
2198 size = last_ptr - chip->last_ptr;
2200 chip->last_ptr = last_ptr;
2202 chip->size += size;
2204 if (chip->size >= runtime->period_size) {
2206 chip->size %= runtime->period_size;
2208 spin_unlock(&chip->lock);
2210 spin_lock(&chip->lock);
2215 spin_unlock(&chip->lock);
2224 In both cases, even if more than one period are elapsed, you don't have
2230 ---------
2232 One of the most important (and thus difficult to debug) problems in
2233 kernel programming are race conditions. In the Linux kernel, they are
2234 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2235 race condition can happen in an interrupt handler, it has to be managed
2237 session. If the critical section is not in interrupt handler code and if
2242 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2243 callback is atomic. This means, the latter is called already in a
2245 account when you choose a locking scheme in the callbacks.
2247 In the atomic callbacks, you cannot use functions which may call
2250 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2256 The recent changes in PCM core code, however, allow all PCM operations
2257 to be non-atomic. This assumes that the all caller sides are in
2258 non-atomic contexts. For example, the function
2261 interrupt handler, this call can be in non-atomic context, too. In such
2264 and rwsem are used internally in the PCM core instead of spin and
2265 rwlocks, so that you can call all PCM functions safely in a non-atomic
2269 -----------
2274 For example, in order to restrict the sample rates in the some supported
2276 call this function in the open callback.
2292 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2306 specified in the :c:type:`struct snd_pcm_hardware
2307 <snd_pcm_hardware>` structure (or in any other
2321 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2334 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2336 SNDRV_PCM_HW_PARAM_FORMAT, -1);
2354 if (c->min < 2) {
2362 ... and in the open callback:
2366 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2368 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2377 periods. In such a case, call
2383 snd_pcm_hw_constraint_integer(substream->runtime,
2398 -------
2401 which are accessed from user-space. Its most important use is the mixer
2402 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2405 ALSA has a well-defined AC97 control module. If your chip supports only
2408 The control API is defined in ``<sound/control.h>``. Include this file
2412 ----------------------
2443 its name. There are pre-defined standard control names. The details
2444 are described in the `Control Names`_ subsection.
2454 there. The details will be explained in the `Access Flags`_
2460 numbers are necessary, you can combine them in bitwise. Or, it's
2470 -------------
2477 pre-defined sources.
2500 Tone-controls
2503 tone-control switch and volumes are specified like “Tone Control - XXX”,
2504 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2510 3D-control switches and volumes are specified like “3D Control - XXX”,
2511 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2516 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2518 More precise information can be found in
2519 ``Documentation/sound/designs/control-names.rst``.
2522 ------------
2530 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2531 instead. In this case, you don't have to define the ``put`` callback.
2532 Similarly, when the control is write-only (although it's a rare case),
2545 -----------------
2561 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2562 uinfo->count = 1;
2563 uinfo->value.integer.min = 0;
2564 uinfo->value.integer.max = 1;
2572 ``INTEGER64``. The ``count`` field specifies the number of elements in
2588 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2589 uinfo->count = 1;
2590 uinfo->value.enumerated.items = 4;
2591 if (uinfo->value.enumerated.item > 3)
2592 uinfo->value.enumerated.item = 3;
2593 strcpy(uinfo->value.enumerated.name,
2594 texts[uinfo->value.enumerated.item]);
2600 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2626 return to user-space.
2637 ucontrol->value.integer.value[0] = get_some_value(chip);
2645 register offset, the bit-shift and the bit-mask. The ``private_value``
2652 and is retrieved in callbacks like
2659 int reg = kcontrol->private_value & 0xff;
2660 int shift = (kcontrol->private_value >> 16) & 0xff;
2661 int mask = (kcontrol->private_value >> 24) & 0xff;
2665 In the ``get`` callback, you have to fill all the elements if the
2666 control has more than one elements, i.e. ``count > 1``. In the example
2673 This callback is used to write a value from user-space.
2685 if (chip->current_value !=
2686 ucontrol->value.integer.value[0]) {
2688 ucontrol->value.integer.value[0]);
2700 As in the ``get`` callback, when the control has more than one
2701 elements, all elements must be evaluated in this callback, too.
2709 -------------------
2715 In the simplest way, you can do like this:
2725 pointer to be passed to kcontrol->private_data which can be referred
2726 to in callbacks.
2734 -------------------
2736 If you need to change and update a control in the interrupt routine, you
2743 This function takes the card pointer, the event-mask, and the control id
2744 pointer for the notification. The event-mask specifies the types of
2745 notification, for example, in the above example, the change of control
2748 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2752 --------
2758 in the ``access`` field; like this:
2762 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2774 about a mixer control where each step in the control's value changes the
2776 variable to be defined. The second parameter is the minimum value, in
2777 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2784 The second parameter is the minimum value, in units of 0.01 dB. The
2785 third parameter is the maximum value, in units of 0.01 dB. If the
2793 -------
2795 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2796 write much code to control it. Only low-level control routines are
2797 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2800 -----------------
2813 struct mychip *chip = ac97->private_data;
2822 struct mychip *chip = ac97->private_data;
2837 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2842 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2847 ----------------
2875 snd_ac97_mixer(bus, &ac97, &chip->ac97);
2877 where chip->ac97 is a pointer to a newly created ``ac97_t``
2878 instance. In this case, the chip pointer is set as the private data,
2880 instance. This instance is not necessarily stored in the chip
2882 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2886 --------------
2890 hardware low-level codes.
2892 The ``read`` callback returns the register value specified in the
2900 struct mychip *chip = ac97->private_data;
2905 Here, the chip can be cast from ``ac97->private_data``.
2916 These callbacks are non-atomic like the control API callbacks.
2923 The ``wait`` callback is used to add some waiting time in the standard
2930 Updating Registers in The Driver
2931 --------------------------------
2957 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2980 ----------------
2982 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2983 (to save a quartz!). In this case, change the field ``bus->clock`` to
2988 ----------
2991 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2996 ---------------
3003 callbacks for each codec or check ``ac97->num`` in the callback
3006 MIDI (MPU401-UART) Interface
3010 -------
3012 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3013 soundcard supports the standard MPU401-UART interface, most likely you
3014 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3021 ----------------
3038 The 4th argument is the I/O port address. Many backward-compatible
3044 might have been already allocated (reserved) by the driver itself. In
3046 mpu401-uart layer will allocate the I/O ports by itself.
3053 (via readb and writeb) instead of iob and outb. In this case, you have
3056 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3059 processing the output stream in the irq handler.
3061 If the MPU-401 interface shares its interrupt with the other logical
3063 `below <#MIDI-Interrupt-Handler>`__).
3070 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3076 mpu = rmidi->private_data;
3082 mpu->cport = my_own_control_port;
3085 no interrupt is to be allocated (because your code is already allocating
3087 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3091 ----------------------
3093 When the interrupt is allocated in
3102 In this case, you need to pass the private_data of the returned rawmidi
3108 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3115 --------
3124 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3127 -------------------
3135 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3138 rmidi->private_data = chip;
3139 strcpy(rmidi->name, "My MIDI");
3140 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3179 These callbacks are explained in the `RawMIDI Callbacks`_ section.
3188 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3190 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3195 -----------------
3197 In all the callbacks, the private data that you've set for the rawmidi
3198 device can be accessed as ``substream->rmidi->private_data``.
3207 int index = substream->number;
3241 in the substream buffer that must be transmitted.
3246 requested when there are no more data in the buffer. After the data have
3270 break; /* no more data */
3280 transmitting data later, either in an interrupt handler, or with a
3298 from the device is usually done in an interrupt handler.
3328 This callback is optional. If you do not set ``drain`` in the struct
3336 -------
3338 The FM OPL3 is still used in many chips (mainly for backward
3340 is defined in ``<sound/opl3.h>``.
3342 FM registers can be directly accessed through the direct-FM API, defined
3343 in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3344 accessed through the Hardware-Dependent Device direct-FM extension API,
3345 whereas in OSS compatible mode, FM registers can be accessed with the
3346 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3358 address, and the third is the right port address. In most cases, the
3364 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3380 ``opl3->private_data`` field.
3398 The third argument is the index-offset for the sequencer client assigned
3399 to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3402 Hardware-Dependent Devices
3403 --------------------------
3405 Some chips need user-space access for special controls or for loading
3406 the micro code. In such a case, you can create a hwdep
3407 (hardware-dependent) device. The hwdep API is defined in
3408 ``<sound/hwdep.h>``. You can find examples in opl3 driver or
3423 destructor function is set in the ``private_free`` field.
3428 hw->private_data = p;
3429 hw->private_free = mydata_free;
3437 struct mydata *p = hw->private_data;
3442 operators are defined in the ``ops`` table. For example, assume that
3447 hw->ops.open = mydata_open;
3448 hw->ops.ioctl = mydata_ioctl;
3449 hw->ops.release = mydata_release;
3454 ---------------
3458 controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3467 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3469 returns the bitmask for professional mode. They are read-only controls,
3476 although in some places it's defined as a MIXER control.
3478 In addition, you can define the control switches to enable/disable or to
3490 ------------
3494 allocation of physically-contiguous pages is done via
3508 is called “pre-allocation”. As already written, you can call the
3509 following function at pcm instance construction time (in the case of PCI
3517 where ``size`` is the byte size to be pre-allocated and the ``max`` is
3524 (typically identical as ``card->dev``) to the third argument with
3526 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the
3529 scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the device
3530 pointer (see the `Non-Contiguous Buffers`_
3533 Once the buffer is pre-allocated, you can use the allocator in the
3540 Note that you have to pre-allocate to use this function.
3543 -------------------------
3546 host memory is not available. In such a case, you need to either 1)
3549 external hardware buffer in interrupts (or in tasklets, preferably).
3554 callbacks for the data transfer, in addition to ``fill_silence``
3560 intermediate buffer to the hardware buffer. You can find an example in
3563 Another case is when the chip uses a PCI memory-map region for the
3564 buffer instead of the host memory. In this case, mmap is available only
3565 on certain architectures like the Intel one. In non-mmap mode, the data
3566 cannot be transferred as in the normal way. Thus you need to define the
3568 as in the cases above. The examples are found in ``rme32.c`` and
3573 interleaved or non-interleaved samples. The ``copy_user`` callback is
3586 In the case of interleaved samples, the second argument (``channel``) is
3588 offset in bytes.
3596 What you have to do in this callback is again different between playback
3597 and capture directions. In the playback case, you copy the given amount
3599 offset (``pos``) on the hardware buffer. When coded like memcpy-like
3615 it's the user-space buffer that is passed to these callbacks. That
3616 is, the callback is supposed to copy from/to the user-space data
3620 arguments in bytes, not in frames like other callbacks. It's because
3622 easier to unify both the interleaved and non-interleaved cases, as
3623 explained in the following.
3625 In the case of non-interleaved samples, the implementation will be a bit
3627 the second argument, so totally it's called for N-channels times per
3632 user-space buffer, but only for the given channel. For the detailed
3636 The above callbacks are the copy from/to the user-space buffer. There
3637 are some cases where we want copy from/to the kernel-space buffer
3638 instead. In such a case, ``copy_kernel`` callback is called. It'd
3651 without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3652 in the fourth argument. Correspondingly, the implementation would be
3653 a version without the user-copy, such as:
3660 defined. It's implemented in a similar way as the copy callbacks
3668 The meanings of arguments are the same as in the ``copy_user`` and
3669 ``copy_kernel`` callbacks, although there is no buffer pointer
3670 argument. In the case of interleaved samples, the channel argument has
3671 no meaning, as well as on ``copy_*`` callbacks.
3676 silent-data is 0), and the implementation using a memset-like function
3683 In the case of non-interleaved samples, again, the implementation
3684 becomes a bit more complicated, as it's called N-times per transfer
3687 Non-Contiguous Buffers
3688 ----------------------
3690 If your hardware supports the page table as in emu10k1 or the buffer
3691 descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3692 provides an interface for handling SG-buffers. The API is provided in
3695 For creating the SG-buffer handler, call
3698 ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3699 pre-allocator. You need to pass ``snd_dma_pci_data(pci)``, where pci is
3702 ``substream->dma_private``. You can cast the pointer like:
3706 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3708 Then call :c:func:`snd_pcm_lib_malloc_pages()` in the ``hw_params``
3709 callback as well as in the case of normal PCI buffer. The SG-buffer
3710 handler will allocate the non-contiguous kernel pages of the given size
3712 is addressed in runtime->dma_area. The physical address
3713 (``runtime->dma_addr``) is set to zero, because the buffer is
3714 physically non-contiguous. The physical address table is set up in
3715 ``sgbuf->table``. You can get the physical address at a certain offset
3718 When a SG-handler is used, you need to set
3722 To release the data, call :c:func:`snd_pcm_lib_free_pages()` in
3726 ------------------
3750 void *pageptr = substream->runtime->dma_area + offset;
3760 found in ``<sound/info.h>``.
3767 int err = snd_card_proc_new(card, "my-file", &entry);
3770 created. The above example will create a file ``my-file`` under the
3771 card directory, e.g. ``/proc/asound/card0/my-file``.
3775 automatically in the card registration and release functions.
3777 When the creation is successful, the function stores a new instance in
3778 the pointer given in the third argument. It is initialized as a text
3779 proc file for read only. To use this proc file as a read-only text file
3787 where the second argument (``chip``) is the private data to be used in
3797 In the read callback, use :c:func:`snd_iprintf()` for output
3806 struct my_chip *chip = entry->private_data;
3809 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3818 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3824 entry->c.text.write = my_proc_write;
3828 a string from the line. Some examples are found in
3831 For a raw-data proc-file, set the attributes as follows:
3839 entry->content = SNDRV_INFO_CONTENT_DATA;
3840 entry->private_data = chip;
3841 entry->c.ops = &my_file_io_ops;
3842 entry->size = 4096;
3843 entry->mode = S_IFREG | S_IRUGO;
3849 You need to use a low-level I/O functions such as
3862 return -EFAULT;
3868 have to check the range in the callbacks unless any other condition is
3874 If the chip is supposed to work with suspend/resume functions, you need
3875 to add power-management code to the driver. The additional code for
3876 power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3880 If the driver *fully* supports suspend/resume that is, the device can be
3881 properly resumed to its state when suspend was called, you can set the
3882 ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3887 Even if the driver doesn't support PM fully but partial suspend/resume
3888 is still possible, it's still worthy to implement suspend/resume
3889 callbacks. In such a case, applications would reset the status by
3891 appropriately. Hence, you can define suspend/resume callbacks below but
3894 Note that the trigger with SUSPEND can always be called when
3897 behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3898 ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3899 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3902 In the earlier version of ALSA drivers, a common power-management layer
3904 suspend/resume hooks according to the bus the device is connected to. In
3911 .... /* do things for suspend */
3916 .... /* do things for suspend */
3920 The scheme of the real suspend job is as follows.
3942 struct mychip *chip = card->private_data;
3946 snd_ac97_suspend(chip->ac97);
3959 2. Re-initialize the chip.
3978 struct mychip *chip = card->private_data;
3984 snd_ac97_resume(chip->ac97);
3996 OK, we have all callbacks now. Let's set them up. In the initialization
3998 instance, typically via ``private_data`` field, in case you created the
4011 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4016 card->private_data = chip;
4033 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4036 chip = card->private_data;
4041 here, too, since it would be fatal if you cannot allocate a memory in
4042 the suspend phase. The allocated buffer should be released in the
4045 And next, set suspend/resume callbacks to the pci_driver.
4076 variables, instead. ``enable`` option is not always necessary in this
4110 -------
4117 module name would be snd-xyz. The new driver is usually put into the
4118 alsa-driver tree, ``sound/pci`` directory in the case of PCI
4121 In the following sections, the driver code is supposed to be put into
4126 --------------------------------
4134 snd-xyz-objs := xyz.o
4135 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4142 as a module, choose M here: the module will be called snd-xyz. the
4143 line, select SND_PCM, specifies that the driver xyz supports PCM. In
4158 ---------------------------------
4160 Suppose that the driver snd-xyz have several source files. They are
4161 located in the new subdirectory, sound/pci/xyz.
4163 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4168 obj-$(CONFIG_SND) += sound/pci/xyz/
4175 snd-xyz-objs := xyz.o abc.o def.o
4176 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4180 This procedure is as same as in the last section.
4187 ----------------------------------
4191 However, in general, the use of such helpers is no longer recommended.
4208 :c:func:`snd_printdd()` is compiled in only when
4212 -------------------
4218 When no debug flag is set, this macro is ignored.
4221 ----------------------
4226 return -EINVAL;
4229 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4231 trace. In both cases it returns the evaluated value.
4239 Kevin Conder reformatted the original plain-text to the DocBook format.
4241 Giuliano Pochini corrected typos and contributed the example codes in