1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <!-- ****************************************************** -->
7 <!-- ****************************************************** -->
8 <book id="Writing-an-ALSA-Driver">
10 <title>Writing an ALSA Driver</title>
12 <firstname>Takashi</firstname>
13 <surname>Iwai</surname>
16 <email>tiwai@suse.de</email>
21 <date>Oct 15, 2007</date>
22 <edition>0.3.7</edition>
26 This document describes how to write an ALSA (Advanced Linux
27 Sound Architecture) driver.
33 Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email>
37 This document is free; you can redistribute it and/or modify it
38 under the terms of the GNU General Public License as published by
39 the Free Software Foundation; either version 2 of the License, or
40 (at your option) any later version.
44 This document is distributed in the hope that it will be useful,
45 but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
46 implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
47 PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
52 You should have received a copy of the GNU General Public
53 License along with this program; if not, write to the Free
54 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
61 <!-- ****************************************************** -->
63 <!-- ****************************************************** -->
64 <preface id="preface">
65 <title>Preface</title>
67 This document describes how to write an
68 <ulink url="http://www.alsa-project.org/"><citetitle>
69 ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
70 driver. The document focuses mainly on PCI soundcards.
71 In the case of other device types, the API might
72 be different, too. However, at least the ALSA kernel API is
73 consistent, and therefore it would be still a bit help for
78 This document targets people who already have enough
79 C language skills and have basic linux kernel programming
80 knowledge. This document doesn't explain the general
81 topic of linux kernel coding and doesn't cover low-level
82 driver implementation details. It only describes
83 the standard way to write a PCI sound driver on ALSA.
87 If you are already familiar with the older ALSA ver.0.5.x API, you
88 can check the drivers such as <filename>sound/pci/es1938.c</filename> or
89 <filename>sound/pci/maestro3.c</filename> which have also almost the same
90 code-base in the ALSA 0.5.x tree, so you can compare the differences.
94 This document is still a draft version. Any feedback and
100 <!-- ****************************************************** -->
101 <!-- File Tree Structure -->
102 <!-- ****************************************************** -->
103 <chapter id="file-tree">
104 <title>File Tree Structure</title>
106 <section id="file-tree-general">
107 <title>General</title>
109 The ALSA drivers are provided in two ways.
113 One is the trees provided as a tarball or via cvs from the
114 ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
115 tree. To synchronize both, the ALSA driver tree is split into
116 two different trees: alsa-kernel and alsa-driver. The former
117 contains purely the source code for the Linux 2.6 (or later)
118 tree. This tree is designed only for compilation on 2.6 or
119 later environment. The latter, alsa-driver, contains many subtle
120 files for compiling ALSA drivers outside of the Linux kernel tree,
121 wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
122 and additional drivers which are still in development or in
123 tests. The drivers in alsa-driver tree will be moved to
124 alsa-kernel (and eventually to the 2.6 kernel tree) when they are
125 finished and confirmed to work fine.
129 The file tree structure of ALSA driver is depicted below. Both
130 alsa-kernel and alsa-driver have almost the same file
131 structure, except for <quote>core</quote> directory. It's
132 named as <quote>acore</quote> in alsa-driver tree.
135 <title>ALSA File Tree Structure</title>
167 <section id="file-tree-core-directory">
168 <title>core directory</title>
170 This directory contains the middle layer which is the heart
171 of ALSA drivers. In this directory, the native ALSA modules are
172 stored. The sub-directories contain different modules and are
173 dependent upon the kernel config.
176 <section id="file-tree-core-directory-oss">
177 <title>core/oss</title>
180 The codes for PCM and mixer OSS emulation modules are stored
181 in this directory. The rawmidi OSS emulation is included in
182 the ALSA rawmidi code since it's quite small. The sequencer
183 code is stored in <filename>core/seq/oss</filename> directory (see
184 <link linkend="file-tree-core-directory-seq-oss"><citetitle>
185 below</citetitle></link>).
189 <section id="file-tree-core-directory-ioctl32">
190 <title>core/ioctl32</title>
193 This directory contains the 32bit-ioctl wrappers for 64bit
194 architectures such like x86-64, ppc64 and sparc64. For 32bit
195 and alpha architectures, these are not compiled.
199 <section id="file-tree-core-directory-seq">
200 <title>core/seq</title>
202 This directory and its sub-directories are for the ALSA
203 sequencer. This directory contains the sequencer core and
204 primary sequencer modules such like snd-seq-midi,
205 snd-seq-virmidi, etc. They are compiled only when
206 <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
211 <section id="file-tree-core-directory-seq-oss">
212 <title>core/seq/oss</title>
214 This contains the OSS sequencer emulation codes.
218 <section id="file-tree-core-directory-deq-instr">
219 <title>core/seq/instr</title>
221 This directory contains the modules for the sequencer
227 <section id="file-tree-include-directory">
228 <title>include directory</title>
230 This is the place for the public header files of ALSA drivers,
231 which are to be exported to user-space, or included by
232 several files at different directories. Basically, the private
233 header files should not be placed in this directory, but you may
234 still find files there, due to historical reasons :)
238 <section id="file-tree-drivers-directory">
239 <title>drivers directory</title>
241 This directory contains code shared among different drivers
242 on different architectures. They are hence supposed not to be
243 architecture-specific.
244 For example, the dummy pcm driver and the serial MIDI
245 driver are found in this directory. In the sub-directories,
246 there is code for components which are independent from
247 bus and cpu architectures.
250 <section id="file-tree-drivers-directory-mpu401">
251 <title>drivers/mpu401</title>
253 The MPU401 and MPU401-UART modules are stored here.
257 <section id="file-tree-drivers-directory-opl3">
258 <title>drivers/opl3 and opl4</title>
260 The OPL3 and OPL4 FM-synth stuff is found here.
265 <section id="file-tree-i2c-directory">
266 <title>i2c directory</title>
268 This contains the ALSA i2c components.
272 Although there is a standard i2c layer on Linux, ALSA has its
273 own i2c code for some cards, because the soundcard needs only a
274 simple operation and the standard i2c API is too complicated for
278 <section id="file-tree-i2c-directory-l3">
279 <title>i2c/l3</title>
281 This is a sub-directory for ARM L3 i2c.
286 <section id="file-tree-synth-directory">
287 <title>synth directory</title>
289 This contains the synth middle-level modules.
293 So far, there is only Emu8000/Emu10k1 synth driver under
294 the <filename>synth/emux</filename> sub-directory.
298 <section id="file-tree-pci-directory">
299 <title>pci directory</title>
301 This directory and its sub-directories hold the top-level card modules
302 for PCI soundcards and the code specific to the PCI BUS.
306 The drivers compiled from a single file are stored directly
307 in the pci directory, while the drivers with several source files are
308 stored on their own sub-directory (e.g. emu10k1, ice1712).
312 <section id="file-tree-isa-directory">
313 <title>isa directory</title>
315 This directory and its sub-directories hold the top-level card modules
320 <section id="file-tree-arm-ppc-sparc-directories">
321 <title>arm, ppc, and sparc directories</title>
323 They are used for top-level card modules which are
324 specific to one of these architectures.
328 <section id="file-tree-usb-directory">
329 <title>usb directory</title>
331 This directory contains the USB-audio driver. In the latest version, the
332 USB MIDI driver is integrated in the usb-audio driver.
336 <section id="file-tree-pcmcia-directory">
337 <title>pcmcia directory</title>
339 The PCMCIA, especially PCCard drivers will go here. CardBus
340 drivers will be in the pci directory, because their API is identical
341 to that of standard PCI cards.
345 <section id="file-tree-oss-directory">
346 <title>oss directory</title>
348 The OSS/Lite source files are stored here in Linux 2.6 (or
349 later) tree. In the ALSA driver tarball, this directory is empty,
356 <!-- ****************************************************** -->
357 <!-- Basic Flow for PCI Drivers -->
358 <!-- ****************************************************** -->
359 <chapter id="basic-flow">
360 <title>Basic Flow for PCI Drivers</title>
362 <section id="basic-flow-outline">
363 <title>Outline</title>
365 The minimum flow for PCI soundcards is as follows:
368 <listitem><para>define the PCI ID table (see the section
369 <link linkend="pci-resource-entries"><citetitle>PCI Entries
370 </citetitle></link>).</para></listitem>
371 <listitem><para>create <function>probe()</function> callback.</para></listitem>
372 <listitem><para>create <function>remove()</function> callback.</para></listitem>
373 <listitem><para>create a <structname>pci_driver</structname> structure
374 containing the three pointers above.</para></listitem>
375 <listitem><para>create an <function>init()</function> function just calling
376 the <function>pci_register_driver()</function> to register the pci_driver table
377 defined above.</para></listitem>
378 <listitem><para>create an <function>exit()</function> function to call
379 the <function>pci_unregister_driver()</function> function.</para></listitem>
384 <section id="basic-flow-example">
385 <title>Full Code Example</title>
387 The code example is shown below. Some parts are kept
388 unimplemented at this moment but will be filled in the
389 next sections. The numbers in the comment lines of the
390 <function>snd_mychip_probe()</function> function
391 refer to details explained in the following section.
394 <title>Basic Flow for PCI Drivers - Example</title>
397 #include <linux/init.h>
398 #include <linux/pci.h>
399 #include <linux/slab.h>
400 #include <sound/core.h>
401 #include <sound/initval.h>
403 /* module parameters (see "Module Parameters") */
404 /* SNDRV_CARDS: maximum number of cards supported by this module */
405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
407 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
409 /* definition of the chip-specific record */
411 struct snd_card *card;
412 /* the rest of the implementation will be in section
413 * "PCI Resource Management"
417 /* chip-specific destructor
418 * (see "PCI Resource Management")
420 static int snd_mychip_free(struct mychip *chip)
422 .... /* will be implemented later... */
425 /* component-destructor
426 * (see "Management of Cards and Components")
428 static int snd_mychip_dev_free(struct snd_device *device)
430 return snd_mychip_free(device->device_data);
433 /* chip-specific constructor
434 * (see "Management of Cards and Components")
436 static int snd_mychip_create(struct snd_card *card,
438 struct mychip **rchip)
442 static struct snd_device_ops ops = {
443 .dev_free = snd_mychip_dev_free,
448 /* check PCI availability here
449 * (see "PCI Resource Management")
453 /* allocate a chip-specific data with zero filled */
454 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
460 /* rest of initialization here; will be implemented
461 * later, see "PCI Resource Management"
465 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
467 snd_mychip_free(chip);
475 /* constructor -- see "Constructor" sub-section */
476 static int snd_mychip_probe(struct pci_dev *pci,
477 const struct pci_device_id *pci_id)
480 struct snd_card *card;
485 if (dev >= SNDRV_CARDS)
493 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
499 err = snd_mychip_create(card, pci, &chip);
506 strcpy(card->driver, "My Chip");
507 strcpy(card->shortname, "My Own Chip 123");
508 sprintf(card->longname, "%s at 0x%lx irq %i",
509 card->shortname, chip->ioport, chip->irq);
512 .... /* implemented later */
515 err = snd_card_register(card);
522 pci_set_drvdata(pci, card);
527 /* destructor -- see the "Destructor" sub-section */
528 static void snd_mychip_remove(struct pci_dev *pci)
530 snd_card_free(pci_get_drvdata(pci));
531 pci_set_drvdata(pci, NULL);
539 <section id="basic-flow-constructor">
540 <title>Constructor</title>
542 The real constructor of PCI drivers is the <function>probe</function> callback.
543 The <function>probe</function> callback and other component-constructors which are called
544 from the <function>probe</function> callback cannot be used with
545 the <parameter>__init</parameter> prefix
546 because any PCI device could be a hotplug device.
550 In the <function>probe</function> callback, the following scheme is often used.
553 <section id="basic-flow-constructor-device-index">
554 <title>1) Check and increment the device index.</title>
561 if (dev >= SNDRV_CARDS)
571 where enable[dev] is the module option.
575 Each time the <function>probe</function> callback is called, check the
576 availability of the device. If not available, simply increment
577 the device index and returns. dev will be incremented also
579 linkend="basic-flow-constructor-set-pci"><citetitle>step
580 7</citetitle></link>).
584 <section id="basic-flow-constructor-create-card">
585 <title>2) Create a card instance</title>
590 struct snd_card *card;
593 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
601 The details will be explained in the section
602 <link linkend="card-management-card-instance"><citetitle>
603 Management of Cards and Components</citetitle></link>.
607 <section id="basic-flow-constructor-create-main">
608 <title>3) Create a main component</title>
610 In this part, the PCI resources are allocated.
617 err = snd_mychip_create(card, pci, &chip);
626 The details will be explained in the section <link
627 linkend="pci-resource"><citetitle>PCI Resource
628 Management</citetitle></link>.
632 <section id="basic-flow-constructor-main-component">
633 <title>4) Set the driver ID and name strings.</title>
638 strcpy(card->driver, "My Chip");
639 strcpy(card->shortname, "My Own Chip 123");
640 sprintf(card->longname, "%s at 0x%lx irq %i",
641 card->shortname, chip->ioport, chip->irq);
646 The driver field holds the minimal ID string of the
647 chip. This is used by alsa-lib's configurator, so keep it
649 Even the same driver can have different driver IDs to
650 distinguish the functionality of each chip type.
654 The shortname field is a string shown as more verbose
655 name. The longname field contains the information
656 shown in <filename>/proc/asound/cards</filename>.
660 <section id="basic-flow-constructor-create-other">
661 <title>5) Create other components, such as mixer, MIDI, etc.</title>
663 Here you define the basic components such as
664 <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
665 mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
666 MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
667 and other interfaces.
668 Also, if you want a <link linkend="proc-interface"><citetitle>proc
669 file</citetitle></link>, define it here, too.
673 <section id="basic-flow-constructor-register-card">
674 <title>6) Register the card instance.</title>
679 err = snd_card_register(card);
690 Will be explained in the section <link
691 linkend="card-management-registration"><citetitle>Management
692 of Cards and Components</citetitle></link>, too.
696 <section id="basic-flow-constructor-set-pci">
697 <title>7) Set the PCI driver data and return zero.</title>
702 pci_set_drvdata(pci, card);
709 In the above, the card record is stored. This pointer is
710 used in the remove callback and power-management
716 <section id="basic-flow-destructor">
717 <title>Destructor</title>
719 The destructor, remove callback, simply releases the card
720 instance. Then the ALSA middle layer will release all the
721 attached components automatically.
725 It would be typically like the following:
730 static void snd_mychip_remove(struct pci_dev *pci)
732 snd_card_free(pci_get_drvdata(pci));
733 pci_set_drvdata(pci, NULL);
739 The above code assumes that the card pointer is set to the PCI
744 <section id="basic-flow-header-files">
745 <title>Header Files</title>
747 For the above example, at least the following include files
753 #include <linux/init.h>
754 #include <linux/pci.h>
755 #include <linux/slab.h>
756 #include <sound/core.h>
757 #include <sound/initval.h>
762 where the last one is necessary only when module options are
763 defined in the source file. If the code is split into several
764 files, the files without module options don't need them.
768 In addition to these headers, you'll need
769 <filename><linux/interrupt.h></filename> for interrupt
770 handling, and <filename><asm/io.h></filename> for I/O
771 access. If you use the <function>mdelay()</function> or
772 <function>udelay()</function> functions, you'll need to include
773 <filename><linux/delay.h></filename> too.
777 The ALSA interfaces like the PCM and control APIs are defined in other
778 <filename><sound/xxx.h></filename> header files.
779 They have to be included after
780 <filename><sound/core.h></filename>.
787 <!-- ****************************************************** -->
788 <!-- Management of Cards and Components -->
789 <!-- ****************************************************** -->
790 <chapter id="card-management">
791 <title>Management of Cards and Components</title>
793 <section id="card-management-card-instance">
794 <title>Card Instance</title>
796 For each soundcard, a <quote>card</quote> record must be allocated.
800 A card record is the headquarters of the soundcard. It manages
801 the whole list of devices (components) on the soundcard, such as
802 PCM, mixers, MIDI, synthesizer, and so on. Also, the card
803 record holds the ID and the name strings of the card, manages
804 the root of proc files, and controls the power-management states
805 and hotplug disconnections. The component list on the card
806 record is used to manage the correct release of resources at
811 As mentioned above, to create a card instance, call
812 <function>snd_card_new()</function>.
817 struct snd_card *card;
819 err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
826 The function takes six arguments: the parent device pointer,
827 the card-index number, the id string, the module pointer (usually
828 <constant>THIS_MODULE</constant>),
829 the size of extra-data space, and the pointer to return the
830 card instance. The extra_size argument is used to
831 allocate card->private_data for the
832 chip-specific data. Note that these data
833 are allocated by <function>snd_card_new()</function>.
837 The first argument, the pointer of struct
838 <structname>device</structname>, specifies the parent device.
839 For PCI devices, typically &pci-> is passed there.
843 <section id="card-management-component">
844 <title>Components</title>
846 After the card is created, you can attach the components
847 (devices) to the card instance. In an ALSA driver, a component is
848 represented as a struct <structname>snd_device</structname> object.
849 A component can be a PCM instance, a control interface, a raw
850 MIDI interface, etc. Each such instance has one component
855 A component can be created via
856 <function>snd_device_new()</function> function.
861 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
868 This takes the card pointer, the device-level
869 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
870 callback pointers (<parameter>&ops</parameter>). The
871 device-level defines the type of components and the order of
872 registration and de-registration. For most components, the
873 device-level is already defined. For a user-defined component,
874 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
878 This function itself doesn't allocate the data space. The data
879 must be allocated manually beforehand, and its pointer is passed
880 as the argument. This pointer (<parameter>chip</parameter> in the
881 above example) is used as the identifier for the instance.
885 Each pre-defined ALSA component such as ac97 and pcm calls
886 <function>snd_device_new()</function> inside its
887 constructor. The destructor for each component is defined in the
888 callback pointers. Hence, you don't need to take care of
889 calling a destructor for such a component.
893 If you wish to create your own component, you need to
894 set the destructor function to the dev_free callback in
895 the <parameter>ops</parameter>, so that it can be released
896 automatically via <function>snd_card_free()</function>.
897 The next example will show an implementation of chip-specific
902 <section id="card-management-chip-specific">
903 <title>Chip-Specific Data</title>
905 Chip-specific information, e.g. the I/O port address, its
906 resource pointer, or the irq number, is stored in the
907 chip-specific record.
921 In general, there are two ways of allocating the chip record.
924 <section id="card-management-chip-specific-snd-card-new">
925 <title>1. Allocating via <function>snd_card_new()</function>.</title>
927 As mentioned above, you can pass the extra-data-length
928 to the 5th argument of <function>snd_card_new()</function>, i.e.
933 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
934 sizeof(struct mychip), &card);
939 struct <structname>mychip</structname> is the type of the chip record.
943 In return, the allocated record can be accessed as
948 struct mychip *chip = card->private_data;
953 With this method, you don't have to allocate twice.
954 The record is released together with the card instance.
958 <section id="card-management-chip-specific-allocate-extra">
959 <title>2. Allocating an extra device.</title>
962 After allocating a card instance via
963 <function>snd_card_new()</function> (with
964 <constant>0</constant> on the 4th arg), call
965 <function>kzalloc()</function>.
970 struct snd_card *card;
972 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
975 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
982 The chip record should have the field to hold the card
989 struct snd_card *card;
998 Then, set the card pointer in the returned chip instance.
1010 Next, initialize the fields, and register this chip
1011 record as a low-level device with a specified
1012 <parameter>ops</parameter>,
1017 static struct snd_device_ops ops = {
1018 .dev_free = snd_mychip_dev_free,
1021 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1026 <function>snd_mychip_dev_free()</function> is the
1027 device-destructor function, which will call the real
1035 static int snd_mychip_dev_free(struct snd_device *device)
1037 return snd_mychip_free(device->device_data);
1043 where <function>snd_mychip_free()</function> is the real destructor.
1048 <section id="card-management-registration">
1049 <title>Registration and Release</title>
1051 After all components are assigned, register the card instance
1052 by calling <function>snd_card_register()</function>. Access
1053 to the device files is enabled at this point. That is, before
1054 <function>snd_card_register()</function> is called, the
1055 components are safely inaccessible from external side. If this
1056 call fails, exit the probe function after releasing the card via
1057 <function>snd_card_free()</function>.
1061 For releasing the card instance, you can call simply
1062 <function>snd_card_free()</function>. As mentioned earlier, all
1063 components are released automatically by this call.
1067 For a device which allows hotplugging, you can use
1068 <function>snd_card_free_when_closed</function>. This one will
1069 postpone the destruction until all devices are closed.
1077 <!-- ****************************************************** -->
1078 <!-- PCI Resource Management -->
1079 <!-- ****************************************************** -->
1080 <chapter id="pci-resource">
1081 <title>PCI Resource Management</title>
1083 <section id="pci-resource-example">
1084 <title>Full Code Example</title>
1086 In this section, we'll complete the chip-specific constructor,
1087 destructor and PCI entries. Example code is shown first,
1091 <title>PCI Resource Management Example</title>
1095 struct snd_card *card;
1096 struct pci_dev *pci;
1102 static int snd_mychip_free(struct mychip *chip)
1104 /* disable hardware here if any */
1105 .... /* (not implemented in this document) */
1107 /* release the irq */
1109 free_irq(chip->irq, chip);
1110 /* release the I/O ports & memory */
1111 pci_release_regions(chip->pci);
1112 /* disable the PCI entry */
1113 pci_disable_device(chip->pci);
1114 /* release the data */
1119 /* chip-specific constructor */
1120 static int snd_mychip_create(struct snd_card *card,
1121 struct pci_dev *pci,
1122 struct mychip **rchip)
1124 struct mychip *chip;
1126 static struct snd_device_ops ops = {
1127 .dev_free = snd_mychip_dev_free,
1132 /* initialize the PCI entry */
1133 err = pci_enable_device(pci);
1136 /* check PCI availability (28bit DMA) */
1137 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1138 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1139 printk(KERN_ERR "error to set 28bit mask DMA\n");
1140 pci_disable_device(pci);
1144 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
1146 pci_disable_device(pci);
1150 /* initialize the stuff */
1155 /* (1) PCI resource allocation */
1156 err = pci_request_regions(pci, "My Chip");
1159 pci_disable_device(pci);
1162 chip->port = pci_resource_start(pci, 0);
1163 if (request_irq(pci->irq, snd_mychip_interrupt,
1164 IRQF_SHARED, KBUILD_MODNAME, chip)) {
1165 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1166 snd_mychip_free(chip);
1169 chip->irq = pci->irq;
1171 /* (2) initialization of the chip hardware */
1172 .... /* (not implemented in this document) */
1174 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1176 snd_mychip_free(chip);
1185 static struct pci_device_id snd_mychip_ids[] = {
1186 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1187 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1191 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1193 /* pci_driver definition */
1194 static struct pci_driver driver = {
1195 .name = KBUILD_MODNAME,
1196 .id_table = snd_mychip_ids,
1197 .probe = snd_mychip_probe,
1198 .remove = snd_mychip_remove,
1201 /* module initialization */
1202 static int __init alsa_card_mychip_init(void)
1204 return pci_register_driver(&driver);
1207 /* module clean up */
1208 static void __exit alsa_card_mychip_exit(void)
1210 pci_unregister_driver(&driver);
1213 module_init(alsa_card_mychip_init)
1214 module_exit(alsa_card_mychip_exit)
1216 EXPORT_NO_SYMBOLS; /* for old kernels only */
1223 <section id="pci-resource-some-haftas">
1224 <title>Some Hafta's</title>
1226 The allocation of PCI resources is done in the
1227 <function>probe()</function> function, and usually an extra
1228 <function>xxx_create()</function> function is written for this
1233 In the case of PCI devices, you first have to call
1234 the <function>pci_enable_device()</function> function before
1235 allocating resources. Also, you need to set the proper PCI DMA
1236 mask to limit the accessed I/O range. In some cases, you might
1237 need to call <function>pci_set_master()</function> function,
1242 Suppose the 28bit mask, and the code to be added would be like:
1247 err = pci_enable_device(pci);
1250 if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1251 pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1252 printk(KERN_ERR "error to set 28bit mask DMA\n");
1253 pci_disable_device(pci);
1263 <section id="pci-resource-resource-allocation">
1264 <title>Resource Allocation</title>
1266 The allocation of I/O ports and irqs is done via standard kernel
1267 functions. Unlike ALSA ver.0.5.x., there are no helpers for
1268 that. And these resources must be released in the destructor
1269 function (see below). Also, on ALSA 0.9.x, you don't need to
1270 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
1274 Now assume that the PCI device has an I/O port with 8 bytes
1275 and an interrupt. Then struct <structname>mychip</structname> will have the
1282 struct snd_card *card;
1293 For an I/O port (and also a memory region), you need to have
1294 the resource pointer for the standard resource management. For
1295 an irq, you have to keep only the irq number (integer). But you
1296 need to initialize this number as -1 before actual allocation,
1297 since irq 0 is valid. The port address and its resource pointer
1298 can be initialized as null by
1299 <function>kzalloc()</function> automatically, so you
1300 don't have to take care of resetting them.
1304 The allocation of an I/O port is done like this:
1309 err = pci_request_regions(pci, "My Chip");
1312 pci_disable_device(pci);
1315 chip->port = pci_resource_start(pci, 0);
1323 It will reserve the I/O port region of 8 bytes of the given
1324 PCI device. The returned value, chip->res_port, is allocated
1325 via <function>kmalloc()</function> by
1326 <function>request_region()</function>. The pointer must be
1327 released via <function>kfree()</function>, but there is a
1328 problem with this. This issue will be explained later.
1332 The allocation of an interrupt source is done like this:
1337 if (request_irq(pci->irq, snd_mychip_interrupt,
1338 IRQF_SHARED, KBUILD_MODNAME, chip)) {
1339 printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1340 snd_mychip_free(chip);
1343 chip->irq = pci->irq;
1348 where <function>snd_mychip_interrupt()</function> is the
1349 interrupt handler defined <link
1350 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1351 Note that chip->irq should be defined
1352 only when <function>request_irq()</function> succeeded.
1356 On the PCI bus, interrupts can be shared. Thus,
1357 <constant>IRQF_SHARED</constant> is used as the interrupt flag of
1358 <function>request_irq()</function>.
1362 The last argument of <function>request_irq()</function> is the
1363 data pointer passed to the interrupt handler. Usually, the
1364 chip-specific record is used for that, but you can use what you
1369 I won't give details about the interrupt handler at this
1370 point, but at least its appearance can be explained now. The
1371 interrupt handler looks usually like the following:
1376 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
1378 struct mychip *chip = dev_id;
1388 Now let's write the corresponding destructor for the resources
1389 above. The role of destructor is simple: disable the hardware
1390 (if already activated) and release the resources. So far, we
1391 have no hardware part, so the disabling code is not written here.
1395 To release the resources, the <quote>check-and-release</quote>
1396 method is a safer way. For the interrupt, do like this:
1402 free_irq(chip->irq, chip);
1407 Since the irq number can start from 0, you should initialize
1408 chip->irq with a negative value (e.g. -1), so that you can
1409 check the validity of the irq number as above.
1413 When you requested I/O ports or memory regions via
1414 <function>pci_request_region()</function> or
1415 <function>pci_request_regions()</function> like in this example,
1416 release the resource(s) using the corresponding function,
1417 <function>pci_release_region()</function> or
1418 <function>pci_release_regions()</function>.
1423 pci_release_regions(chip->pci);
1430 When you requested manually via <function>request_region()</function>
1431 or <function>request_mem_region</function>, you can release it via
1432 <function>release_resource()</function>. Suppose that you keep
1433 the resource pointer returned from <function>request_region()</function>
1434 in chip->res_port, the release procedure looks like:
1439 release_and_free_resource(chip->res_port);
1446 Don't forget to call <function>pci_disable_device()</function>
1451 And finally, release the chip-specific record.
1463 We didn't implement the hardware disabling part in the above.
1464 If you need to do this, please note that the destructor may be
1465 called even before the initialization of the chip is completed.
1466 It would be better to have a flag to skip hardware disabling
1467 if the hardware was not initialized yet.
1471 When the chip-data is assigned to the card using
1472 <function>snd_device_new()</function> with
1473 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
1474 called at the last. That is, it is assured that all other
1475 components like PCMs and controls have already been released.
1476 You don't have to stop PCMs, etc. explicitly, but just
1477 call low-level hardware stopping.
1481 The management of a memory-mapped region is almost as same as
1482 the management of an I/O port. You'll need three fields like
1490 unsigned long iobase_phys;
1491 void __iomem *iobase_virt;
1497 and the allocation would be like below:
1502 if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1506 chip->iobase_phys = pci_resource_start(pci, 0);
1507 chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1508 pci_resource_len(pci, 0));
1513 and the corresponding destructor would be:
1518 static int snd_mychip_free(struct mychip *chip)
1521 if (chip->iobase_virt)
1522 iounmap(chip->iobase_virt);
1524 pci_release_regions(chip->pci);
1534 <section id="pci-resource-entries">
1535 <title>PCI Entries</title>
1537 So far, so good. Let's finish the missing PCI
1538 stuff. At first, we need a
1539 <structname>pci_device_id</structname> table for this
1540 chipset. It's a table of PCI vendor/device ID number, and some
1550 static struct pci_device_id snd_mychip_ids[] = {
1551 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1552 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1556 MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1563 The first and second fields of
1564 the <structname>pci_device_id</structname> structure are the vendor and
1565 device IDs. If you have no reason to filter the matching
1566 devices, you can leave the remaining fields as above. The last
1567 field of the <structname>pci_device_id</structname> struct contains
1568 private data for this entry. You can specify any value here, for
1569 example, to define specific operations for supported device IDs.
1570 Such an example is found in the intel8x0 driver.
1574 The last entry of this list is the terminator. You must
1575 specify this all-zero entry.
1579 Then, prepare the <structname>pci_driver</structname> record:
1584 static struct pci_driver driver = {
1585 .name = KBUILD_MODNAME,
1586 .id_table = snd_mychip_ids,
1587 .probe = snd_mychip_probe,
1588 .remove = snd_mychip_remove,
1596 The <structfield>probe</structfield> and
1597 <structfield>remove</structfield> functions have already
1598 been defined in the previous sections.
1599 The <structfield>name</structfield>
1600 field is the name string of this device. Note that you must not
1601 use a slash <quote>/</quote> in this string.
1605 And at last, the module entries:
1610 static int __init alsa_card_mychip_init(void)
1612 return pci_register_driver(&driver);
1615 static void __exit alsa_card_mychip_exit(void)
1617 pci_unregister_driver(&driver);
1620 module_init(alsa_card_mychip_init)
1621 module_exit(alsa_card_mychip_exit)
1628 Note that these module entries are tagged with
1629 <parameter>__init</parameter> and
1630 <parameter>__exit</parameter> prefixes.
1634 Oh, one thing was forgotten. If you have no exported symbols,
1635 you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1651 <!-- ****************************************************** -->
1652 <!-- PCM Interface -->
1653 <!-- ****************************************************** -->
1654 <chapter id="pcm-interface">
1655 <title>PCM Interface</title>
1657 <section id="pcm-interface-general">
1658 <title>General</title>
1660 The PCM middle layer of ALSA is quite powerful and it is only
1661 necessary for each driver to implement the low-level functions
1662 to access its hardware.
1666 For accessing to the PCM layer, you need to include
1667 <filename><sound/pcm.h></filename> first. In addition,
1668 <filename><sound/pcm_params.h></filename> might be needed
1669 if you access to some functions related with hw_param.
1673 Each card device can have up to four pcm instances. A pcm
1674 instance corresponds to a pcm device file. The limitation of
1675 number of instances comes only from the available bit size of
1676 the Linux's device numbers. Once when 64bit device number is
1677 used, we'll have more pcm instances available.
1681 A pcm instance consists of pcm playback and capture streams,
1682 and each pcm stream consists of one or more pcm substreams. Some
1683 soundcards support multiple playback functions. For example,
1684 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1685 each open, a free substream is (usually) automatically chosen
1686 and opened. Meanwhile, when only one substream exists and it was
1687 already opened, the successful open will either block
1688 or error with <constant>EAGAIN</constant> according to the
1689 file open mode. But you don't have to care about such details in your
1690 driver. The PCM middle layer will take care of such work.
1694 <section id="pcm-interface-example">
1695 <title>Full Code Example</title>
1697 The example code below does not include any hardware access
1698 routines but shows only the skeleton, how to build up the PCM
1702 <title>PCM Example Code</title>
1705 #include <sound/pcm.h>
1708 /* hardware definition */
1709 static struct snd_pcm_hardware snd_mychip_playback_hw = {
1710 .info = (SNDRV_PCM_INFO_MMAP |
1711 SNDRV_PCM_INFO_INTERLEAVED |
1712 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1713 SNDRV_PCM_INFO_MMAP_VALID),
1714 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1715 .rates = SNDRV_PCM_RATE_8000_48000,
1720 .buffer_bytes_max = 32768,
1721 .period_bytes_min = 4096,
1722 .period_bytes_max = 32768,
1724 .periods_max = 1024,
1727 /* hardware definition */
1728 static struct snd_pcm_hardware snd_mychip_capture_hw = {
1729 .info = (SNDRV_PCM_INFO_MMAP |
1730 SNDRV_PCM_INFO_INTERLEAVED |
1731 SNDRV_PCM_INFO_BLOCK_TRANSFER |
1732 SNDRV_PCM_INFO_MMAP_VALID),
1733 .formats = SNDRV_PCM_FMTBIT_S16_LE,
1734 .rates = SNDRV_PCM_RATE_8000_48000,
1739 .buffer_bytes_max = 32768,
1740 .period_bytes_min = 4096,
1741 .period_bytes_max = 32768,
1743 .periods_max = 1024,
1747 static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1749 struct mychip *chip = snd_pcm_substream_chip(substream);
1750 struct snd_pcm_runtime *runtime = substream->runtime;
1752 runtime->hw = snd_mychip_playback_hw;
1753 /* more hardware-initialization will be done here */
1758 /* close callback */
1759 static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1761 struct mychip *chip = snd_pcm_substream_chip(substream);
1762 /* the hardware-specific codes will be here */
1769 static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1771 struct mychip *chip = snd_pcm_substream_chip(substream);
1772 struct snd_pcm_runtime *runtime = substream->runtime;
1774 runtime->hw = snd_mychip_capture_hw;
1775 /* more hardware-initialization will be done here */
1780 /* close callback */
1781 static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1783 struct mychip *chip = snd_pcm_substream_chip(substream);
1784 /* the hardware-specific codes will be here */
1790 /* hw_params callback */
1791 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1792 struct snd_pcm_hw_params *hw_params)
1794 return snd_pcm_lib_malloc_pages(substream,
1795 params_buffer_bytes(hw_params));
1798 /* hw_free callback */
1799 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1801 return snd_pcm_lib_free_pages(substream);
1804 /* prepare callback */
1805 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1807 struct mychip *chip = snd_pcm_substream_chip(substream);
1808 struct snd_pcm_runtime *runtime = substream->runtime;
1810 /* set up the hardware with the current configuration
1813 mychip_set_sample_format(chip, runtime->format);
1814 mychip_set_sample_rate(chip, runtime->rate);
1815 mychip_set_channels(chip, runtime->channels);
1816 mychip_set_dma_setup(chip, runtime->dma_addr,
1822 /* trigger callback */
1823 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1827 case SNDRV_PCM_TRIGGER_START:
1828 /* do something to start the PCM engine */
1831 case SNDRV_PCM_TRIGGER_STOP:
1832 /* do something to stop the PCM engine */
1840 /* pointer callback */
1841 static snd_pcm_uframes_t
1842 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1844 struct mychip *chip = snd_pcm_substream_chip(substream);
1845 unsigned int current_ptr;
1847 /* get the current hardware pointer */
1848 current_ptr = mychip_get_hw_pointer(chip);
1853 static struct snd_pcm_ops snd_mychip_playback_ops = {
1854 .open = snd_mychip_playback_open,
1855 .close = snd_mychip_playback_close,
1856 .ioctl = snd_pcm_lib_ioctl,
1857 .hw_params = snd_mychip_pcm_hw_params,
1858 .hw_free = snd_mychip_pcm_hw_free,
1859 .prepare = snd_mychip_pcm_prepare,
1860 .trigger = snd_mychip_pcm_trigger,
1861 .pointer = snd_mychip_pcm_pointer,
1865 static struct snd_pcm_ops snd_mychip_capture_ops = {
1866 .open = snd_mychip_capture_open,
1867 .close = snd_mychip_capture_close,
1868 .ioctl = snd_pcm_lib_ioctl,
1869 .hw_params = snd_mychip_pcm_hw_params,
1870 .hw_free = snd_mychip_pcm_hw_free,
1871 .prepare = snd_mychip_pcm_prepare,
1872 .trigger = snd_mychip_pcm_trigger,
1873 .pointer = snd_mychip_pcm_pointer,
1877 * definitions of capture are omitted here...
1880 /* create a pcm device */
1881 static int snd_mychip_new_pcm(struct mychip *chip)
1883 struct snd_pcm *pcm;
1886 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1889 pcm->private_data = chip;
1890 strcpy(pcm->name, "My Chip");
1893 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1894 &snd_mychip_playback_ops);
1895 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1896 &snd_mychip_capture_ops);
1897 /* pre-allocation of buffers */
1898 /* NOTE: this may fail */
1899 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1900 snd_dma_pci_data(chip->pci),
1910 <section id="pcm-interface-constructor">
1911 <title>Constructor</title>
1913 A pcm instance is allocated by the <function>snd_pcm_new()</function>
1914 function. It would be better to create a constructor for pcm,
1920 static int snd_mychip_new_pcm(struct mychip *chip)
1922 struct snd_pcm *pcm;
1925 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1928 pcm->private_data = chip;
1929 strcpy(pcm->name, "My Chip");
1940 The <function>snd_pcm_new()</function> function takes four
1941 arguments. The first argument is the card pointer to which this
1942 pcm is assigned, and the second is the ID string.
1946 The third argument (<parameter>index</parameter>, 0 in the
1947 above) is the index of this new pcm. It begins from zero. If
1948 you create more than one pcm instances, specify the
1949 different numbers in this argument. For example,
1950 <parameter>index</parameter> = 1 for the second PCM device.
1954 The fourth and fifth arguments are the number of substreams
1955 for playback and capture, respectively. Here 1 is used for
1956 both arguments. When no playback or capture substreams are available,
1957 pass 0 to the corresponding argument.
1961 If a chip supports multiple playbacks or captures, you can
1962 specify more numbers, but they must be handled properly in
1963 open/close, etc. callbacks. When you need to know which
1964 substream you are referring to, then it can be obtained from
1965 struct <structname>snd_pcm_substream</structname> data passed to each callback
1971 struct snd_pcm_substream *substream;
1972 int index = substream->number;
1979 After the pcm is created, you need to set operators for each
1985 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1986 &snd_mychip_playback_ops);
1987 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1988 &snd_mychip_capture_ops);
1995 The operators are defined typically like this:
2000 static struct snd_pcm_ops snd_mychip_playback_ops = {
2001 .open = snd_mychip_pcm_open,
2002 .close = snd_mychip_pcm_close,
2003 .ioctl = snd_pcm_lib_ioctl,
2004 .hw_params = snd_mychip_pcm_hw_params,
2005 .hw_free = snd_mychip_pcm_hw_free,
2006 .prepare = snd_mychip_pcm_prepare,
2007 .trigger = snd_mychip_pcm_trigger,
2008 .pointer = snd_mychip_pcm_pointer,
2014 All the callbacks are described in the
2015 <link linkend="pcm-interface-operators"><citetitle>
2016 Operators</citetitle></link> subsection.
2020 After setting the operators, you probably will want to
2021 pre-allocate the buffer. For the pre-allocation, simply call
2027 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2028 snd_dma_pci_data(chip->pci),
2034 It will allocate a buffer up to 64kB as default.
2035 Buffer management details will be described in the later section <link
2036 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2037 Management</citetitle></link>.
2041 Additionally, you can set some extra information for this pcm
2042 in pcm->info_flags.
2043 The available values are defined as
2044 <constant>SNDRV_PCM_INFO_XXX</constant> in
2045 <filename><sound/asound.h></filename>, which is used for
2046 the hardware definition (described later). When your soundchip
2047 supports only half-duplex, specify like this:
2052 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2059 <section id="pcm-interface-destructor">
2060 <title>... And the Destructor?</title>
2062 The destructor for a pcm instance is not always
2063 necessary. Since the pcm device will be released by the middle
2064 layer code automatically, you don't have to call the destructor
2069 The destructor would be necessary if you created
2070 special records internally and needed to release them. In such a
2071 case, set the destructor function to
2072 pcm->private_free:
2075 <title>PCM Instance with a Destructor</title>
2078 static void mychip_pcm_free(struct snd_pcm *pcm)
2080 struct mychip *chip = snd_pcm_chip(pcm);
2081 /* free your own data */
2082 kfree(chip->my_private_pcm_data);
2083 /* do what you like else */
2087 static int snd_mychip_new_pcm(struct mychip *chip)
2089 struct snd_pcm *pcm;
2091 /* allocate your own data */
2092 chip->my_private_pcm_data = kmalloc(...);
2093 /* set the destructor */
2094 pcm->private_data = chip;
2095 pcm->private_free = mychip_pcm_free;
2104 <section id="pcm-interface-runtime">
2105 <title>Runtime Pointer - The Chest of PCM Information</title>
2107 When the PCM substream is opened, a PCM runtime instance is
2108 allocated and assigned to the substream. This pointer is
2109 accessible via <constant>substream->runtime</constant>.
2110 This runtime pointer holds most information you need
2111 to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2112 pointers, mmap records, spinlocks, etc.
2116 The definition of runtime instance is found in
2117 <filename><sound/pcm.h></filename>. Here are
2118 the contents of this file:
2122 struct _snd_pcm_runtime {
2124 struct snd_pcm_substream *trigger_master;
2125 snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2127 snd_pcm_uframes_t avail_max;
2128 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
2129 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2131 /* -- HW params -- */
2132 snd_pcm_access_t access; /* access mode */
2133 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
2134 snd_pcm_subformat_t subformat; /* subformat */
2135 unsigned int rate; /* rate in Hz */
2136 unsigned int channels; /* channels */
2137 snd_pcm_uframes_t period_size; /* period size */
2138 unsigned int periods; /* periods */
2139 snd_pcm_uframes_t buffer_size; /* buffer size */
2140 unsigned int tick_time; /* tick time */
2141 snd_pcm_uframes_t min_align; /* Min alignment for the format */
2143 unsigned int frame_bits;
2144 unsigned int sample_bits;
2146 unsigned int rate_num;
2147 unsigned int rate_den;
2149 /* -- SW params -- */
2150 struct timespec tstamp_mode; /* mmap timestamp is updated */
2151 unsigned int period_step;
2152 unsigned int sleep_min; /* min ticks to sleep */
2153 snd_pcm_uframes_t start_threshold;
2154 snd_pcm_uframes_t stop_threshold;
2155 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2156 noise is nearest than this */
2157 snd_pcm_uframes_t silence_size; /* Silence filling size */
2158 snd_pcm_uframes_t boundary; /* pointers wrap point */
2160 snd_pcm_uframes_t silenced_start;
2161 snd_pcm_uframes_t silenced_size;
2163 snd_pcm_sync_id_t sync; /* hardware synchronization ID */
2166 volatile struct snd_pcm_mmap_status *status;
2167 volatile struct snd_pcm_mmap_control *control;
2168 atomic_t mmap_count;
2170 /* -- locking / scheduling -- */
2172 wait_queue_head_t sleep;
2173 struct timer_list tick_timer;
2174 struct fasync_struct *fasync;
2176 /* -- private section -- */
2178 void (*private_free)(struct snd_pcm_runtime *runtime);
2180 /* -- hardware description -- */
2181 struct snd_pcm_hardware hw;
2182 struct snd_pcm_hw_constraints hw_constraints;
2184 /* -- interrupt callbacks -- */
2185 void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2186 void (*transfer_ack_end)(struct snd_pcm_substream *substream);
2189 unsigned int timer_resolution; /* timer resolution */
2192 unsigned char *dma_area; /* DMA area */
2193 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
2194 size_t dma_bytes; /* size of DMA area */
2196 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
2198 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2199 /* -- OSS things -- */
2200 struct snd_pcm_oss_runtime oss;
2209 For the operators (callbacks) of each sound driver, most of
2210 these records are supposed to be read-only. Only the PCM
2211 middle-layer changes / updates them. The exceptions are
2212 the hardware description (hw), interrupt callbacks
2213 (transfer_ack_xxx), DMA buffer information, and the private
2214 data. Besides, if you use the standard buffer allocation
2215 method via <function>snd_pcm_lib_malloc_pages()</function>,
2216 you don't need to set the DMA buffer information by yourself.
2220 In the sections below, important records are explained.
2223 <section id="pcm-interface-runtime-hw">
2224 <title>Hardware Description</title>
2226 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
2227 contains the definitions of the fundamental hardware
2228 configuration. Above all, you'll need to define this in
2229 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2230 the open callback</citetitle></link>.
2231 Note that the runtime instance holds the copy of the
2232 descriptor, not the pointer to the existing descriptor. That
2233 is, in the open callback, you can modify the copied descriptor
2234 (<constant>runtime->hw</constant>) as you need. For example, if the maximum
2235 number of channels is 1 only on some chip models, you can
2236 still use the same hardware descriptor and change the
2241 struct snd_pcm_runtime *runtime = substream->runtime;
2243 runtime->hw = snd_mychip_playback_hw; /* common definition */
2244 if (chip->model == VERY_OLD_ONE)
2245 runtime->hw.channels_max = 1;
2252 Typically, you'll have a hardware descriptor as below:
2256 static struct snd_pcm_hardware snd_mychip_playback_hw = {
2257 .info = (SNDRV_PCM_INFO_MMAP |
2258 SNDRV_PCM_INFO_INTERLEAVED |
2259 SNDRV_PCM_INFO_BLOCK_TRANSFER |
2260 SNDRV_PCM_INFO_MMAP_VALID),
2261 .formats = SNDRV_PCM_FMTBIT_S16_LE,
2262 .rates = SNDRV_PCM_RATE_8000_48000,
2267 .buffer_bytes_max = 32768,
2268 .period_bytes_min = 4096,
2269 .period_bytes_max = 32768,
2271 .periods_max = 1024,
2281 The <structfield>info</structfield> field contains the type and
2282 capabilities of this pcm. The bit flags are defined in
2283 <filename><sound/asound.h></filename> as
2284 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2285 have to specify whether the mmap is supported and which
2286 interleaved format is supported.
2287 When the hardware supports mmap, add the
2288 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2289 hardware supports the interleaved or the non-interleaved
2290 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2291 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2292 be set, respectively. If both are supported, you can set both,
2297 In the above example, <constant>MMAP_VALID</constant> and
2298 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
2299 mode. Usually both are set. Of course,
2300 <constant>MMAP_VALID</constant> is set only if the mmap is
2305 The other possible flags are
2306 <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2307 <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2308 <constant>PAUSE</constant> bit means that the pcm supports the
2309 <quote>pause</quote> operation, while the
2310 <constant>RESUME</constant> bit means that the pcm supports
2311 the full <quote>suspend/resume</quote> operation.
2312 If the <constant>PAUSE</constant> flag is set,
2313 the <structfield>trigger</structfield> callback below
2314 must handle the corresponding (pause push/release) commands.
2315 The suspend/resume trigger commands can be defined even without
2316 the <constant>RESUME</constant> flag. See <link
2317 linkend="power-management"><citetitle>
2318 Power Management</citetitle></link> section for details.
2322 When the PCM substreams can be synchronized (typically,
2323 synchronized start/stop of a playback and a capture streams),
2324 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2325 too. In this case, you'll need to check the linked-list of
2326 PCM substreams in the trigger callback. This will be
2327 described in the later section.
2333 <structfield>formats</structfield> field contains the bit-flags
2334 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2335 If the hardware supports more than one format, give all or'ed
2336 bits. In the example above, the signed 16bit little-endian
2337 format is specified.
2343 <structfield>rates</structfield> field contains the bit-flags of
2344 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2345 When the chip supports continuous rates, pass
2346 <constant>CONTINUOUS</constant> bit additionally.
2347 The pre-defined rate bits are provided only for typical
2348 rates. If your chip supports unconventional rates, you need to add
2349 the <constant>KNOT</constant> bit and set up the hardware
2350 constraint manually (explained later).
2356 <structfield>rate_min</structfield> and
2357 <structfield>rate_max</structfield> define the minimum and
2358 maximum sample rate. This should correspond somehow to
2359 <structfield>rates</structfield> bits.
2365 <structfield>channel_min</structfield> and
2366 <structfield>channel_max</structfield>
2367 define, as you might already expected, the minimum and maximum
2374 <structfield>buffer_bytes_max</structfield> defines the
2375 maximum buffer size in bytes. There is no
2376 <structfield>buffer_bytes_min</structfield> field, since
2377 it can be calculated from the minimum period size and the
2378 minimum number of periods.
2379 Meanwhile, <structfield>period_bytes_min</structfield> and
2380 define the minimum and maximum size of the period in bytes.
2381 <structfield>periods_max</structfield> and
2382 <structfield>periods_min</structfield> define the maximum and
2383 minimum number of periods in the buffer.
2387 The <quote>period</quote> is a term that corresponds to
2388 a fragment in the OSS world. The period defines the size at
2389 which a PCM interrupt is generated. This size strongly
2390 depends on the hardware.
2391 Generally, the smaller period size will give you more
2392 interrupts, that is, more controls.
2393 In the case of capture, this size defines the input latency.
2394 On the other hand, the whole buffer size defines the
2395 output latency for the playback direction.
2401 There is also a field <structfield>fifo_size</structfield>.
2402 This specifies the size of the hardware FIFO, but currently it
2403 is neither used in the driver nor in the alsa-lib. So, you
2404 can ignore this field.
2411 <section id="pcm-interface-runtime-config">
2412 <title>PCM Configurations</title>
2414 Ok, let's go back again to the PCM runtime records.
2415 The most frequently referred records in the runtime instance are
2416 the PCM configurations.
2417 The PCM configurations are stored in the runtime instance
2418 after the application sends <type>hw_params</type> data via
2419 alsa-lib. There are many fields copied from hw_params and
2420 sw_params structs. For example,
2421 <structfield>format</structfield> holds the format type
2422 chosen by the application. This field contains the enum value
2423 <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2427 One thing to be noted is that the configured buffer and period
2428 sizes are stored in <quote>frames</quote> in the runtime.
2429 In the ALSA world, 1 frame = channels * samples-size.
2430 For conversion between frames and bytes, you can use the
2431 <function>frames_to_bytes()</function> and
2432 <function>bytes_to_frames()</function> helper functions.
2436 period_bytes = frames_to_bytes(runtime, runtime->period_size);
2443 Also, many software parameters (sw_params) are
2444 stored in frames, too. Please check the type of the field.
2445 <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2446 integer while <type>snd_pcm_sframes_t</type> is for the frames
2451 <section id="pcm-interface-runtime-dma">
2452 <title>DMA Buffer Information</title>
2454 The DMA buffer is defined by the following four fields,
2455 <structfield>dma_area</structfield>,
2456 <structfield>dma_addr</structfield>,
2457 <structfield>dma_bytes</structfield> and
2458 <structfield>dma_private</structfield>.
2459 The <structfield>dma_area</structfield> holds the buffer
2460 pointer (the logical address). You can call
2461 <function>memcpy</function> from/to
2462 this pointer. Meanwhile, <structfield>dma_addr</structfield>
2463 holds the physical address of the buffer. This field is
2464 specified only when the buffer is a linear buffer.
2465 <structfield>dma_bytes</structfield> holds the size of buffer
2466 in bytes. <structfield>dma_private</structfield> is used for
2467 the ALSA DMA allocator.
2471 If you use a standard ALSA function,
2472 <function>snd_pcm_lib_malloc_pages()</function>, for
2473 allocating the buffer, these fields are set by the ALSA middle
2474 layer, and you should <emphasis>not</emphasis> change them by
2475 yourself. You can read them but not write them.
2476 On the other hand, if you want to allocate the buffer by
2477 yourself, you'll need to manage it in hw_params callback.
2478 At least, <structfield>dma_bytes</structfield> is mandatory.
2479 <structfield>dma_area</structfield> is necessary when the
2480 buffer is mmapped. If your driver doesn't support mmap, this
2481 field is not necessary. <structfield>dma_addr</structfield>
2482 is also optional. You can use
2483 <structfield>dma_private</structfield> as you like, too.
2487 <section id="pcm-interface-runtime-status">
2488 <title>Running Status</title>
2490 The running status can be referred via <constant>runtime->status</constant>.
2491 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
2492 record. For example, you can get the current DMA hardware
2493 pointer via <constant>runtime->status->hw_ptr</constant>.
2497 The DMA application pointer can be referred via
2498 <constant>runtime->control</constant>, which points to the
2499 struct <structname>snd_pcm_mmap_control</structname> record.
2500 However, accessing directly to this value is not recommended.
2504 <section id="pcm-interface-runtime-private">
2505 <title>Private Data</title>
2507 You can allocate a record for the substream and store it in
2508 <constant>runtime->private_data</constant>. Usually, this
2510 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2511 the open callback</citetitle></link>.
2512 Don't mix this with <constant>pcm->private_data</constant>.
2513 The <constant>pcm->private_data</constant> usually points to the
2514 chip instance assigned statically at the creation of PCM, while the
2515 <constant>runtime->private_data</constant> points to a dynamic
2516 data structure created at the PCM open callback.
2521 static int snd_xxx_open(struct snd_pcm_substream *substream)
2523 struct my_pcm_data *data;
2525 data = kmalloc(sizeof(*data), GFP_KERNEL);
2526 substream->runtime->private_data = data;
2535 The allocated object must be released in
2536 <link linkend="pcm-interface-operators-open-callback"><citetitle>
2537 the close callback</citetitle></link>.
2541 <section id="pcm-interface-runtime-intr">
2542 <title>Interrupt Callbacks</title>
2544 The field <structfield>transfer_ack_begin</structfield> and
2545 <structfield>transfer_ack_end</structfield> are called at
2546 the beginning and at the end of
2547 <function>snd_pcm_period_elapsed()</function>, respectively.
2553 <section id="pcm-interface-operators">
2554 <title>Operators</title>
2556 OK, now let me give details about each pcm callback
2557 (<parameter>ops</parameter>). In general, every callback must
2558 return 0 if successful, or a negative error number
2559 such as <constant>-EINVAL</constant>. To choose an appropriate
2560 error number, it is advised to check what value other parts of
2561 the kernel return when the same kind of request fails.
2565 The callback function takes at least the argument with
2566 <structname>snd_pcm_substream</structname> pointer. To retrieve
2567 the chip record from the given substream instance, you can use the
2574 struct mychip *chip = snd_pcm_substream_chip(substream);
2581 The macro reads <constant>substream->private_data</constant>,
2582 which is a copy of <constant>pcm->private_data</constant>.
2583 You can override the former if you need to assign different data
2584 records per PCM substream. For example, the cmi8330 driver assigns
2585 different private_data for playback and capture directions,
2586 because it uses two different codecs (SB- and AD-compatible) for
2587 different directions.
2590 <section id="pcm-interface-operators-open-callback">
2591 <title>open callback</title>
2596 static int snd_xxx_open(struct snd_pcm_substream *substream);
2601 This is called when a pcm substream is opened.
2605 At least, here you have to initialize the runtime->hw
2606 record. Typically, this is done by like this:
2611 static int snd_xxx_open(struct snd_pcm_substream *substream)
2613 struct mychip *chip = snd_pcm_substream_chip(substream);
2614 struct snd_pcm_runtime *runtime = substream->runtime;
2616 runtime->hw = snd_mychip_playback_hw;
2623 where <parameter>snd_mychip_playback_hw</parameter> is the
2624 pre-defined hardware description.
2628 You can allocate a private data in this callback, as described
2629 in <link linkend="pcm-interface-runtime-private"><citetitle>
2630 Private Data</citetitle></link> section.
2634 If the hardware configuration needs more constraints, set the
2635 hardware constraints here, too.
2636 See <link linkend="pcm-interface-constraints"><citetitle>
2637 Constraints</citetitle></link> for more details.
2641 <section id="pcm-interface-operators-close-callback">
2642 <title>close callback</title>
2647 static int snd_xxx_close(struct snd_pcm_substream *substream);
2652 Obviously, this is called when a pcm substream is closed.
2656 Any private instance for a pcm substream allocated in the
2657 open callback will be released here.
2662 static int snd_xxx_close(struct snd_pcm_substream *substream)
2665 kfree(substream->runtime->private_data);
2674 <section id="pcm-interface-operators-ioctl-callback">
2675 <title>ioctl callback</title>
2677 This is used for any special call to pcm ioctls. But
2678 usually you can pass a generic ioctl callback,
2679 <function>snd_pcm_lib_ioctl</function>.
2683 <section id="pcm-interface-operators-hw-params-callback">
2684 <title>hw_params callback</title>
2689 static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2690 struct snd_pcm_hw_params *hw_params);
2697 This is called when the hardware parameter
2698 (<structfield>hw_params</structfield>) is set
2699 up by the application,
2700 that is, once when the buffer size, the period size, the
2701 format, etc. are defined for the pcm substream.
2705 Many hardware setups should be done in this callback,
2706 including the allocation of buffers.
2710 Parameters to be initialized are retrieved by
2711 <function>params_xxx()</function> macros. To allocate
2712 buffer, you can call a helper function,
2717 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2722 <function>snd_pcm_lib_malloc_pages()</function> is available
2723 only when the DMA buffers have been pre-allocated.
2724 See the section <link
2725 linkend="buffer-and-memory-buffer-types"><citetitle>
2726 Buffer Types</citetitle></link> for more details.
2730 Note that this and <structfield>prepare</structfield> callbacks
2731 may be called multiple times per initialization.
2732 For example, the OSS emulation may
2733 call these callbacks at each change via its ioctl.
2737 Thus, you need to be careful not to allocate the same buffers
2738 many times, which will lead to memory leaks! Calling the
2739 helper function above many times is OK. It will release the
2740 previous buffer automatically when it was already allocated.
2744 Another note is that this callback is non-atomic
2745 (schedulable) as default, i.e. when no
2746 <structfield>nonatomic</structfield> flag set.
2747 This is important, because the
2748 <structfield>trigger</structfield> callback
2749 is atomic (non-schedulable). That is, mutexes or any
2750 schedule-related functions are not available in
2751 <structfield>trigger</structfield> callback.
2752 Please see the subsection
2753 <link linkend="pcm-interface-atomicity"><citetitle>
2754 Atomicity</citetitle></link> for details.
2758 <section id="pcm-interface-operators-hw-free-callback">
2759 <title>hw_free callback</title>
2764 static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2771 This is called to release the resources allocated via
2772 <structfield>hw_params</structfield>. For example, releasing the
2774 <function>snd_pcm_lib_malloc_pages()</function> is done by
2775 calling the following:
2780 snd_pcm_lib_free_pages(substream);
2787 This function is always called before the close callback is called.
2788 Also, the callback may be called multiple times, too.
2789 Keep track whether the resource was already released.
2793 <section id="pcm-interface-operators-prepare-callback">
2794 <title>prepare callback</title>
2799 static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2806 This callback is called when the pcm is
2807 <quote>prepared</quote>. You can set the format type, sample
2808 rate, etc. here. The difference from
2809 <structfield>hw_params</structfield> is that the
2810 <structfield>prepare</structfield> callback will be called each
2812 <function>snd_pcm_prepare()</function> is called, i.e. when
2813 recovering after underruns, etc.
2817 Note that this callback is now non-atomic.
2818 You can use schedule-related functions safely in this callback.
2822 In this and the following callbacks, you can refer to the
2823 values via the runtime record,
2824 substream->runtime.
2825 For example, to get the current
2826 rate, format or channels, access to
2828 runtime->format or
2829 runtime->channels, respectively.
2830 The physical address of the allocated buffer is set to
2831 runtime->dma_area. The buffer and period sizes are
2832 in runtime->buffer_size and runtime->period_size,
2837 Be careful that this callback will be called many times at
2842 <section id="pcm-interface-operators-trigger-callback">
2843 <title>trigger callback</title>
2848 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2853 This is called when the pcm is started, stopped or paused.
2857 Which action is specified in the second argument,
2858 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2859 <filename><sound/pcm.h></filename>. At least,
2860 the <constant>START</constant> and <constant>STOP</constant>
2861 commands must be defined in this callback.
2867 case SNDRV_PCM_TRIGGER_START:
2868 /* do something to start the PCM engine */
2870 case SNDRV_PCM_TRIGGER_STOP:
2871 /* do something to stop the PCM engine */
2882 When the pcm supports the pause operation (given in the info
2883 field of the hardware table), the <constant>PAUSE_PUSH</constant>
2884 and <constant>PAUSE_RELEASE</constant> commands must be
2885 handled here, too. The former is the command to pause the pcm,
2886 and the latter to restart the pcm again.
2890 When the pcm supports the suspend/resume operation,
2891 regardless of full or partial suspend/resume support,
2892 the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2893 commands must be handled, too.
2894 These commands are issued when the power-management status is
2895 changed. Obviously, the <constant>SUSPEND</constant> and
2896 <constant>RESUME</constant> commands
2897 suspend and resume the pcm substream, and usually, they
2898 are identical to the <constant>STOP</constant> and
2899 <constant>START</constant> commands, respectively.
2900 See the <link linkend="power-management"><citetitle>
2901 Power Management</citetitle></link> section for details.
2905 As mentioned, this callback is atomic as default unless
2906 <structfield>nonatomic</structfield> flag set, and
2907 you cannot call functions which may sleep.
2908 The trigger callback should be as minimal as possible,
2909 just really triggering the DMA. The other stuff should be
2910 initialized hw_params and prepare callbacks properly
2915 <section id="pcm-interface-operators-pointer-callback">
2916 <title>pointer callback</title>
2921 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2926 This callback is called when the PCM middle layer inquires
2927 the current hardware position on the buffer. The position must
2928 be returned in frames,
2929 ranging from 0 to buffer_size - 1.
2933 This is called usually from the buffer-update routine in the
2934 pcm middle layer, which is invoked when
2935 <function>snd_pcm_period_elapsed()</function> is called in the
2936 interrupt routine. Then the pcm middle layer updates the
2937 position and calculates the available space, and wakes up the
2938 sleeping poll threads, etc.
2942 This callback is also atomic as default.
2946 <section id="pcm-interface-operators-copy-silence">
2947 <title>copy and silence callbacks</title>
2949 These callbacks are not mandatory, and can be omitted in
2950 most cases. These callbacks are used when the hardware buffer
2951 cannot be in the normal memory space. Some chips have their
2952 own buffer on the hardware which is not mappable. In such a
2953 case, you have to transfer the data manually from the memory
2954 buffer to the hardware buffer. Or, if the buffer is
2955 non-contiguous on both physical and virtual memory spaces,
2956 these callbacks must be defined, too.
2960 If these two callbacks are defined, copy and set-silence
2961 operations are done by them. The detailed will be described in
2962 the later section <link
2963 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2964 Management</citetitle></link>.
2968 <section id="pcm-interface-operators-ack">
2969 <title>ack callback</title>
2971 This callback is also not mandatory. This callback is called
2972 when the appl_ptr is updated in read or write operations.
2973 Some drivers like emu10k1-fx and cs46xx need to track the
2974 current appl_ptr for the internal buffer, and this callback
2975 is useful only for such a purpose.
2978 This callback is atomic as default.
2982 <section id="pcm-interface-operators-page-callback">
2983 <title>page callback</title>
2986 This callback is optional too. This callback is used
2987 mainly for non-contiguous buffers. The mmap calls this
2988 callback to get the page address. Some examples will be
2989 explained in the later section <link
2990 linkend="buffer-and-memory"><citetitle>Buffer and Memory
2991 Management</citetitle></link>, too.
2996 <section id="pcm-interface-interrupt-handler">
2997 <title>Interrupt Handler</title>
2999 The rest of pcm stuff is the PCM interrupt handler. The
3000 role of PCM interrupt handler in the sound driver is to update
3001 the buffer position and to tell the PCM middle layer when the
3002 buffer position goes across the prescribed period size. To
3003 inform this, call the <function>snd_pcm_period_elapsed()</function>
3008 There are several types of sound chips to generate the interrupts.
3011 <section id="pcm-interface-interrupt-handler-boundary">
3012 <title>Interrupts at the period (fragment) boundary</title>
3014 This is the most frequently found type: the hardware
3015 generates an interrupt at each period boundary.
3016 In this case, you can call
3017 <function>snd_pcm_period_elapsed()</function> at each
3022 <function>snd_pcm_period_elapsed()</function> takes the
3023 substream pointer as its argument. Thus, you need to keep the
3024 substream pointer accessible from the chip instance. For
3025 example, define substream field in the chip record to hold the
3026 current running substream pointer, and set the pointer value
3027 at open callback (and reset at close callback).
3031 If you acquire a spinlock in the interrupt handler, and the
3032 lock is used in other pcm callbacks, too, then you have to
3033 release the lock before calling
3034 <function>snd_pcm_period_elapsed()</function>, because
3035 <function>snd_pcm_period_elapsed()</function> calls other pcm
3040 Typical code would be like:
3043 <title>Interrupt Handler Case #1</title>
3046 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3048 struct mychip *chip = dev_id;
3049 spin_lock(&chip->lock);
3051 if (pcm_irq_invoked(chip)) {
3052 /* call updater, unlock before it */
3053 spin_unlock(&chip->lock);
3054 snd_pcm_period_elapsed(chip->substream);
3055 spin_lock(&chip->lock);
3056 /* acknowledge the interrupt if necessary */
3059 spin_unlock(&chip->lock);
3068 <section id="pcm-interface-interrupt-handler-timer">
3069 <title>High frequency timer interrupts</title>
3071 This happens when the hardware doesn't generate interrupts
3072 at the period boundary but issues timer interrupts at a fixed
3073 timer rate (e.g. es1968 or ymfpci drivers).
3074 In this case, you need to check the current hardware
3075 position and accumulate the processed sample length at each
3076 interrupt. When the accumulated size exceeds the period
3078 <function>snd_pcm_period_elapsed()</function> and reset the
3083 Typical code would be like the following.
3086 <title>Interrupt Handler Case #2</title>
3089 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3091 struct mychip *chip = dev_id;
3092 spin_lock(&chip->lock);
3094 if (pcm_irq_invoked(chip)) {
3095 unsigned int last_ptr, size;
3096 /* get the current hardware pointer (in frames) */
3097 last_ptr = get_hw_ptr(chip);
3098 /* calculate the processed frames since the
3101 if (last_ptr < chip->last_ptr)
3102 size = runtime->buffer_size + last_ptr
3105 size = last_ptr - chip->last_ptr;
3106 /* remember the last updated point */
3107 chip->last_ptr = last_ptr;
3108 /* accumulate the size */
3110 /* over the period boundary? */
3111 if (chip->size >= runtime->period_size) {
3112 /* reset the accumulator */
3113 chip->size %= runtime->period_size;
3115 spin_unlock(&chip->lock);
3116 snd_pcm_period_elapsed(substream);
3117 spin_lock(&chip->lock);
3119 /* acknowledge the interrupt if necessary */
3122 spin_unlock(&chip->lock);
3131 <section id="pcm-interface-interrupt-handler-both">
3132 <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3134 In both cases, even if more than one period are elapsed, you
3136 <function>snd_pcm_period_elapsed()</function> many times. Call
3137 only once. And the pcm layer will check the current hardware
3138 pointer and update to the latest status.
3143 <section id="pcm-interface-atomicity">
3144 <title>Atomicity</title>
3146 One of the most important (and thus difficult to debug) problems
3147 in kernel programming are race conditions.
3148 In the Linux kernel, they are usually avoided via spin-locks, mutexes
3149 or semaphores. In general, if a race condition can happen
3150 in an interrupt handler, it has to be managed atomically, and you
3151 have to use a spinlock to protect the critical session. If the
3152 critical section is not in interrupt handler code and
3153 if taking a relatively long time to execute is acceptable, you
3154 should use mutexes or semaphores instead.
3158 As already seen, some pcm callbacks are atomic and some are
3159 not. For example, the <parameter>hw_params</parameter> callback is
3160 non-atomic, while <parameter>trigger</parameter> callback is
3161 atomic. This means, the latter is called already in a spinlock
3162 held by the PCM middle layer. Please take this atomicity into
3163 account when you choose a locking scheme in the callbacks.
3167 In the atomic callbacks, you cannot use functions which may call
3168 <function>schedule</function> or go to
3169 <function>sleep</function>. Semaphores and mutexes can sleep,
3170 and hence they cannot be used inside the atomic callbacks
3171 (e.g. <parameter>trigger</parameter> callback).
3172 To implement some delay in such a callback, please use
3173 <function>udelay()</function> or <function>mdelay()</function>.
3177 All three atomic callbacks (trigger, pointer, and ack) are
3178 called with local interrupts disabled.
3182 The recent changes in PCM core code, however, allow all PCM
3183 operations to be non-atomic. This assumes that the all caller
3184 sides are in non-atomic contexts. For example, the function
3185 <function>snd_pcm_period_elapsed()</function> is called
3186 typically from the interrupt handler. But, if you set up the
3187 driver to use a threaded interrupt handler, this call can be in
3188 non-atomic context, too. In such a case, you can set
3189 <structfield>nonatomic</structfield> filed of
3190 <structname>snd_pcm</structname> object after creating it.
3191 When this flag is set, mutex and rwsem are used internally in
3192 the PCM core instead of spin and rwlocks, so that you can call
3193 all PCM functions safely in a non-atomic context.
3197 <section id="pcm-interface-constraints">
3198 <title>Constraints</title>
3200 If your chip supports unconventional sample rates, or only the
3201 limited samples, you need to set a constraint for the
3206 For example, in order to restrict the sample rates in the some
3207 supported values, use
3208 <function>snd_pcm_hw_constraint_list()</function>.
3209 You need to call this function in the open callback.
3212 <title>Example of Hardware Constraints</title>
3215 static unsigned int rates[] =
3216 {4000, 10000, 22050, 44100};
3217 static struct snd_pcm_hw_constraint_list constraints_rates = {
3218 .count = ARRAY_SIZE(rates),
3223 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3227 err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3228 SNDRV_PCM_HW_PARAM_RATE,
3229 &constraints_rates);
3240 There are many different constraints.
3241 Look at <filename>sound/pcm.h</filename> for a complete list.
3242 You can even define your own constraint rules.
3243 For example, let's suppose my_chip can manage a substream of 1 channel
3244 if and only if the format is S16_LE, otherwise it supports any format
3245 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3246 other constraint_list). You can build a rule like this:
3249 <title>Example of Hardware Constraints for Channels</title>
3252 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3253 struct snd_pcm_hw_rule *rule)
3255 struct snd_interval *c = hw_param_interval(params,
3256 SNDRV_PCM_HW_PARAM_CHANNELS);
3257 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3258 struct snd_interval ch;
3260 snd_interval_any(&ch);
3261 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3262 ch.min = ch.max = 1;
3264 return snd_interval_refine(c, &ch);
3274 Then you need to call this function to add your rule:
3279 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3280 hw_rule_channels_by_format, NULL,
3281 SNDRV_PCM_HW_PARAM_FORMAT, -1);
3288 The rule function is called when an application sets the PCM
3289 format, and it refines the number of channels accordingly.
3290 But an application may set the number of channels before
3291 setting the format. Thus you also need to define the inverse rule:
3294 <title>Example of Hardware Constraints for Formats</title>
3297 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3298 struct snd_pcm_hw_rule *rule)
3300 struct snd_interval *c = hw_param_interval(params,
3301 SNDRV_PCM_HW_PARAM_CHANNELS);
3302 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3303 struct snd_mask fmt;
3305 snd_mask_any(&fmt); /* Init the struct */
3307 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3308 return snd_mask_refine(f, &fmt);
3318 ...and in the open callback:
3322 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3323 hw_rule_format_by_channels, NULL,
3324 SNDRV_PCM_HW_PARAM_CHANNELS, -1);
3331 I won't give more details here, rather I
3332 would like to say, <quote>Luke, use the source.</quote>
3339 <!-- ****************************************************** -->
3340 <!-- Control Interface -->
3341 <!-- ****************************************************** -->
3342 <chapter id="control-interface">
3343 <title>Control Interface</title>
3345 <section id="control-interface-general">
3346 <title>General</title>
3348 The control interface is used widely for many switches,
3349 sliders, etc. which are accessed from user-space. Its most
3350 important use is the mixer interface. In other words, since ALSA
3351 0.9.x, all the mixer stuff is implemented on the control kernel API.
3355 ALSA has a well-defined AC97 control module. If your chip
3356 supports only the AC97 and nothing else, you can skip this
3361 The control API is defined in
3362 <filename><sound/control.h></filename>.
3363 Include this file if you want to add your own controls.
3367 <section id="control-interface-definition">
3368 <title>Definition of Controls</title>
3370 To create a new control, you need to define the
3372 callbacks: <structfield>info</structfield>,
3373 <structfield>get</structfield> and
3374 <structfield>put</structfield>. Then, define a
3375 struct <structname>snd_kcontrol_new</structname> record, such as:
3378 <title>Definition of a Control</title>
3381 static struct snd_kcontrol_new my_control = {
3382 .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3383 .name = "PCM Playback Switch",
3385 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3386 .private_value = 0xffff,
3387 .info = my_control_info,
3388 .get = my_control_get,
3389 .put = my_control_put
3397 The <structfield>iface</structfield> field specifies the control
3398 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3399 is usually <constant>MIXER</constant>.
3400 Use <constant>CARD</constant> for global controls that are not
3401 logically part of the mixer.
3402 If the control is closely associated with some specific device on
3403 the sound card, use <constant>HWDEP</constant>,
3404 <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3405 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3406 specify the device number with the
3407 <structfield>device</structfield> and
3408 <structfield>subdevice</structfield> fields.
3412 The <structfield>name</structfield> is the name identifier
3413 string. Since ALSA 0.9.x, the control name is very important,
3414 because its role is classified from its name. There are
3415 pre-defined standard control names. The details are described in
3416 the <link linkend="control-interface-control-names"><citetitle>
3417 Control Names</citetitle></link> subsection.
3421 The <structfield>index</structfield> field holds the index number
3422 of this control. If there are several different controls with
3423 the same name, they can be distinguished by the index
3424 number. This is the case when
3425 several codecs exist on the card. If the index is zero, you can
3426 omit the definition above.
3430 The <structfield>access</structfield> field contains the access
3431 type of this control. Give the combination of bit masks,
3432 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3433 The details will be explained in
3434 the <link linkend="control-interface-access-flags"><citetitle>
3435 Access Flags</citetitle></link> subsection.
3439 The <structfield>private_value</structfield> field contains
3440 an arbitrary long integer value for this record. When using
3441 the generic <structfield>info</structfield>,
3442 <structfield>get</structfield> and
3443 <structfield>put</structfield> callbacks, you can pass a value
3444 through this field. If several small numbers are necessary, you can
3445 combine them in bitwise. Or, it's possible to give a pointer
3446 (casted to unsigned long) of some record to this field, too.
3450 The <structfield>tlv</structfield> field can be used to provide
3451 metadata about the control; see the
3452 <link linkend="control-interface-tlv">
3453 <citetitle>Metadata</citetitle></link> subsection.
3458 <link linkend="control-interface-callbacks"><citetitle>
3459 callback functions</citetitle></link>.
3463 <section id="control-interface-control-names">
3464 <title>Control Names</title>
3466 There are some standards to define the control names. A
3467 control is usually defined from the three parts as
3468 <quote>SOURCE DIRECTION FUNCTION</quote>.
3472 The first, <constant>SOURCE</constant>, specifies the source
3473 of the control, and is a string such as <quote>Master</quote>,
3474 <quote>PCM</quote>, <quote>CD</quote> and
3475 <quote>Line</quote>. There are many pre-defined sources.
3479 The second, <constant>DIRECTION</constant>, is one of the
3480 following strings according to the direction of the control:
3481 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3482 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3483 be omitted, meaning both playback and capture directions.
3487 The third, <constant>FUNCTION</constant>, is one of the
3488 following strings according to the function of the control:
3489 <quote>Switch</quote>, <quote>Volume</quote> and
3490 <quote>Route</quote>.
3494 The example of control names are, thus, <quote>Master Capture
3495 Switch</quote> or <quote>PCM Playback Volume</quote>.
3499 There are some exceptions:
3502 <section id="control-interface-control-names-global">
3503 <title>Global capture and playback</title>
3505 <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3506 and <quote>Capture Volume</quote> are used for the global
3507 capture (input) source, switch and volume. Similarly,
3508 <quote>Playback Switch</quote> and <quote>Playback
3509 Volume</quote> are used for the global output gain switch and
3514 <section id="control-interface-control-names-tone">
3515 <title>Tone-controls</title>
3517 tone-control switch and volumes are specified like
3518 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3519 Switch</quote>, <quote>Tone Control - Bass</quote>,
3520 <quote>Tone Control - Center</quote>.
3524 <section id="control-interface-control-names-3d">
3525 <title>3D controls</title>
3527 3D-control switches and volumes are specified like <quote>3D
3528 Control - XXX</quote>, e.g. <quote>3D Control -
3529 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3530 Control - Space</quote>.
3534 <section id="control-interface-control-names-mic">
3535 <title>Mic boost</title>
3537 Mic-boost switch is set as <quote>Mic Boost</quote> or
3538 <quote>Mic Boost (6dB)</quote>.
3542 More precise information can be found in
3543 <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3548 <section id="control-interface-access-flags">
3549 <title>Access Flags</title>
3552 The access flag is the bitmask which specifies the access type
3553 of the given control. The default access type is
3554 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
3555 which means both read and write are allowed to this control.
3556 When the access flag is omitted (i.e. = 0), it is
3557 considered as <constant>READWRITE</constant> access as default.
3561 When the control is read-only, pass
3562 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3563 In this case, you don't have to define
3564 the <structfield>put</structfield> callback.
3565 Similarly, when the control is write-only (although it's a rare
3566 case), you can use the <constant>WRITE</constant> flag instead, and
3567 you don't need the <structfield>get</structfield> callback.
3571 If the control value changes frequently (e.g. the VU meter),
3572 <constant>VOLATILE</constant> flag should be given. This means
3573 that the control may be changed without
3574 <link linkend="control-interface-change-notification"><citetitle>
3575 notification</citetitle></link>. Applications should poll such
3576 a control constantly.
3580 When the control is inactive, set
3581 the <constant>INACTIVE</constant> flag, too.
3582 There are <constant>LOCK</constant> and
3583 <constant>OWNER</constant> flags to change the write
3589 <section id="control-interface-callbacks">
3590 <title>Callbacks</title>
3592 <section id="control-interface-callbacks-info">
3593 <title>info callback</title>
3595 The <structfield>info</structfield> callback is used to get
3596 detailed information on this control. This must store the
3597 values of the given struct <structname>snd_ctl_elem_info</structname>
3598 object. For example, for a boolean control with a single
3602 <title>Example of info callback</title>
3605 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3606 struct snd_ctl_elem_info *uinfo)
3608 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3610 uinfo->value.integer.min = 0;
3611 uinfo->value.integer.max = 1;
3620 The <structfield>type</structfield> field specifies the type
3621 of the control. There are <constant>BOOLEAN</constant>,
3622 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3623 <constant>BYTES</constant>, <constant>IEC958</constant> and
3624 <constant>INTEGER64</constant>. The
3625 <structfield>count</structfield> field specifies the
3626 number of elements in this control. For example, a stereo
3627 volume would have count = 2. The
3628 <structfield>value</structfield> field is a union, and
3629 the values stored are depending on the type. The boolean and
3630 integer types are identical.
3634 The enumerated type is a bit different from others. You'll
3635 need to set the string for the currently given item index.
3640 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3641 struct snd_ctl_elem_info *uinfo)
3643 static char *texts[4] = {
3644 "First", "Second", "Third", "Fourth"
3646 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3648 uinfo->value.enumerated.items = 4;
3649 if (uinfo->value.enumerated.item > 3)
3650 uinfo->value.enumerated.item = 3;
3651 strcpy(uinfo->value.enumerated.name,
3652 texts[uinfo->value.enumerated.item]);
3661 Some common info callbacks are available for your convenience:
3662 <function>snd_ctl_boolean_mono_info()</function> and
3663 <function>snd_ctl_boolean_stereo_info()</function>.
3664 Obviously, the former is an info callback for a mono channel
3665 boolean item, just like <function>snd_myctl_mono_info</function>
3666 above, and the latter is for a stereo channel boolean item.
3671 <section id="control-interface-callbacks-get">
3672 <title>get callback</title>
3675 This callback is used to read the current value of the
3676 control and to return to user-space.
3683 <title>Example of get callback</title>
3686 static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3687 struct snd_ctl_elem_value *ucontrol)
3689 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3690 ucontrol->value.integer.value[0] = get_some_value(chip);
3699 The <structfield>value</structfield> field depends on
3700 the type of control as well as on the info callback. For example,
3701 the sb driver uses this field to store the register offset,
3702 the bit-shift and the bit-mask. The
3703 <structfield>private_value</structfield> field is set as follows:
3707 .private_value = reg | (shift << 16) | (mask << 24)
3711 and is retrieved in callbacks like
3715 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3716 struct snd_ctl_elem_value *ucontrol)
3718 int reg = kcontrol->private_value & 0xff;
3719 int shift = (kcontrol->private_value >> 16) & 0xff;
3720 int mask = (kcontrol->private_value >> 24) & 0xff;
3729 In the <structfield>get</structfield> callback,
3730 you have to fill all the elements if the
3731 control has more than one elements,
3732 i.e. <structfield>count</structfield> > 1.
3733 In the example above, we filled only one element
3734 (<structfield>value.integer.value[0]</structfield>) since it's
3735 assumed as <structfield>count</structfield> = 1.
3739 <section id="control-interface-callbacks-put">
3740 <title>put callback</title>
3743 This callback is used to write a value from user-space.
3750 <title>Example of put callback</title>
3753 static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3754 struct snd_ctl_elem_value *ucontrol)
3756 struct mychip *chip = snd_kcontrol_chip(kcontrol);
3758 if (chip->current_value !=
3759 ucontrol->value.integer.value[0]) {
3760 change_current_value(chip,
3761 ucontrol->value.integer.value[0]);
3770 As seen above, you have to return 1 if the value is
3771 changed. If the value is not changed, return 0 instead.
3772 If any fatal error happens, return a negative error code as
3777 As in the <structfield>get</structfield> callback,
3778 when the control has more than one elements,
3779 all elements must be evaluated in this callback, too.
3783 <section id="control-interface-callbacks-all">
3784 <title>Callbacks are not atomic</title>
3786 All these three callbacks are basically not atomic.
3791 <section id="control-interface-constructor">
3792 <title>Constructor</title>
3794 When everything is ready, finally we can create a new
3795 control. To create a control, there are two functions to be
3796 called, <function>snd_ctl_new1()</function> and
3797 <function>snd_ctl_add()</function>.
3801 In the simplest way, you can do like this:
3806 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3813 where <parameter>my_control</parameter> is the
3814 struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3815 is the object pointer to be passed to
3816 kcontrol->private_data
3817 which can be referred to in callbacks.
3821 <function>snd_ctl_new1()</function> allocates a new
3822 <structname>snd_kcontrol</structname> instance,
3823 and <function>snd_ctl_add</function> assigns the given
3824 control component to the card.
3828 <section id="control-interface-change-notification">
3829 <title>Change Notification</title>
3831 If you need to change and update a control in the interrupt
3832 routine, you can call <function>snd_ctl_notify()</function>. For
3838 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3843 This function takes the card pointer, the event-mask, and the
3844 control id pointer for the notification. The event-mask
3845 specifies the types of notification, for example, in the above
3846 example, the change of control values is notified.
3847 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3849 You can find some examples in <filename>es1938.c</filename> or
3850 <filename>es1968.c</filename> for hardware volume interrupts.
3854 <section id="control-interface-tlv">
3855 <title>Metadata</title>
3857 To provide information about the dB values of a mixer control, use
3858 on of the <constant>DECLARE_TLV_xxx</constant> macros from
3859 <filename><sound/tlv.h></filename> to define a variable
3860 containing this information, set the<structfield>tlv.p
3861 </structfield> field to point to this variable, and include the
3862 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3863 <structfield>access</structfield> field; like this:
3867 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3869 static struct snd_kcontrol_new my_control = {
3871 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3872 SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3874 .tlv.p = db_scale_my_control,
3882 The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3883 information about a mixer control where each step in the control's
3884 value changes the dB value by a constant dB amount.
3885 The first parameter is the name of the variable to be defined.
3886 The second parameter is the minimum value, in units of 0.01 dB.
3887 The third parameter is the step size, in units of 0.01 dB.
3888 Set the fourth parameter to 1 if the minimum value actually mutes
3893 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3894 information about a mixer control where the control's value affects
3895 the output linearly.
3896 The first parameter is the name of the variable to be defined.
3897 The second parameter is the minimum value, in units of 0.01 dB.
3898 The third parameter is the maximum value, in units of 0.01 dB.
3899 If the minimum value mutes the control, set the second parameter to
3900 <constant>TLV_DB_GAIN_MUTE</constant>.
3907 <!-- ****************************************************** -->
3908 <!-- API for AC97 Codec -->
3909 <!-- ****************************************************** -->
3910 <chapter id="api-ac97">
3911 <title>API for AC97 Codec</title>
3914 <title>General</title>
3916 The ALSA AC97 codec layer is a well-defined one, and you don't
3917 have to write much code to control it. Only low-level control
3918 routines are necessary. The AC97 codec API is defined in
3919 <filename><sound/ac97_codec.h></filename>.
3923 <section id="api-ac97-example">
3924 <title>Full Code Example</title>
3927 <title>Example of AC97 Interface</title>
3932 struct snd_ac97 *ac97;
3936 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3939 struct mychip *chip = ac97->private_data;
3941 /* read a register value here from the codec */
3942 return the_register_value;
3945 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3946 unsigned short reg, unsigned short val)
3948 struct mychip *chip = ac97->private_data;
3950 /* write the given register value to the codec */
3953 static int snd_mychip_ac97(struct mychip *chip)
3955 struct snd_ac97_bus *bus;
3956 struct snd_ac97_template ac97;
3958 static struct snd_ac97_bus_ops ops = {
3959 .write = snd_mychip_ac97_write,
3960 .read = snd_mychip_ac97_read,
3963 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3966 memset(&ac97, 0, sizeof(ac97));
3967 ac97.private_data = chip;
3968 return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3977 <section id="api-ac97-constructor">
3978 <title>Constructor</title>
3980 To create an ac97 instance, first call <function>snd_ac97_bus</function>
3981 with an <type>ac97_bus_ops_t</type> record with callback functions.
3986 struct snd_ac97_bus *bus;
3987 static struct snd_ac97_bus_ops ops = {
3988 .write = snd_mychip_ac97_write,
3989 .read = snd_mychip_ac97_read,
3992 snd_ac97_bus(card, 0, &ops, NULL, &pbus);
3997 The bus record is shared among all belonging ac97 instances.
4001 And then call <function>snd_ac97_mixer()</function> with an
4002 struct <structname>snd_ac97_template</structname>
4003 record together with the bus pointer created above.
4008 struct snd_ac97_template ac97;
4011 memset(&ac97, 0, sizeof(ac97));
4012 ac97.private_data = chip;
4013 snd_ac97_mixer(bus, &ac97, &chip->ac97);
4018 where chip->ac97 is a pointer to a newly created
4019 <type>ac97_t</type> instance.
4020 In this case, the chip pointer is set as the private data, so that
4021 the read/write callback functions can refer to this chip instance.
4022 This instance is not necessarily stored in the chip
4023 record. If you need to change the register values from the
4024 driver, or need the suspend/resume of ac97 codecs, keep this
4025 pointer to pass to the corresponding functions.
4029 <section id="api-ac97-callbacks">
4030 <title>Callbacks</title>
4032 The standard callbacks are <structfield>read</structfield> and
4033 <structfield>write</structfield>. Obviously they
4034 correspond to the functions for read and write accesses to the
4035 hardware low-level codes.
4039 The <structfield>read</structfield> callback returns the
4040 register value specified in the argument.
4045 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4048 struct mychip *chip = ac97->private_data;
4050 return the_register_value;
4056 Here, the chip can be cast from ac97->private_data.
4060 Meanwhile, the <structfield>write</structfield> callback is
4061 used to set the register value.
4066 static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4067 unsigned short reg, unsigned short val)
4074 These callbacks are non-atomic like the control API callbacks.
4078 There are also other callbacks:
4079 <structfield>reset</structfield>,
4080 <structfield>wait</structfield> and
4081 <structfield>init</structfield>.
4085 The <structfield>reset</structfield> callback is used to reset
4086 the codec. If the chip requires a special kind of reset, you can
4087 define this callback.
4091 The <structfield>wait</structfield> callback is used to
4092 add some waiting time in the standard initialization of the codec. If the
4093 chip requires the extra waiting time, define this callback.
4097 The <structfield>init</structfield> callback is used for
4098 additional initialization of the codec.
4102 <section id="api-ac97-updating-registers">
4103 <title>Updating Registers in The Driver</title>
4105 If you need to access to the codec from the driver, you can
4106 call the following functions:
4107 <function>snd_ac97_write()</function>,
4108 <function>snd_ac97_read()</function>,
4109 <function>snd_ac97_update()</function> and
4110 <function>snd_ac97_update_bits()</function>.
4114 Both <function>snd_ac97_write()</function> and
4115 <function>snd_ac97_update()</function> functions are used to
4116 set a value to the given register
4117 (<constant>AC97_XXX</constant>). The difference between them is
4118 that <function>snd_ac97_update()</function> doesn't write a
4119 value if the given value has been already set, while
4120 <function>snd_ac97_write()</function> always rewrites the
4126 snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4127 snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4134 <function>snd_ac97_read()</function> is used to read the value
4135 of the given register. For example,
4140 value = snd_ac97_read(ac97, AC97_MASTER);
4147 <function>snd_ac97_update_bits()</function> is used to update
4148 some bits in the given register.
4153 snd_ac97_update_bits(ac97, reg, mask, value);
4160 Also, there is a function to change the sample rate (of a
4161 given register such as
4162 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4163 DRA is supported by the codec:
4164 <function>snd_ac97_set_rate()</function>.
4169 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4176 The following registers are available to set the rate:
4177 <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4178 <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4179 <constant>AC97_PCM_LR_ADC_RATE</constant>,
4180 <constant>AC97_SPDIF</constant>. When
4181 <constant>AC97_SPDIF</constant> is specified, the register is
4182 not really changed but the corresponding IEC958 status bits will
4187 <section id="api-ac97-clock-adjustment">
4188 <title>Clock Adjustment</title>
4190 In some chips, the clock of the codec isn't 48000 but using a
4191 PCI clock (to save a quartz!). In this case, change the field
4192 bus->clock to the corresponding
4193 value. For example, intel8x0
4194 and es1968 drivers have their own function to read from the clock.
4198 <section id="api-ac97-proc-files">
4199 <title>Proc Files</title>
4201 The ALSA AC97 interface will create a proc file such as
4202 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4203 <filename>ac97#0-0+regs</filename>. You can refer to these files to
4204 see the current status and registers of the codec.
4208 <section id="api-ac97-multiple-codecs">
4209 <title>Multiple Codecs</title>
4211 When there are several codecs on the same card, you need to
4212 call <function>snd_ac97_mixer()</function> multiple times with
4213 ac97.num=1 or greater. The <structfield>num</structfield> field
4214 specifies the codec number.
4218 If you set up multiple codecs, you either need to write
4219 different callbacks for each codec or check
4220 ac97->num in the callback routines.
4227 <!-- ****************************************************** -->
4228 <!-- MIDI (MPU401-UART) Interface -->
4229 <!-- ****************************************************** -->
4230 <chapter id="midi-interface">
4231 <title>MIDI (MPU401-UART) Interface</title>
4233 <section id="midi-interface-general">
4234 <title>General</title>
4236 Many soundcards have built-in MIDI (MPU401-UART)
4237 interfaces. When the soundcard supports the standard MPU401-UART
4238 interface, most likely you can use the ALSA MPU401-UART API. The
4239 MPU401-UART API is defined in
4240 <filename><sound/mpu401.h></filename>.
4244 Some soundchips have a similar but slightly different
4245 implementation of mpu401 stuff. For example, emu10k1 has its own
4250 <section id="midi-interface-constructor">
4251 <title>Constructor</title>
4253 To create a rawmidi object, call
4254 <function>snd_mpu401_uart_new()</function>.
4259 struct snd_rawmidi *rmidi;
4260 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4268 The first argument is the card pointer, and the second is the
4269 index of this component. You can create up to 8 rawmidi
4274 The third argument is the type of the hardware,
4275 <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4276 you can use <constant>MPU401_HW_MPU401</constant>.
4280 The 4th argument is the I/O port address. Many
4281 backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4282 might be a part of its own PCI I/O region. It depends on the
4287 The 5th argument is a bitflag for additional information.
4288 When the I/O port address above is part of the PCI I/O
4289 region, the MPU401 I/O port might have been already allocated
4290 (reserved) by the driver itself. In such a case, pass a bit flag
4291 <constant>MPU401_INFO_INTEGRATED</constant>,
4292 and the mpu401-uart layer will allocate the I/O ports by itself.
4296 When the controller supports only the input or output MIDI stream,
4297 pass the <constant>MPU401_INFO_INPUT</constant> or
4298 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4299 Then the rawmidi instance is created as a single stream.
4303 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4304 the access method to MMIO (via readb and writeb) instead of
4305 iob and outb. In this case, you have to pass the iomapped address
4306 to <function>snd_mpu401_uart_new()</function>.
4310 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4311 stream isn't checked in the default interrupt handler. The driver
4312 needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4313 by itself to start processing the output stream in the irq handler.
4317 If the MPU-401 interface shares its interrupt with the other logical
4318 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4319 (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4320 below</citetitle></link>).
4324 Usually, the port address corresponds to the command port and
4325 port + 1 corresponds to the data port. If not, you may change
4326 the <structfield>cport</structfield> field of
4327 struct <structname>snd_mpu401</structname> manually
4328 afterward. However, <structname>snd_mpu401</structname> pointer is not
4329 returned explicitly by
4330 <function>snd_mpu401_uart_new()</function>. You need to cast
4331 rmidi->private_data to
4332 <structname>snd_mpu401</structname> explicitly,
4337 struct snd_mpu401 *mpu;
4338 mpu = rmidi->private_data;
4343 and reset the cport as you like:
4348 mpu->cport = my_own_control_port;
4355 The 6th argument specifies the ISA irq number that will be
4356 allocated. If no interrupt is to be allocated (because your
4357 code is already allocating a shared interrupt, or because the
4358 device does not use interrupts), pass -1 instead.
4359 For a MPU-401 device without an interrupt, a polling timer
4360 will be used instead.
4364 <section id="midi-interface-interrupt-handler">
4365 <title>Interrupt Handler</title>
4367 When the interrupt is allocated in
4368 <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4369 interrupt handler is automatically used, hence you don't have
4370 anything else to do than creating the mpu401 stuff. Otherwise, you
4371 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4372 <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4373 own interrupt handler when it has determined that a UART interrupt
4378 In this case, you need to pass the private_data of the
4379 returned rawmidi object from
4380 <function>snd_mpu401_uart_new()</function> as the second
4381 argument of <function>snd_mpu401_uart_interrupt()</function>.
4386 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4396 <!-- ****************************************************** -->
4397 <!-- RawMIDI Interface -->
4398 <!-- ****************************************************** -->
4399 <chapter id="rawmidi-interface">
4400 <title>RawMIDI Interface</title>
4402 <section id="rawmidi-interface-overview">
4403 <title>Overview</title>
4406 The raw MIDI interface is used for hardware MIDI ports that can
4407 be accessed as a byte stream. It is not used for synthesizer
4408 chips that do not directly understand MIDI.
4412 ALSA handles file and buffer management. All you have to do is
4413 to write some code to move data between the buffer and the
4418 The rawmidi API is defined in
4419 <filename><sound/rawmidi.h></filename>.
4423 <section id="rawmidi-interface-constructor">
4424 <title>Constructor</title>
4427 To create a rawmidi device, call the
4428 <function>snd_rawmidi_new</function> function:
4432 struct snd_rawmidi *rmidi;
4433 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4436 rmidi->private_data = chip;
4437 strcpy(rmidi->name, "My MIDI");
4438 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4439 SNDRV_RAWMIDI_INFO_INPUT |
4440 SNDRV_RAWMIDI_INFO_DUPLEX;
4447 The first argument is the card pointer, the second argument is
4452 The third argument is the index of this component. You can
4453 create up to 8 rawmidi devices.
4457 The fourth and fifth arguments are the number of output and
4458 input substreams, respectively, of this device (a substream is
4459 the equivalent of a MIDI port).
4463 Set the <structfield>info_flags</structfield> field to specify
4464 the capabilities of the device.
4465 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4466 at least one output port,
4467 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4468 least one input port,
4469 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4470 can handle output and input at the same time.
4474 After the rawmidi device is created, you need to set the
4475 operators (callbacks) for each substream. There are helper
4476 functions to set the operators for all the substreams of a device:
4480 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4481 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4488 The operators are usually defined like this:
4492 static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4493 .open = snd_mymidi_output_open,
4494 .close = snd_mymidi_output_close,
4495 .trigger = snd_mymidi_output_trigger,
4500 These callbacks are explained in the <link
4501 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4506 If there are more than one substream, you should give a
4507 unique name to each of them:
4511 struct snd_rawmidi_substream *substream;
4512 list_for_each_entry(substream,
4513 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4515 sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4517 /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4524 <section id="rawmidi-interface-callbacks">
4525 <title>Callbacks</title>
4528 In all the callbacks, the private data that you've set for the
4529 rawmidi device can be accessed as
4530 substream->rmidi->private_data.
4531 <!-- <code> isn't available before DocBook 4.3 -->
4535 If there is more than one port, your callbacks can determine the
4536 port index from the struct snd_rawmidi_substream data passed to each
4541 struct snd_rawmidi_substream *substream;
4542 int index = substream->number;
4548 <section id="rawmidi-interface-op-open">
4549 <title><function>open</function> callback</title>
4554 static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4560 This is called when a substream is opened.
4561 You can initialize the hardware here, but you shouldn't
4562 start transmitting/receiving data yet.
4566 <section id="rawmidi-interface-op-close">
4567 <title><function>close</function> callback</title>
4572 static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4582 The <function>open</function> and <function>close</function>
4583 callbacks of a rawmidi device are serialized with a mutex,
4588 <section id="rawmidi-interface-op-trigger-out">
4589 <title><function>trigger</function> callback for output
4595 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4601 This is called with a nonzero <parameter>up</parameter>
4602 parameter when there is some data in the substream buffer that
4603 must be transmitted.
4607 To read data from the buffer, call
4608 <function>snd_rawmidi_transmit_peek</function>. It will
4609 return the number of bytes that have been read; this will be
4610 less than the number of bytes requested when there are no more
4612 After the data have been transmitted successfully, call
4613 <function>snd_rawmidi_transmit_ack</function> to remove the
4614 data from the substream buffer:
4619 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4620 if (snd_mychip_try_to_transmit(data))
4621 snd_rawmidi_transmit_ack(substream, 1);
4623 break; /* hardware FIFO full */
4631 If you know beforehand that the hardware will accept data, you
4632 can use the <function>snd_rawmidi_transmit</function> function
4633 which reads some data and removes them from the buffer at once:
4637 while (snd_mychip_transmit_possible()) {
4639 if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4640 break; /* no more data */
4641 snd_mychip_transmit(data);
4649 If you know beforehand how many bytes you can accept, you can
4650 use a buffer size greater than one with the
4651 <function>snd_rawmidi_transmit*</function> functions.
4655 The <function>trigger</function> callback must not sleep. If
4656 the hardware FIFO is full before the substream buffer has been
4657 emptied, you have to continue transmitting data later, either
4658 in an interrupt handler, or with a timer if the hardware
4659 doesn't have a MIDI transmit interrupt.
4663 The <function>trigger</function> callback is called with a
4664 zero <parameter>up</parameter> parameter when the transmission
4665 of data should be aborted.
4669 <section id="rawmidi-interface-op-trigger-in">
4670 <title><function>trigger</function> callback for input
4676 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4682 This is called with a nonzero <parameter>up</parameter>
4683 parameter to enable receiving data, or with a zero
4684 <parameter>up</parameter> parameter do disable receiving data.
4688 The <function>trigger</function> callback must not sleep; the
4689 actual reading of data from the device is usually done in an
4694 When data reception is enabled, your interrupt handler should
4695 call <function>snd_rawmidi_receive</function> for all received
4700 void snd_mychip_midi_interrupt(...)
4702 while (mychip_midi_available()) {
4704 data = mychip_midi_read();
4705 snd_rawmidi_receive(substream, &data, 1);
4714 <section id="rawmidi-interface-op-drain">
4715 <title><function>drain</function> callback</title>
4720 static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4726 This is only used with output substreams. This function should wait
4727 until all data read from the substream buffer have been transmitted.
4728 This ensures that the device can be closed and the driver unloaded
4729 without losing data.
4733 This callback is optional. If you do not set
4734 <structfield>drain</structfield> in the struct snd_rawmidi_ops
4735 structure, ALSA will simply wait for 50 milliseconds
4744 <!-- ****************************************************** -->
4745 <!-- Miscellaneous Devices -->
4746 <!-- ****************************************************** -->
4747 <chapter id="misc-devices">
4748 <title>Miscellaneous Devices</title>
4750 <section id="misc-devices-opl3">
4751 <title>FM OPL3</title>
4753 The FM OPL3 is still used in many chips (mainly for backward
4754 compatibility). ALSA has a nice OPL3 FM control layer, too. The
4755 OPL3 API is defined in
4756 <filename><sound/opl3.h></filename>.
4760 FM registers can be directly accessed through the direct-FM API,
4761 defined in <filename><sound/asound_fm.h></filename>. In
4762 ALSA native mode, FM registers are accessed through
4763 the Hardware-Dependent Device direct-FM extension API, whereas in
4764 OSS compatible mode, FM registers can be accessed with the OSS
4765 direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
4769 To create the OPL3 component, you have two functions to
4770 call. The first one is a constructor for the <type>opl3_t</type>
4776 struct snd_opl3 *opl3;
4777 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4785 The first argument is the card pointer, the second one is the
4786 left port address, and the third is the right port address. In
4787 most cases, the right port is placed at the left port + 2.
4791 The fourth argument is the hardware type.
4795 When the left and right ports have been already allocated by
4796 the card driver, pass non-zero to the fifth argument
4797 (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4798 allocate the specified ports by itself.
4802 When the accessing the hardware requires special method
4803 instead of the standard I/O access, you can create opl3 instance
4804 separately with <function>snd_opl3_new()</function>.
4809 struct snd_opl3 *opl3;
4810 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4817 Then set <structfield>command</structfield>,
4818 <structfield>private_data</structfield> and
4819 <structfield>private_free</structfield> for the private
4820 access function, the private data and the destructor.
4821 The l_port and r_port are not necessarily set. Only the
4822 command must be set properly. You can retrieve the data
4823 from the opl3->private_data field.
4827 After creating the opl3 instance via <function>snd_opl3_new()</function>,
4828 call <function>snd_opl3_init()</function> to initialize the chip to the
4829 proper state. Note that <function>snd_opl3_create()</function> always
4830 calls it internally.
4834 If the opl3 instance is created successfully, then create a
4835 hwdep device for this opl3.
4840 struct snd_hwdep *opl3hwdep;
4841 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4848 The first argument is the <type>opl3_t</type> instance you
4849 created, and the second is the index number, usually 0.
4853 The third argument is the index-offset for the sequencer
4854 client assigned to the OPL3 port. When there is an MPU401-UART,
4855 give 1 for here (UART always takes 0).
4859 <section id="misc-devices-hardware-dependent">
4860 <title>Hardware-Dependent Devices</title>
4862 Some chips need user-space access for special
4863 controls or for loading the micro code. In such a case, you can
4864 create a hwdep (hardware-dependent) device. The hwdep API is
4865 defined in <filename><sound/hwdep.h></filename>. You can
4866 find examples in opl3 driver or
4867 <filename>isa/sb/sb16_csp.c</filename>.
4871 The creation of the <type>hwdep</type> instance is done via
4872 <function>snd_hwdep_new()</function>.
4877 struct snd_hwdep *hw;
4878 snd_hwdep_new(card, "My HWDEP", 0, &hw);
4883 where the third argument is the index number.
4887 You can then pass any pointer value to the
4888 <parameter>private_data</parameter>.
4889 If you assign a private data, you should define the
4890 destructor, too. The destructor function is set in
4891 the <structfield>private_free</structfield> field.
4896 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4897 hw->private_data = p;
4898 hw->private_free = mydata_free;
4903 and the implementation of the destructor would be:
4908 static void mydata_free(struct snd_hwdep *hw)
4910 struct mydata *p = hw->private_data;
4919 The arbitrary file operations can be defined for this
4920 instance. The file operators are defined in
4921 the <parameter>ops</parameter> table. For example, assume that
4922 this chip needs an ioctl.
4927 hw->ops.open = mydata_open;
4928 hw->ops.ioctl = mydata_ioctl;
4929 hw->ops.release = mydata_release;
4934 And implement the callback functions as you like.
4938 <section id="misc-devices-IEC958">
4939 <title>IEC958 (S/PDIF)</title>
4941 Usually the controls for IEC958 devices are implemented via
4942 the control interface. There is a macro to compose a name string for
4943 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4944 defined in <filename><include/asound.h></filename>.
4948 There are some standard controls for IEC958 status bits. These
4949 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4950 and the size of element is fixed as 4 bytes array
4951 (value.iec958.status[x]). For the <structfield>info</structfield>
4952 callback, you don't specify
4953 the value field for this type (the count field must be set,
4958 <quote>IEC958 Playback Con Mask</quote> is used to return the
4959 bit-mask for the IEC958 status bits of consumer mode. Similarly,
4960 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4961 professional mode. They are read-only controls, and are defined
4962 as MIXER controls (iface =
4963 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
4967 Meanwhile, <quote>IEC958 Playback Default</quote> control is
4968 defined for getting and setting the current default IEC958
4969 bits. Note that this one is usually defined as a PCM control
4970 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
4971 although in some places it's defined as a MIXER control.
4975 In addition, you can define the control switches to
4976 enable/disable or to set the raw bit mode. The implementation
4977 will depend on the chip, but the control should be named as
4978 <quote>IEC958 xxx</quote>, preferably using
4979 the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
4983 You can find several cases, for example,
4984 <filename>pci/emu10k1</filename>,
4985 <filename>pci/ice1712</filename>, or
4986 <filename>pci/cmipci.c</filename>.
4993 <!-- ****************************************************** -->
4994 <!-- Buffer and Memory Management -->
4995 <!-- ****************************************************** -->
4996 <chapter id="buffer-and-memory">
4997 <title>Buffer and Memory Management</title>
4999 <section id="buffer-and-memory-buffer-types">
5000 <title>Buffer Types</title>
5002 ALSA provides several different buffer allocation functions
5003 depending on the bus and the architecture. All these have a
5004 consistent API. The allocation of physically-contiguous pages is
5006 <function>snd_malloc_xxx_pages()</function> function, where xxx
5011 The allocation of pages with fallback is
5012 <function>snd_malloc_xxx_pages_fallback()</function>. This
5013 function tries to allocate the specified pages but if the pages
5014 are not available, it tries to reduce the page sizes until
5015 enough space is found.
5019 The release the pages, call
5020 <function>snd_free_xxx_pages()</function> function.
5024 Usually, ALSA drivers try to allocate and reserve
5025 a large contiguous physical space
5026 at the time the module is loaded for the later use.
5027 This is called <quote>pre-allocation</quote>.
5028 As already written, you can call the following function at
5029 pcm instance construction time (in the case of PCI bus).
5034 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5035 snd_dma_pci_data(pci), size, max);
5040 where <parameter>size</parameter> is the byte size to be
5041 pre-allocated and the <parameter>max</parameter> is the maximum
5042 size to be changed via the <filename>prealloc</filename> proc file.
5043 The allocator will try to get an area as large as possible
5044 within the given size.
5048 The second argument (type) and the third argument (device pointer)
5049 are dependent on the bus.
5050 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5051 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5052 For the continuous buffer unrelated to the bus can be pre-allocated
5053 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5054 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5055 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5057 For the PCI scatter-gather buffers, use
5058 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5059 <function>snd_dma_pci_data(pci)</function>
5061 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5062 </citetitle></link> section).
5066 Once the buffer is pre-allocated, you can use the
5067 allocator in the <structfield>hw_params</structfield> callback:
5072 snd_pcm_lib_malloc_pages(substream, size);
5077 Note that you have to pre-allocate to use this function.
5081 <section id="buffer-and-memory-external-hardware">
5082 <title>External Hardware Buffers</title>
5084 Some chips have their own hardware buffers and the DMA
5085 transfer from the host memory is not available. In such a case,
5086 you need to either 1) copy/set the audio data directly to the
5087 external hardware buffer, or 2) make an intermediate buffer and
5088 copy/set the data from it to the external hardware buffer in
5089 interrupts (or in tasklets, preferably).
5093 The first case works fine if the external hardware buffer is large
5094 enough. This method doesn't need any extra buffers and thus is
5095 more effective. You need to define the
5096 <structfield>copy</structfield> and
5097 <structfield>silence</structfield> callbacks for
5098 the data transfer. However, there is a drawback: it cannot
5099 be mmapped. The examples are GUS's GF1 PCM or emu8000's
5104 The second case allows for mmap on the buffer, although you have
5105 to handle an interrupt or a tasklet to transfer the data
5106 from the intermediate buffer to the hardware buffer. You can find an
5107 example in the vxpocket driver.
5111 Another case is when the chip uses a PCI memory-map
5112 region for the buffer instead of the host memory. In this case,
5113 mmap is available only on certain architectures like the Intel one.
5114 In non-mmap mode, the data cannot be transferred as in the normal
5115 way. Thus you need to define the <structfield>copy</structfield> and
5116 <structfield>silence</structfield> callbacks as well,
5117 as in the cases above. The examples are found in
5118 <filename>rme32.c</filename> and <filename>rme96.c</filename>.
5122 The implementation of the <structfield>copy</structfield> and
5123 <structfield>silence</structfield> callbacks depends upon
5124 whether the hardware supports interleaved or non-interleaved
5125 samples. The <structfield>copy</structfield> callback is
5126 defined like below, a bit
5127 differently depending whether the direction is playback or
5133 static int playback_copy(struct snd_pcm_substream *substream, int channel,
5134 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5135 static int capture_copy(struct snd_pcm_substream *substream, int channel,
5136 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5143 In the case of interleaved samples, the second argument
5144 (<parameter>channel</parameter>) is not used. The third argument
5145 (<parameter>pos</parameter>) points the
5146 current position offset in frames.
5150 The meaning of the fourth argument is different between
5151 playback and capture. For playback, it holds the source data
5152 pointer, and for capture, it's the destination data pointer.
5156 The last argument is the number of frames to be copied.
5160 What you have to do in this callback is again different
5161 between playback and capture directions. In the
5162 playback case, you copy the given amount of data
5163 (<parameter>count</parameter>) at the specified pointer
5164 (<parameter>src</parameter>) to the specified offset
5165 (<parameter>pos</parameter>) on the hardware buffer. When
5166 coded like memcpy-like way, the copy would be like:
5171 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5172 frames_to_bytes(runtime, count));
5179 For the capture direction, you copy the given amount of
5180 data (<parameter>count</parameter>) at the specified offset
5181 (<parameter>pos</parameter>) on the hardware buffer to the
5182 specified pointer (<parameter>dst</parameter>).
5187 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5188 frames_to_bytes(runtime, count));
5193 Note that both the position and the amount of data are given
5198 In the case of non-interleaved samples, the implementation
5199 will be a bit more complicated.
5203 You need to check the channel argument, and if it's -1, copy
5204 the whole channels. Otherwise, you have to copy only the
5205 specified channel. Please check
5206 <filename>isa/gus/gus_pcm.c</filename> as an example.
5210 The <structfield>silence</structfield> callback is also
5211 implemented in a similar way.
5216 static int silence(struct snd_pcm_substream *substream, int channel,
5217 snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5224 The meanings of arguments are the same as in the
5225 <structfield>copy</structfield>
5226 callback, although there is no <parameter>src/dst</parameter>
5227 argument. In the case of interleaved samples, the channel
5228 argument has no meaning, as well as on
5229 <structfield>copy</structfield> callback.
5233 The role of <structfield>silence</structfield> callback is to
5234 set the given amount
5235 (<parameter>count</parameter>) of silence data at the
5236 specified offset (<parameter>pos</parameter>) on the hardware
5237 buffer. Suppose that the data format is signed (that is, the
5238 silent-data is 0), and the implementation using a memset-like
5239 function would be like:
5244 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5245 frames_to_bytes(runtime, count));
5252 In the case of non-interleaved samples, again, the
5253 implementation becomes a bit more complicated. See, for example,
5254 <filename>isa/gus/gus_pcm.c</filename>.
5258 <section id="buffer-and-memory-non-contiguous">
5259 <title>Non-Contiguous Buffers</title>
5261 If your hardware supports the page table as in emu10k1 or the
5262 buffer descriptors as in via82xx, you can use the scatter-gather
5263 (SG) DMA. ALSA provides an interface for handling SG-buffers.
5264 The API is provided in <filename><sound/pcm.h></filename>.
5268 For creating the SG-buffer handler, call
5269 <function>snd_pcm_lib_preallocate_pages()</function> or
5270 <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5271 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5272 in the PCM constructor like other PCI pre-allocator.
5273 You need to pass <function>snd_dma_pci_data(pci)</function>,
5274 where pci is the struct <structname>pci_dev</structname> pointer
5275 of the chip as well.
5276 The <type>struct snd_sg_buf</type> instance is created as
5277 substream->dma_private. You can cast
5283 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5290 Then call <function>snd_pcm_lib_malloc_pages()</function>
5291 in the <structfield>hw_params</structfield> callback
5292 as well as in the case of normal PCI buffer.
5293 The SG-buffer handler will allocate the non-contiguous kernel
5294 pages of the given size and map them onto the virtually contiguous
5295 memory. The virtual pointer is addressed in runtime->dma_area.
5296 The physical address (runtime->dma_addr) is set to zero,
5297 because the buffer is physically non-contiguous.
5298 The physical address table is set up in sgbuf->table.
5299 You can get the physical address at a certain offset via
5300 <function>snd_pcm_sgbuf_get_addr()</function>.
5304 When a SG-handler is used, you need to set
5305 <function>snd_pcm_sgbuf_ops_page</function> as
5306 the <structfield>page</structfield> callback.
5307 (See <link linkend="pcm-interface-operators-page-callback">
5308 <citetitle>page callback section</citetitle></link>.)
5312 To release the data, call
5313 <function>snd_pcm_lib_free_pages()</function> in the
5314 <structfield>hw_free</structfield> callback as usual.
5318 <section id="buffer-and-memory-vmalloced">
5319 <title>Vmalloc'ed Buffers</title>
5321 It's possible to use a buffer allocated via
5322 <function>vmalloc</function>, for example, for an intermediate
5323 buffer. Since the allocated pages are not contiguous, you need
5324 to set the <structfield>page</structfield> callback to obtain
5325 the physical address at every offset.
5329 The implementation of <structfield>page</structfield> callback
5335 #include <linux/vmalloc.h>
5337 /* get the physical page pointer on the given offset */
5338 static struct page *mychip_page(struct snd_pcm_substream *substream,
5339 unsigned long offset)
5341 void *pageptr = substream->runtime->dma_area + offset;
5342 return vmalloc_to_page(pageptr);
5353 <!-- ****************************************************** -->
5354 <!-- Proc Interface -->
5355 <!-- ****************************************************** -->
5356 <chapter id="proc-interface">
5357 <title>Proc Interface</title>
5359 ALSA provides an easy interface for procfs. The proc files are
5360 very useful for debugging. I recommend you set up proc files if
5361 you write a driver and want to get a running status or register
5362 dumps. The API is found in
5363 <filename><sound/info.h></filename>.
5367 To create a proc file, call
5368 <function>snd_card_proc_new()</function>.
5373 struct snd_info_entry *entry;
5374 int err = snd_card_proc_new(card, "my-file", &entry);
5379 where the second argument specifies the name of the proc file to be
5380 created. The above example will create a file
5381 <filename>my-file</filename> under the card directory,
5382 e.g. <filename>/proc/asound/card0/my-file</filename>.
5386 Like other components, the proc entry created via
5387 <function>snd_card_proc_new()</function> will be registered and
5388 released automatically in the card registration and release
5393 When the creation is successful, the function stores a new
5394 instance in the pointer given in the third argument.
5395 It is initialized as a text proc file for read only. To use
5396 this proc file as a read-only text file as it is, set the read
5397 callback with a private data via
5398 <function>snd_info_set_text_ops()</function>.
5403 snd_info_set_text_ops(entry, chip, my_proc_read);
5408 where the second argument (<parameter>chip</parameter>) is the
5409 private data to be used in the callbacks. The third parameter
5410 specifies the read buffer size and the fourth
5411 (<parameter>my_proc_read</parameter>) is the callback function, which
5417 static void my_proc_read(struct snd_info_entry *entry,
5418 struct snd_info_buffer *buffer);
5426 In the read callback, use <function>snd_iprintf()</function> for
5427 output strings, which works just like normal
5428 <function>printf()</function>. For example,
5433 static void my_proc_read(struct snd_info_entry *entry,
5434 struct snd_info_buffer *buffer)
5436 struct my_chip *chip = entry->private_data;
5438 snd_iprintf(buffer, "This is my chip!\n");
5439 snd_iprintf(buffer, "Port = %ld\n", chip->port);
5447 The file permissions can be changed afterwards. As default, it's
5448 set as read only for all users. If you want to add write
5449 permission for the user (root as default), do as follows:
5454 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5459 and set the write buffer size and the callback
5464 entry->c.text.write = my_proc_write;
5471 For the write callback, you can use
5472 <function>snd_info_get_line()</function> to get a text line, and
5473 <function>snd_info_get_str()</function> to retrieve a string from
5474 the line. Some examples are found in
5475 <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5476 <filename>pcm_oss.c</filename>.
5480 For a raw-data proc-file, set the attributes as follows:
5485 static struct snd_info_entry_ops my_file_io_ops = {
5486 .read = my_file_io_read,
5489 entry->content = SNDRV_INFO_CONTENT_DATA;
5490 entry->private_data = chip;
5491 entry->c.ops = &my_file_io_ops;
5493 entry->mode = S_IFREG | S_IRUGO;
5498 For the raw data, <structfield>size</structfield> field must be
5499 set properly. This specifies the maximum size of the proc file access.
5503 The read/write callbacks of raw mode are more direct than the text mode.
5504 You need to use a low-level I/O functions such as
5505 <function>copy_from/to_user()</function> to transfer the
5511 static ssize_t my_file_io_read(struct snd_info_entry *entry,
5512 void *file_private_data,
5518 if (copy_to_user(buf, local_data + pos, count))
5526 If the size of the info entry has been set up properly,
5527 <structfield>count</structfield> and <structfield>pos</structfield> are
5528 guaranteed to fit within 0 and the given size.
5529 You don't have to check the range in the callbacks unless any
5530 other condition is required.
5537 <!-- ****************************************************** -->
5538 <!-- Power Management -->
5539 <!-- ****************************************************** -->
5540 <chapter id="power-management">
5541 <title>Power Management</title>
5543 If the chip is supposed to work with suspend/resume
5544 functions, you need to add power-management code to the
5545 driver. The additional code for power-management should be
5546 <function>ifdef</function>'ed with
5547 <constant>CONFIG_PM</constant>.
5551 If the driver <emphasis>fully</emphasis> supports suspend/resume
5552 that is, the device can be
5553 properly resumed to its state when suspend was called,
5554 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5555 in the pcm info field. Usually, this is possible when the
5556 registers of the chip can be safely saved and restored to
5557 RAM. If this is set, the trigger callback is called with
5558 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5563 Even if the driver doesn't support PM fully but
5564 partial suspend/resume is still possible, it's still worthy to
5565 implement suspend/resume callbacks. In such a case, applications
5566 would reset the status by calling
5567 <function>snd_pcm_prepare()</function> and restart the stream
5568 appropriately. Hence, you can define suspend/resume callbacks
5569 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5570 info flag to the PCM.
5574 Note that the trigger with SUSPEND can always be called when
5575 <function>snd_pcm_suspend_all</function> is called,
5576 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5577 The <constant>RESUME</constant> flag affects only the behavior
5578 of <function>snd_pcm_resume()</function>.
5580 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5581 to be handled in the trigger callback when no
5582 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
5583 it's better to keep it for compatibility reasons.)
5586 In the earlier version of ALSA drivers, a common
5587 power-management layer was provided, but it has been removed.
5588 The driver needs to define the suspend/resume hooks according to
5589 the bus the device is connected to. In the case of PCI drivers, the
5590 callbacks look like below:
5596 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5598 .... /* do things for suspend */
5601 static int snd_my_resume(struct pci_dev *pci)
5603 .... /* do things for suspend */
5613 The scheme of the real suspend job is as follows.
5616 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5617 <listitem><para>Call <function>snd_power_change_state()</function> with
5618 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5619 power status.</para></listitem>
5620 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5621 <listitem><para>If AC97 codecs are used, call
5622 <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5623 <listitem><para>Save the register values if necessary.</para></listitem>
5624 <listitem><para>Stop the hardware if necessary.</para></listitem>
5625 <listitem><para>Disable the PCI device by calling
5626 <function>pci_disable_device()</function>. Then, call
5627 <function>pci_save_state()</function> at last.</para></listitem>
5632 A typical code would be like:
5637 static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5640 struct snd_card *card = pci_get_drvdata(pci);
5641 struct mychip *chip = card->private_data;
5643 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5645 snd_pcm_suspend_all(chip->pcm);
5647 snd_ac97_suspend(chip->ac97);
5649 snd_mychip_save_registers(chip);
5651 snd_mychip_stop_hardware(chip);
5653 pci_disable_device(pci);
5654 pci_save_state(pci);
5663 The scheme of the real resume job is as follows.
5666 <listitem><para>Retrieve the card and the chip data.</para></listitem>
5667 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5668 Then enable the pci device again by calling <function>pci_enable_device()</function>.
5669 Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5670 <listitem><para>Re-initialize the chip.</para></listitem>
5671 <listitem><para>Restore the saved registers if necessary.</para></listitem>
5672 <listitem><para>Resume the mixer, e.g. calling
5673 <function>snd_ac97_resume()</function>.</para></listitem>
5674 <listitem><para>Restart the hardware (if any).</para></listitem>
5675 <listitem><para>Call <function>snd_power_change_state()</function> with
5676 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5681 A typical code would be like:
5686 static int mychip_resume(struct pci_dev *pci)
5689 struct snd_card *card = pci_get_drvdata(pci);
5690 struct mychip *chip = card->private_data;
5692 pci_restore_state(pci);
5693 pci_enable_device(pci);
5694 pci_set_master(pci);
5696 snd_mychip_reinit_chip(chip);
5698 snd_mychip_restore_registers(chip);
5700 snd_ac97_resume(chip->ac97);
5702 snd_mychip_restart_chip(chip);
5704 snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5713 As shown in the above, it's better to save registers after
5714 suspending the PCM operations via
5715 <function>snd_pcm_suspend_all()</function> or
5716 <function>snd_pcm_suspend()</function>. It means that the PCM
5717 streams are already stopped when the register snapshot is
5718 taken. But, remember that you don't have to restart the PCM
5719 stream in the resume callback. It'll be restarted via
5720 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5725 OK, we have all callbacks now. Let's set them up. In the
5726 initialization of the card, make sure that you can get the chip
5727 data from the card instance, typically via
5728 <structfield>private_data</structfield> field, in case you
5729 created the chip data individually.
5734 static int snd_mychip_probe(struct pci_dev *pci,
5735 const struct pci_device_id *pci_id)
5738 struct snd_card *card;
5739 struct mychip *chip;
5742 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5745 chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5747 card->private_data = chip;
5754 When you created the chip data with
5755 <function>snd_card_new()</function>, it's anyway accessible
5756 via <structfield>private_data</structfield> field.
5761 static int snd_mychip_probe(struct pci_dev *pci,
5762 const struct pci_device_id *pci_id)
5765 struct snd_card *card;
5766 struct mychip *chip;
5769 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
5770 sizeof(struct mychip), &card);
5772 chip = card->private_data;
5782 If you need a space to save the registers, allocate the
5783 buffer for it here, too, since it would be fatal
5784 if you cannot allocate a memory in the suspend phase.
5785 The allocated buffer should be released in the corresponding
5790 And next, set suspend/resume callbacks to the pci_driver.
5795 static struct pci_driver driver = {
5796 .name = KBUILD_MODNAME,
5797 .id_table = snd_my_ids,
5798 .probe = snd_my_probe,
5799 .remove = snd_my_remove,
5801 .suspend = snd_my_suspend,
5802 .resume = snd_my_resume,
5813 <!-- ****************************************************** -->
5814 <!-- Module Parameters -->
5815 <!-- ****************************************************** -->
5816 <chapter id="module-parameters">
5817 <title>Module Parameters</title>
5819 There are standard module options for ALSA. At least, each
5820 module should have the <parameter>index</parameter>,
5821 <parameter>id</parameter> and <parameter>enable</parameter>
5826 If the module supports multiple cards (usually up to
5827 8 = <constant>SNDRV_CARDS</constant> cards), they should be
5828 arrays. The default initial values are defined already as
5829 constants for easier programming:
5834 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5835 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5836 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5843 If the module supports only a single card, they could be single
5844 variables, instead. <parameter>enable</parameter> option is not
5845 always necessary in this case, but it would be better to have a
5846 dummy option for compatibility.
5850 The module parameters must be declared with the standard
5851 <function>module_param()()</function>,
5852 <function>module_param_array()()</function> and
5853 <function>MODULE_PARM_DESC()</function> macros.
5857 The typical coding would be like below:
5862 #define CARD_NAME "My Chip"
5864 module_param_array(index, int, NULL, 0444);
5865 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5866 module_param_array(id, charp, NULL, 0444);
5867 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5868 module_param_array(enable, bool, NULL, 0444);
5869 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5876 Also, don't forget to define the module description, classes,
5877 license and devices. Especially, the recent modprobe requires to
5878 define the module license as GPL, etc., otherwise the system is
5879 shown as <quote>tainted</quote>.
5884 MODULE_DESCRIPTION("My Chip");
5885 MODULE_LICENSE("GPL");
5886 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5895 <!-- ****************************************************** -->
5896 <!-- How To Put Your Driver -->
5897 <!-- ****************************************************** -->
5898 <chapter id="how-to-put-your-driver">
5899 <title>How To Put Your Driver Into ALSA Tree</title>
5901 <title>General</title>
5903 So far, you've learned how to write the driver codes.
5904 And you might have a question now: how to put my own
5905 driver into the ALSA driver tree?
5906 Here (finally :) the standard procedure is described briefly.
5910 Suppose that you create a new PCI driver for the card
5911 <quote>xyz</quote>. The card module name would be
5912 snd-xyz. The new driver is usually put into the alsa-driver
5913 tree, <filename>alsa-driver/pci</filename> directory in
5914 the case of PCI cards.
5915 Then the driver is evaluated, audited and tested
5916 by developers and users. After a certain time, the driver
5917 will go to the alsa-kernel tree (to the corresponding directory,
5918 such as <filename>alsa-kernel/pci</filename>) and eventually
5919 will be integrated into the Linux 2.6 tree (the directory would be
5920 <filename>linux/sound/pci</filename>).
5924 In the following sections, the driver code is supposed
5925 to be put into alsa-driver tree. The two cases are covered:
5926 a driver consisting of a single source file and one consisting
5927 of several source files.
5932 <title>Driver with A Single Source File</title>
5937 Modify alsa-driver/pci/Makefile
5941 Suppose you have a file xyz.c. Add the following
5946 snd-xyz-objs := xyz.o
5947 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5956 Create the Kconfig entry
5960 Add the new entry of Kconfig for your xyz driver.
5965 tristate "Foobar XYZ"
5969 Say Y here to include support for Foobar XYZ soundcard.
5971 To compile this driver as a module, choose M here: the module
5972 will be called snd-xyz.
5977 the line, select SND_PCM, specifies that the driver xyz supports
5978 PCM. In addition to SND_PCM, the following components are
5979 supported for select command:
5980 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
5981 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
5982 Add the select command for each supported component.
5986 Note that some selections imply the lowlevel selections.
5987 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
5988 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
5989 You don't need to give the lowlevel selections again.
5993 For the details of Kconfig script, refer to the kbuild
6001 Run cvscompile script to re-generate the configure script and
6002 build the whole stuff again.
6010 <title>Drivers with Several Source Files</title>
6012 Suppose that the driver snd-xyz have several source files.
6013 They are located in the new subdirectory,
6019 Add a new directory (<filename>xyz</filename>) in
6020 <filename>alsa-driver/pci/Makefile</filename> as below
6025 obj-$(CONFIG_SND) += xyz/
6034 Under the directory <filename>xyz</filename>, create a Makefile
6037 <title>Sample Makefile for a driver xyz</title>
6044 include $(SND_TOPDIR)/toplevel.config
6045 include $(SND_TOPDIR)/Makefile.conf
6047 snd-xyz-objs := xyz.o abc.o def.o
6049 obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6051 include $(SND_TOPDIR)/Rules.make
6060 Create the Kconfig entry
6064 This procedure is as same as in the last section.
6070 Run cvscompile script to re-generate the configure script and
6071 build the whole stuff again.
6080 <!-- ****************************************************** -->
6081 <!-- Useful Functions -->
6082 <!-- ****************************************************** -->
6083 <chapter id="useful-functions">
6084 <title>Useful Functions</title>
6086 <section id="useful-functions-snd-printk">
6087 <title><function>snd_printk()</function> and friends</title>
6089 ALSA provides a verbose version of the
6090 <function>printk()</function> function. If a kernel config
6091 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6092 function prints the given message together with the file name
6093 and the line of the caller. The <constant>KERN_XXX</constant>
6094 prefix is processed as
6095 well as the original <function>printk()</function> does, so it's
6096 recommended to add this prefix, e.g.
6101 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6108 There are also <function>printk()</function>'s for
6109 debugging. <function>snd_printd()</function> can be used for
6110 general debugging purposes. If
6111 <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6112 compiled, and works just like
6113 <function>snd_printk()</function>. If the ALSA is compiled
6114 without the debugging flag, it's ignored.
6118 <function>snd_printdd()</function> is compiled in only when
6119 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6120 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6121 even if you configure the alsa-driver with
6122 <option>--with-debug=full</option> option. You need to give
6123 explicitly <option>--with-debug=detect</option> option instead.
6127 <section id="useful-functions-snd-bug">
6128 <title><function>snd_BUG()</function></title>
6130 It shows the <computeroutput>BUG?</computeroutput> message and
6131 stack trace as well as <function>snd_BUG_ON</function> at the point.
6132 It's useful to show that a fatal error happens there.
6135 When no debug flag is set, this macro is ignored.
6139 <section id="useful-functions-snd-bug-on">
6140 <title><function>snd_BUG_ON()</function></title>
6142 <function>snd_BUG_ON()</function> macro is similar with
6143 <function>WARN_ON()</function> macro. For example,
6148 snd_BUG_ON(!pointer);
6153 or it can be used as the condition,
6157 if (snd_BUG_ON(non_zero_is_bug))
6166 The macro takes an conditional expression to evaluate.
6167 When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
6168 expression is non-zero, it shows the warning message such as
6169 <computeroutput>BUG? (xxx)</computeroutput>
6170 normally followed by stack trace.
6172 In both cases it returns the evaluated value.
6180 <!-- ****************************************************** -->
6181 <!-- Acknowledgments -->
6182 <!-- ****************************************************** -->
6183 <chapter id="acknowledgments">
6184 <title>Acknowledgments</title>
6186 I would like to thank Phil Kerr for his help for improvement and
6187 corrections of this document.
6190 Kevin Conder reformatted the original plain-text to the
6194 Giuliano Pochini corrected typos and contributed the example codes
6195 in the hardware constraints section.