sound/kernel-api/writing-an-alsa-driver.rst

13 API might be different, too. However, at least the ALSA kernel API is
28 The file tree structure of ALSA driver is depicted below::
58 This directory contains the middle layer which is the heart of ALSA
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
77 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
87 This is the place for the public header files of ALSA drivers, which are
99 in this directory. In the sub-directories, there is code for components
110 The OPL3 and OPL4 FM-synth stuff is found here.
117 Although there is a standard i2c layer on Linux, ALSA has its own i2c
119 and the standard i2c API is too complicated for such a purpose.
126 So far, there is only Emu8000/Emu10k1 synth driver under the
155 The USB MIDI driver is integrated in the usb-audio driver.
161 be in the pci directory, because their API is identical to that of
184 The minimum flow for PCI soundcards is as follows:
205 The code example is shown below. Some parts are kept unimplemented at
353 The real constructor of PCI drivers is the ``probe`` callback. The
358 In the ``probe`` callback, the following scheme is often used.
375 where ``enable[dev]`` is the module option.
377 Each time the ``probe`` callback is called, check the availability of
433 The driver field holds the minimal ID string of the chip. This is used
438 The shortname field is a string shown as more verbose name. The longname
471 In the above, the card record is stored. This pointer is used in the
489 The above code assumes that the card pointer is set to the PCI driver
504 where the last one is necessary only when module options are defined
505 in the source file. If the code is split into several files, the files
525 A card record is the headquarters of the soundcard. It manages the whole
530 list on the card record is used to manage the correct release of
544 return the card instance. The extra_size argument is used to allocate
549 device. For PCI devices, typically ``&pci->`` is passed there.
554 After the card is created, you can attach the components (devices) to
555 the card instance. In an ALSA driver, a component is represented as a
568 de-registration. For most components, the device-level is already
573 allocated manually beforehand, and its pointer is passed as the
574 argument. This pointer (``chip`` in the above example) is used as the
579 for each component is defined in the callback pointers. Hence, you don't
591 pointer, or the irq number, is stored in the chip-specific record::
609 struct mychip is the type of the chip record.
617 With this method, you don't have to allocate twice. The record is
656 :c:func:`snd_mychip_dev_free()` is the device-destructor
664 where :c:func:`snd_mychip_free()` is the real destructor.
666 The demerit of this method is the obviously larger amount of code.
667 The merit is, however, that you can trigger your own callback at
677 :c:func:`snd_card_register()`. Access to the device files is
678 enabled at this point. That is, before
679 :c:func:`snd_card_register()` is called, the components are safely
698 destructor and PCI entries. Example code is shown first, below::
828 The allocation of PCI resources is done in the ``probe`` function, and
829 usually an extra :c:func:`xxx_create()` function is written for this
854 The allocation of I/O ports and irqs is done via standard kernel
873 this number to -1 before actual allocation, since irq 0 is valid. The
878 The allocation of an I/O port is done like this::
889 The returned value, ``chip->res_port``, is allocated via
891 must be released via :c:func:`kfree()`, but there is a problem with
894 The allocation of an interrupt source is done like this::
904 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
909 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
912 The last argument of :c:func:`request_irq()` is the data pointer
913 passed to the interrupt handler. Usually, the chip-specific record is
937 The role of destructor is simple: disable the hardware (if already
939 so the disabling code is not written here.
941 To release the resources, the “check-and-release” method is a safer way.
977 before the initialization of the chip is completed. It would be better
981 When the chip-data is assigned to the card using
983 destructor is called last. That is, it is assured that all other
988 The management of a memory-mapped region is almost as same as the
1030 which is paired with :c:func:`pci_iounmap()` at destructor.
1056 device IDs. Such an example is found in the intel8x0 driver.
1058 The last entry of this list is the terminator. You must specify this
1072 the previous sections. The ``name`` field is the name string of this
1101 The PCM middle layer of ALSA is quite powerful and it is only necessary
1119 substream is (usually) automatically chosen and opened. Meanwhile, when
1335 A PCM instance is allocated by the :c:func:`snd_pcm_new()`
1354 first argument is the card pointer to which this PCM is assigned, and
1355 the second is the ID string.
1357 The third argument (``index``, 0 in the above) is the index of this new
1363 and capture, respectively. Here 1 is used for both arguments. When no
1377 After the PCM is created, you need to set operators for each PCM stream::
1412 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1422 The destructor for a PCM instance is not always necessary. Since the PCM
1456 When the PCM substream is opened, a PCM runtime instance is allocated
1457 and assigned to the substream. This pointer is accessible via
1462 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1463 is the relevant part of this file::
1493           struct timespec tstamp_mode;	/* mmap timestamp is updated */
1499            * hw_avail drops below the threshold, the respective action is triggered:
1564 the descriptor, not a pointer to the existing descriptor. That is,
1567 channels is 1 only on some chip models, you can still use the same
1599    mmap is supported and which interleaving formats are
1609    ``MMAP_VALID`` is set only if mmap is really supported.
1615    ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1616    the corresponding (pause push/release) commands. The suspend/resume
1629    little-endian format is specified.
1645    bytes. There is no ``buffer_bytes_min`` field, since it can be
1652    The “period” is a term that corresponds to a fragment in the OSS
1653    world. The period defines the point at which a PCM interrupt is
1661 -  There is also a field ``fifo_size``. This specifies the size of the
1662    hardware FIFO, but currently it is neither used by the drivers nor
1677 One thing to be noted is that the configured buffer and period sizes
1686 Please check the type of the field. ``snd_pcm_uframes_t`` is for
1687 frames as unsigned integer while ``snd_pcm_sframes_t`` is for
1693 The DMA buffer is defined by the following four fields: ``dma_area``,
1697 the physical address of the buffer. This field is specified only when
1698 the buffer is a linear buffer. ``dma_bytes`` holds the size of the
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
1707 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1708 your driver doesn't support mmap, this field is not
1709 necessary. ``dma_addr`` is also optional. You can use dma_private as
1715 The running status can be referred via ``runtime->status``. This is
1722 However, accessing this value directly is not recommended.
1728 ``runtime->private_data``. Usually, this is done in the `PCM open
1754 number, it is advised to check what value other parts of the kernel
1767 The macro reads ``substream->private_data``, which is a copy of
1781 This is called when a PCM substream is opened.
1784 record. Typically, this is done like this::
1795 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1812 Obviously, this is called when a PCM substream is closed.
1827 This is used for any special call to PCM ioctls. But usually you can
1841 This is called when the hardware parameters (``hw_params``) are set up
1842 by the application, that is, once when the buffer size, the period
1852 a buffer is already allocated before this callback gets
1858 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1868 above many times is OK. It will release the previous buffer
1871 Another note is that this callback is non-atomic (schedulable) by
1872 default, i.e. when no ``nonatomic`` flag set. This is important,
1873 because the ``trigger`` callback is atomic (non-schedulable). That is,
1885 This is called to release the resources allocated via
1888 This function is always called before the close callback is called.
1908 This callback is called when the PCM is “prepared”. You can set the
1910 is that the ``prepare`` callback will be called each time
1911 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
1914 Note that this callback is non-atomic. You can use
1921 physical address of the allocated buffer is set to
1935 This is called when the PCM is started, stopped or paused.
1937 The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
1954 must be handled here, too. The former is the command to pause the PCM,
1960 power-management status is changed. Obviously, the ``SUSPEND`` and
1965 As mentioned, this callback is atomic by default unless the ``nonatomic``
1978 This callback is optional, and NULL can be passed.  It's called after
1984 resources.  A typical behavior is to call a synchronization function
1988 :c:func:`synchronize_irq()`, there is a simpler setup, too.
1994 If the IRQ handler is released by the card destructor, you don't need
1995 to clear ``card->sync_irq``, as the card itself is being released.
2009 This callback is called when the PCM middle layer inquires the current
2013 This is usually called from the buffer-update routine in the PCM
2014 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2015 is called by the interrupt routine. Then the PCM middle layer updates
2019 This callback is also atomic by default.
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,
2039 This callback is also not mandatory. This callback is called when the
2040 ``appl_ptr`` is updated in read or write operations. Some drivers like
2042 internal buffer, and this callback is useful only for such a purpose.
2045 return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
2048 This callback is atomic by default.
2053 This callback is optional too. The mmap calls this callback to get the
2062 This is another optional callback for controlling mmap behavior.
2063 When defined, the PCM core calls this callback when a page is
2072 The remainder of the PCM stuff is the PCM interrupt handler. The role
2074 interrupt handler in the sound driver is to update the buffer position
2084 This is the most frequently found type: the hardware generates an
2094 If you acquire a spinlock in the interrupt handler, and the lock is used
2196 section. If the critical section is not in interrupt handler code and if
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``
2202 callback is atomic. This means, the latter is called already in a
2216 However, it is possible to request all PCM operations to be non-atomic.
2219 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2223 after creating it. When this flag is set, mutex and rwsem are used internally
2230 period gets elapsed during ``ack`` or other callback). There is a
2238 Due to physical limitations, hardware is not infinitely configurable.
2268 and only if the format is ``S16_LE``, otherwise it supports any format
2296 The rule function is called when an application sets the PCM format, and
2324 One typical usage of the hw constraints is to align the buffer size
2338 This assures that the number of periods is integer, hence the buffer
2339 size is aligned with the period size.
2341 The hw constraint is a very powerful mechanism to define the
2352 The control interface is used widely for many switches, sliders, etc.
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
2360 The control API is defined in ``<sound/control.h>``. Include this file
2384 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2386 control is closely associated with some specific device on the sound
2391 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2392 control name is very important, because its role is classified from
2398 distinguished by the index number. This is the case when several
2399 codecs exist on the card. If the index is zero, you can omit the
2422 There are some standards to define the control names. A control is
2425 The first, ``SOURCE``, specifies the source of the control, and is a
2429 The second, ``DIRECTION``, is one of the following strings according to
2434 The third, ``FUNCTION``, is one of the following strings according to
2466 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2474 The access flag is the bitmask which specifies the access type of the
2475 given control. The default access type is
2477 allowed to this control. When the access flag is omitted (i.e. = 0), it
2478 is considered as ``READWRITE`` access by default.
2480 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2482 Similarly, when the control is write-only (although it's a rare case),
2493 controls should be inactive while no PCM device is open.
2503 The ``info`` callback is used to get detailed information on this
2525 ``value`` field is a union, and the values stored depend on the
2528 The enumerated type is a bit different from the others. You'll need to
2567 is an info callback for a mono channel boolean item, just like
2568 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2574 This callback is used to read the current value of the control, so it
2592 field is set as follows::
2596 and is retrieved in callbacks like::
2610 ``count = 1`` is assumed.
2615 This callback is used to write a value coming from user-space.
2635 As seen above, you have to return 1 if the value is changed. If the
2636 value is not changed, return 0 instead. If any fatal error happens,
2650 When everything is ready, finally we can create a new control. To create
2660 where ``my_control`` is the struct snd_kcontrol_new object defined above,
2661 and chip is the object pointer to be passed to kcontrol->private_data which
2679 values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
2705 dB value by a constant dB amount. The first parameter is the name of 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
2713 linearly. The first parameter is the name of the variable to be defined.
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
2725 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2727 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2790 The bus record is shared among all belonging ac97 instances.
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
2830 Meanwhile, the ``write`` callback is used to set the register
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
2848 The ``init`` callback is used for additional initialization of the
2861 the given register (``AC97_XXX``). The difference between them is that
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
2880 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2888 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2889 specified, the register is not really changed but the corresponding
2927 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2943 The first argument is the card pointer, and the second is the index of
2946 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
2949 The 4th argument is the I/O port address. Many backward-compatible
2953 The 5th argument is a bitflag for additional information. When the I/O
2954 port address above is part of the PCI I/O region, the MPU401 I/O port
2961 respectively. Then the rawmidi instance is created as a single stream.
2963 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
2967 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
2979 However, struct snd_mpu401 pointer is
2991 no interrupt is to be allocated (because your code is already allocating
2999 When the interrupt is allocated in
3001 handler is automatically used, hence you don't have anything else to do
3021 The raw MIDI interface is used for hardware MIDI ports that can be
3022 accessed as a byte stream. It is not used for synthesizer chips that do
3025 ALSA handles file and buffer management. All you have to do is to write
3028 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3046 The first argument is the card pointer, the second argument is the ID
3049 The third argument is the index of this component. You can create up to
3053 substreams, respectively, of this device (a substream is the equivalent
3057 device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3058 output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3062 After the rawmidi device is created, you need to set the operators
3096 If there is more than one port, your callbacks can determine the port
3111 This is called when a substream is opened. You can initialize the
3134 This is called with a nonzero ``up`` parameter when there is some data
3167 The ``trigger`` callback must not sleep. If the hardware FIFO is full
3172 The ``trigger`` callback is called with a zero ``up`` parameter when
3183 This is called with a nonzero ``up`` parameter to enable receiving data,
3187 from the device is usually done in an interrupt handler.
3189 When data reception is enabled, your interrupt handler should call
3210 This is only used with output substreams. This function should wait
3215 This callback is optional. If you do not set ``drain`` in the struct
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
3231 accessed through the Hardware-Dependent Device direct-FM extension API,
3233 OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3236 one is a constructor for the ``opl3_t`` instance::
3242 The first argument is the card pointer, the second one is the left port
3243 address, and the third is the right port address. In most cases, the
3244 right port is placed at the left port + 2.
3246 The fourth argument is the hardware type.
3270 If the opl3 instance is created successfully, then create a hwdep device
3276 The first argument is the ``opl3_t`` instance you created, and the
3277 second is the index number, usually 0.
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
3288 (hardware-dependent) device. The hwdep API is defined in
3292 The creation of the ``hwdep`` instance is done via
3298 where the third argument is the index number.
3302 destructor function is set in the ``private_free`` field::
3330 interface. There is a macro to compose a name string for IEC958
3335 use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3340 “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3344 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3368 allocation of physically-contiguous pages is done via the
3369 :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3372 The allocation of pages with fallback is done via
3376 is found, down to one page.
3382 physical space at the time the module is loaded for later use. This
3383 is called “pre-allocation”. As already written, you can call the
3390 where ``size`` is the byte size to be pre-allocated and ``max`` is
3402 You can pass NULL to the device pointer in that case, which is the
3407 NULL to the device pointer, too, if no address restriction is needed.
3412 Once the buffer is pre-allocated, you can use the allocator in the
3421 This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3428 The difference in the managed mode is that PCM core will call
3440 host memory is not available. In such a case, you need to either 1)
3445 The first case works fine if the external hardware buffer is large
3446 enough. This method doesn't need any extra buffers and thus is more
3449 callback for playback. However, there is a drawback: it cannot be
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
3467 interleaved or non-interleaved samples. The ``copy`` callback is
3469 is playback or capture::
3478 In the case of interleaved samples, the second argument (``channel``) is
3481 The meaning of the fourth argument is different between playback and
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
3512 more complicated.  The callback is called for each channel, passed in
3516 interleaved case.  The callback is supposed to copy the data from/to
3521 Usually for the playback, another callback ``fill_silence`` is
3529 although there is no buffer pointer
3533 The role of the ``fill_silence`` callback is to set the given amount
3535 hardware buffer. Suppose that the data format is signed (that is, the
3536 silent-data is 0), and the implementation using a memset-like function
3550 provides an interface for handling SG-buffers. The API is provided in
3557 pre-allocations. You need to pass ``&pci->dev``, where pci is
3563 The ``struct snd_sg_buf`` instance is created as
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
3592 NULL is passed as the device pointer argument, which indicates
3596 Also, note that zero is passed as both the size and the max size
3606 driver and want to get a running status or register dumps. The API is
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
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
3632 the fourth (``my_proc_read``) is the callback function, which is
3647           snd_iprintf(buffer, "This is my chip!\n");
3681 The read/write callbacks of raw mode are more direct than the text mode.
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
3711 If the driver *fully* supports suspend/resume that is, the device can be
3713 ``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
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
3726 :c:func:`snd_pcm_suspend_all()` is called, regardless of the
3730 callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3734 suspend/resume hooks according to the bus the device is connected to. In
3748 The scheme of the real suspend job is as follows:
3781 The scheme of the real resume job is as follows:
3894 variables, instead. ``enable`` option is not always necessary in this
3914 module license as GPL, etc., otherwise the system is shown as “tainted”::
3936 One caveat is that the call of :c:func:`snd_card_free()` would be put
3940 Also, the ``private_free`` callback is always called at the card free,
3947 Another thing to be remarked is that you should use device-managed
3961 (finally :) the standard procedure is described briefly.
3964 module name would be snd-xyz. The new driver is usually put into the
3968 In the following sections, the driver code is supposed to be put into
4027    This procedure is as same as in the last section.
4040 When no debug flag is set, this macro is ignored.
4045 :c:func:`snd_BUG_ON()` macro is similar with
4051 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows