1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Writing an ALSA Driver</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><meta name="description" content="This document describes how to write an ALSA (Advanced Linux Sound Architecture) driver."><link rel="home" href="index.html" title="Writing an ALSA Driver"><link rel="next" href="preface.html" title="Preface"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing an ALSA Driver</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="preface.html">Next</a></td></tr></table><hr></div><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="Writing-an-ALSA-Driver"></a>Writing an ALSA Driver</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Takashi</span> <span class="surname">Iwai</span></h3><div class="affiliation"><div class="address"><p><br> 2          <code class="email"><<a class="email" href="mailto:tiwai@suse.de">tiwai@suse.de</a>></code><br> 3        </p></div></div></div></div><div><div class="legalnotice"><a name="idp1093351556"></a><p> 4 Copyright (c) 2002-2005 Takashi Iwai <code class="email"><<a class="email" href="mailto:tiwai@suse.de">tiwai@suse.de</a>></code> 5 </p><p> 6 This document is free; you can redistribute it and/or modify it 7 under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2 of the License, or 9 (at your option) any later version. 10 </p><p> 11 This document is distributed in the hope that it will be useful, 12 but <span class="emphasis"><em>WITHOUT ANY WARRANTY</em></span>; without even the 13 implied warranty of <span class="emphasis"><em>MERCHANTABILITY or FITNESS FOR A 14 PARTICULAR PURPOSE</em></span>. See the GNU General Public License 15 for more details. 16 </p><p> 17 You should have received a copy of the GNU General Public 18 License along with this program; if not, write to the Free 19 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 20 MA 02111-1307 USA 21 </p></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p> 22 This document describes how to write an ALSA (Advanced Linux 23 Sound Architecture) driver. 24 </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="preface.html">Preface</a></span></dt><dt><span class="chapter"><a href="file-tree.html">1. File Tree Structure</a></span></dt><dd><dl><dt><span class="section"><a href="file-tree.html#file-tree-general">General</a></span></dt><dt><span class="section"><a href="file-tree-core-directory.html">core directory</a></span></dt><dd><dl><dt><span class="section"><a href="file-tree-core-directory.html#file-tree-core-directory-oss">core/oss</a></span></dt><dt><span class="section"><a href="file-tree-core-directory.html#file-tree-core-directory-ioctl32">core/ioctl32</a></span></dt><dt><span class="section"><a href="file-tree-core-directory.html#file-tree-core-directory-seq">core/seq</a></span></dt><dt><span class="section"><a href="file-tree-core-directory.html#file-tree-core-directory-seq-oss">core/seq/oss</a></span></dt><dt><span class="section"><a href="file-tree-core-directory.html#file-tree-core-directory-deq-instr">core/seq/instr</a></span></dt></dl></dd><dt><span class="section"><a href="file-tree-include-directory.html">include directory</a></span></dt><dt><span class="section"><a href="file-tree-drivers-directory.html">drivers directory</a></span></dt><dd><dl><dt><span class="section"><a href="file-tree-drivers-directory.html#file-tree-drivers-directory-mpu401">drivers/mpu401</a></span></dt><dt><span class="section"><a href="file-tree-drivers-directory.html#file-tree-drivers-directory-opl3">drivers/opl3 and opl4</a></span></dt></dl></dd><dt><span class="section"><a href="file-tree-i2c-directory.html">i2c directory</a></span></dt><dd><dl><dt><span class="section"><a href="file-tree-i2c-directory.html#file-tree-i2c-directory-l3">i2c/l3</a></span></dt></dl></dd><dt><span class="section"><a href="file-tree-synth-directory.html">synth directory</a></span></dt><dt><span class="section"><a href="file-tree-pci-directory.html">pci directory</a></span></dt><dt><span class="section"><a href="file-tree-isa-directory.html">isa directory</a></span></dt><dt><span class="section"><a href="file-tree-arm-ppc-sparc-directories.html">arm, ppc, and sparc directories</a></span></dt><dt><span class="section"><a href="file-tree-usb-directory.html">usb directory</a></span></dt><dt><span class="section"><a href="file-tree-pcmcia-directory.html">pcmcia directory</a></span></dt><dt><span class="section"><a href="file-tree-oss-directory.html">oss directory</a></span></dt></dl></dd><dt><span class="chapter"><a href="basic-flow.html">2. Basic Flow for PCI Drivers</a></span></dt><dd><dl><dt><span class="section"><a href="basic-flow.html#basic-flow-outline">Outline</a></span></dt><dt><span class="section"><a href="basic-flow-example.html">Full Code Example</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html">Constructor</a></span></dt><dd><dl><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-device-index">1) Check and increment the device index.</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-create-card">2) Create a card instance</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-create-main">3) Create a main component</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-main-component">4) Set the driver ID and name strings.</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-create-other">5) Create other components, such as mixer, MIDI, etc.</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-register-card">6) Register the card instance.</a></span></dt><dt><span class="section"><a href="basic-flow-constructor.html#basic-flow-constructor-set-pci">7) Set the PCI driver data and return zero.</a></span></dt></dl></dd><dt><span class="section"><a href="basic-flow-destructor.html">Destructor</a></span></dt><dt><span class="section"><a href="basic-flow-header-files.html">Header Files</a></span></dt></dl></dd><dt><span class="chapter"><a href="card-management.html">3. Management of Cards and Components</a></span></dt><dd><dl><dt><span class="section"><a href="card-management.html#card-management-card-instance">Card Instance</a></span></dt><dt><span class="section"><a href="card-management-component.html">Components</a></span></dt><dt><span class="section"><a href="card-management-chip-specific.html">Chip-Specific Data</a></span></dt><dd><dl><dt><span class="section"><a href="card-management-chip-specific.html#card-management-chip-specific-snd-card-new">1. Allocating via <code class="function">snd_card_new()</code>.</a></span></dt><dt><span class="section"><a href="card-management-chip-specific.html#card-management-chip-specific-allocate-extra">2. Allocating an extra device.</a></span></dt></dl></dd><dt><span class="section"><a href="card-management-registration.html">Registration and Release</a></span></dt></dl></dd><dt><span class="chapter"><a href="pci-resource.html">4. PCI Resource Management</a></span></dt><dd><dl><dt><span class="section"><a href="pci-resource.html#pci-resource-example">Full Code Example</a></span></dt><dt><span class="section"><a href="pci-resource-some-haftas.html">Some Hafta's</a></span></dt><dt><span class="section"><a href="pci-resource-resource-allocation.html">Resource Allocation</a></span></dt><dt><span class="section"><a href="pci-resource-entries.html">PCI Entries</a></span></dt></dl></dd><dt><span class="chapter"><a href="pcm-interface.html">5. PCM Interface</a></span></dt><dd><dl><dt><span class="section"><a href="pcm-interface.html#pcm-interface-general">General</a></span></dt><dt><span class="section"><a href="pcm-interface-example.html">Full Code Example</a></span></dt><dt><span class="section"><a href="pcm-interface-constructor.html">Constructor</a></span></dt><dt><span class="section"><a href="pcm-interface-destructor.html">... And the Destructor?</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html">Runtime Pointer - The Chest of PCM Information</a></span></dt><dd><dl><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-hw">Hardware Description</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-config">PCM Configurations</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-dma">DMA Buffer Information</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-status">Running Status</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-private">Private Data</a></span></dt><dt><span class="section"><a href="pcm-interface-runtime.html#pcm-interface-runtime-intr">Interrupt Callbacks</a></span></dt></dl></dd><dt><span class="section"><a href="pcm-interface-operators.html">Operators</a></span></dt><dd><dl><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-open-callback">open callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-close-callback">close callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-ioctl-callback">ioctl callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-hw-params-callback">hw_params callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-hw-free-callback">hw_free callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-prepare-callback">prepare callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-trigger-callback">trigger callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-pointer-callback">pointer callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-copy-silence">copy and silence callbacks</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-ack">ack callback</a></span></dt><dt><span class="section"><a href="pcm-interface-operators.html#pcm-interface-operators-page-callback">page callback</a></span></dt></dl></dd><dt><span class="section"><a href="pcm-interface-interrupt-handler.html">Interrupt Handler</a></span></dt><dd><dl><dt><span class="section"><a href="pcm-interface-interrupt-handler.html#pcm-interface-interrupt-handler-boundary">Interrupts at the period (fragment) boundary</a></span></dt><dt><span class="section"><a href="pcm-interface-interrupt-handler.html#pcm-interface-interrupt-handler-timer">High frequency timer interrupts</a></span></dt><dt><span class="section"><a href="pcm-interface-interrupt-handler.html#pcm-interface-interrupt-handler-both">On calling <code class="function">snd_pcm_period_elapsed()</code></a></span></dt></dl></dd><dt><span class="section"><a href="pcm-interface-atomicity.html">Atomicity</a></span></dt><dt><span class="section"><a href="pcm-interface-constraints.html">Constraints</a></span></dt></dl></dd><dt><span class="chapter"><a href="control-interface.html">6. Control Interface</a></span></dt><dd><dl><dt><span class="section"><a href="control-interface.html#control-interface-general">General</a></span></dt><dt><span class="section"><a href="control-interface-definition.html">Definition of Controls</a></span></dt><dt><span class="section"><a href="control-interface-control-names.html">Control Names</a></span></dt><dd><dl><dt><span class="section"><a href="control-interface-control-names.html#control-interface-control-names-global">Global capture and playback</a></span></dt><dt><span class="section"><a href="control-interface-control-names.html#control-interface-control-names-tone">Tone-controls</a></span></dt><dt><span class="section"><a href="control-interface-control-names.html#control-interface-control-names-3d">3D controls</a></span></dt><dt><span class="section"><a href="control-interface-control-names.html#control-interface-control-names-mic">Mic boost</a></span></dt></dl></dd><dt><span class="section"><a href="control-interface-access-flags.html">Access Flags</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html">Callbacks</a></span></dt><dd><dl><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-info">info callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-get">get callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-put">put callback</a></span></dt><dt><span class="section"><a href="control-interface-callbacks.html#control-interface-callbacks-all">Callbacks are not atomic</a></span></dt></dl></dd><dt><span class="section"><a href="control-interface-constructor.html">Constructor</a></span></dt><dt><span class="section"><a href="control-interface-change-notification.html">Change Notification</a></span></dt><dt><span class="section"><a href="control-interface-tlv.html">Metadata</a></span></dt></dl></dd><dt><span class="chapter"><a href="api-ac97.html">7. API for AC97 Codec</a></span></dt><dd><dl><dt><span class="section"><a href="api-ac97.html#idp1094227412">General</a></span></dt><dt><span class="section"><a href="api-ac97-example.html">Full Code Example</a></span></dt><dt><span class="section"><a href="api-ac97-constructor.html">Constructor</a></span></dt><dt><span class="section"><a href="api-ac97-callbacks.html">Callbacks</a></span></dt><dt><span class="section"><a href="api-ac97-updating-registers.html">Updating Registers in The Driver</a></span></dt><dt><span class="section"><a href="api-ac97-clock-adjustment.html">Clock Adjustment</a></span></dt><dt><span class="section"><a href="api-ac97-proc-files.html">Proc Files</a></span></dt><dt><span class="section"><a href="api-ac97-multiple-codecs.html">Multiple Codecs</a></span></dt></dl></dd><dt><span class="chapter"><a href="midi-interface.html">8. MIDI (MPU401-UART) Interface</a></span></dt><dd><dl><dt><span class="section"><a href="midi-interface.html#midi-interface-general">General</a></span></dt><dt><span class="section"><a href="midi-interface-constructor.html">Constructor</a></span></dt><dt><span class="section"><a href="midi-interface-interrupt-handler.html">Interrupt Handler</a></span></dt></dl></dd><dt><span class="chapter"><a href="rawmidi-interface.html">9. RawMIDI Interface</a></span></dt><dd><dl><dt><span class="section"><a href="rawmidi-interface.html#rawmidi-interface-overview">Overview</a></span></dt><dt><span class="section"><a href="rawmidi-interface-constructor.html">Constructor</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html">Callbacks</a></span></dt><dd><dl><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-open"><code class="function">open</code> callback</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-close"><code class="function">close</code> callback</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-trigger-out"><code class="function">trigger</code> callback for output 25 substreams</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-trigger-in"><code class="function">trigger</code> callback for input 26 substreams</a></span></dt><dt><span class="section"><a href="rawmidi-interface-callbacks.html#rawmidi-interface-op-drain"><code class="function">drain</code> callback</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="misc-devices.html">10. Miscellaneous Devices</a></span></dt><dd><dl><dt><span class="section"><a href="misc-devices.html#misc-devices-opl3">FM OPL3</a></span></dt><dt><span class="section"><a href="misc-devices-hardware-dependent.html">Hardware-Dependent Devices</a></span></dt><dt><span class="section"><a href="misc-devices-IEC958.html">IEC958 (S/PDIF)</a></span></dt></dl></dd><dt><span class="chapter"><a href="buffer-and-memory.html">11. Buffer and Memory Management</a></span></dt><dd><dl><dt><span class="section"><a href="buffer-and-memory.html#buffer-and-memory-buffer-types">Buffer Types</a></span></dt><dt><span class="section"><a href="buffer-and-memory-external-hardware.html">External Hardware Buffers</a></span></dt><dt><span class="section"><a href="buffer-and-memory-non-contiguous.html">Non-Contiguous Buffers</a></span></dt><dt><span class="section"><a href="buffer-and-memory-vmalloced.html">Vmalloc'ed Buffers</a></span></dt></dl></dd><dt><span class="chapter"><a href="proc-interface.html">12. Proc Interface</a></span></dt><dt><span class="chapter"><a href="power-management.html">13. Power Management</a></span></dt><dt><span class="chapter"><a href="module-parameters.html">14. Module Parameters</a></span></dt><dt><span class="chapter"><a href="how-to-put-your-driver.html">15. How To Put Your Driver Into ALSA Tree</a></span></dt><dd><dl><dt><span class="section"><a href="how-to-put-your-driver.html#idp1094431804">General</a></span></dt><dt><span class="section"><a href="ch15s02.html">Driver with A Single Source File</a></span></dt><dt><span class="section"><a href="ch15s03.html">Drivers with Several Source Files</a></span></dt></dl></dd><dt><span class="chapter"><a href="useful-functions.html">16. Useful Functions</a></span></dt><dd><dl><dt><span class="section"><a href="useful-functions.html#useful-functions-snd-printk"><code class="function">snd_printk()</code> and friends</a></span></dt><dt><span class="section"><a href="useful-functions-snd-bug.html"><code class="function">snd_BUG()</code></a></span></dt><dt><span class="section"><a href="useful-functions-snd-bug-on.html"><code class="function">snd_BUG_ON()</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="acknowledgments.html">17. Acknowledgments</a></span></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>1.1. <a href="file-tree.html#idp1091273276">ALSA File Tree Structure</a></dt><dt>2.1. <a href="basic-flow-example.html#idp1090981916">Basic Flow for PCI Drivers - Example</a></dt><dt>4.1. <a href="pci-resource.html#idp1093954540">PCI Resource Management Example</a></dt><dt>5.1. <a href="pcm-interface-example.html#idp1094006196">PCM Example Code</a></dt><dt>5.2. <a href="pcm-interface-destructor.html#idp1094035556">PCM Instance with a Destructor</a></dt><dt>5.3. <a href="pcm-interface-interrupt-handler.html#idp1094132124">Interrupt Handler Case #1</a></dt><dt>5.4. <a href="pcm-interface-interrupt-handler.html#idp1094135868">Interrupt Handler Case #2</a></dt><dt>5.5. <a href="pcm-interface-constraints.html#idp1094149308">Example of Hardware Constraints</a></dt><dt>5.6. <a href="pcm-interface-constraints.html#idp1094152404">Example of Hardware Constraints for Channels</a></dt><dt>5.7. <a href="pcm-interface-constraints.html#idp1094156172">Example of Hardware Constraints for Formats</a></dt><dt>6.1. <a href="control-interface-definition.html#idp1094164476">Definition of a Control</a></dt><dt>6.2. <a href="control-interface-callbacks.html#idp1094193780">Example of info callback</a></dt><dt>6.3. <a href="control-interface-callbacks.html#idp1094203812">Example of get callback</a></dt><dt>6.4. <a href="control-interface-callbacks.html#idp1094210188">Example of put callback</a></dt><dt>7.1. <a href="api-ac97-example.html#idp1094229132">Example of AC97 Interface</a></dt><dt>15.1. <a href="ch15s03.html#idp1094443684">Sample Makefile for a driver xyz</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="preface.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Preface</td></tr></table></div></body></html> 27