Lines Matching +full:always +full:- +full:wait +full:- +full:for +full:- +full:ack
11 Architecture) <http://www.alsa-project.org/>`__ driver. The document
14 consistent, and therefore it would be still a bit help for writing them.
19 low-level driver implementation details. It only describes the standard
26 -------
56 --------------
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
74 This directory and its sub-directories are for the ALSA sequencer. This
76 as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
85 -----------------
87 This is the place for the public header files of ALSA drivers, which are
88 to be exported to user-space, or included by several files in different
94 -----------------
97 architectures. They are hence supposed not to be architecture-specific.
98 For example, the dummy PCM driver and the serial MIDI driver are found
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 -------------
118 code for some cards, because the soundcard needs only a simple operation
119 and the standard i2c API is too complicated for such a purpose.
122 ---------------
124 This contains the synth middle-level modules.
127 ``synth/emux`` sub-directory.
130 -------------
132 This directory and its sub-directories hold the top-level card modules
133 for PCI soundcards and the code specific to the PCI BUS.
137 their own sub-directory (e.g. emu10k1, ice1712).
140 -------------
142 This directory and its sub-directories hold the top-level card modules
143 for ISA soundcards.
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 ----------------
165 -------------
167 This directory contains the codes for ASoC (ALSA System on Chip)
171 -------------
174 At the time of writing, all code has been removed except for dmasound
178 Basic Flow for PCI Drivers
182 -------
184 The minimum flow for PCI soundcards is as follows:
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 -----------------
224 /* definition of the chip-specific record */
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
368 return -ENODEV;
371 return -ENOENT;
390 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
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
445 mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
446 `MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
472 remove callback and power-management callbacks, too.
475 ----------
493 ------------
495 For the above example, at least the following include files are
508 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
509 interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
521 -------------
523 For each soundcard, a “card” record must be allocated.
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 ----------
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
575 identifier for the instance.
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
580 need to take care of calling a destructor for such a component.
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::
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,
615 struct mychip *chip = card->private_data;
628 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
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);
674 ------------------------
683 For releasing the card instance, you can call simply
687 For a device which allows hotplugging, you can use
695 -----------------
697 In this section, we'll complete the chip-specific constructor,
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;
823 EXPORT_NO_SYMBOLS; /* for old kernels only */
826 ------------
829 usually an extra :c:func:`xxx_create()` function is written for this
847 return -ENXIO;
852 -------------------
870 For an I/O port (and also a memory region), you need to have the
871 resource pointer for the standard resource management. For an irq, you
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
914 used for that, but you can use what you like, too.
927 After requesting the IRQ, you can passed it to ``card->sync_irq``
930 card->irq = chip->irq;
934 See the later section `sync_stop callback`_ for details.
936 Now let's write the corresponding destructor for the resources above.
941 To release the resources, the “check-and-release” method is a safer way.
942 For the interrupt, do like this::
944 if (chip->irq >= 0)
945 free_irq(chip->irq, chip);
948 ``chip->irq`` with a negative value (e.g. -1), so that you can check
958 pci_release_regions(chip->pci);
964 chip->res_port, the release procedure looks like::
966 release_and_free_resource(chip->res_port);
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 -----------
1037 struct pci_device_id table for
1041 For example::
1054 struct pci_device_id contains private data for this entry. You can specify
1055 any value here, for example, to define specific operations for supported
1059 all-zero entry.
1099 -------
1102 for each driver to implement the low-level functions to access its
1117 support multiple playback functions. For example, emu10k1 has a PCM
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;
1239 * for example...
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 ---------------
1336 function. It would be better to create a constructor for the PCM, namely::
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;
1359 specify the different numbers in this argument. For example, ``index =
1360 1`` for the second PCM device.
1362 The fourth and fifth arguments are the number of substreams for playback
1363 and capture, respectively. Here 1 is used for both arguments. When no
1374 int index = substream->number;
1377 After the PCM is created, you need to set operators for each PCM stream::
1398 After setting the operators, you probably will want to pre-allocate the
1400 For that, simply call the following::
1403 &chip->pci->dev,
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 -----------------------
1422 The destructor for a PCM instance is not always necessary. Since the PCM
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
1466 /* -- Status -- */
1474 /* -- HW params -- */
1484 snd_pcm_uframes_t min_align; /* Min alignment for the format */
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 -- */
1549 For the operators (callbacks) of each sound driver, most of these
1550 records are supposed to be read-only. Only the PCM middle-layer changes
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
1602 interleaved or the non-interleaved formats, the
1608 specified for the OSS mmap mode. Usually both are set. Of course,
1618 flag. See the `Power Management`_ section for details.
1623 need to check the linked-list of PCM substreams in the trigger
1626 - The ``formats`` field contains the bit-flags of supported formats
1629 little-endian format is specified.
1631 - The ``rates`` field contains the bit-flags of supported rates
1633 pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
1634 are provided only for typical rates. If your chip supports
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
1658 the whole buffer size defines the output latency for the playback
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.
1672 alsa-lib. There are many fields copied from hw_params and sw_params
1673 structs. For example, ``format`` holds the format type chosen by the
1679 channels \* samples-size``. For conversion between frames and bytes,
1683 period_bytes = frames_to_bytes(runtime, runtime->period_size);
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
1699 buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1702 API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1715 The running status can be referred via ``runtime->status``. This is
1717 For example, you can get the current
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``
1741 substream->runtime->private_data = data;
1749 ---------
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
1769 assign different data records per PCM substream. For example, the
1770 cmi8330 driver assigns different ``private_data`` for playback and
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
1802 constraints here, too. See Constraints_ for more details.
1814 Any private instance for a PCM substream allocated in the ``open``
1820 kfree(substream->runtime->private_data);
1827 This is used for any special call to PCM ioctls. But usually you can
1843 size, the format, etc. are defined for the PCM substream.
1851 When you choose managed buffer allocation mode for the substream,
1853 called. Alternatively, you can call a helper function below for
1859 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1860 for more details.
1863 times per initialization. For example, the OSS emulation may call these
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
1875 ``trigger`` callback. Please see the subsection Atomicity_ for
1888 This function is always called before the close callback is called.
1892 When you have chosen managed buffer allocation mode for the PCM
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.
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.
1949 return -EINVAL;
1960 power-management status is changed. Obviously, the ``SUSPEND`` and
1963 See the `Power Management`_ section for details.
1981 Since the IRQ handler might be still pending, we need to wait until
1987 For the majority of drivers that need only a call of
1990 the ``card->sync_irq`` field to the returned interrupt number after
1995 to clear ``card->sync_irq``, as the card itself is being released.
1996 So, usually you'll need to add just a single line for assigning
1997 ``card->sync_irq`` in the driver code unless the driver re-acquires
1998 the IRQ. When the driver frees and re-acquires the IRQ dynamically
1999 (e.g. for suspend/resume), it needs to clear and re-set
2000 ``card->sync_irq`` again appropriately.
2011 frames, ranging from 0 to ``buffer_size - 1``.
2013 This is usually called from the buffer-update routine in the PCM
2029 buffer is non-contiguous on both physical and virtual memory spaces,
2032 If these two callbacks are defined, copy and set-silence operations
2036 ack callback
2041 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
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,
2056 You need no special callback for the standard SG-buffer or vmalloc-
2062 This is another optional callback for controlling mmap behavior.
2064 memory-mapped, instead of using the standard helper.
2066 device-specific issues), implement everything here as you like.
2070 ---------------------
2090 from the chip instance. For example, define ``substream`` field in the
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);
2144 spin_lock(&chip->lock);
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);
2189 ---------
2193 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2200 As already seen, some PCM callbacks are atomic and some are not. For
2201 example, the ``hw_params`` callback is non-atomic, while the ``trigger``
2213 All three atomic callbacks (trigger, pointer, and ack) are called with
2216 However, it is possible to request all PCM operations to be non-atomic.
2218 non-atomic contexts. For example, the function
2221 interrupt handler, this call can be in non-atomic context, too. In such
2225 functions safely in a non-atomic
2230 period gets elapsed during ``ack`` or other callback). There is a
2232 :c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,
2236 -----------
2241 For example, in order to restrict the sample rates to some supported
2257 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2265 There are many different constraints. Look at ``sound/pcm.h`` for a
2266 complete list. You can even define your own constraint rules. For
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) {
2320 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2322 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2326 buffer size to be aligned with the period size. For example, it'd be
2332 :c:func:`snd_pcm_hw_constraint_integer()` for
2335 snd_pcm_hw_constraint_integer(substream->runtime,
2350 -------
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
2357 ALSA has a well-defined AC97 control module. If your chip supports only
2364 ----------------------
2385 for global controls that are not logically part of the mixer. If the
2393 its name. There are pre-defined standard control names. The details
2408 for this record. When using the generic ``info``, ``get`` and ``put``
2420 -------------
2427 pre-defined sources.
2445 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2447 Switch” and “Playback Volume” are used for the global output gain switch
2450 Tone-controls
2453 tone-control switch and volumes are specified like “Tone Control - XXX”,
2454 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2460 3D-control switches and volumes are specified like “3D Control - XXX”,
2461 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2466 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2469 ``Documentation/sound/designs/control-names.rst``.
2472 ------------
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),
2492 setting the ``INACTIVE`` flag may be appropriate. For example, PCM
2498 -----------------
2505 struct snd_ctl_elem_info object. For example,
2506 for a boolean control with a single element::
2512 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513 uinfo->count = 1;
2514 uinfo->value.integer.min = 0;
2515 uinfo->value.integer.max = 1;
2524 this control. For example, a stereo volume would have count = 2. The
2529 set the string for the selectec item index::
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]);
2564 Some common info callbacks are available for your convenience:
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
2575 can be returned to user-space.
2577 For example::
2583 ucontrol->value.integer.value[0] = get_some_value(chip);
2590 info callback. For example, the sb driver uses this field to store the
2591 register offset, the bit-shift and the bit-mask. The ``private_value``
2601 int reg = kcontrol->private_value & 0xff;
2602 int shift = (kcontrol->private_value >> 16) & 0xff;
2603 int mask = (kcontrol->private_value >> 24) & 0xff;
2615 This callback is used to write a value coming from user-space.
2617 For example::
2624 if (chip->current_value !=
2625 ucontrol->value.integer.value[0]) {
2627 ucontrol->value.integer.value[0]);
2645 All these three callbacks are not-atomic.
2648 -------------------
2661 and chip is the object pointer to be passed to kcontrol->private_data which
2669 -------------------
2672 can call :c:func:`snd_ctl_notify()`. For example::
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
2681 for hardware volume interrupts.
2684 --------
2692 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2719 API for AC97 Codec
2723 -------
2725 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2726 write much code to control it. Only low-level control routines are
2730 -----------------
2743 struct mychip *chip = ac97->private_data;
2752 struct mychip *chip = ac97->private_data;
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``
2811 --------------
2814 correspond to the functions for read and write accesses to the
2815 hardware low-level codes.
2823 struct mychip *chip = ac97->private_data;
2828 Here, the chip can be cast from ``ac97->private_data``.
2837 These callbacks are non-atomic like the control API callbacks.
2839 There are also other callbacks: ``reset``, ``wait`` and ``init``.
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
2852 --------------------------------
2864 always rewrites the value::
2870 register. For example::
2893 ----------------
2896 (to save a quartz!). In this case, change the field ``bus->clock`` to
2897 the corresponding value. For example, intel8x0 and es1968 drivers have
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
2931 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
2934 ----------------
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
2957 mpu401-uart layer will allocate the I/O ports by itself.
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 ----------------------
3012 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3019 --------
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
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 |
3063 (callbacks) for each substream. There are helper functions to set the
3064 operators for all the substreams of a device::
3084 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3086 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3088 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
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;
3126 Rawmidi trigger callback for output substreams
3175 RawMIDI trigger callback for input substreams
3190 :c:func:`snd_rawmidi_receive()` for all received data::
3210 This is only used with output substreams. This function should wait
3216 snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3223 -------
3225 The FM OPL3 is still used in many chips (mainly for backward
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::
3249 driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3259 Then set ``command``, ``private_data`` and ``private_free`` for the
3263 ``opl3->private_data`` field.
3267 proper state. Note that :c:func:`snd_opl3_create()` always calls
3271 for this opl3::
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
3281 always takes 0).
3283 Hardware-Dependent Devices
3284 --------------------------
3286 Some chips need user-space access for special controls or for loading
3288 (hardware-dependent) device. The hwdep API is defined in
3305 hw->private_data = p;
3306 hw->private_free = mydata_free;
3312 struct mydata *p = hw->private_data;
3316 The arbitrary file operations can be defined for this instance. The file
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 ---------------
3329 Usually the controls for IEC958 devices are implemented via the control
3330 interface. There is a macro to compose a name string for IEC958
3334 There are some standard controls for IEC958 status bits. These controls
3336 fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3337 callback, you don't specify the value field for this type (the count
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.
3344 Meanwhile, “IEC958 Playback Default” control is defined for getting and
3357 You can find several cases, for example, ``pci/emu10k1``,
3364 ------------
3368 allocation of physically-contiguous pages is done via the
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
3388 &pci->dev, size, max);
3390 where ``size`` is the byte size to be pre-allocated and ``max`` is
3396 dependent on the bus. For normal devices, pass the device pointer
3397 (typically identical as ``card->dev``) to the third argument with
3401 bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3405 bits for the device, and pass the device pointer, like the normal
3406 device memory allocations. For this type, it's still allowed to pass
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);
3427 where the passed arguments are identical for both functions.
3437 -------------------------
3448 for the data transfer, in addition to the ``fill_silence``
3449 callback for playback. However, there is a drawback: it cannot be
3452 The second case allows for mmap on the buffer, although you have to
3457 Another case is when the chip uses a PCI memory-map region for the
3459 on certain architectures like the Intel one. In non-mmap mode, the data
3467 interleaved or non-interleaved samples. The ``copy`` callback is
3482 capture. For playback, it holds the source data pointer, and for
3490 offset (``pos``) in the hardware buffer. When coded like memcpy-like
3495 For the capture direction, you copy the given amount of data (``count``)
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
3517 the given user-space buffer, but only for the given channel. For
3521 Usually for the playback, another callback ``fill_silence`` is
3531 no meaning, as for the ``copy`` callback.
3536 silent-data is 0), and the implementation using a memset-like function
3541 In the case of non-interleaved samples, again, the implementation
3543 for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3545 Non-Contiguous Buffers
3546 ----------------------
3549 descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
3550 provides an interface for handling SG-buffers. The API is provided in
3553 For creating the SG-buffer handler, call
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 ------------------
3583 It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3584 example, for an intermediate buffer.
3598 we don't need to pre-allocate the buffers like other continuous
3604 ALSA provides an easy interface for procfs. The proc files are very
3605 useful for debugging. I recommend you set up proc files if you write a
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``.
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
3638 In the read callback, use :c:func:`snd_iprintf()` for output
3639 strings, which works just like normal :c:func:`printf()`. For
3645 struct my_chip *chip = entry->private_data;
3648 snd_iprintf(buffer, "Port = %ld\n", chip->port);
3652 read only for all users. If you want to add write permission for the
3655 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3659 entry->c.text.write = my_proc_write;
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;
3678 For raw data, ``size`` field must be set properly. This specifies
3682 You need to use a low-level I/O functions such as
3694 return -EFAULT;
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
3725 Note that the trigger with SUSPEND can always be called when
3731 to keep it for compatibility reasons.)
3739 .... /* do things for suspend */
3744 .... /* do things for suspend */
3755 3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
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);
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;
3860 If you need space to save the registers, allocate the buffer for it
3882 There are standard module options for ALSA. At least, each module should
3887 already as constants for easier programming::
3894 variables, instead. ``enable`` option is not always necessary in this
3895 case, but it would be better to have a dummy option for compatibility.
3906 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
3908 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
3916 MODULE_DESCRIPTION("Sound driver for My Chip");
3920 Device-Managed Resources
3926 the (device-)managed resources aka devres or devm family. For
3930 ALSA core provides also the device-managed helper, namely,
3931 :c:func:`snd_devm_card_new()` for creating a card object.
3940 Also, the ``private_free`` callback is always called at the card free,
3941 so be careful to put the hardware clean-up procedure in
3943 actually set up at an earlier error path. For avoiding such an
3947 Another thing to be remarked is that you should use device-managed
3948 helpers for each component as much as possible once when you manage
3957 -------
3963 Suppose that you create a new PCI driver for the card “xyz”. The card
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
3973 --------------------------------
3979 snd-xyz-y := xyz.o
3980 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3984 Add the new entry of Kconfig for your xyz driver::
3991 Say Y here to include support for Foobar XYZ soundcard.
3993 the module will be called snd-xyz.
3996 In addition to SND_PCM, the following components are supported for
3999 Add the select command for each supported component.
4001 Note that some selections imply the lowlevel selections. For example,
4006 For the details of Kconfig script, refer to the kbuild documentation.
4009 ---------------------------------
4011 Suppose that the driver snd-xyz have several source files. They are
4017 obj-$(CONFIG_SND) += sound/pci/xyz/
4022 snd-xyz-y := xyz.o abc.o def.o
4023 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4034 -------------------
4043 ----------------------
4046 :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4048 return -EINVAL;
4051 ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4058 I would like to thank Phil Kerr for his help for improvement and
4061 Kevin Conder reformatted the original plain-text to the DocBook format.