linux/Documentation/DocBook/writing-an-alsa-driver.tmpl
<<
>>
Prefs
   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" []>
   4
   5<!-- ****************************************************** -->
   6<!-- Header  -->
   7<!-- ****************************************************** -->
   8<book id="Writing-an-ALSA-Driver">
   9  <bookinfo>
  10    <title>Writing an ALSA Driver</title>
  11    <author>
  12      <firstname>Takashi</firstname>
  13      <surname>Iwai</surname>
  14      <affiliation>
  15        <address>
  16          <email>tiwai@suse.de</email>
  17        </address>
  18      </affiliation>
  19     </author>
  20
  21     <date>Oct 15, 2007</date>
  22     <edition>0.3.7</edition>
  23
  24    <abstract>
  25      <para>
  26        This document describes how to write an ALSA (Advanced Linux
  27        Sound Architecture) driver.
  28      </para>
  29    </abstract>
  30
  31    <legalnotice>
  32    <para>
  33    Copyright (c) 2002-2005  Takashi Iwai <email>tiwai@suse.de</email>
  34    </para>
  35
  36    <para>
  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. 
  41    </para>
  42
  43    <para>
  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
  48    for more details.
  49    </para>
  50
  51    <para>
  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,
  55    MA 02111-1307 USA
  56    </para>
  57    </legalnotice>
  58
  59  </bookinfo>
  60
  61<!-- ****************************************************** -->
  62<!-- Preface  -->
  63<!-- ****************************************************** -->
  64  <preface id="preface">
  65    <title>Preface</title>
  66    <para>
  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
  74      writing them.
  75    </para>
  76
  77    <para>
  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.
  84    </para>
  85
  86    <para>
  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.
  91    </para>
  92
  93    <para>
  94      This document is still a draft version. Any feedback and
  95    corrections, please!!
  96    </para>
  97  </preface>
  98
  99
 100<!-- ****************************************************** -->
 101<!-- File Tree Structure  -->
 102<!-- ****************************************************** -->
 103  <chapter id="file-tree">
 104    <title>File Tree Structure</title>
 105
 106    <section id="file-tree-general">
 107      <title>General</title>
 108      <para>
 109        The ALSA drivers are provided in two ways.
 110      </para>
 111
 112      <para>
 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.
 126      </para>
 127
 128      <para>
 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. 
 133
 134        <example>
 135          <title>ALSA File Tree Structure</title>
 136          <literallayout>
 137        sound
 138                /core
 139                        /oss
 140                        /seq
 141                                /oss
 142                                /instr
 143                /ioctl32
 144                /include
 145                /drivers
 146                        /mpu401
 147                        /opl3
 148                /i2c
 149                        /l3
 150                /synth
 151                        /emux
 152                /pci
 153                        /(cards)
 154                /isa
 155                        /(cards)
 156                /arm
 157                /ppc
 158                /sparc
 159                /usb
 160                /pcmcia /(cards)
 161                /oss
 162          </literallayout>
 163        </example>
 164      </para>
 165    </section>
 166
 167    <section id="file-tree-core-directory">
 168      <title>core directory</title>
 169      <para>
 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. 
 174      </para>
 175
 176      <section id="file-tree-core-directory-oss">
 177        <title>core/oss</title>
 178
 179        <para>
 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>).
 186        </para>
 187      </section>
 188
 189      <section id="file-tree-core-directory-ioctl32">
 190        <title>core/ioctl32</title>
 191
 192        <para>
 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. 
 196        </para>
 197      </section>
 198
 199      <section id="file-tree-core-directory-seq">
 200        <title>core/seq</title>
 201        <para>
 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
 207        config. 
 208        </para>
 209      </section>
 210
 211      <section id="file-tree-core-directory-seq-oss">
 212        <title>core/seq/oss</title>
 213        <para>
 214          This contains the OSS sequencer emulation codes.
 215        </para>
 216      </section>
 217
 218      <section id="file-tree-core-directory-deq-instr">
 219        <title>core/seq/instr</title>
 220        <para>
 221          This directory contains the modules for the sequencer
 222        instrument layer. 
 223        </para>
 224      </section>
 225    </section>
 226
 227    <section id="file-tree-include-directory">
 228      <title>include directory</title>
 229      <para>
 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 :) 
 235      </para>
 236    </section>
 237
 238    <section id="file-tree-drivers-directory">
 239      <title>drivers directory</title>
 240      <para>
 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. 
 248      </para>
 249
 250      <section id="file-tree-drivers-directory-mpu401">
 251        <title>drivers/mpu401</title>
 252        <para>
 253          The MPU401 and MPU401-UART modules are stored here.
 254        </para>
 255      </section>
 256
 257      <section id="file-tree-drivers-directory-opl3">
 258        <title>drivers/opl3 and opl4</title>
 259        <para>
 260          The OPL3 and OPL4 FM-synth stuff is found here.
 261        </para>
 262      </section>
 263    </section>
 264
 265    <section id="file-tree-i2c-directory">
 266      <title>i2c directory</title>
 267      <para>
 268        This contains the ALSA i2c components.
 269      </para>
 270
 271      <para>
 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
 275      such a purpose. 
 276      </para>
 277
 278      <section id="file-tree-i2c-directory-l3">
 279        <title>i2c/l3</title>
 280        <para>
 281          This is a sub-directory for ARM L3 i2c.
 282        </para>
 283      </section>
 284    </section>
 285
 286    <section id="file-tree-synth-directory">
 287        <title>synth directory</title>
 288        <para>
 289          This contains the synth middle-level modules.
 290        </para>
 291
 292        <para>
 293          So far, there is only Emu8000/Emu10k1 synth driver under
 294        the <filename>synth/emux</filename> sub-directory. 
 295        </para>
 296    </section>
 297
 298    <section id="file-tree-pci-directory">
 299      <title>pci directory</title>
 300      <para>
 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.
 303      </para>
 304
 305      <para>
 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). 
 309      </para>
 310    </section>
 311
 312    <section id="file-tree-isa-directory">
 313      <title>isa directory</title>
 314      <para>
 315        This directory and its sub-directories hold the top-level card modules
 316      for ISA soundcards. 
 317      </para>
 318    </section>
 319
 320    <section id="file-tree-arm-ppc-sparc-directories">
 321      <title>arm, ppc, and sparc directories</title>
 322      <para>
 323        They are used for top-level card modules which are
 324      specific to one of these architectures. 
 325      </para>
 326    </section>
 327
 328    <section id="file-tree-usb-directory">
 329      <title>usb directory</title>
 330      <para>
 331        This directory contains the USB-audio driver. In the latest version, the
 332      USB MIDI driver is integrated in the usb-audio driver. 
 333      </para>
 334    </section>
 335
 336    <section id="file-tree-pcmcia-directory">
 337      <title>pcmcia directory</title>
 338      <para>
 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. 
 342      </para>
 343    </section>
 344
 345    <section id="file-tree-oss-directory">
 346      <title>oss directory</title>
 347      <para>
 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,
 350      of course :) 
 351      </para>
 352    </section>
 353  </chapter>
 354
 355
 356<!-- ****************************************************** -->
 357<!-- Basic Flow for PCI Drivers  -->
 358<!-- ****************************************************** -->
 359  <chapter id="basic-flow">
 360    <title>Basic Flow for PCI Drivers</title>
 361
 362    <section id="basic-flow-outline">
 363      <title>Outline</title>
 364      <para>
 365        The minimum flow for PCI soundcards is as follows:
 366
 367        <itemizedlist>
 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>
 380        </itemizedlist>
 381      </para>
 382    </section>
 383
 384    <section id="basic-flow-example">
 385      <title>Full Code Example</title>
 386      <para>
 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. 
 392
 393        <example>
 394          <title>Basic Flow for PCI Drivers - Example</title>
 395          <programlisting>
 396<![CDATA[
 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>
 402
 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;
 408
 409  /* definition of the chip-specific record */
 410  struct mychip {
 411          struct snd_card *card;
 412          /* the rest of the implementation will be in section
 413           * "PCI Resource Management"
 414           */
 415  };
 416
 417  /* chip-specific destructor
 418   * (see "PCI Resource Management")
 419   */
 420  static int snd_mychip_free(struct mychip *chip)
 421  {
 422          .... /* will be implemented later... */
 423  }
 424
 425  /* component-destructor
 426   * (see "Management of Cards and Components")
 427   */
 428  static int snd_mychip_dev_free(struct snd_device *device)
 429  {
 430          return snd_mychip_free(device->device_data);
 431  }
 432
 433  /* chip-specific constructor
 434   * (see "Management of Cards and Components")
 435   */
 436  static int __devinit snd_mychip_create(struct snd_card *card,
 437                                         struct pci_dev *pci,
 438                                         struct mychip **rchip)
 439  {
 440          struct mychip *chip;
 441          int err;
 442          static struct snd_device_ops ops = {
 443                 .dev_free = snd_mychip_dev_free,
 444          };
 445
 446          *rchip = NULL;
 447
 448          /* check PCI availability here
 449           * (see "PCI Resource Management")
 450           */
 451          ....
 452
 453          /* allocate a chip-specific data with zero filled */
 454          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
 455          if (chip == NULL)
 456                  return -ENOMEM;
 457
 458          chip->card = card;
 459
 460          /* rest of initialization here; will be implemented
 461           * later, see "PCI Resource Management"
 462           */
 463          ....
 464
 465          err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
 466          if (err < 0) {
 467                  snd_mychip_free(chip);
 468                  return err;
 469          }
 470
 471          snd_card_set_dev(card, &pci->dev);
 472
 473          *rchip = chip;
 474          return 0;
 475  }
 476
 477  /* constructor -- see "Constructor" sub-section */
 478  static int __devinit snd_mychip_probe(struct pci_dev *pci,
 479                               const struct pci_device_id *pci_id)
 480  {
 481          static int dev;
 482          struct snd_card *card;
 483          struct mychip *chip;
 484          int err;
 485
 486          /* (1) */
 487          if (dev >= SNDRV_CARDS)
 488                  return -ENODEV;
 489          if (!enable[dev]) {
 490                  dev++;
 491                  return -ENOENT;
 492          }
 493
 494          /* (2) */
 495          err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
 496          if (err < 0)
 497                  return err;
 498
 499          /* (3) */
 500          err = snd_mychip_create(card, pci, &chip);
 501          if (err < 0) {
 502                  snd_card_free(card);
 503                  return err;
 504          }
 505
 506          /* (4) */
 507          strcpy(card->driver, "My Chip");
 508          strcpy(card->shortname, "My Own Chip 123");
 509          sprintf(card->longname, "%s at 0x%lx irq %i",
 510                  card->shortname, chip->ioport, chip->irq);
 511
 512          /* (5) */
 513          .... /* implemented later */
 514
 515          /* (6) */
 516          err = snd_card_register(card);
 517          if (err < 0) {
 518                  snd_card_free(card);
 519                  return err;
 520          }
 521
 522          /* (7) */
 523          pci_set_drvdata(pci, card);
 524          dev++;
 525          return 0;
 526  }
 527
 528  /* destructor -- see the "Destructor" sub-section */
 529  static void __devexit snd_mychip_remove(struct pci_dev *pci)
 530  {
 531          snd_card_free(pci_get_drvdata(pci));
 532          pci_set_drvdata(pci, NULL);
 533  }
 534]]>
 535          </programlisting>
 536        </example>
 537      </para>
 538    </section>
 539
 540    <section id="basic-flow-constructor">
 541      <title>Constructor</title>
 542      <para>
 543        The real constructor of PCI drivers is the <function>probe</function> callback.
 544      The <function>probe</function> callback and other component-constructors which are called
 545      from the <function>probe</function> callback should be defined with
 546      the <parameter>__devinit</parameter> prefix. You 
 547      cannot use the <parameter>__init</parameter> prefix for them,
 548      because any PCI device could be a hotplug device. 
 549      </para>
 550
 551      <para>
 552        In the <function>probe</function> callback, the following scheme is often used.
 553      </para>
 554
 555      <section id="basic-flow-constructor-device-index">
 556        <title>1) Check and increment the device index.</title>
 557        <para>
 558          <informalexample>
 559            <programlisting>
 560<![CDATA[
 561  static int dev;
 562  ....
 563  if (dev >= SNDRV_CARDS)
 564          return -ENODEV;
 565  if (!enable[dev]) {
 566          dev++;
 567          return -ENOENT;
 568  }
 569]]>
 570            </programlisting>
 571          </informalexample>
 572
 573        where enable[dev] is the module option.
 574        </para>
 575
 576        <para>
 577          Each time the <function>probe</function> callback is called, check the
 578        availability of the device. If not available, simply increment
 579        the device index and returns. dev will be incremented also
 580        later (<link
 581        linkend="basic-flow-constructor-set-pci"><citetitle>step
 582        7</citetitle></link>). 
 583        </para>
 584      </section>
 585
 586      <section id="basic-flow-constructor-create-card">
 587        <title>2) Create a card instance</title>
 588        <para>
 589          <informalexample>
 590            <programlisting>
 591<![CDATA[
 592  struct snd_card *card;
 593  int err;
 594  ....
 595  err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
 596]]>
 597            </programlisting>
 598          </informalexample>
 599        </para>
 600
 601        <para>
 602          The details will be explained in the section
 603          <link linkend="card-management-card-instance"><citetitle>
 604          Management of Cards and Components</citetitle></link>.
 605        </para>
 606      </section>
 607
 608      <section id="basic-flow-constructor-create-main">
 609        <title>3) Create a main component</title>
 610        <para>
 611          In this part, the PCI resources are allocated.
 612
 613          <informalexample>
 614            <programlisting>
 615<![CDATA[
 616  struct mychip *chip;
 617  ....
 618  err = snd_mychip_create(card, pci, &chip);
 619  if (err < 0) {
 620          snd_card_free(card);
 621          return err;
 622  }
 623]]>
 624            </programlisting>
 625          </informalexample>
 626
 627          The details will be explained in the section <link
 628        linkend="pci-resource"><citetitle>PCI Resource
 629        Management</citetitle></link>.
 630        </para>
 631      </section>
 632
 633      <section id="basic-flow-constructor-main-component">
 634        <title>4) Set the driver ID and name strings.</title>
 635        <para>
 636          <informalexample>
 637            <programlisting>
 638<![CDATA[
 639  strcpy(card->driver, "My Chip");
 640  strcpy(card->shortname, "My Own Chip 123");
 641  sprintf(card->longname, "%s at 0x%lx irq %i",
 642          card->shortname, chip->ioport, chip->irq);
 643]]>
 644            </programlisting>
 645          </informalexample>
 646
 647          The driver field holds the minimal ID string of the
 648        chip. This is used by alsa-lib's configurator, so keep it
 649        simple but unique. 
 650          Even the same driver can have different driver IDs to
 651        distinguish the functionality of each chip type. 
 652        </para>
 653
 654        <para>
 655          The shortname field is a string shown as more verbose
 656        name. The longname field contains the information
 657        shown in <filename>/proc/asound/cards</filename>. 
 658        </para>
 659      </section>
 660
 661      <section id="basic-flow-constructor-create-other">
 662        <title>5) Create other components, such as mixer, MIDI, etc.</title>
 663        <para>
 664          Here you define the basic components such as
 665          <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
 666          mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
 667          MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
 668          and other interfaces.
 669          Also, if you want a <link linkend="proc-interface"><citetitle>proc
 670        file</citetitle></link>, define it here, too.
 671        </para>
 672      </section>
 673
 674      <section id="basic-flow-constructor-register-card">
 675        <title>6) Register the card instance.</title>
 676        <para>
 677          <informalexample>
 678            <programlisting>
 679<![CDATA[
 680  err = snd_card_register(card);
 681  if (err < 0) {
 682          snd_card_free(card);
 683          return err;
 684  }
 685]]>
 686            </programlisting>
 687          </informalexample>
 688        </para>
 689
 690        <para>
 691          Will be explained in the section <link
 692        linkend="card-management-registration"><citetitle>Management
 693        of Cards and Components</citetitle></link>, too. 
 694        </para>
 695      </section>
 696
 697      <section id="basic-flow-constructor-set-pci">
 698        <title>7) Set the PCI driver data and return zero.</title>
 699        <para>
 700          <informalexample>
 701            <programlisting>
 702<![CDATA[
 703        pci_set_drvdata(pci, card);
 704        dev++;
 705        return 0;
 706]]>
 707            </programlisting>
 708          </informalexample>
 709
 710          In the above, the card record is stored. This pointer is
 711        used in the remove callback and power-management
 712        callbacks, too. 
 713        </para>
 714      </section>
 715    </section>
 716
 717    <section id="basic-flow-destructor">
 718      <title>Destructor</title>
 719      <para>
 720        The destructor, remove callback, simply releases the card
 721      instance. Then the ALSA middle layer will release all the
 722      attached components automatically. 
 723      </para>
 724
 725      <para>
 726        It would be typically like the following:
 727
 728        <informalexample>
 729          <programlisting>
 730<![CDATA[
 731  static void __devexit snd_mychip_remove(struct pci_dev *pci)
 732  {
 733          snd_card_free(pci_get_drvdata(pci));
 734          pci_set_drvdata(pci, NULL);
 735  }
 736]]>
 737          </programlisting>
 738        </informalexample>
 739
 740        The above code assumes that the card pointer is set to the PCI
 741        driver data.
 742      </para>
 743    </section>
 744
 745    <section id="basic-flow-header-files">
 746      <title>Header Files</title>
 747      <para>
 748        For the above example, at least the following include files
 749      are necessary. 
 750
 751        <informalexample>
 752          <programlisting>
 753<![CDATA[
 754  #include <linux/init.h>
 755  #include <linux/pci.h>
 756  #include <linux/slab.h>
 757  #include <sound/core.h>
 758  #include <sound/initval.h>
 759]]>
 760          </programlisting>
 761        </informalexample>
 762
 763        where the last one is necessary only when module options are
 764      defined in the source file.  If the code is split into several
 765      files, the files without module options don't need them.
 766      </para>
 767
 768      <para>
 769        In addition to these headers, you'll need
 770      <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
 771      handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
 772      access. If you use the <function>mdelay()</function> or
 773      <function>udelay()</function> functions, you'll need to include
 774      <filename>&lt;linux/delay.h&gt;</filename> too. 
 775      </para>
 776
 777      <para>
 778      The ALSA interfaces like the PCM and control APIs are defined in other
 779      <filename>&lt;sound/xxx.h&gt;</filename> header files.
 780      They have to be included after
 781      <filename>&lt;sound/core.h&gt;</filename>.
 782      </para>
 783
 784    </section>
 785  </chapter>
 786
 787
 788<!-- ****************************************************** -->
 789<!-- Management of Cards and Components  -->
 790<!-- ****************************************************** -->
 791  <chapter id="card-management">
 792    <title>Management of Cards and Components</title>
 793
 794    <section id="card-management-card-instance">
 795      <title>Card Instance</title>
 796      <para>
 797      For each soundcard, a <quote>card</quote> record must be allocated.
 798      </para>
 799
 800      <para>
 801      A card record is the headquarters of the soundcard.  It manages
 802      the whole list of devices (components) on the soundcard, such as
 803      PCM, mixers, MIDI, synthesizer, and so on.  Also, the card
 804      record holds the ID and the name strings of the card, manages
 805      the root of proc files, and controls the power-management states
 806      and hotplug disconnections.  The component list on the card
 807      record is used to manage the correct release of resources at
 808      destruction. 
 809      </para>
 810
 811      <para>
 812        As mentioned above, to create a card instance, call
 813      <function>snd_card_create()</function>.
 814
 815        <informalexample>
 816          <programlisting>
 817<![CDATA[
 818  struct snd_card *card;
 819  int err;
 820  err = snd_card_create(index, id, module, extra_size, &card);
 821]]>
 822          </programlisting>
 823        </informalexample>
 824      </para>
 825
 826      <para>
 827        The function takes five arguments, the card-index number, the
 828        id string, the module pointer (usually
 829        <constant>THIS_MODULE</constant>),
 830        the size of extra-data space, and the pointer to return the
 831        card instance.  The extra_size argument is used to
 832        allocate card-&gt;private_data for the
 833        chip-specific data.  Note that these data
 834        are allocated by <function>snd_card_create()</function>.
 835      </para>
 836    </section>
 837
 838    <section id="card-management-component">
 839      <title>Components</title>
 840      <para>
 841        After the card is created, you can attach the components
 842      (devices) to the card instance. In an ALSA driver, a component is
 843      represented as a struct <structname>snd_device</structname> object.
 844      A component can be a PCM instance, a control interface, a raw
 845      MIDI interface, etc.  Each such instance has one component
 846      entry.
 847      </para>
 848
 849      <para>
 850        A component can be created via
 851        <function>snd_device_new()</function> function. 
 852
 853        <informalexample>
 854          <programlisting>
 855<![CDATA[
 856  snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
 857]]>
 858          </programlisting>
 859        </informalexample>
 860      </para>
 861
 862      <para>
 863        This takes the card pointer, the device-level
 864      (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
 865      callback pointers (<parameter>&amp;ops</parameter>). The
 866      device-level defines the type of components and the order of
 867      registration and de-registration.  For most components, the
 868      device-level is already defined.  For a user-defined component,
 869      you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
 870      </para>
 871
 872      <para>
 873      This function itself doesn't allocate the data space. The data
 874      must be allocated manually beforehand, and its pointer is passed
 875      as the argument. This pointer is used as the
 876      (<parameter>chip</parameter> identifier in the above example)
 877      for the instance. 
 878      </para>
 879
 880      <para>
 881        Each pre-defined ALSA component such as ac97 and pcm calls
 882      <function>snd_device_new()</function> inside its
 883      constructor. The destructor for each component is defined in the
 884      callback pointers.  Hence, you don't need to take care of
 885      calling a destructor for such a component.
 886      </para>
 887
 888      <para>
 889        If you wish to create your own component, you need to
 890      set the destructor function to the dev_free callback in
 891      the <parameter>ops</parameter>, so that it can be released
 892      automatically via <function>snd_card_free()</function>.
 893      The next example will show an implementation of chip-specific
 894      data.
 895      </para>
 896    </section>
 897
 898    <section id="card-management-chip-specific">
 899      <title>Chip-Specific Data</title>
 900      <para>
 901      Chip-specific information, e.g. the I/O port address, its
 902      resource pointer, or the irq number, is stored in the
 903      chip-specific record.
 904
 905        <informalexample>
 906          <programlisting>
 907<![CDATA[
 908  struct mychip {
 909          ....
 910  };
 911]]>
 912          </programlisting>
 913        </informalexample>
 914      </para>
 915
 916      <para>
 917        In general, there are two ways of allocating the chip record.
 918      </para>
 919
 920      <section id="card-management-chip-specific-snd-card-new">
 921        <title>1. Allocating via <function>snd_card_create()</function>.</title>
 922        <para>
 923          As mentioned above, you can pass the extra-data-length
 924          to the 4th argument of <function>snd_card_create()</function>, i.e.
 925
 926          <informalexample>
 927            <programlisting>
 928<![CDATA[
 929  err = snd_card_create(index[dev], id[dev], THIS_MODULE,
 930                        sizeof(struct mychip), &card);
 931]]>
 932            </programlisting>
 933          </informalexample>
 934
 935          struct <structname>mychip</structname> is the type of the chip record.
 936        </para>
 937
 938        <para>
 939          In return, the allocated record can be accessed as
 940
 941          <informalexample>
 942            <programlisting>
 943<![CDATA[
 944  struct mychip *chip = card->private_data;
 945]]>
 946            </programlisting>
 947          </informalexample>
 948
 949          With this method, you don't have to allocate twice.
 950          The record is released together with the card instance.
 951        </para>
 952      </section>
 953
 954      <section id="card-management-chip-specific-allocate-extra">
 955        <title>2. Allocating an extra device.</title>
 956
 957        <para>
 958          After allocating a card instance via
 959          <function>snd_card_create()</function> (with
 960          <constant>0</constant> on the 4th arg), call
 961          <function>kzalloc()</function>. 
 962
 963          <informalexample>
 964            <programlisting>
 965<![CDATA[
 966  struct snd_card *card;
 967  struct mychip *chip;
 968  err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
 969  .....
 970  chip = kzalloc(sizeof(*chip), GFP_KERNEL);
 971]]>
 972            </programlisting>
 973          </informalexample>
 974        </para>
 975
 976        <para>
 977          The chip record should have the field to hold the card
 978          pointer at least, 
 979
 980          <informalexample>
 981            <programlisting>
 982<![CDATA[
 983  struct mychip {
 984          struct snd_card *card;
 985          ....
 986  };
 987]]>
 988            </programlisting>
 989          </informalexample>
 990        </para>
 991
 992        <para>
 993          Then, set the card pointer in the returned chip instance.
 994
 995          <informalexample>
 996            <programlisting>
 997<![CDATA[
 998  chip->card = card;
 999]]>
1000            </programlisting>
1001          </informalexample>
1002        </para>
1003
1004        <para>
1005          Next, initialize the fields, and register this chip
1006          record as a low-level device with a specified
1007          <parameter>ops</parameter>, 
1008
1009          <informalexample>
1010            <programlisting>
1011<![CDATA[
1012  static struct snd_device_ops ops = {
1013          .dev_free =        snd_mychip_dev_free,
1014  };
1015  ....
1016  snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1017]]>
1018            </programlisting>
1019          </informalexample>
1020
1021          <function>snd_mychip_dev_free()</function> is the
1022        device-destructor function, which will call the real
1023        destructor. 
1024        </para>
1025
1026        <para>
1027          <informalexample>
1028            <programlisting>
1029<![CDATA[
1030  static int snd_mychip_dev_free(struct snd_device *device)
1031  {
1032          return snd_mychip_free(device->device_data);
1033  }
1034]]>
1035            </programlisting>
1036          </informalexample>
1037
1038          where <function>snd_mychip_free()</function> is the real destructor.
1039        </para>
1040      </section>
1041    </section>
1042
1043    <section id="card-management-registration">
1044      <title>Registration and Release</title>
1045      <para>
1046        After all components are assigned, register the card instance
1047      by calling <function>snd_card_register()</function>. Access
1048      to the device files is enabled at this point. That is, before
1049      <function>snd_card_register()</function> is called, the
1050      components are safely inaccessible from external side. If this
1051      call fails, exit the probe function after releasing the card via
1052      <function>snd_card_free()</function>. 
1053      </para>
1054
1055      <para>
1056        For releasing the card instance, you can call simply
1057      <function>snd_card_free()</function>. As mentioned earlier, all
1058      components are released automatically by this call. 
1059      </para>
1060
1061      <para>
1062        As further notes, the destructors (both
1063      <function>snd_mychip_dev_free</function> and
1064      <function>snd_mychip_free</function>) cannot be defined with
1065      the <parameter>__devexit</parameter> prefix, because they may be
1066      called from the constructor, too, at the false path. 
1067      </para>
1068
1069      <para>
1070      For a device which allows hotplugging, you can use
1071      <function>snd_card_free_when_closed</function>.  This one will
1072      postpone the destruction until all devices are closed.
1073      </para>
1074
1075    </section>
1076
1077  </chapter>
1078
1079
1080<!-- ****************************************************** -->
1081<!-- PCI Resource Management  -->
1082<!-- ****************************************************** -->
1083  <chapter id="pci-resource">
1084    <title>PCI Resource Management</title>
1085
1086    <section id="pci-resource-example">
1087      <title>Full Code Example</title>
1088      <para>
1089        In this section, we'll complete the chip-specific constructor,
1090      destructor and PCI entries. Example code is shown first,
1091      below. 
1092
1093        <example>
1094          <title>PCI Resource Management Example</title>
1095          <programlisting>
1096<![CDATA[
1097  struct mychip {
1098          struct snd_card *card;
1099          struct pci_dev *pci;
1100
1101          unsigned long port;
1102          int irq;
1103  };
1104
1105  static int snd_mychip_free(struct mychip *chip)
1106  {
1107          /* disable hardware here if any */
1108          .... /* (not implemented in this document) */
1109
1110          /* release the irq */
1111          if (chip->irq >= 0)
1112                  free_irq(chip->irq, chip);
1113          /* release the I/O ports & memory */
1114          pci_release_regions(chip->pci);
1115          /* disable the PCI entry */
1116          pci_disable_device(chip->pci);
1117          /* release the data */
1118          kfree(chip);
1119          return 0;
1120  }
1121
1122  /* chip-specific constructor */
1123  static int __devinit snd_mychip_create(struct snd_card *card,
1124                                         struct pci_dev *pci,
1125                                         struct mychip **rchip)
1126  {
1127          struct mychip *chip;
1128          int err;
1129          static struct snd_device_ops ops = {
1130                 .dev_free = snd_mychip_dev_free,
1131          };
1132
1133          *rchip = NULL;
1134
1135          /* initialize the PCI entry */
1136          err = pci_enable_device(pci);
1137          if (err < 0)
1138                  return err;
1139          /* check PCI availability (28bit DMA) */
1140          if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1141              pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1142                  printk(KERN_ERR "error to set 28bit mask DMA\n");
1143                  pci_disable_device(pci);
1144                  return -ENXIO;
1145          }
1146
1147          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
1148          if (chip == NULL) {
1149                  pci_disable_device(pci);
1150                  return -ENOMEM;
1151          }
1152
1153          /* initialize the stuff */
1154          chip->card = card;
1155          chip->pci = pci;
1156          chip->irq = -1;
1157
1158          /* (1) PCI resource allocation */
1159          err = pci_request_regions(pci, "My Chip");
1160          if (err < 0) {
1161                  kfree(chip);
1162                  pci_disable_device(pci);
1163                  return err;
1164          }
1165          chip->port = pci_resource_start(pci, 0);
1166          if (request_irq(pci->irq, snd_mychip_interrupt,
1167                          IRQF_SHARED, KBUILD_MODNAME, chip)) {
1168                  printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1169                  snd_mychip_free(chip);
1170                  return -EBUSY;
1171          }
1172          chip->irq = pci->irq;
1173
1174          /* (2) initialization of the chip hardware */
1175          .... /*   (not implemented in this document) */
1176
1177          err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
1178          if (err < 0) {
1179                  snd_mychip_free(chip);
1180                  return err;
1181          }
1182
1183          snd_card_set_dev(card, &pci->dev);
1184
1185          *rchip = chip;
1186          return 0;
1187  }        
1188
1189  /* PCI IDs */
1190  static struct pci_device_id snd_mychip_ids[] = {
1191          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1192            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1193          ....
1194          { 0, }
1195  };
1196  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1197
1198  /* pci_driver definition */
1199  static struct pci_driver driver = {
1200          .name = KBUILD_MODNAME,
1201          .id_table = snd_mychip_ids,
1202          .probe = snd_mychip_probe,
1203          .remove = __devexit_p(snd_mychip_remove),
1204  };
1205
1206  /* module initialization */
1207  static int __init alsa_card_mychip_init(void)
1208  {
1209          return pci_register_driver(&driver);
1210  }
1211
1212  /* module clean up */
1213  static void __exit alsa_card_mychip_exit(void)
1214  {
1215          pci_unregister_driver(&driver);
1216  }
1217
1218  module_init(alsa_card_mychip_init)
1219  module_exit(alsa_card_mychip_exit)
1220
1221  EXPORT_NO_SYMBOLS; /* for old kernels only */
1222]]>
1223          </programlisting>
1224        </example>
1225      </para>
1226    </section>
1227
1228    <section id="pci-resource-some-haftas">
1229      <title>Some Hafta's</title>
1230      <para>
1231        The allocation of PCI resources is done in the
1232      <function>probe()</function> function, and usually an extra
1233      <function>xxx_create()</function> function is written for this
1234      purpose.
1235      </para>
1236
1237      <para>
1238        In the case of PCI devices, you first have to call
1239      the <function>pci_enable_device()</function> function before
1240      allocating resources. Also, you need to set the proper PCI DMA
1241      mask to limit the accessed I/O range. In some cases, you might
1242      need to call <function>pci_set_master()</function> function,
1243      too.
1244      </para>
1245
1246      <para>
1247        Suppose the 28bit mask, and the code to be added would be like:
1248
1249        <informalexample>
1250          <programlisting>
1251<![CDATA[
1252  err = pci_enable_device(pci);
1253  if (err < 0)
1254          return err;
1255  if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
1256      pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
1257          printk(KERN_ERR "error to set 28bit mask DMA\n");
1258          pci_disable_device(pci);
1259          return -ENXIO;
1260  }
1261  
1262]]>
1263          </programlisting>
1264        </informalexample>
1265      </para>
1266    </section>
1267
1268    <section id="pci-resource-resource-allocation">
1269      <title>Resource Allocation</title>
1270      <para>
1271        The allocation of I/O ports and irqs is done via standard kernel
1272      functions. Unlike ALSA ver.0.5.x., there are no helpers for
1273      that. And these resources must be released in the destructor
1274      function (see below). Also, on ALSA 0.9.x, you don't need to
1275      allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
1276      </para>
1277
1278      <para>
1279        Now assume that the PCI device has an I/O port with 8 bytes
1280        and an interrupt. Then struct <structname>mychip</structname> will have the
1281        following fields:
1282
1283        <informalexample>
1284          <programlisting>
1285<![CDATA[
1286  struct mychip {
1287          struct snd_card *card;
1288
1289          unsigned long port;
1290          int irq;
1291  };
1292]]>
1293          </programlisting>
1294        </informalexample>
1295      </para>
1296
1297      <para>
1298        For an I/O port (and also a memory region), you need to have
1299      the resource pointer for the standard resource management. For
1300      an irq, you have to keep only the irq number (integer). But you
1301      need to initialize this number as -1 before actual allocation,
1302      since irq 0 is valid. The port address and its resource pointer
1303      can be initialized as null by
1304      <function>kzalloc()</function> automatically, so you
1305      don't have to take care of resetting them. 
1306      </para>
1307
1308      <para>
1309        The allocation of an I/O port is done like this:
1310
1311        <informalexample>
1312          <programlisting>
1313<![CDATA[
1314  err = pci_request_regions(pci, "My Chip");
1315  if (err < 0) { 
1316          kfree(chip);
1317          pci_disable_device(pci);
1318          return err;
1319  }
1320  chip->port = pci_resource_start(pci, 0);
1321]]>
1322          </programlisting>
1323        </informalexample>
1324      </para>
1325
1326      <para>
1327        <!-- obsolete -->
1328        It will reserve the I/O port region of 8 bytes of the given
1329      PCI device. The returned value, chip-&gt;res_port, is allocated
1330      via <function>kmalloc()</function> by
1331      <function>request_region()</function>. The pointer must be
1332      released via <function>kfree()</function>, but there is a
1333      problem with this. This issue will be explained later.
1334      </para>
1335
1336      <para>
1337        The allocation of an interrupt source is done like this:
1338
1339        <informalexample>
1340          <programlisting>
1341<![CDATA[
1342  if (request_irq(pci->irq, snd_mychip_interrupt,
1343                  IRQF_SHARED, KBUILD_MODNAME, chip)) {
1344          printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
1345          snd_mychip_free(chip);
1346          return -EBUSY;
1347  }
1348  chip->irq = pci->irq;
1349]]>
1350          </programlisting>
1351        </informalexample>
1352
1353        where <function>snd_mychip_interrupt()</function> is the
1354      interrupt handler defined <link
1355      linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
1356      Note that chip-&gt;irq should be defined
1357      only when <function>request_irq()</function> succeeded.
1358      </para>
1359
1360      <para>
1361      On the PCI bus, interrupts can be shared. Thus,
1362      <constant>IRQF_SHARED</constant> is used as the interrupt flag of
1363      <function>request_irq()</function>. 
1364      </para>
1365
1366      <para>
1367        The last argument of <function>request_irq()</function> is the
1368      data pointer passed to the interrupt handler. Usually, the
1369      chip-specific record is used for that, but you can use what you
1370      like, too. 
1371      </para>
1372
1373      <para>
1374        I won't give details about the interrupt handler at this
1375        point, but at least its appearance can be explained now. The
1376        interrupt handler looks usually like the following: 
1377
1378        <informalexample>
1379          <programlisting>
1380<![CDATA[
1381  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
1382  {
1383          struct mychip *chip = dev_id;
1384          ....
1385          return IRQ_HANDLED;
1386  }
1387]]>
1388          </programlisting>
1389        </informalexample>
1390      </para>
1391
1392      <para>
1393        Now let's write the corresponding destructor for the resources
1394      above. The role of destructor is simple: disable the hardware
1395      (if already activated) and release the resources. So far, we
1396      have no hardware part, so the disabling code is not written here. 
1397      </para>
1398
1399      <para>
1400        To release the resources, the <quote>check-and-release</quote>
1401        method is a safer way. For the interrupt, do like this: 
1402
1403        <informalexample>
1404          <programlisting>
1405<![CDATA[
1406  if (chip->irq >= 0)
1407          free_irq(chip->irq, chip);
1408]]>
1409          </programlisting>
1410        </informalexample>
1411
1412        Since the irq number can start from 0, you should initialize
1413        chip-&gt;irq with a negative value (e.g. -1), so that you can
1414        check the validity of the irq number as above.
1415      </para>
1416
1417      <para>
1418        When you requested I/O ports or memory regions via
1419        <function>pci_request_region()</function> or
1420        <function>pci_request_regions()</function> like in this example,
1421        release the resource(s) using the corresponding function,
1422        <function>pci_release_region()</function> or
1423        <function>pci_release_regions()</function>.
1424
1425        <informalexample>
1426          <programlisting>
1427<![CDATA[
1428  pci_release_regions(chip->pci);
1429]]>
1430          </programlisting>
1431        </informalexample>
1432      </para>
1433
1434      <para>
1435        When you requested manually via <function>request_region()</function>
1436        or <function>request_mem_region</function>, you can release it via
1437        <function>release_resource()</function>.  Suppose that you keep
1438        the resource pointer returned from <function>request_region()</function>
1439        in chip-&gt;res_port, the release procedure looks like:
1440
1441        <informalexample>
1442          <programlisting>
1443<![CDATA[
1444  release_and_free_resource(chip->res_port);
1445]]>
1446          </programlisting>
1447        </informalexample>
1448      </para>
1449
1450      <para>
1451      Don't forget to call <function>pci_disable_device()</function>
1452      before the end.
1453      </para>
1454
1455      <para>
1456        And finally, release the chip-specific record.
1457
1458        <informalexample>
1459          <programlisting>
1460<![CDATA[
1461  kfree(chip);
1462]]>
1463          </programlisting>
1464        </informalexample>
1465      </para>
1466
1467      <para>
1468      Again, remember that you cannot
1469      use the <parameter>__devexit</parameter> prefix for this destructor. 
1470      </para>
1471
1472      <para>
1473      We didn't implement the hardware disabling part in the above.
1474      If you need to do this, please note that the destructor may be
1475      called even before the initialization of the chip is completed.
1476      It would be better to have a flag to skip hardware disabling
1477      if the hardware was not initialized yet.
1478      </para>
1479
1480      <para>
1481      When the chip-data is assigned to the card using
1482      <function>snd_device_new()</function> with
1483      <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is 
1484      called at the last.  That is, it is assured that all other
1485      components like PCMs and controls have already been released.
1486      You don't have to stop PCMs, etc. explicitly, but just
1487      call low-level hardware stopping.
1488      </para>
1489
1490      <para>
1491        The management of a memory-mapped region is almost as same as
1492        the management of an I/O port. You'll need three fields like
1493        the following: 
1494
1495        <informalexample>
1496          <programlisting>
1497<![CDATA[
1498  struct mychip {
1499          ....
1500          unsigned long iobase_phys;
1501          void __iomem *iobase_virt;
1502  };
1503]]>
1504          </programlisting>
1505        </informalexample>
1506
1507        and the allocation would be like below:
1508
1509        <informalexample>
1510          <programlisting>
1511<![CDATA[
1512  if ((err = pci_request_regions(pci, "My Chip")) < 0) {
1513          kfree(chip);
1514          return err;
1515  }
1516  chip->iobase_phys = pci_resource_start(pci, 0);
1517  chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1518                                      pci_resource_len(pci, 0));
1519]]>
1520          </programlisting>
1521        </informalexample>
1522        
1523        and the corresponding destructor would be:
1524
1525        <informalexample>
1526          <programlisting>
1527<![CDATA[
1528  static int snd_mychip_free(struct mychip *chip)
1529  {
1530          ....
1531          if (chip->iobase_virt)
1532                  iounmap(chip->iobase_virt);
1533          ....
1534          pci_release_regions(chip->pci);
1535          ....
1536  }
1537]]>
1538          </programlisting>
1539        </informalexample>
1540      </para>
1541
1542    </section>
1543
1544    <section id="pci-resource-device-struct">
1545      <title>Registration of Device Struct</title>
1546      <para>
1547        At some point, typically after calling <function>snd_device_new()</function>,
1548        you need to register the struct <structname>device</structname> of the chip
1549        you're handling for udev and co.  ALSA provides a macro for compatibility with
1550        older kernels.  Simply call like the following:
1551        <informalexample>
1552          <programlisting>
1553<![CDATA[
1554  snd_card_set_dev(card, &pci->dev);
1555]]>
1556          </programlisting>
1557        </informalexample>
1558        so that it stores the PCI's device pointer to the card.  This will be
1559        referred by ALSA core functions later when the devices are registered.
1560      </para>
1561      <para>
1562        In the case of non-PCI, pass the proper device struct pointer of the BUS
1563        instead.  (In the case of legacy ISA without PnP, you don't have to do
1564        anything.)
1565      </para>
1566    </section>
1567
1568    <section id="pci-resource-entries">
1569      <title>PCI Entries</title>
1570      <para>
1571        So far, so good. Let's finish the missing PCI
1572      stuff. At first, we need a
1573      <structname>pci_device_id</structname> table for this
1574      chipset. It's a table of PCI vendor/device ID number, and some
1575      masks. 
1576      </para>
1577
1578      <para>
1579        For example,
1580
1581        <informalexample>
1582          <programlisting>
1583<![CDATA[
1584  static struct pci_device_id snd_mychip_ids[] = {
1585          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1586            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1587          ....
1588          { 0, }
1589  };
1590  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1591]]>
1592          </programlisting>
1593        </informalexample>
1594      </para>
1595
1596      <para>
1597        The first and second fields of
1598      the <structname>pci_device_id</structname> structure are the vendor and
1599      device IDs. If you have no reason to filter the matching
1600      devices, you can leave the remaining fields as above. The last
1601      field of the <structname>pci_device_id</structname> struct contains
1602      private data for this entry. You can specify any value here, for
1603      example, to define specific operations for supported device IDs.
1604      Such an example is found in the intel8x0 driver. 
1605      </para>
1606
1607      <para>
1608        The last entry of this list is the terminator. You must
1609      specify this all-zero entry. 
1610      </para>
1611
1612      <para>
1613        Then, prepare the <structname>pci_driver</structname> record:
1614
1615        <informalexample>
1616          <programlisting>
1617<![CDATA[
1618  static struct pci_driver driver = {
1619          .name = KBUILD_MODNAME,
1620          .id_table = snd_mychip_ids,
1621          .probe = snd_mychip_probe,
1622          .remove = __devexit_p(snd_mychip_remove),
1623  };
1624]]>
1625          </programlisting>
1626        </informalexample>
1627      </para>
1628
1629      <para>
1630        The <structfield>probe</structfield> and
1631      <structfield>remove</structfield> functions have already
1632      been defined in the previous sections.
1633      The <structfield>remove</structfield> function should
1634      be defined with the 
1635      <function>__devexit_p()</function> macro, so that it's not
1636      defined for built-in (and non-hot-pluggable) case. The
1637      <structfield>name</structfield> 
1638      field is the name string of this device. Note that you must not
1639      use a slash <quote>/</quote> in this string. 
1640      </para>
1641
1642      <para>
1643        And at last, the module entries:
1644
1645        <informalexample>
1646          <programlisting>
1647<![CDATA[
1648  static int __init alsa_card_mychip_init(void)
1649  {
1650          return pci_register_driver(&driver);
1651  }
1652
1653  static void __exit alsa_card_mychip_exit(void)
1654  {
1655          pci_unregister_driver(&driver);
1656  }
1657
1658  module_init(alsa_card_mychip_init)
1659  module_exit(alsa_card_mychip_exit)
1660]]>
1661          </programlisting>
1662        </informalexample>
1663      </para>
1664
1665      <para>
1666        Note that these module entries are tagged with
1667      <parameter>__init</parameter> and 
1668      <parameter>__exit</parameter> prefixes, not
1669      <parameter>__devinit</parameter> nor
1670      <parameter>__devexit</parameter>.
1671      </para>
1672
1673      <para>
1674        Oh, one thing was forgotten. If you have no exported symbols,
1675        you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
1676
1677        <informalexample>
1678          <programlisting>
1679<![CDATA[
1680  EXPORT_NO_SYMBOLS;
1681]]>
1682          </programlisting>
1683        </informalexample>
1684
1685        That's all!
1686      </para>
1687    </section>
1688  </chapter>
1689
1690
1691<!-- ****************************************************** -->
1692<!-- PCM Interface  -->
1693<!-- ****************************************************** -->
1694  <chapter id="pcm-interface">
1695    <title>PCM Interface</title>
1696
1697    <section id="pcm-interface-general">
1698      <title>General</title>
1699      <para>
1700        The PCM middle layer of ALSA is quite powerful and it is only
1701      necessary for each driver to implement the low-level functions
1702      to access its hardware.
1703      </para>
1704
1705      <para>
1706        For accessing to the PCM layer, you need to include
1707      <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
1708      <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
1709      if you access to some functions related with hw_param. 
1710      </para>
1711
1712      <para>
1713        Each card device can have up to four pcm instances. A pcm
1714      instance corresponds to a pcm device file. The limitation of
1715      number of instances comes only from the available bit size of
1716      the Linux's device numbers. Once when 64bit device number is
1717      used, we'll have more pcm instances available. 
1718      </para>
1719
1720      <para>
1721        A pcm instance consists of pcm playback and capture streams,
1722      and each pcm stream consists of one or more pcm substreams. Some
1723      soundcards support multiple playback functions. For example,
1724      emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
1725      each open, a free substream is (usually) automatically chosen
1726      and opened. Meanwhile, when only one substream exists and it was
1727      already opened, the successful open will either block
1728      or error with <constant>EAGAIN</constant> according to the
1729      file open mode. But you don't have to care about such details in your
1730      driver. The PCM middle layer will take care of such work.
1731      </para>
1732    </section>
1733
1734    <section id="pcm-interface-example">
1735      <title>Full Code Example</title>
1736      <para>
1737      The example code below does not include any hardware access
1738      routines but shows only the skeleton, how to build up the PCM
1739      interfaces.
1740
1741        <example>
1742          <title>PCM Example Code</title>
1743          <programlisting>
1744<![CDATA[
1745  #include <sound/pcm.h>
1746  ....
1747
1748  /* hardware definition */
1749  static struct snd_pcm_hardware snd_mychip_playback_hw = {
1750          .info = (SNDRV_PCM_INFO_MMAP |
1751                   SNDRV_PCM_INFO_INTERLEAVED |
1752                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
1753                   SNDRV_PCM_INFO_MMAP_VALID),
1754          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1755          .rates =            SNDRV_PCM_RATE_8000_48000,
1756          .rate_min =         8000,
1757          .rate_max =         48000,
1758          .channels_min =     2,
1759          .channels_max =     2,
1760          .buffer_bytes_max = 32768,
1761          .period_bytes_min = 4096,
1762          .period_bytes_max = 32768,
1763          .periods_min =      1,
1764          .periods_max =      1024,
1765  };
1766
1767  /* hardware definition */
1768  static struct snd_pcm_hardware snd_mychip_capture_hw = {
1769          .info = (SNDRV_PCM_INFO_MMAP |
1770                   SNDRV_PCM_INFO_INTERLEAVED |
1771                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
1772                   SNDRV_PCM_INFO_MMAP_VALID),
1773          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1774          .rates =            SNDRV_PCM_RATE_8000_48000,
1775          .rate_min =         8000,
1776          .rate_max =         48000,
1777          .channels_min =     2,
1778          .channels_max =     2,
1779          .buffer_bytes_max = 32768,
1780          .period_bytes_min = 4096,
1781          .period_bytes_max = 32768,
1782          .periods_min =      1,
1783          .periods_max =      1024,
1784  };
1785
1786  /* open callback */
1787  static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1788  {
1789          struct mychip *chip = snd_pcm_substream_chip(substream);
1790          struct snd_pcm_runtime *runtime = substream->runtime;
1791
1792          runtime->hw = snd_mychip_playback_hw;
1793          /* more hardware-initialization will be done here */
1794          ....
1795          return 0;
1796  }
1797
1798  /* close callback */
1799  static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1800  {
1801          struct mychip *chip = snd_pcm_substream_chip(substream);
1802          /* the hardware-specific codes will be here */
1803          ....
1804          return 0;
1805
1806  }
1807
1808  /* open callback */
1809  static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1810  {
1811          struct mychip *chip = snd_pcm_substream_chip(substream);
1812          struct snd_pcm_runtime *runtime = substream->runtime;
1813
1814          runtime->hw = snd_mychip_capture_hw;
1815          /* more hardware-initialization will be done here */
1816          ....
1817          return 0;
1818  }
1819
1820  /* close callback */
1821  static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1822  {
1823          struct mychip *chip = snd_pcm_substream_chip(substream);
1824          /* the hardware-specific codes will be here */
1825          ....
1826          return 0;
1827
1828  }
1829
1830  /* hw_params callback */
1831  static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1832                               struct snd_pcm_hw_params *hw_params)
1833  {
1834          return snd_pcm_lib_malloc_pages(substream,
1835                                     params_buffer_bytes(hw_params));
1836  }
1837
1838  /* hw_free callback */
1839  static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1840  {
1841          return snd_pcm_lib_free_pages(substream);
1842  }
1843
1844  /* prepare callback */
1845  static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1846  {
1847          struct mychip *chip = snd_pcm_substream_chip(substream);
1848          struct snd_pcm_runtime *runtime = substream->runtime;
1849
1850          /* set up the hardware with the current configuration
1851           * for example...
1852           */
1853          mychip_set_sample_format(chip, runtime->format);
1854          mychip_set_sample_rate(chip, runtime->rate);
1855          mychip_set_channels(chip, runtime->channels);
1856          mychip_set_dma_setup(chip, runtime->dma_addr,
1857                               chip->buffer_size,
1858                               chip->period_size);
1859          return 0;
1860  }
1861
1862  /* trigger callback */
1863  static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1864                                    int cmd)
1865  {
1866          switch (cmd) {
1867          case SNDRV_PCM_TRIGGER_START:
1868                  /* do something to start the PCM engine */
1869                  ....
1870                  break;
1871          case SNDRV_PCM_TRIGGER_STOP:
1872                  /* do something to stop the PCM engine */
1873                  ....
1874                  break;
1875          default:
1876                  return -EINVAL;
1877          }
1878  }
1879
1880  /* pointer callback */
1881  static snd_pcm_uframes_t
1882  snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1883  {
1884          struct mychip *chip = snd_pcm_substream_chip(substream);
1885          unsigned int current_ptr;
1886
1887          /* get the current hardware pointer */
1888          current_ptr = mychip_get_hw_pointer(chip);
1889          return current_ptr;
1890  }
1891
1892  /* operators */
1893  static struct snd_pcm_ops snd_mychip_playback_ops = {
1894          .open =        snd_mychip_playback_open,
1895          .close =       snd_mychip_playback_close,
1896          .ioctl =       snd_pcm_lib_ioctl,
1897          .hw_params =   snd_mychip_pcm_hw_params,
1898          .hw_free =     snd_mychip_pcm_hw_free,
1899          .prepare =     snd_mychip_pcm_prepare,
1900          .trigger =     snd_mychip_pcm_trigger,
1901          .pointer =     snd_mychip_pcm_pointer,
1902  };
1903
1904  /* operators */
1905  static struct snd_pcm_ops snd_mychip_capture_ops = {
1906          .open =        snd_mychip_capture_open,
1907          .close =       snd_mychip_capture_close,
1908          .ioctl =       snd_pcm_lib_ioctl,
1909          .hw_params =   snd_mychip_pcm_hw_params,
1910          .hw_free =     snd_mychip_pcm_hw_free,
1911          .prepare =     snd_mychip_pcm_prepare,
1912          .trigger =     snd_mychip_pcm_trigger,
1913          .pointer =     snd_mychip_pcm_pointer,
1914  };
1915
1916  /*
1917   *  definitions of capture are omitted here...
1918   */
1919
1920  /* create a pcm device */
1921  static int __devinit snd_mychip_new_pcm(struct mychip *chip)
1922  {
1923          struct snd_pcm *pcm;
1924          int err;
1925
1926          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1927          if (err < 0) 
1928                  return err;
1929          pcm->private_data = chip;
1930          strcpy(pcm->name, "My Chip");
1931          chip->pcm = pcm;
1932          /* set operators */
1933          snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1934                          &snd_mychip_playback_ops);
1935          snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1936                          &snd_mychip_capture_ops);
1937          /* pre-allocation of buffers */
1938          /* NOTE: this may fail */
1939          snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1940                                                snd_dma_pci_data(chip->pci),
1941                                                64*1024, 64*1024);
1942          return 0;
1943  }
1944]]>
1945          </programlisting>
1946        </example>
1947      </para>
1948    </section>
1949
1950    <section id="pcm-interface-constructor">
1951      <title>Constructor</title>
1952      <para>
1953        A pcm instance is allocated by the <function>snd_pcm_new()</function>
1954      function. It would be better to create a constructor for pcm,
1955      namely, 
1956
1957        <informalexample>
1958          <programlisting>
1959<![CDATA[
1960  static int __devinit snd_mychip_new_pcm(struct mychip *chip)
1961  {
1962          struct snd_pcm *pcm;
1963          int err;
1964
1965          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1966          if (err < 0) 
1967                  return err;
1968          pcm->private_data = chip;
1969          strcpy(pcm->name, "My Chip");
1970          chip->pcm = pcm;
1971          ....
1972          return 0;
1973  }
1974]]>
1975          </programlisting>
1976        </informalexample>
1977      </para>
1978
1979      <para>
1980        The <function>snd_pcm_new()</function> function takes four
1981      arguments. The first argument is the card pointer to which this
1982      pcm is assigned, and the second is the ID string. 
1983      </para>
1984
1985      <para>
1986        The third argument (<parameter>index</parameter>, 0 in the
1987      above) is the index of this new pcm. It begins from zero. If
1988      you create more than one pcm instances, specify the
1989      different numbers in this argument. For example,
1990      <parameter>index</parameter> = 1 for the second PCM device.  
1991      </para>
1992
1993      <para>
1994        The fourth and fifth arguments are the number of substreams
1995      for playback and capture, respectively. Here 1 is used for
1996      both arguments. When no playback or capture substreams are available,
1997      pass 0 to the corresponding argument.
1998      </para>
1999
2000      <para>
2001        If a chip supports multiple playbacks or captures, you can
2002      specify more numbers, but they must be handled properly in
2003      open/close, etc. callbacks.  When you need to know which
2004      substream you are referring to, then it can be obtained from
2005      struct <structname>snd_pcm_substream</structname> data passed to each callback
2006      as follows: 
2007
2008        <informalexample>
2009          <programlisting>
2010<![CDATA[
2011  struct snd_pcm_substream *substream;
2012  int index = substream->number;
2013]]>
2014          </programlisting>
2015        </informalexample>
2016      </para>
2017
2018      <para>
2019        After the pcm is created, you need to set operators for each
2020        pcm stream. 
2021
2022        <informalexample>
2023          <programlisting>
2024<![CDATA[
2025  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
2026                  &snd_mychip_playback_ops);
2027  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
2028                  &snd_mychip_capture_ops);
2029]]>
2030          </programlisting>
2031        </informalexample>
2032      </para>
2033
2034      <para>
2035        The operators are defined typically like this:
2036
2037        <informalexample>
2038          <programlisting>
2039<![CDATA[
2040  static struct snd_pcm_ops snd_mychip_playback_ops = {
2041          .open =        snd_mychip_pcm_open,
2042          .close =       snd_mychip_pcm_close,
2043          .ioctl =       snd_pcm_lib_ioctl,
2044          .hw_params =   snd_mychip_pcm_hw_params,
2045          .hw_free =     snd_mychip_pcm_hw_free,
2046          .prepare =     snd_mychip_pcm_prepare,
2047          .trigger =     snd_mychip_pcm_trigger,
2048          .pointer =     snd_mychip_pcm_pointer,
2049  };
2050]]>
2051          </programlisting>
2052        </informalexample>
2053
2054        All the callbacks are described in the
2055        <link linkend="pcm-interface-operators"><citetitle>
2056        Operators</citetitle></link> subsection.
2057      </para>
2058
2059      <para>
2060        After setting the operators, you probably will want to
2061        pre-allocate the buffer. For the pre-allocation, simply call
2062        the following: 
2063
2064        <informalexample>
2065          <programlisting>
2066<![CDATA[
2067  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
2068                                        snd_dma_pci_data(chip->pci),
2069                                        64*1024, 64*1024);
2070]]>
2071          </programlisting>
2072        </informalexample>
2073
2074        It will allocate a buffer up to 64kB as default.
2075      Buffer management details will be described in the later section <link
2076      linkend="buffer-and-memory"><citetitle>Buffer and Memory
2077      Management</citetitle></link>. 
2078      </para>
2079
2080      <para>
2081        Additionally, you can set some extra information for this pcm
2082        in pcm-&gt;info_flags.
2083        The available values are defined as
2084        <constant>SNDRV_PCM_INFO_XXX</constant> in
2085        <filename>&lt;sound/asound.h&gt;</filename>, which is used for
2086        the hardware definition (described later). When your soundchip
2087        supports only half-duplex, specify like this: 
2088
2089        <informalexample>
2090          <programlisting>
2091<![CDATA[
2092  pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
2093]]>
2094          </programlisting>
2095        </informalexample>
2096      </para>
2097    </section>
2098
2099    <section id="pcm-interface-destructor">
2100      <title>... And the Destructor?</title>
2101      <para>
2102        The destructor for a pcm instance is not always
2103      necessary. Since the pcm device will be released by the middle
2104      layer code automatically, you don't have to call the destructor
2105      explicitly.
2106      </para>
2107
2108      <para>
2109        The destructor would be necessary if you created
2110        special records internally and needed to release them. In such a
2111        case, set the destructor function to
2112        pcm-&gt;private_free: 
2113
2114        <example>
2115          <title>PCM Instance with a Destructor</title>
2116          <programlisting>
2117<![CDATA[
2118  static void mychip_pcm_free(struct snd_pcm *pcm)
2119  {
2120          struct mychip *chip = snd_pcm_chip(pcm);
2121          /* free your own data */
2122          kfree(chip->my_private_pcm_data);
2123          /* do what you like else */
2124          ....
2125  }
2126
2127  static int __devinit snd_mychip_new_pcm(struct mychip *chip)
2128  {
2129          struct snd_pcm *pcm;
2130          ....
2131          /* allocate your own data */
2132          chip->my_private_pcm_data = kmalloc(...);
2133          /* set the destructor */
2134          pcm->private_data = chip;
2135          pcm->private_free = mychip_pcm_free;
2136          ....
2137  }
2138]]>
2139          </programlisting>
2140        </example>
2141      </para>
2142    </section>
2143
2144    <section id="pcm-interface-runtime">
2145      <title>Runtime Pointer - The Chest of PCM Information</title>
2146        <para>
2147          When the PCM substream is opened, a PCM runtime instance is
2148        allocated and assigned to the substream. This pointer is
2149        accessible via <constant>substream-&gt;runtime</constant>.
2150        This runtime pointer holds most information you need
2151        to control the PCM: the copy of hw_params and sw_params configurations, the buffer
2152        pointers, mmap records, spinlocks, etc.
2153        </para>
2154
2155        <para>
2156        The definition of runtime instance is found in
2157        <filename>&lt;sound/pcm.h&gt;</filename>.  Here are
2158       the contents of this file:
2159          <informalexample>
2160            <programlisting>
2161<![CDATA[
2162struct _snd_pcm_runtime {
2163        /* -- Status -- */
2164        struct snd_pcm_substream *trigger_master;
2165        snd_timestamp_t trigger_tstamp; /* trigger timestamp */
2166        int overrange;
2167        snd_pcm_uframes_t avail_max;
2168        snd_pcm_uframes_t hw_ptr_base;  /* Position at buffer restart */
2169        snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
2170
2171        /* -- HW params -- */
2172        snd_pcm_access_t access;        /* access mode */
2173        snd_pcm_format_t format;        /* SNDRV_PCM_FORMAT_* */
2174        snd_pcm_subformat_t subformat;  /* subformat */
2175        unsigned int rate;              /* rate in Hz */
2176        unsigned int channels;          /* channels */
2177        snd_pcm_uframes_t period_size;  /* period size */
2178        unsigned int periods;           /* periods */
2179        snd_pcm_uframes_t buffer_size;  /* buffer size */
2180        unsigned int tick_time;         /* tick time */
2181        snd_pcm_uframes_t min_align;    /* Min alignment for the format */
2182        size_t byte_align;
2183        unsigned int frame_bits;
2184        unsigned int sample_bits;
2185        unsigned int info;
2186        unsigned int rate_num;
2187        unsigned int rate_den;
2188
2189        /* -- SW params -- */
2190        struct timespec tstamp_mode;    /* mmap timestamp is updated */
2191        unsigned int period_step;
2192        unsigned int sleep_min;         /* min ticks to sleep */
2193        snd_pcm_uframes_t start_threshold;
2194        snd_pcm_uframes_t stop_threshold;
2195        snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
2196                                                noise is nearest than this */
2197        snd_pcm_uframes_t silence_size; /* Silence filling size */
2198        snd_pcm_uframes_t boundary;     /* pointers wrap point */
2199
2200        snd_pcm_uframes_t silenced_start;
2201        snd_pcm_uframes_t silenced_size;
2202
2203        snd_pcm_sync_id_t sync;         /* hardware synchronization ID */
2204
2205        /* -- mmap -- */
2206        volatile struct snd_pcm_mmap_status *status;
2207        volatile struct snd_pcm_mmap_control *control;
2208        atomic_t mmap_count;
2209
2210        /* -- locking / scheduling -- */
2211        spinlock_t lock;
2212        wait_queue_head_t sleep;
2213        struct timer_list tick_timer;
2214        struct fasync_struct *fasync;
2215
2216        /* -- private section -- */
2217        void *private_data;
2218        void (*private_free)(struct snd_pcm_runtime *runtime);
2219
2220        /* -- hardware description -- */
2221        struct snd_pcm_hardware hw;
2222        struct snd_pcm_hw_constraints hw_constraints;
2223
2224        /* -- interrupt callbacks -- */
2225        void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
2226        void (*transfer_ack_end)(struct snd_pcm_substream *substream);
2227
2228        /* -- timer -- */
2229        unsigned int timer_resolution;  /* timer resolution */
2230
2231        /* -- DMA -- */           
2232        unsigned char *dma_area;        /* DMA area */
2233        dma_addr_t dma_addr;            /* physical bus address (not accessible from main CPU) */
2234        size_t dma_bytes;               /* size of DMA area */
2235
2236        struct snd_dma_buffer *dma_buffer_p;    /* allocated buffer */
2237
2238#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
2239        /* -- OSS things -- */
2240        struct snd_pcm_oss_runtime oss;
2241#endif
2242};
2243]]>
2244            </programlisting>
2245          </informalexample>
2246        </para>
2247
2248        <para>
2249          For the operators (callbacks) of each sound driver, most of
2250        these records are supposed to be read-only.  Only the PCM
2251        middle-layer changes / updates them.  The exceptions are
2252        the hardware description (hw), interrupt callbacks
2253        (transfer_ack_xxx), DMA buffer information, and the private
2254        data.  Besides, if you use the standard buffer allocation
2255        method via <function>snd_pcm_lib_malloc_pages()</function>,
2256        you don't need to set the DMA buffer information by yourself.
2257        </para>
2258
2259        <para>
2260        In the sections below, important records are explained.
2261        </para>
2262
2263        <section id="pcm-interface-runtime-hw">
2264        <title>Hardware Description</title>
2265        <para>
2266          The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
2267        contains the definitions of the fundamental hardware
2268        configuration.  Above all, you'll need to define this in
2269        <link linkend="pcm-interface-operators-open-callback"><citetitle>
2270        the open callback</citetitle></link>.
2271        Note that the runtime instance holds the copy of the
2272        descriptor, not the pointer to the existing descriptor.  That
2273        is, in the open callback, you can modify the copied descriptor
2274        (<constant>runtime-&gt;hw</constant>) as you need.  For example, if the maximum
2275        number of channels is 1 only on some chip models, you can
2276        still use the same hardware descriptor and change the
2277        channels_max later:
2278          <informalexample>
2279            <programlisting>
2280<![CDATA[
2281          struct snd_pcm_runtime *runtime = substream->runtime;
2282          ...
2283          runtime->hw = snd_mychip_playback_hw; /* common definition */
2284          if (chip->model == VERY_OLD_ONE)
2285                  runtime->hw.channels_max = 1;
2286]]>
2287            </programlisting>
2288          </informalexample>
2289        </para>
2290
2291        <para>
2292          Typically, you'll have a hardware descriptor as below:
2293          <informalexample>
2294            <programlisting>
2295<![CDATA[
2296  static struct snd_pcm_hardware snd_mychip_playback_hw = {
2297          .info = (SNDRV_PCM_INFO_MMAP |
2298                   SNDRV_PCM_INFO_INTERLEAVED |
2299                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
2300                   SNDRV_PCM_INFO_MMAP_VALID),
2301          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
2302          .rates =            SNDRV_PCM_RATE_8000_48000,
2303          .rate_min =         8000,
2304          .rate_max =         48000,
2305          .channels_min =     2,
2306          .channels_max =     2,
2307          .buffer_bytes_max = 32768,
2308          .period_bytes_min = 4096,
2309          .period_bytes_max = 32768,
2310          .periods_min =      1,
2311          .periods_max =      1024,
2312  };
2313]]>
2314            </programlisting>
2315          </informalexample>
2316        </para>
2317
2318        <para>
2319        <itemizedlist>
2320        <listitem><para>
2321          The <structfield>info</structfield> field contains the type and
2322        capabilities of this pcm. The bit flags are defined in
2323        <filename>&lt;sound/asound.h&gt;</filename> as
2324        <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
2325        have to specify whether the mmap is supported and which
2326        interleaved format is supported.
2327        When the is supported, add the
2328        <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
2329        hardware supports the interleaved or the non-interleaved
2330        formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
2331        <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
2332        be set, respectively. If both are supported, you can set both,
2333        too. 
2334        </para>
2335
2336        <para>
2337          In the above example, <constant>MMAP_VALID</constant> and
2338        <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
2339        mode. Usually both are set. Of course,
2340        <constant>MMAP_VALID</constant> is set only if the mmap is
2341        really supported. 
2342        </para>
2343
2344        <para>
2345          The other possible flags are
2346        <constant>SNDRV_PCM_INFO_PAUSE</constant> and
2347        <constant>SNDRV_PCM_INFO_RESUME</constant>. The
2348        <constant>PAUSE</constant> bit means that the pcm supports the
2349        <quote>pause</quote> operation, while the
2350        <constant>RESUME</constant> bit means that the pcm supports
2351        the full <quote>suspend/resume</quote> operation.
2352        If the <constant>PAUSE</constant> flag is set,
2353        the <structfield>trigger</structfield> callback below
2354        must handle the corresponding (pause push/release) commands.
2355        The suspend/resume trigger commands can be defined even without
2356        the <constant>RESUME</constant> flag.  See <link
2357        linkend="power-management"><citetitle>
2358        Power Management</citetitle></link> section for details.
2359        </para>
2360
2361        <para>
2362          When the PCM substreams can be synchronized (typically,
2363        synchronized start/stop of a playback and a capture streams),
2364        you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2365        too.  In this case, you'll need to check the linked-list of
2366        PCM substreams in the trigger callback.  This will be
2367        described in the later section.
2368        </para>
2369        </listitem>
2370
2371        <listitem>
2372        <para>
2373          <structfield>formats</structfield> field contains the bit-flags
2374        of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
2375        If the hardware supports more than one format, give all or'ed
2376        bits.  In the example above, the signed 16bit little-endian
2377        format is specified.
2378        </para>
2379        </listitem>
2380
2381        <listitem>
2382        <para>
2383        <structfield>rates</structfield> field contains the bit-flags of
2384        supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
2385        When the chip supports continuous rates, pass
2386        <constant>CONTINUOUS</constant> bit additionally.
2387        The pre-defined rate bits are provided only for typical
2388        rates. If your chip supports unconventional rates, you need to add
2389        the <constant>KNOT</constant> bit and set up the hardware
2390        constraint manually (explained later).
2391        </para>
2392        </listitem>
2393
2394        <listitem>
2395        <para>
2396        <structfield>rate_min</structfield> and
2397        <structfield>rate_max</structfield> define the minimum and
2398        maximum sample rate.  This should correspond somehow to
2399        <structfield>rates</structfield> bits.
2400        </para>
2401        </listitem>
2402
2403        <listitem>
2404        <para>
2405        <structfield>channel_min</structfield> and
2406        <structfield>channel_max</structfield> 
2407        define, as you might already expected, the minimum and maximum
2408        number of channels.
2409        </para>
2410        </listitem>
2411
2412        <listitem>
2413        <para>
2414        <structfield>buffer_bytes_max</structfield> defines the
2415        maximum buffer size in bytes.  There is no
2416        <structfield>buffer_bytes_min</structfield> field, since
2417        it can be calculated from the minimum period size and the
2418        minimum number of periods.
2419        Meanwhile, <structfield>period_bytes_min</structfield> and
2420        define the minimum and maximum size of the period in bytes.
2421        <structfield>periods_max</structfield> and
2422        <structfield>periods_min</structfield> define the maximum and
2423        minimum number of periods in the buffer.
2424        </para>
2425
2426        <para>
2427        The <quote>period</quote> is a term that corresponds to
2428        a fragment in the OSS world. The period defines the size at
2429        which a PCM interrupt is generated. This size strongly
2430        depends on the hardware. 
2431        Generally, the smaller period size will give you more
2432        interrupts, that is, more controls. 
2433        In the case of capture, this size defines the input latency.
2434        On the other hand, the whole buffer size defines the
2435        output latency for the playback direction.
2436        </para>
2437        </listitem>
2438
2439        <listitem>
2440        <para>
2441        There is also a field <structfield>fifo_size</structfield>.
2442        This specifies the size of the hardware FIFO, but currently it
2443        is neither used in the driver nor in the alsa-lib.  So, you
2444        can ignore this field.
2445        </para>
2446        </listitem>
2447        </itemizedlist>
2448        </para>
2449        </section>
2450
2451        <section id="pcm-interface-runtime-config">
2452        <title>PCM Configurations</title>
2453        <para>
2454        Ok, let's go back again to the PCM runtime records.
2455        The most frequently referred records in the runtime instance are
2456        the PCM configurations.
2457        The PCM configurations are stored in the runtime instance
2458        after the application sends <type>hw_params</type> data via
2459        alsa-lib.  There are many fields copied from hw_params and
2460        sw_params structs.  For example,
2461        <structfield>format</structfield> holds the format type
2462        chosen by the application.  This field contains the enum value
2463        <constant>SNDRV_PCM_FORMAT_XXX</constant>.
2464        </para>
2465
2466        <para>
2467        One thing to be noted is that the configured buffer and period
2468        sizes are stored in <quote>frames</quote> in the runtime.
2469        In the ALSA world, 1 frame = channels * samples-size.
2470        For conversion between frames and bytes, you can use the
2471        <function>frames_to_bytes()</function> and
2472          <function>bytes_to_frames()</function> helper functions. 
2473          <informalexample>
2474            <programlisting>
2475<![CDATA[
2476  period_bytes = frames_to_bytes(runtime, runtime->period_size);
2477]]>
2478            </programlisting>
2479          </informalexample>
2480        </para>
2481
2482        <para>
2483        Also, many software parameters (sw_params) are
2484        stored in frames, too.  Please check the type of the field.
2485        <type>snd_pcm_uframes_t</type> is for the frames as unsigned
2486        integer while <type>snd_pcm_sframes_t</type> is for the frames
2487        as signed integer.
2488        </para>
2489        </section>
2490
2491        <section id="pcm-interface-runtime-dma">
2492        <title>DMA Buffer Information</title>
2493        <para>
2494        The DMA buffer is defined by the following four fields,
2495        <structfield>dma_area</structfield>,
2496        <structfield>dma_addr</structfield>,
2497        <structfield>dma_bytes</structfield> and
2498        <structfield>dma_private</structfield>.
2499        The <structfield>dma_area</structfield> holds the buffer
2500        pointer (the logical address).  You can call
2501        <function>memcpy</function> from/to 
2502        this pointer.  Meanwhile, <structfield>dma_addr</structfield>
2503        holds the physical address of the buffer.  This field is
2504        specified only when the buffer is a linear buffer.
2505        <structfield>dma_bytes</structfield> holds the size of buffer
2506        in bytes.  <structfield>dma_private</structfield> is used for
2507        the ALSA DMA allocator.
2508        </para>
2509
2510        <para>
2511        If you use a standard ALSA function,
2512        <function>snd_pcm_lib_malloc_pages()</function>, for
2513        allocating the buffer, these fields are set by the ALSA middle
2514        layer, and you should <emphasis>not</emphasis> change them by
2515        yourself.  You can read them but not write them.
2516        On the other hand, if you want to allocate the buffer by
2517        yourself, you'll need to manage it in hw_params callback.
2518        At least, <structfield>dma_bytes</structfield> is mandatory.
2519        <structfield>dma_area</structfield> is necessary when the
2520        buffer is mmapped.  If your driver doesn't support mmap, this
2521        field is not necessary.  <structfield>dma_addr</structfield>
2522        is also optional.  You can use
2523        <structfield>dma_private</structfield> as you like, too.
2524        </para>
2525        </section>
2526
2527        <section id="pcm-interface-runtime-status">
2528        <title>Running Status</title>
2529        <para>
2530        The running status can be referred via <constant>runtime-&gt;status</constant>.
2531        This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
2532        record.  For example, you can get the current DMA hardware
2533        pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
2534        </para>
2535
2536        <para>
2537        The DMA application pointer can be referred via
2538        <constant>runtime-&gt;control</constant>, which points to the
2539        struct <structname>snd_pcm_mmap_control</structname> record.
2540        However, accessing directly to this value is not recommended.
2541        </para>
2542        </section>
2543
2544        <section id="pcm-interface-runtime-private">
2545        <title>Private Data</title> 
2546        <para>
2547        You can allocate a record for the substream and store it in
2548        <constant>runtime-&gt;private_data</constant>.  Usually, this
2549        is done in
2550        <link linkend="pcm-interface-operators-open-callback"><citetitle>
2551        the open callback</citetitle></link>.
2552        Don't mix this with <constant>pcm-&gt;private_data</constant>.
2553        The <constant>pcm-&gt;private_data</constant> usually points to the
2554        chip instance assigned statically at the creation of PCM, while the 
2555        <constant>runtime-&gt;private_data</constant> points to a dynamic
2556        data structure created at the PCM open callback.
2557
2558          <informalexample>
2559            <programlisting>
2560<![CDATA[
2561  static int snd_xxx_open(struct snd_pcm_substream *substream)
2562  {
2563          struct my_pcm_data *data;
2564          ....
2565          data = kmalloc(sizeof(*data), GFP_KERNEL);
2566          substream->runtime->private_data = data;
2567          ....
2568  }
2569]]>
2570            </programlisting>
2571          </informalexample>
2572        </para>
2573
2574        <para>
2575          The allocated object must be released in
2576        <link linkend="pcm-interface-operators-open-callback"><citetitle>
2577        the close callback</citetitle></link>.
2578        </para>
2579        </section>
2580
2581        <section id="pcm-interface-runtime-intr">
2582        <title>Interrupt Callbacks</title>
2583        <para>
2584        The field <structfield>transfer_ack_begin</structfield> and
2585        <structfield>transfer_ack_end</structfield> are called at
2586        the beginning and at the end of
2587        <function>snd_pcm_period_elapsed()</function>, respectively. 
2588        </para>
2589        </section>
2590
2591    </section>
2592
2593    <section id="pcm-interface-operators">
2594      <title>Operators</title>
2595      <para>
2596        OK, now let me give details about each pcm callback
2597      (<parameter>ops</parameter>). In general, every callback must
2598      return 0 if successful, or a negative error number
2599      such as <constant>-EINVAL</constant>. To choose an appropriate
2600      error number, it is advised to check what value other parts of
2601      the kernel return when the same kind of request fails.
2602      </para>
2603
2604      <para>
2605        The callback function takes at least the argument with
2606        <structname>snd_pcm_substream</structname> pointer. To retrieve
2607        the chip record from the given substream instance, you can use the
2608        following macro. 
2609
2610        <informalexample>
2611          <programlisting>
2612<![CDATA[
2613  int xxx() {
2614          struct mychip *chip = snd_pcm_substream_chip(substream);
2615          ....
2616  }
2617]]>
2618          </programlisting>
2619        </informalexample>
2620
2621        The macro reads <constant>substream-&gt;private_data</constant>,
2622        which is a copy of <constant>pcm-&gt;private_data</constant>.
2623        You can override the former if you need to assign different data
2624        records per PCM substream.  For example, the cmi8330 driver assigns
2625        different private_data for playback and capture directions,
2626        because it uses two different codecs (SB- and AD-compatible) for
2627        different directions.
2628      </para>
2629
2630      <section id="pcm-interface-operators-open-callback">
2631        <title>open callback</title>
2632        <para>
2633          <informalexample>
2634            <programlisting>
2635<![CDATA[
2636  static int snd_xxx_open(struct snd_pcm_substream *substream);
2637]]>
2638            </programlisting>
2639          </informalexample>
2640
2641          This is called when a pcm substream is opened.
2642        </para>
2643
2644        <para>
2645          At least, here you have to initialize the runtime-&gt;hw
2646          record. Typically, this is done by like this: 
2647
2648          <informalexample>
2649            <programlisting>
2650<![CDATA[
2651  static int snd_xxx_open(struct snd_pcm_substream *substream)
2652  {
2653          struct mychip *chip = snd_pcm_substream_chip(substream);
2654          struct snd_pcm_runtime *runtime = substream->runtime;
2655
2656          runtime->hw = snd_mychip_playback_hw;
2657          return 0;
2658  }
2659]]>
2660            </programlisting>
2661          </informalexample>
2662
2663          where <parameter>snd_mychip_playback_hw</parameter> is the
2664          pre-defined hardware description.
2665        </para>
2666
2667        <para>
2668        You can allocate a private data in this callback, as described
2669        in <link linkend="pcm-interface-runtime-private"><citetitle>
2670        Private Data</citetitle></link> section.
2671        </para>
2672
2673        <para>
2674        If the hardware configuration needs more constraints, set the
2675        hardware constraints here, too.
2676        See <link linkend="pcm-interface-constraints"><citetitle>
2677        Constraints</citetitle></link> for more details.
2678        </para>
2679      </section>
2680
2681      <section id="pcm-interface-operators-close-callback">
2682        <title>close callback</title>
2683        <para>
2684          <informalexample>
2685            <programlisting>
2686<![CDATA[
2687  static int snd_xxx_close(struct snd_pcm_substream *substream);
2688]]>
2689            </programlisting>
2690          </informalexample>
2691
2692          Obviously, this is called when a pcm substream is closed.
2693        </para>
2694
2695        <para>
2696          Any private instance for a pcm substream allocated in the
2697          open callback will be released here. 
2698
2699          <informalexample>
2700            <programlisting>
2701<![CDATA[
2702  static int snd_xxx_close(struct snd_pcm_substream *substream)
2703  {
2704          ....
2705          kfree(substream->runtime->private_data);
2706          ....
2707  }
2708]]>
2709            </programlisting>
2710          </informalexample>
2711        </para>
2712      </section>
2713
2714      <section id="pcm-interface-operators-ioctl-callback">
2715        <title>ioctl callback</title>
2716        <para>
2717          This is used for any special call to pcm ioctls. But
2718        usually you can pass a generic ioctl callback, 
2719        <function>snd_pcm_lib_ioctl</function>.
2720        </para>
2721      </section>
2722
2723      <section id="pcm-interface-operators-hw-params-callback">
2724        <title>hw_params callback</title>
2725        <para>
2726          <informalexample>
2727            <programlisting>
2728<![CDATA[
2729  static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
2730                               struct snd_pcm_hw_params *hw_params);
2731]]>
2732            </programlisting>
2733          </informalexample>
2734        </para>
2735
2736        <para>
2737          This is called when the hardware parameter
2738        (<structfield>hw_params</structfield>) is set
2739        up by the application, 
2740        that is, once when the buffer size, the period size, the
2741        format, etc. are defined for the pcm substream. 
2742        </para>
2743
2744        <para>
2745          Many hardware setups should be done in this callback,
2746        including the allocation of buffers. 
2747        </para>
2748
2749        <para>
2750          Parameters to be initialized are retrieved by
2751          <function>params_xxx()</function> macros. To allocate
2752          buffer, you can call a helper function, 
2753
2754          <informalexample>
2755            <programlisting>
2756<![CDATA[
2757  snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
2758]]>
2759            </programlisting>
2760          </informalexample>
2761
2762          <function>snd_pcm_lib_malloc_pages()</function> is available
2763          only when the DMA buffers have been pre-allocated.
2764          See the section <link
2765          linkend="buffer-and-memory-buffer-types"><citetitle>
2766          Buffer Types</citetitle></link> for more details.
2767        </para>
2768
2769        <para>
2770          Note that this and <structfield>prepare</structfield> callbacks
2771        may be called multiple times per initialization.
2772        For example, the OSS emulation may
2773        call these callbacks at each change via its ioctl. 
2774        </para>
2775
2776        <para>
2777          Thus, you need to be careful not to allocate the same buffers
2778        many times, which will lead to memory leaks!  Calling the
2779        helper function above many times is OK. It will release the
2780        previous buffer automatically when it was already allocated. 
2781        </para>
2782
2783        <para>
2784          Another note is that this callback is non-atomic
2785        (schedulable). This is important, because the
2786        <structfield>trigger</structfield> callback 
2787        is atomic (non-schedulable). That is, mutexes or any
2788        schedule-related functions are not available in
2789        <structfield>trigger</structfield> callback.
2790        Please see the subsection
2791        <link linkend="pcm-interface-atomicity"><citetitle>
2792        Atomicity</citetitle></link> for details.
2793        </para>
2794      </section>
2795
2796      <section id="pcm-interface-operators-hw-free-callback">
2797        <title>hw_free callback</title>
2798        <para>
2799          <informalexample>
2800            <programlisting>
2801<![CDATA[
2802  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
2803]]>
2804            </programlisting>
2805          </informalexample>
2806        </para>
2807
2808        <para>
2809          This is called to release the resources allocated via
2810          <structfield>hw_params</structfield>. For example, releasing the
2811          buffer via 
2812          <function>snd_pcm_lib_malloc_pages()</function> is done by
2813          calling the following: 
2814
2815          <informalexample>
2816            <programlisting>
2817<![CDATA[
2818  snd_pcm_lib_free_pages(substream);
2819]]>
2820            </programlisting>
2821          </informalexample>
2822        </para>
2823
2824        <para>
2825          This function is always called before the close callback is called.
2826          Also, the callback may be called multiple times, too.
2827          Keep track whether the resource was already released. 
2828        </para>
2829      </section>
2830
2831      <section id="pcm-interface-operators-prepare-callback">
2832       <title>prepare callback</title>
2833        <para>
2834          <informalexample>
2835            <programlisting>
2836<![CDATA[
2837  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2838]]>
2839            </programlisting>
2840          </informalexample>
2841        </para>
2842
2843        <para>
2844          This callback is called when the pcm is
2845        <quote>prepared</quote>. You can set the format type, sample
2846        rate, etc. here. The difference from
2847        <structfield>hw_params</structfield> is that the 
2848        <structfield>prepare</structfield> callback will be called each
2849        time 
2850        <function>snd_pcm_prepare()</function> is called, i.e. when
2851        recovering after underruns, etc. 
2852        </para>
2853
2854        <para>
2855        Note that this callback is now non-atomic.
2856        You can use schedule-related functions safely in this callback.
2857        </para>
2858
2859        <para>
2860          In this and the following callbacks, you can refer to the
2861        values via the runtime record,
2862        substream-&gt;runtime.
2863        For example, to get the current
2864        rate, format or channels, access to
2865        runtime-&gt;rate,
2866        runtime-&gt;format or
2867        runtime-&gt;channels, respectively. 
2868        The physical address of the allocated buffer is set to
2869        runtime-&gt;dma_area.  The buffer and period sizes are
2870        in runtime-&gt;buffer_size and runtime-&gt;period_size,
2871        respectively.
2872        </para>
2873
2874        <para>
2875          Be careful that this callback will be called many times at
2876        each setup, too. 
2877        </para>
2878      </section>
2879
2880      <section id="pcm-interface-operators-trigger-callback">
2881        <title>trigger callback</title>
2882        <para>
2883          <informalexample>
2884            <programlisting>
2885<![CDATA[
2886  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2887]]>
2888            </programlisting>
2889          </informalexample>
2890
2891          This is called when the pcm is started, stopped or paused.
2892        </para>
2893
2894        <para>
2895          Which action is specified in the second argument,
2896          <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
2897          <filename>&lt;sound/pcm.h&gt;</filename>. At least,
2898          the <constant>START</constant> and <constant>STOP</constant>
2899          commands must be defined in this callback. 
2900
2901          <informalexample>
2902            <programlisting>
2903<![CDATA[
2904  switch (cmd) {
2905  case SNDRV_PCM_TRIGGER_START:
2906          /* do something to start the PCM engine */
2907          break;
2908  case SNDRV_PCM_TRIGGER_STOP:
2909          /* do something to stop the PCM engine */
2910          break;
2911  default:
2912          return -EINVAL;
2913  }
2914]]>
2915            </programlisting>
2916          </informalexample>
2917        </para>
2918
2919        <para>
2920          When the pcm supports the pause operation (given in the info
2921        field of the hardware table), the <constant>PAUSE_PUSE</constant>
2922        and <constant>PAUSE_RELEASE</constant> commands must be
2923        handled here, too. The former is the command to pause the pcm,
2924        and the latter to restart the pcm again. 
2925        </para>
2926
2927        <para>
2928          When the pcm supports the suspend/resume operation,
2929        regardless of full or partial suspend/resume support,
2930        the <constant>SUSPEND</constant> and <constant>RESUME</constant>
2931        commands must be handled, too.
2932        These commands are issued when the power-management status is
2933        changed.  Obviously, the <constant>SUSPEND</constant> and
2934        <constant>RESUME</constant> commands
2935        suspend and resume the pcm substream, and usually, they
2936        are identical to the <constant>STOP</constant> and
2937        <constant>START</constant> commands, respectively.
2938          See the <link linkend="power-management"><citetitle>
2939        Power Management</citetitle></link> section for details.
2940        </para>
2941
2942        <para>
2943          As mentioned, this callback is atomic.  You cannot call
2944          functions which may sleep.
2945          The trigger callback should be as minimal as possible,
2946          just really triggering the DMA.  The other stuff should be
2947          initialized hw_params and prepare callbacks properly
2948          beforehand.
2949        </para>
2950      </section>
2951
2952      <section id="pcm-interface-operators-pointer-callback">
2953        <title>pointer callback</title>
2954        <para>
2955          <informalexample>
2956            <programlisting>
2957<![CDATA[
2958  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2959]]>
2960            </programlisting>
2961          </informalexample>
2962
2963          This callback is called when the PCM middle layer inquires
2964        the current hardware position on the buffer. The position must
2965        be returned in frames,
2966        ranging from 0 to buffer_size - 1.
2967        </para>
2968
2969        <para>
2970          This is called usually from the buffer-update routine in the
2971        pcm middle layer, which is invoked when
2972        <function>snd_pcm_period_elapsed()</function> is called in the
2973        interrupt routine. Then the pcm middle layer updates the
2974        position and calculates the available space, and wakes up the
2975        sleeping poll threads, etc. 
2976        </para>
2977
2978        <para>
2979          This callback is also atomic.
2980        </para>
2981      </section>
2982
2983      <section id="pcm-interface-operators-copy-silence">
2984        <title>copy and silence callbacks</title>
2985        <para>
2986          These callbacks are not mandatory, and can be omitted in
2987        most cases. These callbacks are used when the hardware buffer
2988        cannot be in the normal memory space. Some chips have their
2989        own buffer on the hardware which is not mappable. In such a
2990        case, you have to transfer the data manually from the memory
2991        buffer to the hardware buffer. Or, if the buffer is
2992        non-contiguous on both physical and virtual memory spaces,
2993        these callbacks must be defined, too. 
2994        </para>
2995
2996        <para>
2997          If these two callbacks are defined, copy and set-silence
2998        operations are done by them. The detailed will be described in
2999        the later section <link
3000        linkend="buffer-and-memory"><citetitle>Buffer and Memory
3001        Management</citetitle></link>. 
3002        </para>
3003      </section>
3004
3005      <section id="pcm-interface-operators-ack">
3006        <title>ack callback</title>
3007        <para>
3008          This callback is also not mandatory. This callback is called
3009        when the appl_ptr is updated in read or write operations.
3010        Some drivers like emu10k1-fx and cs46xx need to track the
3011        current appl_ptr for the internal buffer, and this callback
3012        is useful only for such a purpose.
3013        </para>
3014        <para>
3015          This callback is atomic.
3016        </para>
3017      </section>
3018
3019      <section id="pcm-interface-operators-page-callback">
3020        <title>page callback</title>
3021
3022        <para>
3023          This callback is optional too. This callback is used
3024        mainly for non-contiguous buffers. The mmap calls this
3025        callback to get the page address. Some examples will be
3026        explained in the later section <link
3027        linkend="buffer-and-memory"><citetitle>Buffer and Memory
3028        Management</citetitle></link>, too. 
3029        </para>
3030      </section>
3031    </section>
3032
3033    <section id="pcm-interface-interrupt-handler">
3034      <title>Interrupt Handler</title>
3035      <para>
3036        The rest of pcm stuff is the PCM interrupt handler. The
3037      role of PCM interrupt handler in the sound driver is to update
3038      the buffer position and to tell the PCM middle layer when the
3039      buffer position goes across the prescribed period size. To
3040      inform this, call the <function>snd_pcm_period_elapsed()</function>
3041      function. 
3042      </para>
3043
3044      <para>
3045        There are several types of sound chips to generate the interrupts.
3046      </para>
3047
3048      <section id="pcm-interface-interrupt-handler-boundary">
3049        <title>Interrupts at the period (fragment) boundary</title>
3050        <para>
3051          This is the most frequently found type:  the hardware
3052        generates an interrupt at each period boundary.
3053        In this case, you can call
3054        <function>snd_pcm_period_elapsed()</function> at each 
3055        interrupt. 
3056        </para>
3057
3058        <para>
3059          <function>snd_pcm_period_elapsed()</function> takes the
3060        substream pointer as its argument. Thus, you need to keep the
3061        substream pointer accessible from the chip instance. For
3062        example, define substream field in the chip record to hold the
3063        current running substream pointer, and set the pointer value
3064        at open callback (and reset at close callback). 
3065        </para>
3066
3067        <para>
3068          If you acquire a spinlock in the interrupt handler, and the
3069        lock is used in other pcm callbacks, too, then you have to
3070        release the lock before calling
3071        <function>snd_pcm_period_elapsed()</function>, because
3072        <function>snd_pcm_period_elapsed()</function> calls other pcm
3073        callbacks inside. 
3074        </para>
3075
3076        <para>
3077          Typical code would be like:
3078
3079          <example>
3080            <title>Interrupt Handler Case #1</title>
3081            <programlisting>
3082<![CDATA[
3083  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3084  {
3085          struct mychip *chip = dev_id;
3086          spin_lock(&chip->lock);
3087          ....
3088          if (pcm_irq_invoked(chip)) {
3089                  /* call updater, unlock before it */
3090                  spin_unlock(&chip->lock);
3091                  snd_pcm_period_elapsed(chip->substream);
3092                  spin_lock(&chip->lock);
3093                  /* acknowledge the interrupt if necessary */
3094          }
3095          ....
3096          spin_unlock(&chip->lock);
3097          return IRQ_HANDLED;
3098  }
3099]]>
3100            </programlisting>
3101          </example>
3102        </para>
3103      </section>
3104
3105      <section id="pcm-interface-interrupt-handler-timer">
3106        <title>High frequency timer interrupts</title>
3107        <para>
3108        This happense when the hardware doesn't generate interrupts
3109        at the period boundary but issues timer interrupts at a fixed
3110        timer rate (e.g. es1968 or ymfpci drivers). 
3111        In this case, you need to check the current hardware
3112        position and accumulate the processed sample length at each
3113        interrupt.  When the accumulated size exceeds the period
3114        size, call 
3115        <function>snd_pcm_period_elapsed()</function> and reset the
3116        accumulator. 
3117        </para>
3118
3119        <para>
3120          Typical code would be like the following.
3121
3122          <example>
3123            <title>Interrupt Handler Case #2</title>
3124            <programlisting>
3125<![CDATA[
3126  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3127  {
3128          struct mychip *chip = dev_id;
3129          spin_lock(&chip->lock);
3130          ....
3131          if (pcm_irq_invoked(chip)) {
3132                  unsigned int last_ptr, size;
3133                  /* get the current hardware pointer (in frames) */
3134                  last_ptr = get_hw_ptr(chip);
3135                  /* calculate the processed frames since the
3136                   * last update
3137                   */
3138                  if (last_ptr < chip->last_ptr)
3139                          size = runtime->buffer_size + last_ptr 
3140                                   - chip->last_ptr; 
3141                  else
3142                          size = last_ptr - chip->last_ptr;
3143                  /* remember the last updated point */
3144                  chip->last_ptr = last_ptr;
3145                  /* accumulate the size */
3146                  chip->size += size;
3147                  /* over the period boundary? */
3148                  if (chip->size >= runtime->period_size) {
3149                          /* reset the accumulator */
3150                          chip->size %= runtime->period_size;
3151                          /* call updater */
3152                          spin_unlock(&chip->lock);
3153                          snd_pcm_period_elapsed(substream);
3154                          spin_lock(&chip->lock);
3155                  }
3156                  /* acknowledge the interrupt if necessary */
3157          }
3158          ....
3159          spin_unlock(&chip->lock);
3160          return IRQ_HANDLED;
3161  }
3162]]>
3163            </programlisting>
3164          </example>
3165        </para>
3166      </section>
3167
3168      <section id="pcm-interface-interrupt-handler-both">
3169        <title>On calling <function>snd_pcm_period_elapsed()</function></title>
3170        <para>
3171          In both cases, even if more than one period are elapsed, you
3172        don't have to call
3173        <function>snd_pcm_period_elapsed()</function> many times. Call
3174        only once. And the pcm layer will check the current hardware
3175        pointer and update to the latest status. 
3176        </para>
3177      </section>
3178    </section>
3179
3180    <section id="pcm-interface-atomicity">
3181      <title>Atomicity</title>
3182      <para>
3183      One of the most important (and thus difficult to debug) problems
3184      in kernel programming are race conditions.
3185      In the Linux kernel, they are usually avoided via spin-locks, mutexes
3186      or semaphores.  In general, if a race condition can happen
3187      in an interrupt handler, it has to be managed atomically, and you
3188      have to use a spinlock to protect the critical session. If the
3189      critical section is not in interrupt handler code and
3190      if taking a relatively long time to execute is acceptable, you
3191      should use mutexes or semaphores instead.
3192      </para>
3193
3194      <para>
3195      As already seen, some pcm callbacks are atomic and some are
3196      not.  For example, the <parameter>hw_params</parameter> callback is
3197      non-atomic, while <parameter>trigger</parameter> callback is
3198      atomic.  This means, the latter is called already in a spinlock
3199      held by the PCM middle layer. Please take this atomicity into
3200      account when you choose a locking scheme in the callbacks.
3201      </para>
3202
3203      <para>
3204      In the atomic callbacks, you cannot use functions which may call
3205      <function>schedule</function> or go to
3206      <function>sleep</function>.  Semaphores and mutexes can sleep,
3207      and hence they cannot be used inside the atomic callbacks
3208      (e.g. <parameter>trigger</parameter> callback).
3209      To implement some delay in such a callback, please use
3210      <function>udelay()</function> or <function>mdelay()</function>.
3211      </para>
3212
3213      <para>
3214      All three atomic callbacks (trigger, pointer, and ack) are
3215      called with local interrupts disabled.
3216      </para>
3217
3218    </section>
3219    <section id="pcm-interface-constraints">
3220      <title>Constraints</title>
3221      <para>
3222        If your chip supports unconventional sample rates, or only the
3223      limited samples, you need to set a constraint for the
3224      condition. 
3225      </para>
3226
3227      <para>
3228        For example, in order to restrict the sample rates in the some
3229        supported values, use
3230        <function>snd_pcm_hw_constraint_list()</function>.
3231        You need to call this function in the open callback.
3232
3233        <example>
3234          <title>Example of Hardware Constraints</title>
3235          <programlisting>
3236<![CDATA[
3237  static unsigned int rates[] =
3238          {4000, 10000, 22050, 44100};
3239  static struct snd_pcm_hw_constraint_list constraints_rates = {
3240          .count = ARRAY_SIZE(rates),
3241          .list = rates,
3242          .mask = 0,
3243  };
3244
3245  static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
3246  {
3247          int err;
3248          ....
3249          err = snd_pcm_hw_constraint_list(substream->runtime, 0,
3250                                           SNDRV_PCM_HW_PARAM_RATE,
3251                                           &constraints_rates);
3252          if (err < 0)
3253                  return err;
3254          ....
3255  }
3256]]>
3257          </programlisting>
3258        </example>
3259      </para>
3260
3261      <para>
3262        There are many different constraints.
3263        Look at <filename>sound/pcm.h</filename> for a complete list.
3264        You can even define your own constraint rules.
3265        For example, let's suppose my_chip can manage a substream of 1 channel
3266        if and only if the format is S16_LE, otherwise it supports any format
3267        specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3268        other constraint_list). You can build a rule like this:
3269
3270        <example>
3271          <title>Example of Hardware Constraints for Channels</title>
3272          <programlisting>
3273<![CDATA[
3274  static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
3275                                        struct snd_pcm_hw_rule *rule)
3276  {
3277          struct snd_interval *c = hw_param_interval(params,
3278                SNDRV_PCM_HW_PARAM_CHANNELS);
3279          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3280          struct snd_mask fmt;
3281
3282          snd_mask_any(&fmt);    /* Init the struct */
3283          if (c->min < 2) {
3284                  fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3285                  return snd_mask_refine(f, &fmt);
3286          }
3287          return 0;
3288  }
3289]]>
3290          </programlisting>
3291        </example>
3292      </para>
3293 
3294      <para>
3295        Then you need to call this function to add your rule:
3296
3297       <informalexample>
3298         <programlisting>
3299<![CDATA[
3300  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3301                      hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3302                      -1);
3303]]>
3304          </programlisting>
3305        </informalexample>
3306      </para>
3307
3308      <para>
3309        The rule function is called when an application sets the number of
3310        channels. But an application can set the format before the number of
3311        channels. Thus you also need to define the inverse rule:
3312
3313       <example>
3314         <title>Example of Hardware Constraints for Channels</title>
3315         <programlisting>
3316<![CDATA[
3317  static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
3318                                        struct snd_pcm_hw_rule *rule)
3319  {
3320          struct snd_interval *c = hw_param_interval(params,
3321                        SNDRV_PCM_HW_PARAM_CHANNELS);
3322          struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3323          struct snd_interval ch;
3324
3325          snd_interval_any(&ch);
3326          if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3327                  ch.min = ch.max = 1;
3328                  ch.integer = 1;
3329                  return snd_interval_refine(c, &ch);
3330          }
3331          return 0;
3332  }
3333]]>
3334          </programlisting>
3335        </example>
3336      </para>
3337
3338      <para>
3339      ...and in the open callback:
3340       <informalexample>
3341         <programlisting>
3342<![CDATA[
3343  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3344                      hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3345                      -1);
3346]]>
3347          </programlisting>
3348        </informalexample>
3349      </para>
3350
3351      <para>
3352        I won't give more details here, rather I
3353        would like to say, <quote>Luke, use the source.</quote>
3354      </para>
3355    </section>
3356
3357  </chapter>
3358
3359
3360<!-- ****************************************************** -->
3361<!-- Control Interface  -->
3362<!-- ****************************************************** -->
3363  <chapter id="control-interface">
3364    <title>Control Interface</title>
3365
3366    <section id="control-interface-general">
3367      <title>General</title>
3368      <para>
3369        The control interface is used widely for many switches,
3370      sliders, etc. which are accessed from user-space. Its most
3371      important use is the mixer interface. In other words, since ALSA
3372      0.9.x, all the mixer stuff is implemented on the control kernel API.
3373      </para>
3374
3375      <para>
3376        ALSA has a well-defined AC97 control module. If your chip
3377      supports only the AC97 and nothing else, you can skip this
3378      section. 
3379      </para>
3380
3381      <para>
3382        The control API is defined in
3383      <filename>&lt;sound/control.h&gt;</filename>.
3384      Include this file if you want to add your own controls.
3385      </para>
3386    </section>
3387
3388    <section id="control-interface-definition">
3389      <title>Definition of Controls</title>
3390      <para>
3391        To create a new control, you need to define the
3392        following three
3393      callbacks: <structfield>info</structfield>,
3394      <structfield>get</structfield> and
3395      <structfield>put</structfield>. Then, define a
3396      struct <structname>snd_kcontrol_new</structname> record, such as: 
3397
3398        <example>
3399          <title>Definition of a Control</title>
3400          <programlisting>
3401<![CDATA[
3402  static struct snd_kcontrol_new my_control __devinitdata = {
3403          .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
3404          .name = "PCM Playback Switch",
3405          .index = 0,
3406          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
3407          .private_value = 0xffff,
3408          .info = my_control_info,
3409          .get = my_control_get,
3410          .put = my_control_put
3411  };
3412]]>
3413          </programlisting>
3414        </example>
3415      </para>
3416
3417      <para>
3418        Most likely the control is created via
3419      <function>snd_ctl_new1()</function>, and in such a case, you can
3420      add the <parameter>__devinitdata</parameter> prefix to the
3421      definition as above. 
3422      </para>
3423
3424      <para>
3425        The <structfield>iface</structfield> field specifies the control
3426      type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
3427      is usually <constant>MIXER</constant>.
3428      Use <constant>CARD</constant> for global controls that are not
3429      logically part of the mixer.
3430      If the control is closely associated with some specific device on
3431      the sound card, use <constant>HWDEP</constant>,
3432      <constant>PCM</constant>, <constant>RAWMIDI</constant>,
3433      <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
3434      specify the device number with the
3435      <structfield>device</structfield> and
3436      <structfield>subdevice</structfield> fields.
3437      </para>
3438
3439      <para>
3440        The <structfield>name</structfield> is the name identifier
3441      string. Since ALSA 0.9.x, the control name is very important,
3442      because its role is classified from its name. There are
3443      pre-defined standard control names. The details are described in
3444      the <link linkend="control-interface-control-names"><citetitle>
3445      Control Names</citetitle></link> subsection.
3446      </para>
3447
3448      <para>
3449        The <structfield>index</structfield> field holds the index number
3450      of this control. If there are several different controls with
3451      the same name, they can be distinguished by the index
3452      number. This is the case when 
3453      several codecs exist on the card. If the index is zero, you can
3454      omit the definition above. 
3455      </para>
3456
3457      <para>
3458        The <structfield>access</structfield> field contains the access
3459      type of this control. Give the combination of bit masks,
3460      <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
3461      The details will be explained in
3462      the <link linkend="control-interface-access-flags"><citetitle>
3463      Access Flags</citetitle></link> subsection.
3464      </para>
3465
3466      <para>
3467        The <structfield>private_value</structfield> field contains
3468      an arbitrary long integer value for this record. When using
3469      the generic <structfield>info</structfield>,
3470      <structfield>get</structfield> and
3471      <structfield>put</structfield> callbacks, you can pass a value 
3472      through this field. If several small numbers are necessary, you can
3473      combine them in bitwise. Or, it's possible to give a pointer
3474      (casted to unsigned long) of some record to this field, too. 
3475      </para>
3476
3477      <para>
3478      The <structfield>tlv</structfield> field can be used to provide
3479      metadata about the control; see the
3480      <link linkend="control-interface-tlv">
3481      <citetitle>Metadata</citetitle></link> subsection.
3482      </para>
3483
3484      <para>
3485        The other three are
3486        <link linkend="control-interface-callbacks"><citetitle>
3487        callback functions</citetitle></link>.
3488      </para>
3489    </section>
3490
3491    <section id="control-interface-control-names">
3492      <title>Control Names</title>
3493      <para>
3494        There are some standards to define the control names. A
3495      control is usually defined from the three parts as
3496      <quote>SOURCE DIRECTION FUNCTION</quote>. 
3497      </para>
3498
3499      <para>
3500        The first, <constant>SOURCE</constant>, specifies the source
3501      of the control, and is a string such as <quote>Master</quote>,
3502      <quote>PCM</quote>, <quote>CD</quote> and
3503      <quote>Line</quote>. There are many pre-defined sources. 
3504      </para>
3505
3506      <para>
3507        The second, <constant>DIRECTION</constant>, is one of the
3508      following strings according to the direction of the control:
3509      <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
3510      Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
3511      be omitted, meaning both playback and capture directions. 
3512      </para>
3513
3514      <para>
3515        The third, <constant>FUNCTION</constant>, is one of the
3516      following strings according to the function of the control:
3517      <quote>Switch</quote>, <quote>Volume</quote> and
3518      <quote>Route</quote>. 
3519      </para>
3520
3521      <para>
3522        The example of control names are, thus, <quote>Master Capture
3523      Switch</quote> or <quote>PCM Playback Volume</quote>. 
3524      </para>
3525
3526      <para>
3527        There are some exceptions:
3528      </para>
3529
3530      <section id="control-interface-control-names-global">
3531        <title>Global capture and playback</title>
3532        <para>
3533          <quote>Capture Source</quote>, <quote>Capture Switch</quote>
3534        and <quote>Capture Volume</quote> are used for the global
3535        capture (input) source, switch and volume. Similarly,
3536        <quote>Playback Switch</quote> and <quote>Playback
3537        Volume</quote> are used for the global output gain switch and
3538        volume. 
3539        </para>
3540      </section>
3541
3542      <section id="control-interface-control-names-tone">
3543        <title>Tone-controls</title>
3544        <para>
3545          tone-control switch and volumes are specified like
3546        <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
3547        Switch</quote>, <quote>Tone Control - Bass</quote>,
3548        <quote>Tone Control - Center</quote>.  
3549        </para>
3550      </section>
3551
3552      <section id="control-interface-control-names-3d">
3553        <title>3D controls</title>
3554        <para>
3555          3D-control switches and volumes are specified like <quote>3D
3556        Control - XXX</quote>, e.g. <quote>3D Control -
3557        Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
3558        Control - Space</quote>. 
3559        </para>
3560      </section>
3561
3562      <section id="control-interface-control-names-mic">
3563        <title>Mic boost</title>
3564        <para>
3565          Mic-boost switch is set as <quote>Mic Boost</quote> or
3566        <quote>Mic Boost (6dB)</quote>. 
3567        </para>
3568
3569        <para>
3570          More precise information can be found in
3571        <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
3572        </para>
3573      </section>
3574    </section>
3575
3576    <section id="control-interface-access-flags">
3577      <title>Access Flags</title>
3578
3579      <para>
3580      The access flag is the bitmask which specifies the access type
3581      of the given control.  The default access type is
3582      <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 
3583      which means both read and write are allowed to this control.
3584      When the access flag is omitted (i.e. = 0), it is
3585      considered as <constant>READWRITE</constant> access as default. 
3586      </para>
3587
3588      <para>
3589      When the control is read-only, pass
3590      <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
3591      In this case, you don't have to define
3592      the <structfield>put</structfield> callback.
3593      Similarly, when the control is write-only (although it's a rare
3594      case), you can use the <constant>WRITE</constant> flag instead, and
3595      you don't need the <structfield>get</structfield> callback.
3596      </para>
3597
3598      <para>
3599      If the control value changes frequently (e.g. the VU meter),
3600      <constant>VOLATILE</constant> flag should be given.  This means
3601      that the control may be changed without
3602      <link linkend="control-interface-change-notification"><citetitle>
3603      notification</citetitle></link>. Applications should poll such
3604      a control constantly.
3605      </para>
3606
3607      <para>
3608      When the control is inactive, set
3609      the <constant>INACTIVE</constant> flag, too.
3610      There are <constant>LOCK</constant> and
3611      <constant>OWNER</constant> flags to change the write
3612      permissions.
3613      </para>
3614
3615    </section>
3616
3617    <section id="control-interface-callbacks">
3618      <title>Callbacks</title>
3619
3620      <section id="control-interface-callbacks-info">
3621        <title>info callback</title>
3622        <para>
3623          The <structfield>info</structfield> callback is used to get
3624        detailed information on this control. This must store the
3625        values of the given struct <structname>snd_ctl_elem_info</structname>
3626        object. For example, for a boolean control with a single
3627        element: 
3628
3629          <example>
3630            <title>Example of info callback</title>
3631            <programlisting>
3632<![CDATA[
3633  static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
3634                          struct snd_ctl_elem_info *uinfo)
3635  {
3636          uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
3637          uinfo->count = 1;
3638          uinfo->value.integer.min = 0;
3639          uinfo->value.integer.max = 1;
3640          return 0;
3641  }
3642]]>
3643            </programlisting>
3644          </example>
3645        </para>
3646
3647        <para>
3648          The <structfield>type</structfield> field specifies the type
3649        of the control. There are <constant>BOOLEAN</constant>,
3650        <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
3651        <constant>BYTES</constant>, <constant>IEC958</constant> and
3652        <constant>INTEGER64</constant>. The
3653        <structfield>count</structfield> field specifies the 
3654        number of elements in this control. For example, a stereo
3655        volume would have count = 2. The
3656        <structfield>value</structfield> field is a union, and 
3657        the values stored are depending on the type. The boolean and
3658        integer types are identical. 
3659        </para>
3660
3661        <para>
3662          The enumerated type is a bit different from others.  You'll
3663          need to set the string for the currently given item index. 
3664
3665          <informalexample>
3666            <programlisting>
3667<![CDATA[
3668  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
3669                          struct snd_ctl_elem_info *uinfo)
3670  {
3671          static char *texts[4] = {
3672                  "First", "Second", "Third", "Fourth"
3673          };
3674          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
3675          uinfo->count = 1;
3676          uinfo->value.enumerated.items = 4;
3677          if (uinfo->value.enumerated.item > 3)
3678                  uinfo->value.enumerated.item = 3;
3679          strcpy(uinfo->value.enumerated.name,
3680                 texts[uinfo->value.enumerated.item]);
3681          return 0;
3682  }
3683]]>
3684            </programlisting>
3685          </informalexample>
3686        </para>
3687
3688        <para>
3689          Some common info callbacks are available for your convenience:
3690        <function>snd_ctl_boolean_mono_info()</function> and
3691        <function>snd_ctl_boolean_stereo_info()</function>.
3692        Obviously, the former is an info callback for a mono channel
3693        boolean item, just like <function>snd_myctl_mono_info</function>
3694        above, and the latter is for a stereo channel boolean item.
3695        </para>
3696
3697      </section>
3698
3699      <section id="control-interface-callbacks-get">
3700        <title>get callback</title>
3701
3702        <para>
3703          This callback is used to read the current value of the
3704        control and to return to user-space. 
3705        </para>
3706
3707        <para>
3708          For example,
3709
3710          <example>
3711            <title>Example of get callback</title>
3712            <programlisting>
3713<![CDATA[
3714  static int snd_myctl_get(struct snd_kcontrol *kcontrol,
3715                           struct snd_ctl_elem_value *ucontrol)
3716  {
3717          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3718          ucontrol->value.integer.value[0] = get_some_value(chip);
3719          return 0;
3720  }
3721]]>
3722            </programlisting>
3723          </example>
3724        </para>
3725
3726        <para>
3727        The <structfield>value</structfield> field depends on 
3728        the type of control as well as on the info callback.  For example,
3729        the sb driver uses this field to store the register offset,
3730        the bit-shift and the bit-mask.  The
3731        <structfield>private_value</structfield> field is set as follows:
3732          <informalexample>
3733            <programlisting>
3734<![CDATA[
3735  .private_value = reg | (shift << 16) | (mask << 24)
3736]]>
3737            </programlisting>
3738          </informalexample>
3739        and is retrieved in callbacks like
3740          <informalexample>
3741            <programlisting>
3742<![CDATA[
3743  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
3744                                    struct snd_ctl_elem_value *ucontrol)
3745  {
3746          int reg = kcontrol->private_value & 0xff;
3747          int shift = (kcontrol->private_value >> 16) & 0xff;
3748          int mask = (kcontrol->private_value >> 24) & 0xff;
3749          ....
3750  }
3751]]>
3752            </programlisting>
3753          </informalexample>
3754        </para>
3755
3756        <para>
3757        In the <structfield>get</structfield> callback,
3758        you have to fill all the elements if the
3759        control has more than one elements,
3760        i.e. <structfield>count</structfield> &gt; 1.
3761        In the example above, we filled only one element
3762        (<structfield>value.integer.value[0]</structfield>) since it's
3763        assumed as <structfield>count</structfield> = 1.
3764        </para>
3765      </section>
3766
3767      <section id="control-interface-callbacks-put">
3768        <title>put callback</title>
3769
3770        <para>
3771          This callback is used to write a value from user-space.
3772        </para>
3773
3774        <para>
3775          For example,
3776
3777          <example>
3778            <title>Example of put callback</title>
3779            <programlisting>
3780<![CDATA[
3781  static int snd_myctl_put(struct snd_kcontrol *kcontrol,
3782                           struct snd_ctl_elem_value *ucontrol)
3783  {
3784          struct mychip *chip = snd_kcontrol_chip(kcontrol);
3785          int changed = 0;
3786          if (chip->current_value !=
3787               ucontrol->value.integer.value[0]) {
3788                  change_current_value(chip,
3789                              ucontrol->value.integer.value[0]);
3790                  changed = 1;
3791          }
3792          return changed;
3793  }
3794]]>
3795            </programlisting>
3796          </example>
3797
3798          As seen above, you have to return 1 if the value is
3799        changed. If the value is not changed, return 0 instead. 
3800        If any fatal error happens, return a negative error code as
3801        usual.
3802        </para>
3803
3804        <para>
3805        As in the <structfield>get</structfield> callback,
3806        when the control has more than one elements,
3807        all elements must be evaluated in this callback, too.
3808        </para>
3809      </section>
3810
3811      <section id="control-interface-callbacks-all">
3812        <title>Callbacks are not atomic</title>
3813        <para>
3814          All these three callbacks are basically not atomic.
3815        </para>
3816      </section>
3817    </section>
3818
3819    <section id="control-interface-constructor">
3820      <title>Constructor</title>
3821      <para>
3822        When everything is ready, finally we can create a new
3823      control. To create a control, there are two functions to be
3824      called, <function>snd_ctl_new1()</function> and
3825      <function>snd_ctl_add()</function>. 
3826      </para>
3827
3828      <para>
3829        In the simplest way, you can do like this:
3830
3831        <informalexample>
3832          <programlisting>
3833<![CDATA[
3834  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
3835  if (err < 0)
3836          return err;
3837]]>
3838          </programlisting>
3839        </informalexample>
3840
3841        where <parameter>my_control</parameter> is the
3842      struct <structname>snd_kcontrol_new</structname> object defined above, and chip
3843      is the object pointer to be passed to
3844      kcontrol-&gt;private_data 
3845      which can be referred to in callbacks. 
3846      </para>
3847
3848      <para>
3849        <function>snd_ctl_new1()</function> allocates a new
3850      <structname>snd_kcontrol</structname> instance (that's why the definition
3851      of <parameter>my_control</parameter> can be with
3852      the <parameter>__devinitdata</parameter> 
3853      prefix), and <function>snd_ctl_add</function> assigns the given
3854      control component to the card. 
3855      </para>
3856    </section>
3857
3858    <section id="control-interface-change-notification">
3859      <title>Change Notification</title>
3860      <para>
3861        If you need to change and update a control in the interrupt
3862      routine, you can call <function>snd_ctl_notify()</function>. For
3863      example, 
3864
3865        <informalexample>
3866          <programlisting>
3867<![CDATA[
3868  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
3869]]>
3870          </programlisting>
3871        </informalexample>
3872
3873        This function takes the card pointer, the event-mask, and the
3874      control id pointer for the notification. The event-mask
3875      specifies the types of notification, for example, in the above
3876      example, the change of control values is notified.
3877      The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
3878      to be notified.
3879      You can find some examples in <filename>es1938.c</filename> or
3880      <filename>es1968.c</filename> for hardware volume interrupts. 
3881      </para>
3882    </section>
3883
3884    <section id="control-interface-tlv">
3885      <title>Metadata</title>
3886      <para>
3887      To provide information about the dB values of a mixer control, use
3888      on of the <constant>DECLARE_TLV_xxx</constant> macros from
3889      <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
3890      containing this information, set the<structfield>tlv.p
3891      </structfield> field to point to this variable, and include the
3892      <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
3893      <structfield>access</structfield> field; like this:
3894      <informalexample>
3895        <programlisting>
3896<![CDATA[
3897  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
3898
3899  static struct snd_kcontrol_new my_control __devinitdata = {
3900          ...
3901          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
3902                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
3903          ...
3904          .tlv.p = db_scale_my_control,
3905  };
3906]]>
3907        </programlisting>
3908      </informalexample>
3909      </para>
3910
3911      <para>
3912      The <function>DECLARE_TLV_DB_SCALE</function> macro defines
3913      information about a mixer control where each step in the control's
3914      value changes the dB value by a constant dB amount.
3915      The first parameter is the name of the variable to be defined.
3916      The second parameter is the minimum value, in units of 0.01 dB.
3917      The third parameter is the step size, in units of 0.01 dB.
3918      Set the fourth parameter to 1 if the minimum value actually mutes
3919      the control.
3920      </para>
3921
3922      <para>
3923      The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
3924      information about a mixer control where the control's value affects
3925      the output linearly.
3926      The first parameter is the name of the variable to be defined.
3927      The second parameter is the minimum value, in units of 0.01 dB.
3928      The third parameter is the maximum value, in units of 0.01 dB.
3929      If the minimum value mutes the control, set the second parameter to
3930      <constant>TLV_DB_GAIN_MUTE</constant>.
3931      </para>
3932    </section>
3933
3934  </chapter>
3935
3936
3937<!-- ****************************************************** -->
3938<!-- API for AC97 Codec  -->
3939<!-- ****************************************************** -->
3940  <chapter id="api-ac97">
3941    <title>API for AC97 Codec</title>
3942
3943    <section>
3944      <title>General</title>
3945      <para>
3946        The ALSA AC97 codec layer is a well-defined one, and you don't
3947      have to write much code to control it. Only low-level control
3948      routines are necessary. The AC97 codec API is defined in
3949      <filename>&lt;sound/ac97_codec.h&gt;</filename>. 
3950      </para>
3951    </section>
3952
3953    <section id="api-ac97-example">
3954      <title>Full Code Example</title>
3955      <para>
3956          <example>
3957            <title>Example of AC97 Interface</title>
3958            <programlisting>
3959<![CDATA[
3960  struct mychip {
3961          ....
3962          struct snd_ac97 *ac97;
3963          ....
3964  };
3965
3966  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
3967                                             unsigned short reg)
3968  {
3969          struct mychip *chip = ac97->private_data;
3970          ....
3971          /* read a register value here from the codec */
3972          return the_register_value;
3973  }
3974
3975  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
3976                                   unsigned short reg, unsigned short val)
3977  {
3978          struct mychip *chip = ac97->private_data;
3979          ....
3980          /* write the given register value to the codec */
3981  }
3982
3983  static int snd_mychip_ac97(struct mychip *chip)
3984  {
3985          struct snd_ac97_bus *bus;
3986          struct snd_ac97_template ac97;
3987          int err;
3988          static struct snd_ac97_bus_ops ops = {
3989                  .write = snd_mychip_ac97_write,
3990                  .read = snd_mychip_ac97_read,
3991          };
3992
3993          err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
3994          if (err < 0)
3995                  return err;
3996          memset(&ac97, 0, sizeof(ac97));
3997          ac97.private_data = chip;
3998          return snd_ac97_mixer(bus, &ac97, &chip->ac97);
3999  }
4000
4001]]>
4002          </programlisting>
4003        </example>
4004      </para>
4005    </section>
4006
4007    <section id="api-ac97-constructor">
4008      <title>Constructor</title>
4009      <para>
4010        To create an ac97 instance, first call <function>snd_ac97_bus</function>
4011      with an <type>ac97_bus_ops_t</type> record with callback functions.
4012
4013        <informalexample>
4014          <programlisting>
4015<![CDATA[
4016  struct snd_ac97_bus *bus;
4017  static struct snd_ac97_bus_ops ops = {
4018        .write = snd_mychip_ac97_write,
4019        .read = snd_mychip_ac97_read,
4020  };
4021
4022  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
4023]]>
4024          </programlisting>
4025        </informalexample>
4026
4027      The bus record is shared among all belonging ac97 instances.
4028      </para>
4029
4030      <para>
4031      And then call <function>snd_ac97_mixer()</function> with an
4032      struct <structname>snd_ac97_template</structname>
4033      record together with the bus pointer created above.
4034
4035        <informalexample>
4036          <programlisting>
4037<![CDATA[
4038  struct snd_ac97_template ac97;
4039  int err;
4040
4041  memset(&ac97, 0, sizeof(ac97));
4042  ac97.private_data = chip;
4043  snd_ac97_mixer(bus, &ac97, &chip->ac97);
4044]]>
4045          </programlisting>
4046        </informalexample>
4047
4048        where chip-&gt;ac97 is a pointer to a newly created
4049        <type>ac97_t</type> instance.
4050        In this case, the chip pointer is set as the private data, so that
4051        the read/write callback functions can refer to this chip instance.
4052        This instance is not necessarily stored in the chip
4053        record.  If you need to change the register values from the
4054        driver, or need the suspend/resume of ac97 codecs, keep this
4055        pointer to pass to the corresponding functions.
4056      </para>
4057    </section>
4058
4059    <section id="api-ac97-callbacks">
4060      <title>Callbacks</title>
4061      <para>
4062        The standard callbacks are <structfield>read</structfield> and
4063      <structfield>write</structfield>. Obviously they 
4064      correspond to the functions for read and write accesses to the
4065      hardware low-level codes. 
4066      </para>
4067
4068      <para>
4069        The <structfield>read</structfield> callback returns the
4070        register value specified in the argument. 
4071
4072        <informalexample>
4073          <programlisting>
4074<![CDATA[
4075  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
4076                                             unsigned short reg)
4077  {
4078          struct mychip *chip = ac97->private_data;
4079          ....
4080          return the_register_value;
4081  }
4082]]>
4083          </programlisting>
4084        </informalexample>
4085
4086        Here, the chip can be cast from ac97-&gt;private_data.
4087      </para>
4088
4089      <para>
4090        Meanwhile, the <structfield>write</structfield> callback is
4091        used to set the register value. 
4092
4093        <informalexample>
4094          <programlisting>
4095<![CDATA[
4096  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
4097                       unsigned short reg, unsigned short val)
4098]]>
4099          </programlisting>
4100        </informalexample>
4101      </para>
4102
4103      <para>
4104      These callbacks are non-atomic like the control API callbacks.
4105      </para>
4106
4107      <para>
4108        There are also other callbacks:
4109      <structfield>reset</structfield>,
4110      <structfield>wait</structfield> and
4111      <structfield>init</structfield>. 
4112      </para>
4113
4114      <para>
4115        The <structfield>reset</structfield> callback is used to reset
4116      the codec. If the chip requires a special kind of reset, you can
4117      define this callback. 
4118      </para>
4119
4120      <para>
4121        The <structfield>wait</structfield> callback is used to
4122      add some waiting time in the standard initialization of the codec. If the
4123      chip requires the extra waiting time, define this callback. 
4124      </para>
4125
4126      <para>
4127        The <structfield>init</structfield> callback is used for
4128      additional initialization of the codec.
4129      </para>
4130    </section>
4131
4132    <section id="api-ac97-updating-registers">
4133      <title>Updating Registers in The Driver</title>
4134      <para>
4135        If you need to access to the codec from the driver, you can
4136      call the following functions:
4137      <function>snd_ac97_write()</function>,
4138      <function>snd_ac97_read()</function>,
4139      <function>snd_ac97_update()</function> and
4140      <function>snd_ac97_update_bits()</function>. 
4141      </para>
4142
4143      <para>
4144        Both <function>snd_ac97_write()</function> and
4145        <function>snd_ac97_update()</function> functions are used to
4146        set a value to the given register
4147        (<constant>AC97_XXX</constant>). The difference between them is
4148        that <function>snd_ac97_update()</function> doesn't write a
4149        value if the given value has been already set, while
4150        <function>snd_ac97_write()</function> always rewrites the
4151        value. 
4152
4153        <informalexample>
4154          <programlisting>
4155<![CDATA[
4156  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
4157  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
4158]]>
4159          </programlisting>
4160        </informalexample>
4161      </para>
4162
4163      <para>
4164        <function>snd_ac97_read()</function> is used to read the value
4165        of the given register. For example, 
4166
4167        <informalexample>
4168          <programlisting>
4169<![CDATA[
4170  value = snd_ac97_read(ac97, AC97_MASTER);
4171]]>
4172          </programlisting>
4173        </informalexample>
4174      </para>
4175
4176      <para>
4177        <function>snd_ac97_update_bits()</function> is used to update
4178        some bits in the given register.  
4179
4180        <informalexample>
4181          <programlisting>
4182<![CDATA[
4183  snd_ac97_update_bits(ac97, reg, mask, value);
4184]]>
4185          </programlisting>
4186        </informalexample>
4187      </para>
4188
4189      <para>
4190        Also, there is a function to change the sample rate (of a
4191        given register such as
4192        <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
4193        DRA is supported by the codec:
4194        <function>snd_ac97_set_rate()</function>. 
4195
4196        <informalexample>
4197          <programlisting>
4198<![CDATA[
4199  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
4200]]>
4201          </programlisting>
4202        </informalexample>
4203      </para>
4204
4205      <para>
4206        The following registers are available to set the rate:
4207      <constant>AC97_PCM_MIC_ADC_RATE</constant>,
4208      <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
4209      <constant>AC97_PCM_LR_ADC_RATE</constant>,
4210      <constant>AC97_SPDIF</constant>. When
4211      <constant>AC97_SPDIF</constant> is specified, the register is
4212      not really changed but the corresponding IEC958 status bits will
4213      be updated. 
4214      </para>
4215    </section>
4216
4217    <section id="api-ac97-clock-adjustment">
4218      <title>Clock Adjustment</title>
4219      <para>
4220        In some chips, the clock of the codec isn't 48000 but using a
4221      PCI clock (to save a quartz!). In this case, change the field
4222      bus-&gt;clock to the corresponding
4223      value. For example, intel8x0 
4224      and es1968 drivers have their own function to read from the clock.
4225      </para>
4226    </section>
4227
4228    <section id="api-ac97-proc-files">
4229      <title>Proc Files</title>
4230      <para>
4231        The ALSA AC97 interface will create a proc file such as
4232      <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
4233      <filename>ac97#0-0+regs</filename>. You can refer to these files to
4234      see the current status and registers of the codec. 
4235      </para>
4236    </section>
4237
4238    <section id="api-ac97-multiple-codecs">
4239      <title>Multiple Codecs</title>
4240      <para>
4241        When there are several codecs on the same card, you need to
4242      call <function>snd_ac97_mixer()</function> multiple times with
4243      ac97.num=1 or greater. The <structfield>num</structfield> field
4244      specifies the codec number. 
4245      </para>
4246
4247      <para>
4248        If you set up multiple codecs, you either need to write
4249      different callbacks for each codec or check
4250      ac97-&gt;num in the callback routines. 
4251      </para>
4252    </section>
4253
4254  </chapter>
4255
4256
4257<!-- ****************************************************** -->
4258<!-- MIDI (MPU401-UART) Interface  -->
4259<!-- ****************************************************** -->
4260  <chapter id="midi-interface">
4261    <title>MIDI (MPU401-UART) Interface</title>
4262
4263    <section id="midi-interface-general">
4264      <title>General</title>
4265      <para>
4266        Many soundcards have built-in MIDI (MPU401-UART)
4267      interfaces. When the soundcard supports the standard MPU401-UART
4268      interface, most likely you can use the ALSA MPU401-UART API. The
4269      MPU401-UART API is defined in
4270      <filename>&lt;sound/mpu401.h&gt;</filename>. 
4271      </para>
4272
4273      <para>
4274        Some soundchips have a similar but slightly different
4275      implementation of mpu401 stuff. For example, emu10k1 has its own
4276      mpu401 routines. 
4277      </para>
4278    </section>
4279
4280    <section id="midi-interface-constructor">
4281      <title>Constructor</title>
4282      <para>
4283        To create a rawmidi object, call
4284      <function>snd_mpu401_uart_new()</function>. 
4285
4286        <informalexample>
4287          <programlisting>
4288<![CDATA[
4289  struct snd_rawmidi *rmidi;
4290  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
4291                      irq, &rmidi);
4292]]>
4293          </programlisting>
4294        </informalexample>
4295      </para>
4296
4297      <para>
4298        The first argument is the card pointer, and the second is the
4299      index of this component. You can create up to 8 rawmidi
4300      devices. 
4301      </para>
4302
4303      <para>
4304        The third argument is the type of the hardware,
4305      <constant>MPU401_HW_XXX</constant>. If it's not a special one,
4306      you can use <constant>MPU401_HW_MPU401</constant>. 
4307      </para>
4308
4309      <para>
4310        The 4th argument is the I/O port address. Many
4311      backward-compatible MPU401 have an I/O port such as 0x330. Or, it
4312      might be a part of its own PCI I/O region. It depends on the
4313      chip design. 
4314      </para>
4315
4316      <para>
4317        The 5th argument is a bitflag for additional information.
4318        When the I/O port address above is part of the PCI I/O
4319      region, the MPU401 I/O port might have been already allocated
4320      (reserved) by the driver itself. In such a case, pass a bit flag
4321      <constant>MPU401_INFO_INTEGRATED</constant>,
4322      and the mpu401-uart layer will allocate the I/O ports by itself. 
4323      </para>
4324
4325        <para>
4326        When the controller supports only the input or output MIDI stream,
4327        pass the <constant>MPU401_INFO_INPUT</constant> or
4328        <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
4329        Then the rawmidi instance is created as a single stream.
4330        </para>
4331
4332        <para>
4333        <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
4334        the access method to MMIO (via readb and writeb) instead of
4335        iob and outb. In this case, you have to pass the iomapped address
4336        to <function>snd_mpu401_uart_new()</function>.
4337        </para>
4338
4339        <para>
4340        When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
4341        stream isn't checked in the default interrupt handler.  The driver
4342        needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
4343        by itself to start processing the output stream in the irq handler.
4344        </para>
4345
4346        <para>
4347        If the MPU-401 interface shares its interrupt with the other logical
4348        devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
4349        (see <link linkend="midi-interface-interrupt-handler"><citetitle>
4350        below</citetitle></link>).
4351        </para>
4352
4353      <para>
4354        Usually, the port address corresponds to the command port and
4355        port + 1 corresponds to the data port. If not, you may change
4356        the <structfield>cport</structfield> field of
4357        struct <structname>snd_mpu401</structname> manually 
4358        afterward. However, <structname>snd_mpu401</structname> pointer is not
4359        returned explicitly by
4360        <function>snd_mpu401_uart_new()</function>. You need to cast
4361        rmidi-&gt;private_data to
4362        <structname>snd_mpu401</structname> explicitly, 
4363
4364        <informalexample>
4365          <programlisting>
4366<![CDATA[
4367  struct snd_mpu401 *mpu;
4368  mpu = rmidi->private_data;
4369]]>
4370          </programlisting>
4371        </informalexample>
4372
4373        and reset the cport as you like:
4374
4375        <informalexample>
4376          <programlisting>
4377<![CDATA[
4378  mpu->cport = my_own_control_port;
4379]]>
4380          </programlisting>
4381        </informalexample>
4382      </para>
4383
4384      <para>
4385        The 6th argument specifies the ISA irq number that will be
4386        allocated.  If no interrupt is to be allocated (because your
4387        code is already allocating a shared interrupt, or because the
4388        device does not use interrupts), pass -1 instead.
4389        For a MPU-401 device without an interrupt, a polling timer
4390        will be used instead.
4391      </para>
4392    </section>
4393
4394    <section id="midi-interface-interrupt-handler">
4395      <title>Interrupt Handler</title>
4396      <para>
4397        When the interrupt is allocated in
4398      <function>snd_mpu401_uart_new()</function>, an exclusive ISA
4399      interrupt handler is automatically used, hence you don't have
4400      anything else to do than creating the mpu401 stuff.  Otherwise, you
4401      have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
4402      <function>snd_mpu401_uart_interrupt()</function> explicitly from your
4403      own interrupt handler when it has determined that a UART interrupt
4404      has occurred.
4405      </para>
4406
4407      <para>
4408        In this case, you need to pass the private_data of the
4409        returned rawmidi object from
4410        <function>snd_mpu401_uart_new()</function> as the second
4411        argument of <function>snd_mpu401_uart_interrupt()</function>. 
4412
4413        <informalexample>
4414          <programlisting>
4415<![CDATA[
4416  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
4417]]>
4418          </programlisting>
4419        </informalexample>
4420      </para>
4421    </section>
4422
4423  </chapter>
4424
4425
4426<!-- ****************************************************** -->
4427<!-- RawMIDI Interface  -->
4428<!-- ****************************************************** -->
4429  <chapter id="rawmidi-interface">
4430    <title>RawMIDI Interface</title>
4431
4432    <section id="rawmidi-interface-overview">
4433      <title>Overview</title>
4434
4435      <para>
4436      The raw MIDI interface is used for hardware MIDI ports that can
4437      be accessed as a byte stream.  It is not used for synthesizer
4438      chips that do not directly understand MIDI.
4439      </para>
4440
4441      <para>
4442      ALSA handles file and buffer management.  All you have to do is
4443      to write some code to move data between the buffer and the
4444      hardware.
4445      </para>
4446
4447      <para>
4448      The rawmidi API is defined in
4449      <filename>&lt;sound/rawmidi.h&gt;</filename>.
4450      </para>
4451    </section>
4452
4453    <section id="rawmidi-interface-constructor">
4454      <title>Constructor</title>
4455
4456      <para>
4457      To create a rawmidi device, call the
4458      <function>snd_rawmidi_new</function> function:
4459        <informalexample>
4460          <programlisting>
4461<![CDATA[
4462  struct snd_rawmidi *rmidi;
4463  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
4464  if (err < 0)
4465          return err;
4466  rmidi->private_data = chip;
4467  strcpy(rmidi->name, "My MIDI");
4468  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
4469                      SNDRV_RAWMIDI_INFO_INPUT |
4470                      SNDRV_RAWMIDI_INFO_DUPLEX;
4471]]>
4472          </programlisting>
4473        </informalexample>
4474      </para>
4475
4476      <para>
4477      The first argument is the card pointer, the second argument is
4478      the ID string.
4479      </para>
4480
4481      <para>
4482      The third argument is the index of this component.  You can
4483      create up to 8 rawmidi devices.
4484      </para>
4485
4486      <para>
4487      The fourth and fifth arguments are the number of output and
4488      input substreams, respectively, of this device (a substream is
4489      the equivalent of a MIDI port).
4490      </para>
4491
4492      <para>
4493      Set the <structfield>info_flags</structfield> field to specify
4494      the capabilities of the device.
4495      Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
4496      at least one output port,
4497      <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
4498      least one input port,
4499      and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
4500      can handle output and input at the same time.
4501      </para>
4502
4503      <para>
4504      After the rawmidi device is created, you need to set the
4505      operators (callbacks) for each substream.  There are helper
4506      functions to set the operators for all the substreams of a device:
4507        <informalexample>
4508          <programlisting>
4509<![CDATA[
4510  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
4511  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
4512]]>
4513          </programlisting>
4514        </informalexample>
4515      </para>
4516
4517      <para>
4518      The operators are usually defined like this:
4519        <informalexample>
4520          <programlisting>
4521<![CDATA[
4522  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
4523          .open =    snd_mymidi_output_open,
4524          .close =   snd_mymidi_output_close,
4525          .trigger = snd_mymidi_output_trigger,
4526  };
4527]]>
4528          </programlisting>
4529        </informalexample>
4530      These callbacks are explained in the <link
4531      linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
4532      section.
4533      </para>
4534
4535      <para>
4536      If there are more than one substream, you should give a
4537      unique name to each of them:
4538        <informalexample>
4539          <programlisting>
4540<![CDATA[
4541  struct snd_rawmidi_substream *substream;
4542  list_for_each_entry(substream,
4543                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
4544                      list {
4545          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
4546  }
4547  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
4548]]>
4549          </programlisting>
4550        </informalexample>
4551      </para>
4552    </section>
4553
4554    <section id="rawmidi-interface-callbacks">
4555      <title>Callbacks</title>
4556
4557      <para>
4558      In all the callbacks, the private data that you've set for the
4559      rawmidi device can be accessed as
4560      substream-&gt;rmidi-&gt;private_data.
4561      <!-- <code> isn't available before DocBook 4.3 -->
4562      </para>
4563
4564      <para>
4565      If there is more than one port, your callbacks can determine the
4566      port index from the struct snd_rawmidi_substream data passed to each
4567      callback:
4568        <informalexample>
4569          <programlisting>
4570<![CDATA[
4571  struct snd_rawmidi_substream *substream;
4572  int index = substream->number;
4573]]>
4574          </programlisting>
4575        </informalexample>
4576      </para>
4577
4578      <section id="rawmidi-interface-op-open">
4579      <title><function>open</function> callback</title>
4580
4581        <informalexample>
4582          <programlisting>
4583<![CDATA[
4584  static int snd_xxx_open(struct snd_rawmidi_substream *substream);
4585]]>
4586          </programlisting>
4587        </informalexample>
4588
4589        <para>
4590        This is called when a substream is opened.
4591        You can initialize the hardware here, but you shouldn't
4592        start transmitting/receiving data yet.
4593        </para>
4594      </section>
4595
4596      <section id="rawmidi-interface-op-close">
4597      <title><function>close</function> callback</title>
4598
4599        <informalexample>
4600          <programlisting>
4601<![CDATA[
4602  static int snd_xxx_close(struct snd_rawmidi_substream *substream);
4603]]>
4604          </programlisting>
4605        </informalexample>
4606
4607        <para>
4608        Guess what.
4609        </para>
4610
4611        <para>
4612        The <function>open</function> and <function>close</function>
4613        callbacks of a rawmidi device are serialized with a mutex,
4614        and can sleep.
4615        </para>
4616      </section>
4617
4618      <section id="rawmidi-interface-op-trigger-out">
4619      <title><function>trigger</function> callback for output
4620      substreams</title>
4621
4622        <informalexample>
4623          <programlisting>
4624<![CDATA[
4625  static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
4626]]>
4627          </programlisting>
4628        </informalexample>
4629
4630        <para>
4631        This is called with a nonzero <parameter>up</parameter>
4632        parameter when there is some data in the substream buffer that
4633        must be transmitted.
4634        </para>
4635
4636        <para>
4637        To read data from the buffer, call
4638        <function>snd_rawmidi_transmit_peek</function>.  It will
4639        return the number of bytes that have been read; this will be
4640        less than the number of bytes requested when there are no more
4641        data in the buffer.
4642        After the data have been transmitted successfully, call
4643        <function>snd_rawmidi_transmit_ack</function> to remove the
4644        data from the substream buffer:
4645          <informalexample>
4646            <programlisting>
4647<![CDATA[
4648  unsigned char data;
4649  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
4650          if (snd_mychip_try_to_transmit(data))
4651                  snd_rawmidi_transmit_ack(substream, 1);
4652          else
4653                  break; /* hardware FIFO full */
4654  }
4655]]>
4656            </programlisting>
4657          </informalexample>
4658        </para>
4659
4660        <para>
4661        If you know beforehand that the hardware will accept data, you
4662        can use the <function>snd_rawmidi_transmit</function> function
4663        which reads some data and removes them from the buffer at once:
4664          <informalexample>
4665            <programlisting>
4666<![CDATA[
4667  while (snd_mychip_transmit_possible()) {
4668          unsigned char data;
4669          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
4670                  break; /* no more data */
4671          snd_mychip_transmit(data);
4672  }
4673]]>
4674            </programlisting>
4675          </informalexample>
4676        </para>
4677
4678        <para>
4679        If you know beforehand how many bytes you can accept, you can
4680        use a buffer size greater than one with the
4681        <function>snd_rawmidi_transmit*</function> functions.
4682        </para>
4683
4684        <para>
4685        The <function>trigger</function> callback must not sleep.  If
4686        the hardware FIFO is full before the substream buffer has been
4687        emptied, you have to continue transmitting data later, either
4688        in an interrupt handler, or with a timer if the hardware
4689        doesn't have a MIDI transmit interrupt.
4690        </para>
4691
4692        <para>
4693        The <function>trigger</function> callback is called with a
4694        zero <parameter>up</parameter> parameter when the transmission
4695        of data should be aborted.
4696        </para>
4697      </section>
4698
4699      <section id="rawmidi-interface-op-trigger-in">
4700      <title><function>trigger</function> callback for input
4701      substreams</title>
4702
4703        <informalexample>
4704          <programlisting>
4705<![CDATA[
4706  static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
4707]]>
4708          </programlisting>
4709        </informalexample>
4710
4711        <para>
4712        This is called with a nonzero <parameter>up</parameter>
4713        parameter to enable receiving data, or with a zero
4714        <parameter>up</parameter> parameter do disable receiving data.
4715        </para>
4716
4717        <para>
4718        The <function>trigger</function> callback must not sleep; the
4719        actual reading of data from the device is usually done in an
4720        interrupt handler.
4721        </para>
4722
4723        <para>
4724        When data reception is enabled, your interrupt handler should
4725        call <function>snd_rawmidi_receive</function> for all received
4726        data:
4727          <informalexample>
4728            <programlisting>
4729<![CDATA[
4730  void snd_mychip_midi_interrupt(...)
4731  {
4732          while (mychip_midi_available()) {
4733                  unsigned char data;
4734                  data = mychip_midi_read();
4735                  snd_rawmidi_receive(substream, &data, 1);
4736          }
4737  }
4738]]>
4739            </programlisting>
4740          </informalexample>
4741        </para>
4742      </section>
4743
4744      <section id="rawmidi-interface-op-drain">
4745      <title><function>drain</function> callback</title>
4746
4747        <informalexample>
4748          <programlisting>
4749<![CDATA[
4750  static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
4751]]>
4752          </programlisting>
4753        </informalexample>
4754
4755        <para>
4756        This is only used with output substreams.  This function should wait
4757        until all data read from the substream buffer have been transmitted.
4758        This ensures that the device can be closed and the driver unloaded
4759        without losing data.
4760        </para>
4761
4762        <para>
4763        This callback is optional. If you do not set
4764        <structfield>drain</structfield> in the struct snd_rawmidi_ops
4765        structure, ALSA will simply wait for 50&nbsp;milliseconds
4766        instead.
4767        </para>
4768      </section>
4769    </section>
4770
4771  </chapter>
4772
4773
4774<!-- ****************************************************** -->
4775<!-- Miscellaneous Devices  -->
4776<!-- ****************************************************** -->
4777  <chapter id="misc-devices">
4778    <title>Miscellaneous Devices</title>
4779
4780    <section id="misc-devices-opl3">
4781      <title>FM OPL3</title>
4782      <para>
4783        The FM OPL3 is still used in many chips (mainly for backward
4784      compatibility). ALSA has a nice OPL3 FM control layer, too. The
4785      OPL3 API is defined in
4786      <filename>&lt;sound/opl3.h&gt;</filename>. 
4787      </para>
4788
4789      <para>
4790        FM registers can be directly accessed through the direct-FM API,
4791      defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
4792      ALSA native mode, FM registers are accessed through
4793      the Hardware-Dependent Device direct-FM extension API, whereas in
4794      OSS compatible mode, FM registers can be accessed with the OSS
4795      direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 
4796      </para>
4797
4798      <para>
4799        To create the OPL3 component, you have two functions to
4800        call. The first one is a constructor for the <type>opl3_t</type>
4801        instance. 
4802
4803        <informalexample>
4804          <programlisting>
4805<![CDATA[
4806  struct snd_opl3 *opl3;
4807  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
4808                  integrated, &opl3);
4809]]>
4810          </programlisting>
4811        </informalexample>
4812      </para>
4813
4814      <para>
4815        The first argument is the card pointer, the second one is the
4816      left port address, and the third is the right port address. In
4817      most cases, the right port is placed at the left port + 2. 
4818      </para>
4819
4820      <para>
4821        The fourth argument is the hardware type.
4822      </para>
4823
4824      <para>
4825        When the left and right ports have been already allocated by
4826      the card driver, pass non-zero to the fifth argument
4827      (<parameter>integrated</parameter>). Otherwise, the opl3 module will
4828      allocate the specified ports by itself. 
4829      </para>
4830
4831      <para>
4832        When the accessing the hardware requires special method
4833        instead of the standard I/O access, you can create opl3 instance
4834        separately with <function>snd_opl3_new()</function>.
4835
4836        <informalexample>
4837          <programlisting>
4838<![CDATA[
4839  struct snd_opl3 *opl3;
4840  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
4841]]>
4842          </programlisting>
4843        </informalexample>
4844      </para>
4845
4846      <para>
4847        Then set <structfield>command</structfield>,
4848        <structfield>private_data</structfield> and
4849        <structfield>private_free</structfield> for the private
4850        access function, the private data and the destructor.
4851        The l_port and r_port are not necessarily set.  Only the
4852        command must be set properly.  You can retrieve the data
4853        from the opl3-&gt;private_data field.
4854      </para>
4855
4856      <para>
4857        After creating the opl3 instance via <function>snd_opl3_new()</function>,
4858        call <function>snd_opl3_init()</function> to initialize the chip to the
4859        proper state. Note that <function>snd_opl3_create()</function> always
4860        calls it internally.
4861      </para>
4862
4863      <para>
4864        If the opl3 instance is created successfully, then create a
4865        hwdep device for this opl3. 
4866
4867        <informalexample>
4868          <programlisting>
4869<![CDATA[
4870  struct snd_hwdep *opl3hwdep;
4871  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
4872]]>
4873          </programlisting>
4874        </informalexample>
4875      </para>
4876
4877      <para>
4878        The first argument is the <type>opl3_t</type> instance you
4879      created, and the second is the index number, usually 0. 
4880      </para>
4881
4882      <para>
4883        The third argument is the index-offset for the sequencer
4884      client assigned to the OPL3 port. When there is an MPU401-UART,
4885      give 1 for here (UART always takes 0). 
4886      </para>
4887    </section>
4888
4889    <section id="misc-devices-hardware-dependent">
4890      <title>Hardware-Dependent Devices</title>
4891      <para>
4892        Some chips need user-space access for special
4893      controls or for loading the micro code. In such a case, you can
4894      create a hwdep (hardware-dependent) device. The hwdep API is
4895      defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
4896      find examples in opl3 driver or
4897      <filename>isa/sb/sb16_csp.c</filename>. 
4898      </para>
4899
4900      <para>
4901        The creation of the <type>hwdep</type> instance is done via
4902        <function>snd_hwdep_new()</function>. 
4903
4904        <informalexample>
4905          <programlisting>
4906<![CDATA[
4907  struct snd_hwdep *hw;
4908  snd_hwdep_new(card, "My HWDEP", 0, &hw);
4909]]>
4910          </programlisting>
4911        </informalexample>
4912
4913        where the third argument is the index number.
4914      </para>
4915
4916      <para>
4917        You can then pass any pointer value to the
4918        <parameter>private_data</parameter>.
4919        If you assign a private data, you should define the
4920        destructor, too. The destructor function is set in
4921        the <structfield>private_free</structfield> field.  
4922
4923        <informalexample>
4924          <programlisting>
4925<![CDATA[
4926  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
4927  hw->private_data = p;
4928  hw->private_free = mydata_free;
4929]]>
4930          </programlisting>
4931        </informalexample>
4932
4933        and the implementation of the destructor would be:
4934
4935        <informalexample>
4936          <programlisting>
4937<![CDATA[
4938  static void mydata_free(struct snd_hwdep *hw)
4939  {
4940          struct mydata *p = hw->private_data;
4941          kfree(p);
4942  }
4943]]>
4944          </programlisting>
4945        </informalexample>
4946      </para>
4947
4948      <para>
4949        The arbitrary file operations can be defined for this
4950        instance. The file operators are defined in
4951        the <parameter>ops</parameter> table. For example, assume that
4952        this chip needs an ioctl. 
4953
4954        <informalexample>
4955          <programlisting>
4956<![CDATA[
4957  hw->ops.open = mydata_open;
4958  hw->ops.ioctl = mydata_ioctl;
4959  hw->ops.release = mydata_release;
4960]]>
4961          </programlisting>
4962        </informalexample>
4963
4964        And implement the callback functions as you like.
4965      </para>
4966    </section>
4967
4968    <section id="misc-devices-IEC958">
4969      <title>IEC958 (S/PDIF)</title>
4970      <para>
4971        Usually the controls for IEC958 devices are implemented via
4972      the control interface. There is a macro to compose a name string for
4973      IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
4974      defined in <filename>&lt;include/asound.h&gt;</filename>.  
4975      </para>
4976
4977      <para>
4978        There are some standard controls for IEC958 status bits. These
4979      controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
4980      and the size of element is fixed as 4 bytes array
4981      (value.iec958.status[x]). For the <structfield>info</structfield>
4982      callback, you don't specify 
4983      the value field for this type (the count field must be set,
4984      though). 
4985      </para>
4986
4987      <para>
4988        <quote>IEC958 Playback Con Mask</quote> is used to return the
4989      bit-mask for the IEC958 status bits of consumer mode. Similarly,
4990      <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
4991      professional mode. They are read-only controls, and are defined
4992      as MIXER controls (iface =
4993      <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).  
4994      </para>
4995
4996      <para>
4997        Meanwhile, <quote>IEC958 Playback Default</quote> control is
4998      defined for getting and setting the current default IEC958
4999      bits. Note that this one is usually defined as a PCM control
5000      (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
5001      although in some places it's defined as a MIXER control. 
5002      </para>
5003
5004      <para>
5005        In addition, you can define the control switches to
5006      enable/disable or to set the raw bit mode. The implementation
5007      will depend on the chip, but the control should be named as
5008      <quote>IEC958 xxx</quote>, preferably using
5009      the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 
5010      </para>
5011
5012      <para>
5013        You can find several cases, for example,
5014      <filename>pci/emu10k1</filename>,
5015      <filename>pci/ice1712</filename>, or
5016      <filename>pci/cmipci.c</filename>.  
5017      </para>
5018    </section>
5019
5020  </chapter>
5021
5022
5023<!-- ****************************************************** -->
5024<!-- Buffer and Memory Management  -->
5025<!-- ****************************************************** -->
5026  <chapter id="buffer-and-memory">
5027    <title>Buffer and Memory Management</title>
5028
5029    <section id="buffer-and-memory-buffer-types">
5030      <title>Buffer Types</title>
5031      <para>
5032        ALSA provides several different buffer allocation functions
5033      depending on the bus and the architecture. All these have a
5034      consistent API. The allocation of physically-contiguous pages is
5035      done via 
5036      <function>snd_malloc_xxx_pages()</function> function, where xxx
5037      is the bus type. 
5038      </para>
5039
5040      <para>
5041        The allocation of pages with fallback is
5042      <function>snd_malloc_xxx_pages_fallback()</function>. This
5043      function tries to allocate the specified pages but if the pages
5044      are not available, it tries to reduce the page sizes until
5045      enough space is found.
5046      </para>
5047
5048      <para>
5049      The release the pages, call
5050      <function>snd_free_xxx_pages()</function> function. 
5051      </para>
5052
5053      <para>
5054      Usually, ALSA drivers try to allocate and reserve
5055       a large contiguous physical space
5056       at the time the module is loaded for the later use.
5057       This is called <quote>pre-allocation</quote>.
5058       As already written, you can call the following function at 
5059       pcm instance construction time (in the case of PCI bus). 
5060
5061        <informalexample>
5062          <programlisting>
5063<![CDATA[
5064  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
5065                                        snd_dma_pci_data(pci), size, max);
5066]]>
5067          </programlisting>
5068        </informalexample>
5069
5070        where <parameter>size</parameter> is the byte size to be
5071      pre-allocated and the <parameter>max</parameter> is the maximum
5072      size to be changed via the <filename>prealloc</filename> proc file.
5073      The allocator will try to get an area as large as possible
5074      within the given size. 
5075      </para>
5076
5077      <para>
5078      The second argument (type) and the third argument (device pointer)
5079      are dependent on the bus.
5080      In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
5081      as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
5082      For the continuous buffer unrelated to the bus can be pre-allocated
5083      with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5084      <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5085      where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5086      use.
5087      For the PCI scatter-gather buffers, use
5088      <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5089      <function>snd_dma_pci_data(pci)</function>
5090      (see the 
5091          <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
5092          </citetitle></link> section).
5093      </para>
5094
5095      <para>
5096        Once the buffer is pre-allocated, you can use the
5097        allocator in the <structfield>hw_params</structfield> callback: 
5098
5099        <informalexample>
5100          <programlisting>
5101<![CDATA[
5102  snd_pcm_lib_malloc_pages(substream, size);
5103]]>
5104          </programlisting>
5105        </informalexample>
5106
5107        Note that you have to pre-allocate to use this function.
5108      </para>
5109    </section>
5110
5111    <section id="buffer-and-memory-external-hardware">
5112      <title>External Hardware Buffers</title>
5113      <para>
5114        Some chips have their own hardware buffers and the DMA
5115      transfer from the host memory is not available. In such a case,
5116      you need to either 1) copy/set the audio data directly to the
5117      external hardware buffer, or 2) make an intermediate buffer and
5118      copy/set the data from it to the external hardware buffer in
5119      interrupts (or in tasklets, preferably).
5120      </para>
5121
5122      <para>
5123        The first case works fine if the external hardware buffer is large
5124      enough.  This method doesn't need any extra buffers and thus is
5125      more effective. You need to define the
5126      <structfield>copy</structfield> and
5127      <structfield>silence</structfield> callbacks for 
5128      the data transfer. However, there is a drawback: it cannot
5129      be mmapped. The examples are GUS's GF1 PCM or emu8000's
5130      wavetable PCM. 
5131      </para>
5132
5133      <para>
5134        The second case allows for mmap on the buffer, although you have
5135      to handle an interrupt or a tasklet to transfer the data
5136      from the intermediate buffer to the hardware buffer. You can find an
5137      example in the vxpocket driver. 
5138      </para>
5139
5140      <para>
5141        Another case is when the chip uses a PCI memory-map
5142      region for the buffer instead of the host memory. In this case,
5143      mmap is available only on certain architectures like the Intel one.
5144      In non-mmap mode, the data cannot be transferred as in the normal
5145      way. Thus you need to define the <structfield>copy</structfield> and
5146      <structfield>silence</structfield> callbacks as well, 
5147      as in the cases above. The examples are found in
5148      <filename>rme32.c</filename> and <filename>rme96.c</filename>. 
5149      </para>
5150
5151      <para>
5152        The implementation of the <structfield>copy</structfield> and
5153        <structfield>silence</structfield> callbacks depends upon 
5154        whether the hardware supports interleaved or non-interleaved
5155        samples. The <structfield>copy</structfield> callback is
5156        defined like below, a bit 
5157        differently depending whether the direction is playback or
5158        capture: 
5159
5160        <informalexample>
5161          <programlisting>
5162<![CDATA[
5163  static int playback_copy(struct snd_pcm_substream *substream, int channel,
5164               snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
5165  static int capture_copy(struct snd_pcm_substream *substream, int channel,
5166               snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
5167]]>
5168          </programlisting>
5169        </informalexample>
5170      </para>
5171
5172      <para>
5173        In the case of interleaved samples, the second argument
5174      (<parameter>channel</parameter>) is not used. The third argument
5175      (<parameter>pos</parameter>) points the 
5176      current position offset in frames. 
5177      </para>
5178
5179      <para>
5180        The meaning of the fourth argument is different between
5181      playback and capture. For playback, it holds the source data
5182      pointer, and for capture, it's the destination data pointer. 
5183      </para>
5184
5185      <para>
5186        The last argument is the number of frames to be copied.
5187      </para>
5188
5189      <para>
5190        What you have to do in this callback is again different
5191        between playback and capture directions. In the
5192        playback case, you copy the given amount of data
5193        (<parameter>count</parameter>) at the specified pointer
5194        (<parameter>src</parameter>) to the specified offset
5195        (<parameter>pos</parameter>) on the hardware buffer. When
5196        coded like memcpy-like way, the copy would be like: 
5197
5198        <informalexample>
5199          <programlisting>
5200<![CDATA[
5201  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
5202            frames_to_bytes(runtime, count));
5203]]>
5204          </programlisting>
5205        </informalexample>
5206      </para>
5207
5208      <para>
5209        For the capture direction, you copy the given amount of
5210        data (<parameter>count</parameter>) at the specified offset
5211        (<parameter>pos</parameter>) on the hardware buffer to the
5212        specified pointer (<parameter>dst</parameter>). 
5213
5214        <informalexample>
5215          <programlisting>
5216<![CDATA[
5217  my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
5218            frames_to_bytes(runtime, count));
5219]]>
5220          </programlisting>
5221        </informalexample>
5222
5223        Note that both the position and the amount of data are given
5224      in frames. 
5225      </para>
5226
5227      <para>
5228        In the case of non-interleaved samples, the implementation
5229      will be a bit more complicated. 
5230      </para>
5231
5232      <para>
5233        You need to check the channel argument, and if it's -1, copy
5234      the whole channels. Otherwise, you have to copy only the
5235      specified channel. Please check
5236      <filename>isa/gus/gus_pcm.c</filename> as an example. 
5237      </para>
5238
5239      <para>
5240        The <structfield>silence</structfield> callback is also
5241        implemented in a similar way. 
5242
5243        <informalexample>
5244          <programlisting>
5245<![CDATA[
5246  static int silence(struct snd_pcm_substream *substream, int channel,
5247                     snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
5248]]>
5249          </programlisting>
5250        </informalexample>
5251      </para>
5252
5253      <para>
5254        The meanings of arguments are the same as in the
5255      <structfield>copy</structfield> 
5256      callback, although there is no <parameter>src/dst</parameter>
5257      argument. In the case of interleaved samples, the channel
5258      argument has no meaning, as well as on
5259      <structfield>copy</structfield> callback.  
5260      </para>
5261
5262      <para>
5263        The role of <structfield>silence</structfield> callback is to
5264        set the given amount 
5265        (<parameter>count</parameter>) of silence data at the
5266        specified offset (<parameter>pos</parameter>) on the hardware
5267        buffer. Suppose that the data format is signed (that is, the
5268        silent-data is 0), and the implementation using a memset-like
5269        function would be like: 
5270
5271        <informalexample>
5272          <programlisting>
5273<![CDATA[
5274  my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
5275            frames_to_bytes(runtime, count));
5276]]>
5277          </programlisting>
5278        </informalexample>
5279      </para>
5280
5281      <para>
5282        In the case of non-interleaved samples, again, the
5283      implementation becomes a bit more complicated. See, for example,
5284      <filename>isa/gus/gus_pcm.c</filename>. 
5285      </para>
5286    </section>
5287
5288    <section id="buffer-and-memory-non-contiguous">
5289      <title>Non-Contiguous Buffers</title>
5290      <para>
5291        If your hardware supports the page table as in emu10k1 or the
5292      buffer descriptors as in via82xx, you can use the scatter-gather
5293      (SG) DMA. ALSA provides an interface for handling SG-buffers.
5294      The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>. 
5295      </para>
5296
5297      <para>
5298        For creating the SG-buffer handler, call
5299        <function>snd_pcm_lib_preallocate_pages()</function> or
5300        <function>snd_pcm_lib_preallocate_pages_for_all()</function>
5301        with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
5302        in the PCM constructor like other PCI pre-allocator.
5303        You need to pass <function>snd_dma_pci_data(pci)</function>,
5304        where pci is the struct <structname>pci_dev</structname> pointer
5305        of the chip as well.
5306        The <type>struct snd_sg_buf</type> instance is created as
5307        substream-&gt;dma_private. You can cast
5308        the pointer like: 
5309
5310        <informalexample>
5311          <programlisting>
5312<![CDATA[
5313  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
5314]]>
5315          </programlisting>
5316        </informalexample>
5317      </para>
5318
5319      <para>
5320        Then call <function>snd_pcm_lib_malloc_pages()</function>
5321      in the <structfield>hw_params</structfield> callback
5322      as well as in the case of normal PCI buffer.
5323      The SG-buffer handler will allocate the non-contiguous kernel
5324      pages of the given size and map them onto the virtually contiguous
5325      memory.  The virtual pointer is addressed in runtime-&gt;dma_area.
5326      The physical address (runtime-&gt;dma_addr) is set to zero,
5327      because the buffer is physically non-contiguous.
5328      The physical address table is set up in sgbuf-&gt;table.
5329      You can get the physical address at a certain offset via
5330      <function>snd_pcm_sgbuf_get_addr()</function>. 
5331      </para>
5332
5333      <para>
5334        When a SG-handler is used, you need to set
5335      <function>snd_pcm_sgbuf_ops_page</function> as
5336      the <structfield>page</structfield> callback.
5337      (See <link linkend="pcm-interface-operators-page-callback">
5338      <citetitle>page callback section</citetitle></link>.)
5339      </para>
5340
5341      <para>
5342        To release the data, call
5343      <function>snd_pcm_lib_free_pages()</function> in the
5344      <structfield>hw_free</structfield> callback as usual.
5345      </para>
5346    </section>
5347
5348    <section id="buffer-and-memory-vmalloced">
5349      <title>Vmalloc'ed Buffers</title>
5350      <para>
5351        It's possible to use a buffer allocated via
5352      <function>vmalloc</function>, for example, for an intermediate
5353      buffer. Since the allocated pages are not contiguous, you need
5354      to set the <structfield>page</structfield> callback to obtain
5355      the physical address at every offset. 
5356      </para>
5357
5358      <para>
5359        The implementation of <structfield>page</structfield> callback
5360        would be like this: 
5361
5362        <informalexample>
5363          <programlisting>
5364<![CDATA[
5365  #include <linux/vmalloc.h>
5366
5367  /* get the physical page pointer on the given offset */
5368  static struct page *mychip_page(struct snd_pcm_substream *substream,
5369                                  unsigned long offset)
5370  {
5371          void *pageptr = substream->runtime->dma_area + offset;
5372          return vmalloc_to_page(pageptr);
5373  }
5374]]>
5375          </programlisting>
5376        </informalexample>
5377      </para>
5378    </section>
5379
5380  </chapter>
5381
5382
5383<!-- ****************************************************** -->
5384<!-- Proc Interface  -->
5385<!-- ****************************************************** -->
5386  <chapter id="proc-interface">
5387    <title>Proc Interface</title>
5388    <para>
5389      ALSA provides an easy interface for procfs. The proc files are
5390      very useful for debugging. I recommend you set up proc files if
5391      you write a driver and want to get a running status or register
5392      dumps. The API is found in
5393      <filename>&lt;sound/info.h&gt;</filename>. 
5394    </para>
5395
5396    <para>
5397      To create a proc file, call
5398      <function>snd_card_proc_new()</function>. 
5399
5400      <informalexample>
5401        <programlisting>
5402<![CDATA[
5403  struct snd_info_entry *entry;
5404  int err = snd_card_proc_new(card, "my-file", &entry);
5405]]>
5406        </programlisting>
5407      </informalexample>
5408
5409      where the second argument specifies the name of the proc file to be
5410    created. The above example will create a file
5411    <filename>my-file</filename> under the card directory,
5412    e.g. <filename>/proc/asound/card0/my-file</filename>. 
5413    </para>
5414
5415    <para>
5416    Like other components, the proc entry created via
5417    <function>snd_card_proc_new()</function> will be registered and
5418    released automatically in the card registration and release
5419    functions.
5420    </para>
5421
5422    <para>
5423      When the creation is successful, the function stores a new
5424    instance in the pointer given in the third argument.
5425    It is initialized as a text proc file for read only.  To use
5426    this proc file as a read-only text file as it is, set the read
5427    callback with a private data via 
5428     <function>snd_info_set_text_ops()</function>.
5429
5430      <informalexample>
5431        <programlisting>
5432<![CDATA[
5433  snd_info_set_text_ops(entry, chip, my_proc_read);
5434]]>
5435        </programlisting>
5436      </informalexample>
5437    
5438    where the second argument (<parameter>chip</parameter>) is the
5439    private data to be used in the callbacks. The third parameter
5440    specifies the read buffer size and the fourth
5441    (<parameter>my_proc_read</parameter>) is the callback function, which
5442    is defined like
5443
5444      <informalexample>
5445        <programlisting>
5446<![CDATA[
5447  static void my_proc_read(struct snd_info_entry *entry,
5448                           struct snd_info_buffer *buffer);
5449]]>
5450        </programlisting>
5451      </informalexample>
5452    
5453    </para>
5454
5455    <para>
5456    In the read callback, use <function>snd_iprintf()</function> for
5457    output strings, which works just like normal
5458    <function>printf()</function>.  For example,
5459
5460      <informalexample>
5461        <programlisting>
5462<![CDATA[
5463  static void my_proc_read(struct snd_info_entry *entry,
5464                           struct snd_info_buffer *buffer)
5465  {
5466          struct my_chip *chip = entry->private_data;
5467
5468          snd_iprintf(buffer, "This is my chip!\n");
5469          snd_iprintf(buffer, "Port = %ld\n", chip->port);
5470  }
5471]]>
5472        </programlisting>
5473      </informalexample>
5474    </para>
5475
5476    <para>
5477    The file permissions can be changed afterwards.  As default, it's
5478    set as read only for all users.  If you want to add write
5479    permission for the user (root as default), do as follows:
5480
5481      <informalexample>
5482        <programlisting>
5483<![CDATA[
5484 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
5485]]>
5486        </programlisting>
5487      </informalexample>
5488
5489    and set the write buffer size and the callback
5490
5491      <informalexample>
5492        <programlisting>
5493<![CDATA[
5494  entry->c.text.write = my_proc_write;
5495]]>
5496        </programlisting>
5497      </informalexample>
5498    </para>
5499
5500    <para>
5501      For the write callback, you can use
5502    <function>snd_info_get_line()</function> to get a text line, and
5503    <function>snd_info_get_str()</function> to retrieve a string from
5504    the line. Some examples are found in
5505    <filename>core/oss/mixer_oss.c</filename>, core/oss/and
5506    <filename>pcm_oss.c</filename>. 
5507    </para>
5508
5509    <para>
5510      For a raw-data proc-file, set the attributes as follows:
5511
5512      <informalexample>
5513        <programlisting>
5514<![CDATA[
5515  static struct snd_info_entry_ops my_file_io_ops = {
5516          .read = my_file_io_read,
5517  };
5518
5519  entry->content = SNDRV_INFO_CONTENT_DATA;
5520  entry->private_data = chip;
5521  entry->c.ops = &my_file_io_ops;
5522  entry->size = 4096;
5523  entry->mode = S_IFREG | S_IRUGO;
5524]]>
5525        </programlisting>
5526      </informalexample>
5527
5528      For the raw data, <structfield>size</structfield> field must be
5529      set properly.  This specifies the maximum size of the proc file access.
5530    </para>
5531
5532    <para>
5533      The read/write callbacks of raw mode are more direct than the text mode.
5534      You need to use a low-level I/O functions such as
5535      <function>copy_from/to_user()</function> to transfer the
5536      data.
5537
5538      <informalexample>
5539        <programlisting>
5540<![CDATA[
5541  static ssize_t my_file_io_read(struct snd_info_entry *entry,
5542                              void *file_private_data,
5543                              struct file *file,
5544                              char *buf,
5545                              size_t count,
5546                              loff_t pos)
5547  {
5548          if (copy_to_user(buf, local_data + pos, count))
5549                  return -EFAULT;
5550          return count;
5551  }
5552]]>
5553        </programlisting>
5554      </informalexample>
5555
5556      If the size of the info entry has been set up properly,
5557      <structfield>count</structfield> and <structfield>pos</structfield> are
5558      guaranteed to fit within 0 and the given size.
5559      You don't have to check the range in the callbacks unless any
5560      other condition is required.
5561
5562    </para>
5563
5564  </chapter>
5565
5566
5567<!-- ****************************************************** -->
5568<!-- Power Management  -->
5569<!-- ****************************************************** -->
5570  <chapter id="power-management">
5571    <title>Power Management</title>
5572    <para>
5573      If the chip is supposed to work with suspend/resume
5574      functions, you need to add power-management code to the
5575      driver. The additional code for power-management should be
5576      <function>ifdef</function>'ed with
5577      <constant>CONFIG_PM</constant>. 
5578    </para>
5579
5580        <para>
5581        If the driver <emphasis>fully</emphasis> supports suspend/resume
5582        that is, the device can be
5583        properly resumed to its state when suspend was called,
5584        you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
5585        in the pcm info field.  Usually, this is possible when the
5586        registers of the chip can be safely saved and restored to
5587        RAM. If this is set, the trigger callback is called with
5588        <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
5589        callback completes. 
5590        </para>
5591
5592        <para>
5593        Even if the driver doesn't support PM fully but 
5594        partial suspend/resume is still possible, it's still worthy to
5595        implement suspend/resume callbacks. In such a case, applications
5596        would reset the status by calling
5597        <function>snd_pcm_prepare()</function> and restart the stream
5598        appropriately.  Hence, you can define suspend/resume callbacks
5599        below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
5600        info flag to the PCM.
5601        </para>
5602        
5603        <para>
5604        Note that the trigger with SUSPEND can always be called when
5605        <function>snd_pcm_suspend_all</function> is called,
5606        regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
5607        The <constant>RESUME</constant> flag affects only the behavior
5608        of <function>snd_pcm_resume()</function>.
5609        (Thus, in theory,
5610        <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
5611        to be handled in the trigger callback when no
5612        <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set.  But,
5613        it's better to keep it for compatibility reasons.)
5614        </para>
5615    <para>
5616      In the earlier version of ALSA drivers, a common
5617      power-management layer was provided, but it has been removed.
5618      The driver needs to define the suspend/resume hooks according to
5619      the bus the device is connected to.  In the case of PCI drivers, the
5620      callbacks look like below:
5621
5622      <informalexample>
5623        <programlisting>
5624<![CDATA[
5625  #ifdef CONFIG_PM
5626  static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5627  {
5628          .... /* do things for suspend */
5629          return 0;
5630  }
5631  static int snd_my_resume(struct pci_dev *pci)
5632  {
5633          .... /* do things for suspend */
5634          return 0;
5635  }
5636  #endif
5637]]>
5638        </programlisting>
5639      </informalexample>
5640    </para>
5641
5642    <para>
5643      The scheme of the real suspend job is as follows.
5644
5645      <orderedlist>
5646        <listitem><para>Retrieve the card and the chip data.</para></listitem>
5647        <listitem><para>Call <function>snd_power_change_state()</function> with
5648          <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
5649          power status.</para></listitem>
5650        <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
5651        <listitem><para>If AC97 codecs are used, call
5652        <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
5653        <listitem><para>Save the register values if necessary.</para></listitem>
5654        <listitem><para>Stop the hardware if necessary.</para></listitem>
5655        <listitem><para>Disable the PCI device by calling
5656          <function>pci_disable_device()</function>.  Then, call
5657          <function>pci_save_state()</function> at last.</para></listitem>
5658      </orderedlist>
5659    </para>
5660
5661    <para>
5662      A typical code would be like:
5663
5664      <informalexample>
5665        <programlisting>
5666<![CDATA[
5667  static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
5668  {
5669          /* (1) */
5670          struct snd_card *card = pci_get_drvdata(pci);
5671          struct mychip *chip = card->private_data;
5672          /* (2) */
5673          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
5674          /* (3) */
5675          snd_pcm_suspend_all(chip->pcm);
5676          /* (4) */
5677          snd_ac97_suspend(chip->ac97);
5678          /* (5) */
5679          snd_mychip_save_registers(chip);
5680          /* (6) */
5681          snd_mychip_stop_hardware(chip);
5682          /* (7) */
5683          pci_disable_device(pci);
5684          pci_save_state(pci);
5685          return 0;
5686  }
5687]]>
5688        </programlisting>
5689      </informalexample>
5690    </para>
5691
5692    <para>
5693    The scheme of the real resume job is as follows.
5694
5695    <orderedlist>
5696    <listitem><para>Retrieve the card and the chip data.</para></listitem>
5697    <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
5698        Then enable the pci device again by calling <function>pci_enable_device()</function>.
5699        Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
5700    <listitem><para>Re-initialize the chip.</para></listitem>
5701    <listitem><para>Restore the saved registers if necessary.</para></listitem>
5702    <listitem><para>Resume the mixer, e.g. calling
5703    <function>snd_ac97_resume()</function>.</para></listitem>
5704    <listitem><para>Restart the hardware (if any).</para></listitem>
5705    <listitem><para>Call <function>snd_power_change_state()</function> with
5706        <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
5707    </orderedlist>
5708    </para>
5709
5710    <para>
5711    A typical code would be like:
5712
5713      <informalexample>
5714        <programlisting>
5715<![CDATA[
5716  static int mychip_resume(struct pci_dev *pci)
5717  {
5718          /* (1) */
5719          struct snd_card *card = pci_get_drvdata(pci);
5720          struct mychip *chip = card->private_data;
5721          /* (2) */
5722          pci_restore_state(pci);
5723          pci_enable_device(pci);
5724          pci_set_master(pci);
5725          /* (3) */
5726          snd_mychip_reinit_chip(chip);
5727          /* (4) */
5728          snd_mychip_restore_registers(chip);
5729          /* (5) */
5730          snd_ac97_resume(chip->ac97);
5731          /* (6) */
5732          snd_mychip_restart_chip(chip);
5733          /* (7) */
5734          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
5735          return 0;
5736  }
5737]]>
5738        </programlisting>
5739      </informalexample>
5740    </para>
5741
5742    <para>
5743        As shown in the above, it's better to save registers after
5744        suspending the PCM operations via
5745        <function>snd_pcm_suspend_all()</function> or
5746        <function>snd_pcm_suspend()</function>.  It means that the PCM
5747        streams are already stoppped when the register snapshot is
5748        taken.  But, remember that you don't have to restart the PCM
5749        stream in the resume callback. It'll be restarted via 
5750        trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
5751        when necessary.
5752    </para>
5753
5754    <para>
5755      OK, we have all callbacks now. Let's set them up. In the
5756      initialization of the card, make sure that you can get the chip
5757      data from the card instance, typically via
5758      <structfield>private_data</structfield> field, in case you
5759      created the chip data individually.
5760
5761      <informalexample>
5762        <programlisting>
5763<![CDATA[
5764  static int __devinit snd_mychip_probe(struct pci_dev *pci,
5765                               const struct pci_device_id *pci_id)
5766  {
5767          ....
5768          struct snd_card *card;
5769          struct mychip *chip;
5770          int err;
5771          ....
5772          err = snd_card_create(index[dev], id[dev], THIS_MODULE, 0, &card);
5773          ....
5774          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
5775          ....
5776          card->private_data = chip;
5777          ....
5778  }
5779]]>
5780        </programlisting>
5781      </informalexample>
5782
5783        When you created the chip data with
5784        <function>snd_card_create()</function>, it's anyway accessible
5785        via <structfield>private_data</structfield> field.
5786
5787      <informalexample>
5788        <programlisting>
5789<![CDATA[
5790  static int __devinit snd_mychip_probe(struct pci_dev *pci,
5791                               const struct pci_device_id *pci_id)
5792  {
5793          ....
5794          struct snd_card *card;
5795          struct mychip *chip;
5796          int err;
5797          ....
5798          err = snd_card_create(index[dev], id[dev], THIS_MODULE,
5799                                sizeof(struct mychip), &card);
5800          ....
5801          chip = card->private_data;
5802          ....
5803  }
5804]]>
5805        </programlisting>
5806      </informalexample>
5807
5808    </para>
5809
5810    <para>
5811      If you need a space to save the registers, allocate the
5812        buffer for it here, too, since it would be fatal
5813    if you cannot allocate a memory in the suspend phase.
5814    The allocated buffer should be released in the corresponding
5815    destructor.
5816    </para>
5817
5818    <para>
5819      And next, set suspend/resume callbacks to the pci_driver.
5820
5821      <informalexample>
5822        <programlisting>
5823<![CDATA[
5824  static struct pci_driver driver = {
5825          .name = KBUILD_MODNAME,
5826          .id_table = snd_my_ids,
5827          .probe = snd_my_probe,
5828          .remove = __devexit_p(snd_my_remove),
5829  #ifdef CONFIG_PM
5830          .suspend = snd_my_suspend,
5831          .resume = snd_my_resume,
5832  #endif
5833  };
5834]]>
5835        </programlisting>
5836      </informalexample>
5837    </para>
5838
5839  </chapter>
5840
5841
5842<!-- ****************************************************** -->
5843<!-- Module Parameters  -->
5844<!-- ****************************************************** -->
5845  <chapter id="module-parameters">
5846    <title>Module Parameters</title>
5847    <para>
5848      There are standard module options for ALSA. At least, each
5849      module should have the <parameter>index</parameter>,
5850      <parameter>id</parameter> and <parameter>enable</parameter>
5851      options. 
5852    </para>
5853
5854    <para>
5855      If the module supports multiple cards (usually up to
5856      8 = <constant>SNDRV_CARDS</constant> cards), they should be
5857      arrays. The default initial values are defined already as
5858      constants for easier programming:
5859
5860      <informalexample>
5861        <programlisting>
5862<![CDATA[
5863  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
5864  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
5865  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
5866]]>
5867        </programlisting>
5868      </informalexample>
5869    </para>
5870
5871    <para>
5872      If the module supports only a single card, they could be single
5873    variables, instead.  <parameter>enable</parameter> option is not
5874    always necessary in this case, but it would be better to have a
5875    dummy option for compatibility.
5876    </para>
5877
5878    <para>
5879      The module parameters must be declared with the standard
5880    <function>module_param()()</function>,
5881    <function>module_param_array()()</function> and
5882    <function>MODULE_PARM_DESC()</function> macros.
5883    </para>
5884
5885    <para>
5886      The typical coding would be like below:
5887
5888      <informalexample>
5889        <programlisting>
5890<![CDATA[
5891  #define CARD_NAME "My Chip"
5892
5893  module_param_array(index, int, NULL, 0444);
5894  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
5895  module_param_array(id, charp, NULL, 0444);
5896  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
5897  module_param_array(enable, bool, NULL, 0444);
5898  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
5899]]>
5900        </programlisting>
5901      </informalexample>
5902    </para>
5903
5904    <para>
5905      Also, don't forget to define the module description, classes,
5906      license and devices. Especially, the recent modprobe requires to
5907      define the module license as GPL, etc., otherwise the system is
5908      shown as <quote>tainted</quote>. 
5909
5910      <informalexample>
5911        <programlisting>
5912<![CDATA[
5913  MODULE_DESCRIPTION("My Chip");
5914  MODULE_LICENSE("GPL");
5915  MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
5916]]>
5917        </programlisting>
5918      </informalexample>
5919    </para>
5920
5921  </chapter>
5922
5923
5924<!-- ****************************************************** -->
5925<!-- How To Put Your Driver  -->
5926<!-- ****************************************************** -->
5927  <chapter id="how-to-put-your-driver">
5928    <title>How To Put Your Driver Into ALSA Tree</title>
5929        <section>
5930        <title>General</title>
5931        <para>
5932        So far, you've learned how to write the driver codes.
5933        And you might have a question now: how to put my own
5934        driver into the ALSA driver tree?
5935        Here (finally :) the standard procedure is described briefly.
5936        </para>
5937
5938        <para>
5939        Suppose that you create a new PCI driver for the card
5940        <quote>xyz</quote>.  The card module name would be
5941        snd-xyz.  The new driver is usually put into the alsa-driver
5942        tree, <filename>alsa-driver/pci</filename> directory in
5943        the case of PCI cards.
5944        Then the driver is evaluated, audited and tested
5945        by developers and users.  After a certain time, the driver
5946        will go to the alsa-kernel tree (to the corresponding directory,
5947        such as <filename>alsa-kernel/pci</filename>) and eventually
5948        will be integrated into the Linux 2.6 tree (the directory would be
5949        <filename>linux/sound/pci</filename>).
5950        </para>
5951
5952        <para>
5953        In the following sections, the driver code is supposed
5954        to be put into alsa-driver tree. The two cases are covered:
5955        a driver consisting of a single source file and one consisting
5956        of several source files.
5957        </para>
5958        </section>
5959
5960        <section>
5961        <title>Driver with A Single Source File</title>
5962        <para>
5963        <orderedlist>
5964        <listitem>
5965        <para>
5966        Modify alsa-driver/pci/Makefile
5967        </para>
5968
5969        <para>
5970        Suppose you have a file xyz.c.  Add the following
5971        two lines
5972      <informalexample>
5973        <programlisting>
5974<![CDATA[
5975  snd-xyz-objs := xyz.o
5976  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
5977]]>
5978        </programlisting>
5979      </informalexample>
5980        </para>
5981        </listitem>
5982
5983        <listitem>
5984        <para>
5985        Create the Kconfig entry
5986        </para>
5987
5988        <para>
5989        Add the new entry of Kconfig for your xyz driver.
5990      <informalexample>
5991        <programlisting>
5992<![CDATA[
5993  config SND_XYZ
5994          tristate "Foobar XYZ"
5995          depends on SND
5996          select SND_PCM
5997          help
5998            Say Y here to include support for Foobar XYZ soundcard.
5999
6000            To compile this driver as a module, choose M here: the module
6001            will be called snd-xyz.
6002]]>
6003        </programlisting>
6004      </informalexample>
6005
6006        the line, select SND_PCM, specifies that the driver xyz supports
6007        PCM.  In addition to SND_PCM, the following components are
6008        supported for select command:
6009        SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
6010        SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
6011        Add the select command for each supported component.
6012        </para>
6013
6014        <para>
6015        Note that some selections imply the lowlevel selections.
6016        For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
6017        AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
6018        You don't need to give the lowlevel selections again.
6019        </para>
6020
6021        <para>
6022        For the details of Kconfig script, refer to the kbuild
6023        documentation.
6024        </para>
6025
6026        </listitem>
6027
6028        <listitem>
6029        <para>
6030        Run cvscompile script to re-generate the configure script and
6031        build the whole stuff again.
6032        </para>
6033        </listitem>
6034        </orderedlist>
6035        </para>
6036        </section>
6037
6038        <section>
6039        <title>Drivers with Several Source Files</title>
6040        <para>
6041        Suppose that the driver snd-xyz have several source files.
6042        They are located in the new subdirectory,
6043        pci/xyz.
6044
6045        <orderedlist>
6046        <listitem>
6047        <para>
6048        Add a new directory (<filename>xyz</filename>) in
6049        <filename>alsa-driver/pci/Makefile</filename> as below
6050
6051      <informalexample>
6052        <programlisting>
6053<![CDATA[
6054  obj-$(CONFIG_SND) += xyz/
6055]]>
6056        </programlisting>
6057      </informalexample>
6058        </para>
6059        </listitem>
6060
6061        <listitem>
6062        <para>
6063        Under the directory <filename>xyz</filename>, create a Makefile
6064
6065      <example>
6066        <title>Sample Makefile for a driver xyz</title>
6067        <programlisting>
6068<![CDATA[
6069  ifndef SND_TOPDIR
6070  SND_TOPDIR=../..
6071  endif
6072
6073  include $(SND_TOPDIR)/toplevel.config
6074  include $(SND_TOPDIR)/Makefile.conf
6075
6076  snd-xyz-objs := xyz.o abc.o def.o
6077
6078  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
6079
6080  include $(SND_TOPDIR)/Rules.make
6081]]>
6082        </programlisting>
6083      </example>
6084        </para>
6085        </listitem>
6086
6087        <listitem>
6088        <para>
6089        Create the Kconfig entry
6090        </para>
6091
6092        <para>
6093        This procedure is as same as in the last section.
6094        </para>
6095        </listitem>
6096
6097        <listitem>
6098        <para>
6099        Run cvscompile script to re-generate the configure script and
6100        build the whole stuff again.
6101        </para>
6102        </listitem>
6103        </orderedlist>
6104        </para>
6105        </section>
6106
6107  </chapter>
6108
6109<!-- ****************************************************** -->
6110<!-- Useful Functions  -->
6111<!-- ****************************************************** -->
6112  <chapter id="useful-functions">
6113    <title>Useful Functions</title>
6114
6115    <section id="useful-functions-snd-printk">
6116      <title><function>snd_printk()</function> and friends</title>
6117      <para>
6118        ALSA provides a verbose version of the
6119      <function>printk()</function> function. If a kernel config
6120      <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
6121      function prints the given message together with the file name
6122      and the line of the caller. The <constant>KERN_XXX</constant>
6123      prefix is processed as 
6124      well as the original <function>printk()</function> does, so it's
6125      recommended to add this prefix, e.g. 
6126
6127        <informalexample>
6128          <programlisting>
6129<![CDATA[
6130  snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
6131]]>
6132          </programlisting>
6133        </informalexample>
6134      </para>
6135
6136      <para>
6137        There are also <function>printk()</function>'s for
6138      debugging. <function>snd_printd()</function> can be used for
6139      general debugging purposes. If
6140      <constant>CONFIG_SND_DEBUG</constant> is set, this function is
6141      compiled, and works just like
6142      <function>snd_printk()</function>. If the ALSA is compiled
6143      without the debugging flag, it's ignored. 
6144      </para>
6145
6146      <para>
6147        <function>snd_printdd()</function> is compiled in only when
6148      <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
6149      that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
6150      even if you configure the alsa-driver with
6151      <option>--with-debug=full</option> option. You need to give
6152      explicitly <option>--with-debug=detect</option> option instead. 
6153      </para>
6154    </section>
6155
6156    <section id="useful-functions-snd-bug">
6157      <title><function>snd_BUG()</function></title>
6158      <para>
6159        It shows the <computeroutput>BUG?</computeroutput> message and
6160      stack trace as well as <function>snd_BUG_ON</function> at the point.
6161      It's useful to show that a fatal error happens there. 
6162      </para>
6163      <para>
6164         When no debug flag is set, this macro is ignored. 
6165      </para>
6166    </section>
6167
6168    <section id="useful-functions-snd-bug-on">
6169      <title><function>snd_BUG_ON()</function></title>
6170      <para>
6171        <function>snd_BUG_ON()</function> macro is similar with
6172        <function>WARN_ON()</function> macro. For example,  
6173
6174        <informalexample>
6175          <programlisting>
6176<![CDATA[
6177  snd_BUG_ON(!pointer);
6178]]>
6179          </programlisting>
6180        </informalexample>
6181
6182        or it can be used as the condition,
6183        <informalexample>
6184          <programlisting>
6185<![CDATA[
6186  if (snd_BUG_ON(non_zero_is_bug))
6187          return -EINVAL;
6188]]>
6189          </programlisting>
6190        </informalexample>
6191
6192      </para>
6193
6194      <para>
6195        The macro takes an conditional expression to evaluate.
6196        When <constant>CONFIG_SND_DEBUG</constant>, is set, the
6197        expression is actually evaluated. If it's non-zero, it shows
6198        the warning message such as
6199        <computeroutput>BUG? (xxx)</computeroutput>
6200        normally followed by stack trace.  It returns the evaluated
6201        value.
6202        When no <constant>CONFIG_SND_DEBUG</constant> is set, this
6203        macro always returns zero.
6204      </para>
6205
6206    </section>
6207
6208  </chapter>
6209
6210
6211<!-- ****************************************************** -->
6212<!-- Acknowledgments  -->
6213<!-- ****************************************************** -->
6214  <chapter id="acknowledgments">
6215    <title>Acknowledgments</title>
6216    <para>
6217      I would like to thank Phil Kerr for his help for improvement and
6218      corrections of this document. 
6219    </para>
6220    <para>
6221    Kevin Conder reformatted the original plain-text to the
6222    DocBook format.
6223    </para>
6224    <para>
6225    Giuliano Pochini corrected typos and contributed the example codes
6226    in the hardware constraints section.
6227    </para>
6228  </chapter>
6229</book>
6230
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.