cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

writing-an-alsa-driver.rst (146499B)


      1======================
      2Writing an ALSA Driver
      3======================
      4
      5:Author: Takashi Iwai <tiwai@suse.de>
      6
      7Preface
      8=======
      9
     10This document describes how to write an `ALSA (Advanced Linux Sound
     11Architecture) <http://www.alsa-project.org/>`__ driver. The document
     12focuses mainly on PCI soundcards. In the case of other device types, the
     13API might be different, too. However, at least the ALSA kernel API is
     14consistent, and therefore it would be still a bit help for writing them.
     15
     16This document targets people who already have enough C language skills
     17and have basic linux kernel programming knowledge. This document doesn't
     18explain the general topic of linux kernel coding and doesn't cover
     19low-level driver implementation details. It only describes the standard
     20way to write a PCI sound driver on ALSA.
     21
     22This document is still a draft version. Any feedback and corrections,
     23please!!
     24
     25File Tree Structure
     26===================
     27
     28General
     29-------
     30
     31The file tree structure of ALSA driver is depicted below.
     32
     33::
     34
     35            sound
     36                    /core
     37                            /oss
     38                            /seq
     39                                    /oss
     40                    /include
     41                    /drivers
     42                            /mpu401
     43                            /opl3
     44                    /i2c
     45                    /synth
     46                            /emux
     47                    /pci
     48                            /(cards)
     49                    /isa
     50                            /(cards)
     51                    /arm
     52                    /ppc
     53                    /sparc
     54                    /usb
     55                    /pcmcia /(cards)
     56                    /soc
     57                    /oss
     58
     59
     60core directory
     61--------------
     62
     63This directory contains the middle layer which is the heart of ALSA
     64drivers. In this directory, the native ALSA modules are stored. The
     65sub-directories contain different modules and are dependent upon the
     66kernel config.
     67
     68core/oss
     69~~~~~~~~
     70
     71The codes for PCM and mixer OSS emulation modules are stored in this
     72directory. The rawmidi OSS emulation is included in the ALSA rawmidi
     73code since it's quite small. The sequencer code is stored in
     74``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
     75
     76core/seq
     77~~~~~~~~
     78
     79This directory and its sub-directories are for the ALSA sequencer. This
     80directory contains the sequencer core and primary sequencer modules such
     81like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
     82``CONFIG_SND_SEQUENCER`` is set in the kernel config.
     83
     84core/seq/oss
     85~~~~~~~~~~~~
     86
     87This contains the OSS sequencer emulation codes.
     88
     89include directory
     90-----------------
     91
     92This is the place for the public header files of ALSA drivers, which are
     93to be exported to user-space, or included by several files at different
     94directories. Basically, the private header files should not be placed in
     95this directory, but you may still find files there, due to historical
     96reasons :)
     97
     98drivers directory
     99-----------------
    100
    101This directory contains code shared among different drivers on different
    102architectures. They are hence supposed not to be architecture-specific.
    103For example, the dummy pcm driver and the serial MIDI driver are found
    104in this directory. In the sub-directories, there is code for components
    105which are independent from bus and cpu architectures.
    106
    107drivers/mpu401
    108~~~~~~~~~~~~~~
    109
    110The MPU401 and MPU401-UART modules are stored here.
    111
    112drivers/opl3 and opl4
    113~~~~~~~~~~~~~~~~~~~~~
    114
    115The OPL3 and OPL4 FM-synth stuff is found here.
    116
    117i2c directory
    118-------------
    119
    120This contains the ALSA i2c components.
    121
    122Although there is a standard i2c layer on Linux, ALSA has its own i2c
    123code for some cards, because the soundcard needs only a simple operation
    124and the standard i2c API is too complicated for such a purpose.
    125
    126synth directory
    127---------------
    128
    129This contains the synth middle-level modules.
    130
    131So far, there is only Emu8000/Emu10k1 synth driver under the
    132``synth/emux`` sub-directory.
    133
    134pci directory
    135-------------
    136
    137This directory and its sub-directories hold the top-level card modules
    138for PCI soundcards and the code specific to the PCI BUS.
    139
    140The drivers compiled from a single file are stored directly in the pci
    141directory, while the drivers with several source files are stored on
    142their own sub-directory (e.g. emu10k1, ice1712).
    143
    144isa directory
    145-------------
    146
    147This directory and its sub-directories hold the top-level card modules
    148for ISA soundcards.
    149
    150arm, ppc, and sparc directories
    151-------------------------------
    152
    153They are used for top-level card modules which are specific to one of
    154these architectures.
    155
    156usb directory
    157-------------
    158
    159This directory contains the USB-audio driver. In the latest version, the
    160USB MIDI driver is integrated in the usb-audio driver.
    161
    162pcmcia directory
    163----------------
    164
    165The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
    166be in the pci directory, because their API is identical to that of
    167standard PCI cards.
    168
    169soc directory
    170-------------
    171
    172This directory contains the codes for ASoC (ALSA System on Chip)
    173layer including ASoC core, codec and machine drivers.
    174
    175oss directory
    176-------------
    177
    178Here contains OSS/Lite codes.
    179All codes have been deprecated except for dmasound on m68k as of
    180writing this.
    181
    182
    183Basic Flow for PCI Drivers
    184==========================
    185
    186Outline
    187-------
    188
    189The minimum flow for PCI soundcards is as follows:
    190
    191-  define the PCI ID table (see the section `PCI Entries`_).
    192
    193-  create ``probe`` callback.
    194
    195-  create ``remove`` callback.
    196
    197-  create a struct pci_driver structure
    198   containing the three pointers above.
    199
    200-  create an ``init`` function just calling the
    201   :c:func:`pci_register_driver()` to register the pci_driver
    202   table defined above.
    203
    204-  create an ``exit`` function to call the
    205   :c:func:`pci_unregister_driver()` function.
    206
    207Full Code Example
    208-----------------
    209
    210The code example is shown below. Some parts are kept unimplemented at
    211this moment but will be filled in the next sections. The numbers in the
    212comment lines of the :c:func:`snd_mychip_probe()` function refer
    213to details explained in the following section.
    214
    215::
    216
    217      #include <linux/init.h>
    218      #include <linux/pci.h>
    219      #include <linux/slab.h>
    220      #include <sound/core.h>
    221      #include <sound/initval.h>
    222
    223      /* module parameters (see "Module Parameters") */
    224      /* SNDRV_CARDS: maximum number of cards supported by this module */
    225      static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
    226      static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
    227      static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
    228
    229      /* definition of the chip-specific record */
    230      struct mychip {
    231              struct snd_card *card;
    232              /* the rest of the implementation will be in section
    233               * "PCI Resource Management"
    234               */
    235      };
    236
    237      /* chip-specific destructor
    238       * (see "PCI Resource Management")
    239       */
    240      static int snd_mychip_free(struct mychip *chip)
    241      {
    242              .... /* will be implemented later... */
    243      }
    244
    245      /* component-destructor
    246       * (see "Management of Cards and Components")
    247       */
    248      static int snd_mychip_dev_free(struct snd_device *device)
    249      {
    250              return snd_mychip_free(device->device_data);
    251      }
    252
    253      /* chip-specific constructor
    254       * (see "Management of Cards and Components")
    255       */
    256      static int snd_mychip_create(struct snd_card *card,
    257                                   struct pci_dev *pci,
    258                                   struct mychip **rchip)
    259      {
    260              struct mychip *chip;
    261              int err;
    262              static const struct snd_device_ops ops = {
    263                     .dev_free = snd_mychip_dev_free,
    264              };
    265
    266              *rchip = NULL;
    267
    268              /* check PCI availability here
    269               * (see "PCI Resource Management")
    270               */
    271              ....
    272
    273              /* allocate a chip-specific data with zero filled */
    274              chip = kzalloc(sizeof(*chip), GFP_KERNEL);
    275              if (chip == NULL)
    276                      return -ENOMEM;
    277
    278              chip->card = card;
    279
    280              /* rest of initialization here; will be implemented
    281               * later, see "PCI Resource Management"
    282               */
    283              ....
    284
    285              err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
    286              if (err < 0) {
    287                      snd_mychip_free(chip);
    288                      return err;
    289              }
    290
    291              *rchip = chip;
    292              return 0;
    293      }
    294
    295      /* constructor -- see "Driver Constructor" sub-section */
    296      static int snd_mychip_probe(struct pci_dev *pci,
    297                                  const struct pci_device_id *pci_id)
    298      {
    299              static int dev;
    300              struct snd_card *card;
    301              struct mychip *chip;
    302              int err;
    303
    304              /* (1) */
    305              if (dev >= SNDRV_CARDS)
    306                      return -ENODEV;
    307              if (!enable[dev]) {
    308                      dev++;
    309                      return -ENOENT;
    310              }
    311
    312              /* (2) */
    313              err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
    314                                 0, &card);
    315              if (err < 0)
    316                      return err;
    317
    318              /* (3) */
    319              err = snd_mychip_create(card, pci, &chip);
    320              if (err < 0)
    321                      goto error;
    322
    323              /* (4) */
    324              strcpy(card->driver, "My Chip");
    325              strcpy(card->shortname, "My Own Chip 123");
    326              sprintf(card->longname, "%s at 0x%lx irq %i",
    327                      card->shortname, chip->port, chip->irq);
    328
    329              /* (5) */
    330              .... /* implemented later */
    331
    332              /* (6) */
    333              err = snd_card_register(card);
    334              if (err < 0)
    335                      goto error;
    336
    337              /* (7) */
    338              pci_set_drvdata(pci, card);
    339              dev++;
    340              return 0;
    341
    342      error:
    343              snd_card_free(card);
    344	      return err;
    345      }
    346
    347      /* destructor -- see the "Destructor" sub-section */
    348      static void snd_mychip_remove(struct pci_dev *pci)
    349      {
    350              snd_card_free(pci_get_drvdata(pci));
    351      }
    352
    353
    354
    355Driver Constructor
    356------------------
    357
    358The real constructor of PCI drivers is the ``probe`` callback. The
    359``probe`` callback and other component-constructors which are called
    360from the ``probe`` callback cannot be used with the ``__init`` prefix
    361because any PCI device could be a hotplug device.
    362
    363In the ``probe`` callback, the following scheme is often used.
    364
    3651) Check and increment the device index.
    366~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    367
    368::
    369
    370  static int dev;
    371  ....
    372  if (dev >= SNDRV_CARDS)
    373          return -ENODEV;
    374  if (!enable[dev]) {
    375          dev++;
    376          return -ENOENT;
    377  }
    378
    379
    380where ``enable[dev]`` is the module option.
    381
    382Each time the ``probe`` callback is called, check the availability of
    383the device. If not available, simply increment the device index and
    384returns. dev will be incremented also later (`step 7
    385<7) Set the PCI driver data and return zero._>`__).
    386
    3872) Create a card instance
    388~~~~~~~~~~~~~~~~~~~~~~~~~
    389
    390::
    391
    392  struct snd_card *card;
    393  int err;
    394  ....
    395  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
    396                     0, &card);
    397
    398
    399The details will be explained in the section `Management of Cards and
    400Components`_.
    401
    4023) Create a main component
    403~~~~~~~~~~~~~~~~~~~~~~~~~~
    404
    405In this part, the PCI resources are allocated.
    406
    407::
    408
    409  struct mychip *chip;
    410  ....
    411  err = snd_mychip_create(card, pci, &chip);
    412  if (err < 0)
    413          goto error;
    414
    415The details will be explained in the section `PCI Resource
    416Management`_.
    417
    418When something goes wrong, the probe function needs to deal with the
    419error.  In this example, we have a single error handling path placed
    420at the end of the function.
    421
    422::
    423
    424  error:
    425          snd_card_free(card);
    426	  return err;
    427
    428Since each component can be properly freed, the single
    429:c:func:`snd_card_free()` call should suffice in most cases.
    430
    431
    4324) Set the driver ID and name strings.
    433~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    434
    435::
    436
    437  strcpy(card->driver, "My Chip");
    438  strcpy(card->shortname, "My Own Chip 123");
    439  sprintf(card->longname, "%s at 0x%lx irq %i",
    440          card->shortname, chip->port, chip->irq);
    441
    442The driver field holds the minimal ID string of the chip. This is used
    443by alsa-lib's configurator, so keep it simple but unique. Even the
    444same driver can have different driver IDs to distinguish the
    445functionality of each chip type.
    446
    447The shortname field is a string shown as more verbose name. The longname
    448field contains the information shown in ``/proc/asound/cards``.
    449
    4505) Create other components, such as mixer, MIDI, etc.
    451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    452
    453Here you define the basic components such as `PCM <PCM Interface_>`__,
    454mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
    455`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
    456Also, if you want a `proc file <Proc Interface_>`__, define it here,
    457too.
    458
    4596) Register the card instance.
    460~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    461
    462::
    463
    464  err = snd_card_register(card);
    465  if (err < 0)
    466          goto error;
    467
    468Will be explained in the section `Management of Cards and
    469Components`_, too.
    470
    4717) Set the PCI driver data and return zero.
    472~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    473
    474::
    475
    476  pci_set_drvdata(pci, card);
    477  dev++;
    478  return 0;
    479
    480In the above, the card record is stored. This pointer is used in the
    481remove callback and power-management callbacks, too.
    482
    483Destructor
    484----------
    485
    486The destructor, remove callback, simply releases the card instance. Then
    487the ALSA middle layer will release all the attached components
    488automatically.
    489
    490It would be typically just calling :c:func:`snd_card_free()`:
    491
    492::
    493
    494  static void snd_mychip_remove(struct pci_dev *pci)
    495  {
    496          snd_card_free(pci_get_drvdata(pci));
    497  }
    498
    499
    500The above code assumes that the card pointer is set to the PCI driver
    501data.
    502
    503Header Files
    504------------
    505
    506For the above example, at least the following include files are
    507necessary.
    508
    509::
    510
    511  #include <linux/init.h>
    512  #include <linux/pci.h>
    513  #include <linux/slab.h>
    514  #include <sound/core.h>
    515  #include <sound/initval.h>
    516
    517where the last one is necessary only when module options are defined
    518in the source file. If the code is split into several files, the files
    519without module options don't need them.
    520
    521In addition to these headers, you'll need ``<linux/interrupt.h>`` for
    522interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
    523:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
    524to include ``<linux/delay.h>`` too.
    525
    526The ALSA interfaces like the PCM and control APIs are defined in other
    527``<sound/xxx.h>`` header files. They have to be included after
    528``<sound/core.h>``.
    529
    530Management of Cards and Components
    531==================================
    532
    533Card Instance
    534-------------
    535
    536For each soundcard, a “card” record must be allocated.
    537
    538A card record is the headquarters of the soundcard. It manages the whole
    539list of devices (components) on the soundcard, such as PCM, mixers,
    540MIDI, synthesizer, and so on. Also, the card record holds the ID and the
    541name strings of the card, manages the root of proc files, and controls
    542the power-management states and hotplug disconnections. The component
    543list on the card record is used to manage the correct release of
    544resources at destruction.
    545
    546As mentioned above, to create a card instance, call
    547:c:func:`snd_card_new()`.
    548
    549::
    550
    551  struct snd_card *card;
    552  int err;
    553  err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
    554
    555
    556The function takes six arguments: the parent device pointer, the
    557card-index number, the id string, the module pointer (usually
    558``THIS_MODULE``), the size of extra-data space, and the pointer to
    559return the card instance. The extra_size argument is used to allocate
    560card->private_data for the chip-specific data. Note that these data are
    561allocated by :c:func:`snd_card_new()`.
    562
    563The first argument, the pointer of struct device, specifies the parent
    564device. For PCI devices, typically ``&pci->`` is passed there.
    565
    566Components
    567----------
    568
    569After the card is created, you can attach the components (devices) to
    570the card instance. In an ALSA driver, a component is represented as a
    571struct snd_device object. A component
    572can be a PCM instance, a control interface, a raw MIDI interface, etc.
    573Each such instance has one component entry.
    574
    575A component can be created via :c:func:`snd_device_new()`
    576function.
    577
    578::
    579
    580  snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
    581
    582This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
    583data pointer, and the callback pointers (``&ops``). The device-level
    584defines the type of components and the order of registration and
    585de-registration. For most components, the device-level is already
    586defined. For a user-defined component, you can use
    587``SNDRV_DEV_LOWLEVEL``.
    588
    589This function itself doesn't allocate the data space. The data must be
    590allocated manually beforehand, and its pointer is passed as the
    591argument. This pointer (``chip`` in the above example) is used as the
    592identifier for the instance.
    593
    594Each pre-defined ALSA component such as ac97 and pcm calls
    595:c:func:`snd_device_new()` inside its constructor. The destructor
    596for each component is defined in the callback pointers. Hence, you don't
    597need to take care of calling a destructor for such a component.
    598
    599If you wish to create your own component, you need to set the destructor
    600function to the dev_free callback in the ``ops``, so that it can be
    601released automatically via :c:func:`snd_card_free()`. The next
    602example will show an implementation of chip-specific data.
    603
    604Chip-Specific Data
    605------------------
    606
    607Chip-specific information, e.g. the I/O port address, its resource
    608pointer, or the irq number, is stored in the chip-specific record.
    609
    610::
    611
    612  struct mychip {
    613          ....
    614  };
    615
    616
    617In general, there are two ways of allocating the chip record.
    618
    6191. Allocating via :c:func:`snd_card_new()`.
    620~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    621
    622As mentioned above, you can pass the extra-data-length to the 5th
    623argument of :c:func:`snd_card_new()`, i.e.
    624
    625::
    626
    627  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
    628                     sizeof(struct mychip), &card);
    629
    630struct mychip is the type of the chip record.
    631
    632In return, the allocated record can be accessed as
    633
    634::
    635
    636  struct mychip *chip = card->private_data;
    637
    638With this method, you don't have to allocate twice. The record is
    639released together with the card instance.
    640
    6412. Allocating an extra device.
    642~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    643
    644After allocating a card instance via :c:func:`snd_card_new()`
    645(with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
    646
    647::
    648
    649  struct snd_card *card;
    650  struct mychip *chip;
    651  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
    652                     0, &card);
    653  .....
    654  chip = kzalloc(sizeof(*chip), GFP_KERNEL);
    655
    656The chip record should have the field to hold the card pointer at least,
    657
    658::
    659
    660  struct mychip {
    661          struct snd_card *card;
    662          ....
    663  };
    664
    665
    666Then, set the card pointer in the returned chip instance.
    667
    668::
    669
    670  chip->card = card;
    671
    672Next, initialize the fields, and register this chip record as a
    673low-level device with a specified ``ops``,
    674
    675::
    676
    677  static const struct snd_device_ops ops = {
    678          .dev_free =        snd_mychip_dev_free,
    679  };
    680  ....
    681  snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
    682
    683:c:func:`snd_mychip_dev_free()` is the device-destructor
    684function, which will call the real destructor.
    685
    686::
    687
    688  static int snd_mychip_dev_free(struct snd_device *device)
    689  {
    690          return snd_mychip_free(device->device_data);
    691  }
    692
    693where :c:func:`snd_mychip_free()` is the real destructor.
    694
    695The demerit of this method is the obviously more amount of codes.
    696The merit is, however, you can trigger the own callback at registering
    697and disconnecting the card via setting in snd_device_ops.
    698About the registering and disconnecting the card, see the subsections
    699below.
    700
    701
    702Registration and Release
    703------------------------
    704
    705After all components are assigned, register the card instance by calling
    706:c:func:`snd_card_register()`. Access to the device files is
    707enabled at this point. That is, before
    708:c:func:`snd_card_register()` is called, the components are safely
    709inaccessible from external side. If this call fails, exit the probe
    710function after releasing the card via :c:func:`snd_card_free()`.
    711
    712For releasing the card instance, you can call simply
    713:c:func:`snd_card_free()`. As mentioned earlier, all components
    714are released automatically by this call.
    715
    716For a device which allows hotplugging, you can use
    717:c:func:`snd_card_free_when_closed()`. This one will postpone
    718the destruction until all devices are closed.
    719
    720PCI Resource Management
    721=======================
    722
    723Full Code Example
    724-----------------
    725
    726In this section, we'll complete the chip-specific constructor,
    727destructor and PCI entries. Example code is shown first, below.
    728
    729::
    730
    731      struct mychip {
    732              struct snd_card *card;
    733              struct pci_dev *pci;
    734
    735              unsigned long port;
    736              int irq;
    737      };
    738
    739      static int snd_mychip_free(struct mychip *chip)
    740      {
    741              /* disable hardware here if any */
    742              .... /* (not implemented in this document) */
    743
    744              /* release the irq */
    745              if (chip->irq >= 0)
    746                      free_irq(chip->irq, chip);
    747              /* release the I/O ports & memory */
    748              pci_release_regions(chip->pci);
    749              /* disable the PCI entry */
    750              pci_disable_device(chip->pci);
    751              /* release the data */
    752              kfree(chip);
    753              return 0;
    754      }
    755
    756      /* chip-specific constructor */
    757      static int snd_mychip_create(struct snd_card *card,
    758                                   struct pci_dev *pci,
    759                                   struct mychip **rchip)
    760      {
    761              struct mychip *chip;
    762              int err;
    763              static const struct snd_device_ops ops = {
    764                     .dev_free = snd_mychip_dev_free,
    765              };
    766
    767              *rchip = NULL;
    768
    769              /* initialize the PCI entry */
    770              err = pci_enable_device(pci);
    771              if (err < 0)
    772                      return err;
    773              /* check PCI availability (28bit DMA) */
    774              if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
    775                  pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
    776                      printk(KERN_ERR "error to set 28bit mask DMA\n");
    777                      pci_disable_device(pci);
    778                      return -ENXIO;
    779              }
    780
    781              chip = kzalloc(sizeof(*chip), GFP_KERNEL);
    782              if (chip == NULL) {
    783                      pci_disable_device(pci);
    784                      return -ENOMEM;
    785              }
    786
    787              /* initialize the stuff */
    788              chip->card = card;
    789              chip->pci = pci;
    790              chip->irq = -1;
    791
    792              /* (1) PCI resource allocation */
    793              err = pci_request_regions(pci, "My Chip");
    794              if (err < 0) {
    795                      kfree(chip);
    796                      pci_disable_device(pci);
    797                      return err;
    798              }
    799              chip->port = pci_resource_start(pci, 0);
    800              if (request_irq(pci->irq, snd_mychip_interrupt,
    801                              IRQF_SHARED, KBUILD_MODNAME, chip)) {
    802                      printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
    803                      snd_mychip_free(chip);
    804                      return -EBUSY;
    805              }
    806              chip->irq = pci->irq;
    807              card->sync_irq = chip->irq;
    808
    809              /* (2) initialization of the chip hardware */
    810              .... /*   (not implemented in this document) */
    811
    812              err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
    813              if (err < 0) {
    814                      snd_mychip_free(chip);
    815                      return err;
    816              }
    817
    818              *rchip = chip;
    819              return 0;
    820      }
    821
    822      /* PCI IDs */
    823      static struct pci_device_id snd_mychip_ids[] = {
    824              { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
    825                PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
    826              ....
    827              { 0, }
    828      };
    829      MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
    830
    831      /* pci_driver definition */
    832      static struct pci_driver driver = {
    833              .name = KBUILD_MODNAME,
    834              .id_table = snd_mychip_ids,
    835              .probe = snd_mychip_probe,
    836              .remove = snd_mychip_remove,
    837      };
    838
    839      /* module initialization */
    840      static int __init alsa_card_mychip_init(void)
    841      {
    842              return pci_register_driver(&driver);
    843      }
    844
    845      /* module clean up */
    846      static void __exit alsa_card_mychip_exit(void)
    847      {
    848              pci_unregister_driver(&driver);
    849      }
    850
    851      module_init(alsa_card_mychip_init)
    852      module_exit(alsa_card_mychip_exit)
    853
    854      EXPORT_NO_SYMBOLS; /* for old kernels only */
    855
    856Some Hafta's
    857------------
    858
    859The allocation of PCI resources is done in the ``probe`` function, and
    860usually an extra :c:func:`xxx_create()` function is written for this
    861purpose.
    862
    863In the case of PCI devices, you first have to call the
    864:c:func:`pci_enable_device()` function before allocating
    865resources. Also, you need to set the proper PCI DMA mask to limit the
    866accessed I/O range. In some cases, you might need to call
    867:c:func:`pci_set_master()` function, too.
    868
    869Suppose the 28bit mask, and the code to be added would be like:
    870
    871::
    872
    873  err = pci_enable_device(pci);
    874  if (err < 0)
    875          return err;
    876  if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
    877      pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
    878          printk(KERN_ERR "error to set 28bit mask DMA\n");
    879          pci_disable_device(pci);
    880          return -ENXIO;
    881  }
    882  
    883
    884Resource Allocation
    885-------------------
    886
    887The allocation of I/O ports and irqs is done via standard kernel
    888functions.  These resources must be released in the destructor
    889function (see below).
    890
    891Now assume that the PCI device has an I/O port with 8 bytes and an
    892interrupt. Then struct mychip will have the
    893following fields:
    894
    895::
    896
    897  struct mychip {
    898          struct snd_card *card;
    899
    900          unsigned long port;
    901          int irq;
    902  };
    903
    904
    905For an I/O port (and also a memory region), you need to have the
    906resource pointer for the standard resource management. For an irq, you
    907have to keep only the irq number (integer). But you need to initialize
    908this number as -1 before actual allocation, since irq 0 is valid. The
    909port address and its resource pointer can be initialized as null by
    910:c:func:`kzalloc()` automatically, so you don't have to take care of
    911resetting them.
    912
    913The allocation of an I/O port is done like this:
    914
    915::
    916
    917  err = pci_request_regions(pci, "My Chip");
    918  if (err < 0) { 
    919          kfree(chip);
    920          pci_disable_device(pci);
    921          return err;
    922  }
    923  chip->port = pci_resource_start(pci, 0);
    924
    925It will reserve the I/O port region of 8 bytes of the given PCI device.
    926The returned value, ``chip->res_port``, is allocated via
    927:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
    928must be released via :c:func:`kfree()`, but there is a problem with
    929this. This issue will be explained later.
    930
    931The allocation of an interrupt source is done like this:
    932
    933::
    934
    935  if (request_irq(pci->irq, snd_mychip_interrupt,
    936                  IRQF_SHARED, KBUILD_MODNAME, chip)) {
    937          printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
    938          snd_mychip_free(chip);
    939          return -EBUSY;
    940  }
    941  chip->irq = pci->irq;
    942
    943where :c:func:`snd_mychip_interrupt()` is the interrupt handler
    944defined `later <PCM Interrupt Handler_>`__. Note that
    945``chip->irq`` should be defined only when :c:func:`request_irq()`
    946succeeded.
    947
    948On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
    949as the interrupt flag of :c:func:`request_irq()`.
    950
    951The last argument of :c:func:`request_irq()` is the data pointer
    952passed to the interrupt handler. Usually, the chip-specific record is
    953used for that, but you can use what you like, too.
    954
    955I won't give details about the interrupt handler at this point, but at
    956least its appearance can be explained now. The interrupt handler looks
    957usually like the following:
    958
    959::
    960
    961  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
    962  {
    963          struct mychip *chip = dev_id;
    964          ....
    965          return IRQ_HANDLED;
    966  }
    967
    968After requesting the IRQ, you can passed it to ``card->sync_irq``
    969field:
    970::
    971
    972          card->irq = chip->irq;
    973
    974This allows PCM core automatically performing
    975:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
    976See the later section `sync_stop callback`_ for details.
    977
    978Now let's write the corresponding destructor for the resources above.
    979The role of destructor is simple: disable the hardware (if already
    980activated) and release the resources. So far, we have no hardware part,
    981so the disabling code is not written here.
    982
    983To release the resources, the “check-and-release” method is a safer way.
    984For the interrupt, do like this:
    985
    986::
    987
    988  if (chip->irq >= 0)
    989          free_irq(chip->irq, chip);
    990
    991Since the irq number can start from 0, you should initialize
    992``chip->irq`` with a negative value (e.g. -1), so that you can check
    993the validity of the irq number as above.
    994
    995When you requested I/O ports or memory regions via
    996:c:func:`pci_request_region()` or
    997:c:func:`pci_request_regions()` like in this example, release the
    998resource(s) using the corresponding function,
    999:c:func:`pci_release_region()` or
   1000:c:func:`pci_release_regions()`.
   1001
   1002::
   1003
   1004  pci_release_regions(chip->pci);
   1005
   1006When you requested manually via :c:func:`request_region()` or
   1007:c:func:`request_mem_region()`, you can release it via
   1008:c:func:`release_resource()`. Suppose that you keep the resource
   1009pointer returned from :c:func:`request_region()` in
   1010chip->res_port, the release procedure looks like:
   1011
   1012::
   1013
   1014  release_and_free_resource(chip->res_port);
   1015
   1016Don't forget to call :c:func:`pci_disable_device()` before the
   1017end.
   1018
   1019And finally, release the chip-specific record.
   1020
   1021::
   1022
   1023  kfree(chip);
   1024
   1025We didn't implement the hardware disabling part in the above. If you
   1026need to do this, please note that the destructor may be called even
   1027before the initialization of the chip is completed. It would be better
   1028to have a flag to skip hardware disabling if the hardware was not
   1029initialized yet.
   1030
   1031When the chip-data is assigned to the card using
   1032:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
   1033destructor is called at the last. That is, it is assured that all other
   1034components like PCMs and controls have already been released. You don't
   1035have to stop PCMs, etc. explicitly, but just call low-level hardware
   1036stopping.
   1037
   1038The management of a memory-mapped region is almost as same as the
   1039management of an I/O port. You'll need three fields like the
   1040following:
   1041
   1042::
   1043
   1044  struct mychip {
   1045          ....
   1046          unsigned long iobase_phys;
   1047          void __iomem *iobase_virt;
   1048  };
   1049
   1050and the allocation would be like below:
   1051
   1052::
   1053
   1054  err = pci_request_regions(pci, "My Chip");
   1055  if (err < 0) {
   1056          kfree(chip);
   1057          return err;
   1058  }
   1059  chip->iobase_phys = pci_resource_start(pci, 0);
   1060  chip->iobase_virt = ioremap(chip->iobase_phys,
   1061                                      pci_resource_len(pci, 0));
   1062
   1063and the corresponding destructor would be:
   1064
   1065::
   1066
   1067  static int snd_mychip_free(struct mychip *chip)
   1068  {
   1069          ....
   1070          if (chip->iobase_virt)
   1071                  iounmap(chip->iobase_virt);
   1072          ....
   1073          pci_release_regions(chip->pci);
   1074          ....
   1075  }
   1076
   1077Of course, a modern way with :c:func:`pci_iomap()` will make things a
   1078bit easier, too.
   1079
   1080::
   1081
   1082  err = pci_request_regions(pci, "My Chip");
   1083  if (err < 0) {
   1084          kfree(chip);
   1085          return err;
   1086  }
   1087  chip->iobase_virt = pci_iomap(pci, 0, 0);
   1088
   1089which is paired with :c:func:`pci_iounmap()` at destructor.
   1090
   1091
   1092PCI Entries
   1093-----------
   1094
   1095So far, so good. Let's finish the missing PCI stuff. At first, we need a
   1096struct pci_device_id table for
   1097this chipset. It's a table of PCI vendor/device ID number, and some
   1098masks.
   1099
   1100For example,
   1101
   1102::
   1103
   1104  static struct pci_device_id snd_mychip_ids[] = {
   1105          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
   1106            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
   1107          ....
   1108          { 0, }
   1109  };
   1110  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
   1111
   1112The first and second fields of the struct pci_device_id are the vendor
   1113and device IDs. If you have no reason to filter the matching devices, you can
   1114leave the remaining fields as above. The last field of the
   1115struct pci_device_id contains private data for this entry. You can specify
   1116any value here, for example, to define specific operations for supported
   1117device IDs. Such an example is found in the intel8x0 driver.
   1118
   1119The last entry of this list is the terminator. You must specify this
   1120all-zero entry.
   1121
   1122Then, prepare the struct pci_driver
   1123record:
   1124
   1125::
   1126
   1127  static struct pci_driver driver = {
   1128          .name = KBUILD_MODNAME,
   1129          .id_table = snd_mychip_ids,
   1130          .probe = snd_mychip_probe,
   1131          .remove = snd_mychip_remove,
   1132  };
   1133
   1134The ``probe`` and ``remove`` functions have already been defined in
   1135the previous sections. The ``name`` field is the name string of this
   1136device. Note that you must not use a slash “/” in this string.
   1137
   1138And at last, the module entries:
   1139
   1140::
   1141
   1142  static int __init alsa_card_mychip_init(void)
   1143  {
   1144          return pci_register_driver(&driver);
   1145  }
   1146
   1147  static void __exit alsa_card_mychip_exit(void)
   1148  {
   1149          pci_unregister_driver(&driver);
   1150  }
   1151
   1152  module_init(alsa_card_mychip_init)
   1153  module_exit(alsa_card_mychip_exit)
   1154
   1155Note that these module entries are tagged with ``__init`` and ``__exit``
   1156prefixes.
   1157
   1158That's all!
   1159
   1160PCM Interface
   1161=============
   1162
   1163General
   1164-------
   1165
   1166The PCM middle layer of ALSA is quite powerful and it is only necessary
   1167for each driver to implement the low-level functions to access its
   1168hardware.
   1169
   1170For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
   1171first. In addition, ``<sound/pcm_params.h>`` might be needed if you
   1172access to some functions related with hw_param.
   1173
   1174Each card device can have up to four pcm instances. A pcm instance
   1175corresponds to a pcm device file. The limitation of number of instances
   1176comes only from the available bit size of the Linux's device numbers.
   1177Once when 64bit device number is used, we'll have more pcm instances
   1178available.
   1179
   1180A pcm instance consists of pcm playback and capture streams, and each
   1181pcm stream consists of one or more pcm substreams. Some soundcards
   1182support multiple playback functions. For example, emu10k1 has a PCM
   1183playback of 32 stereo substreams. In this case, at each open, a free
   1184substream is (usually) automatically chosen and opened. Meanwhile, when
   1185only one substream exists and it was already opened, the successful open
   1186will either block or error with ``EAGAIN`` according to the file open
   1187mode. But you don't have to care about such details in your driver. The
   1188PCM middle layer will take care of such work.
   1189
   1190Full Code Example
   1191-----------------
   1192
   1193The example code below does not include any hardware access routines but
   1194shows only the skeleton, how to build up the PCM interfaces.
   1195
   1196::
   1197
   1198      #include <sound/pcm.h>
   1199      ....
   1200
   1201      /* hardware definition */
   1202      static struct snd_pcm_hardware snd_mychip_playback_hw = {
   1203              .info = (SNDRV_PCM_INFO_MMAP |
   1204                       SNDRV_PCM_INFO_INTERLEAVED |
   1205                       SNDRV_PCM_INFO_BLOCK_TRANSFER |
   1206                       SNDRV_PCM_INFO_MMAP_VALID),
   1207              .formats =          SNDRV_PCM_FMTBIT_S16_LE,
   1208              .rates =            SNDRV_PCM_RATE_8000_48000,
   1209              .rate_min =         8000,
   1210              .rate_max =         48000,
   1211              .channels_min =     2,
   1212              .channels_max =     2,
   1213              .buffer_bytes_max = 32768,
   1214              .period_bytes_min = 4096,
   1215              .period_bytes_max = 32768,
   1216              .periods_min =      1,
   1217              .periods_max =      1024,
   1218      };
   1219
   1220      /* hardware definition */
   1221      static struct snd_pcm_hardware snd_mychip_capture_hw = {
   1222              .info = (SNDRV_PCM_INFO_MMAP |
   1223                       SNDRV_PCM_INFO_INTERLEAVED |
   1224                       SNDRV_PCM_INFO_BLOCK_TRANSFER |
   1225                       SNDRV_PCM_INFO_MMAP_VALID),
   1226              .formats =          SNDRV_PCM_FMTBIT_S16_LE,
   1227              .rates =            SNDRV_PCM_RATE_8000_48000,
   1228              .rate_min =         8000,
   1229              .rate_max =         48000,
   1230              .channels_min =     2,
   1231              .channels_max =     2,
   1232              .buffer_bytes_max = 32768,
   1233              .period_bytes_min = 4096,
   1234              .period_bytes_max = 32768,
   1235              .periods_min =      1,
   1236              .periods_max =      1024,
   1237      };
   1238
   1239      /* open callback */
   1240      static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
   1241      {
   1242              struct mychip *chip = snd_pcm_substream_chip(substream);
   1243              struct snd_pcm_runtime *runtime = substream->runtime;
   1244
   1245              runtime->hw = snd_mychip_playback_hw;
   1246              /* more hardware-initialization will be done here */
   1247              ....
   1248              return 0;
   1249      }
   1250
   1251      /* close callback */
   1252      static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
   1253      {
   1254              struct mychip *chip = snd_pcm_substream_chip(substream);
   1255              /* the hardware-specific codes will be here */
   1256              ....
   1257              return 0;
   1258
   1259      }
   1260
   1261      /* open callback */
   1262      static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
   1263      {
   1264              struct mychip *chip = snd_pcm_substream_chip(substream);
   1265              struct snd_pcm_runtime *runtime = substream->runtime;
   1266
   1267              runtime->hw = snd_mychip_capture_hw;
   1268              /* more hardware-initialization will be done here */
   1269              ....
   1270              return 0;
   1271      }
   1272
   1273      /* close callback */
   1274      static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
   1275      {
   1276              struct mychip *chip = snd_pcm_substream_chip(substream);
   1277              /* the hardware-specific codes will be here */
   1278              ....
   1279              return 0;
   1280      }
   1281
   1282      /* hw_params callback */
   1283      static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
   1284                                   struct snd_pcm_hw_params *hw_params)
   1285      {
   1286              /* the hardware-specific codes will be here */
   1287              ....
   1288              return 0;
   1289      }
   1290
   1291      /* hw_free callback */
   1292      static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
   1293      {
   1294              /* the hardware-specific codes will be here */
   1295              ....
   1296              return 0;
   1297      }
   1298
   1299      /* prepare callback */
   1300      static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
   1301      {
   1302              struct mychip *chip = snd_pcm_substream_chip(substream);
   1303              struct snd_pcm_runtime *runtime = substream->runtime;
   1304
   1305              /* set up the hardware with the current configuration
   1306               * for example...
   1307               */
   1308              mychip_set_sample_format(chip, runtime->format);
   1309              mychip_set_sample_rate(chip, runtime->rate);
   1310              mychip_set_channels(chip, runtime->channels);
   1311              mychip_set_dma_setup(chip, runtime->dma_addr,
   1312                                   chip->buffer_size,
   1313                                   chip->period_size);
   1314              return 0;
   1315      }
   1316
   1317      /* trigger callback */
   1318      static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
   1319                                        int cmd)
   1320      {
   1321              switch (cmd) {
   1322              case SNDRV_PCM_TRIGGER_START:
   1323                      /* do something to start the PCM engine */
   1324                      ....
   1325                      break;
   1326              case SNDRV_PCM_TRIGGER_STOP:
   1327                      /* do something to stop the PCM engine */
   1328                      ....
   1329                      break;
   1330              default:
   1331                      return -EINVAL;
   1332              }
   1333      }
   1334
   1335      /* pointer callback */
   1336      static snd_pcm_uframes_t
   1337      snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
   1338      {
   1339              struct mychip *chip = snd_pcm_substream_chip(substream);
   1340              unsigned int current_ptr;
   1341
   1342              /* get the current hardware pointer */
   1343              current_ptr = mychip_get_hw_pointer(chip);
   1344              return current_ptr;
   1345      }
   1346
   1347      /* operators */
   1348      static struct snd_pcm_ops snd_mychip_playback_ops = {
   1349              .open =        snd_mychip_playback_open,
   1350              .close =       snd_mychip_playback_close,
   1351              .hw_params =   snd_mychip_pcm_hw_params,
   1352              .hw_free =     snd_mychip_pcm_hw_free,
   1353              .prepare =     snd_mychip_pcm_prepare,
   1354              .trigger =     snd_mychip_pcm_trigger,
   1355              .pointer =     snd_mychip_pcm_pointer,
   1356      };
   1357
   1358      /* operators */
   1359      static struct snd_pcm_ops snd_mychip_capture_ops = {
   1360              .open =        snd_mychip_capture_open,
   1361              .close =       snd_mychip_capture_close,
   1362              .hw_params =   snd_mychip_pcm_hw_params,
   1363              .hw_free =     snd_mychip_pcm_hw_free,
   1364              .prepare =     snd_mychip_pcm_prepare,
   1365              .trigger =     snd_mychip_pcm_trigger,
   1366              .pointer =     snd_mychip_pcm_pointer,
   1367      };
   1368
   1369      /*
   1370       *  definitions of capture are omitted here...
   1371       */
   1372
   1373      /* create a pcm device */
   1374      static int snd_mychip_new_pcm(struct mychip *chip)
   1375      {
   1376              struct snd_pcm *pcm;
   1377              int err;
   1378
   1379              err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
   1380              if (err < 0)
   1381                      return err;
   1382              pcm->private_data = chip;
   1383              strcpy(pcm->name, "My Chip");
   1384              chip->pcm = pcm;
   1385              /* set operators */
   1386              snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
   1387                              &snd_mychip_playback_ops);
   1388              snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
   1389                              &snd_mychip_capture_ops);
   1390              /* pre-allocation of buffers */
   1391              /* NOTE: this may fail */
   1392              snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
   1393                                             &chip->pci->dev,
   1394                                             64*1024, 64*1024);
   1395              return 0;
   1396      }
   1397
   1398
   1399PCM Constructor
   1400---------------
   1401
   1402A pcm instance is allocated by the :c:func:`snd_pcm_new()`
   1403function. It would be better to create a constructor for pcm, namely,
   1404
   1405::
   1406
   1407  static int snd_mychip_new_pcm(struct mychip *chip)
   1408  {
   1409          struct snd_pcm *pcm;
   1410          int err;
   1411
   1412          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
   1413          if (err < 0) 
   1414                  return err;
   1415          pcm->private_data = chip;
   1416          strcpy(pcm->name, "My Chip");
   1417          chip->pcm = pcm;
   1418	  ....
   1419          return 0;
   1420  }
   1421
   1422The :c:func:`snd_pcm_new()` function takes four arguments. The
   1423first argument is the card pointer to which this pcm is assigned, and
   1424the second is the ID string.
   1425
   1426The third argument (``index``, 0 in the above) is the index of this new
   1427pcm. It begins from zero. If you create more than one pcm instances,
   1428specify the different numbers in this argument. For example, ``index =
   14291`` for the second PCM device.
   1430
   1431The fourth and fifth arguments are the number of substreams for playback
   1432and capture, respectively. Here 1 is used for both arguments. When no
   1433playback or capture substreams are available, pass 0 to the
   1434corresponding argument.
   1435
   1436If a chip supports multiple playbacks or captures, you can specify more
   1437numbers, but they must be handled properly in open/close, etc.
   1438callbacks. When you need to know which substream you are referring to,
   1439then it can be obtained from struct snd_pcm_substream data passed to each
   1440callback as follows:
   1441
   1442::
   1443
   1444  struct snd_pcm_substream *substream;
   1445  int index = substream->number;
   1446
   1447
   1448After the pcm is created, you need to set operators for each pcm stream.
   1449
   1450::
   1451
   1452  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
   1453                  &snd_mychip_playback_ops);
   1454  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
   1455                  &snd_mychip_capture_ops);
   1456
   1457The operators are defined typically like this:
   1458
   1459::
   1460
   1461  static struct snd_pcm_ops snd_mychip_playback_ops = {
   1462          .open =        snd_mychip_pcm_open,
   1463          .close =       snd_mychip_pcm_close,
   1464          .hw_params =   snd_mychip_pcm_hw_params,
   1465          .hw_free =     snd_mychip_pcm_hw_free,
   1466          .prepare =     snd_mychip_pcm_prepare,
   1467          .trigger =     snd_mychip_pcm_trigger,
   1468          .pointer =     snd_mychip_pcm_pointer,
   1469  };
   1470
   1471All the callbacks are described in the Operators_ subsection.
   1472
   1473After setting the operators, you probably will want to pre-allocate the
   1474buffer and set up the managed allocation mode.
   1475For that, simply call the following:
   1476
   1477::
   1478
   1479  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
   1480                                 &chip->pci->dev,
   1481                                 64*1024, 64*1024);
   1482
   1483It will allocate a buffer up to 64kB as default. Buffer management
   1484details will be described in the later section `Buffer and Memory
   1485Management`_.
   1486
   1487Additionally, you can set some extra information for this pcm in
   1488``pcm->info_flags``. The available values are defined as
   1489``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
   1490hardware definition (described later). When your soundchip supports only
   1491half-duplex, specify like this:
   1492
   1493::
   1494
   1495  pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
   1496
   1497
   1498... And the Destructor?
   1499-----------------------
   1500
   1501The destructor for a pcm instance is not always necessary. Since the pcm
   1502device will be released by the middle layer code automatically, you
   1503don't have to call the destructor explicitly.
   1504
   1505The destructor would be necessary if you created special records
   1506internally and needed to release them. In such a case, set the
   1507destructor function to ``pcm->private_free``:
   1508
   1509::
   1510
   1511      static void mychip_pcm_free(struct snd_pcm *pcm)
   1512      {
   1513              struct mychip *chip = snd_pcm_chip(pcm);
   1514              /* free your own data */
   1515              kfree(chip->my_private_pcm_data);
   1516              /* do what you like else */
   1517              ....
   1518      }
   1519
   1520      static int snd_mychip_new_pcm(struct mychip *chip)
   1521      {
   1522              struct snd_pcm *pcm;
   1523              ....
   1524              /* allocate your own data */
   1525              chip->my_private_pcm_data = kmalloc(...);
   1526              /* set the destructor */
   1527              pcm->private_data = chip;
   1528              pcm->private_free = mychip_pcm_free;
   1529              ....
   1530      }
   1531
   1532
   1533
   1534Runtime Pointer - The Chest of PCM Information
   1535----------------------------------------------
   1536
   1537When the PCM substream is opened, a PCM runtime instance is allocated
   1538and assigned to the substream. This pointer is accessible via
   1539``substream->runtime``. This runtime pointer holds most information you
   1540need to control the PCM: the copy of hw_params and sw_params
   1541configurations, the buffer pointers, mmap records, spinlocks, etc.
   1542
   1543The definition of runtime instance is found in ``<sound/pcm.h>``. Here
   1544are the contents of this file:
   1545
   1546::
   1547
   1548  struct _snd_pcm_runtime {
   1549          /* -- Status -- */
   1550          struct snd_pcm_substream *trigger_master;
   1551          snd_timestamp_t trigger_tstamp;	/* trigger timestamp */
   1552          int overrange;
   1553          snd_pcm_uframes_t avail_max;
   1554          snd_pcm_uframes_t hw_ptr_base;	/* Position at buffer restart */
   1555          snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
   1556  
   1557          /* -- HW params -- */
   1558          snd_pcm_access_t access;	/* access mode */
   1559          snd_pcm_format_t format;	/* SNDRV_PCM_FORMAT_* */
   1560          snd_pcm_subformat_t subformat;	/* subformat */
   1561          unsigned int rate;		/* rate in Hz */
   1562          unsigned int channels;		/* channels */
   1563          snd_pcm_uframes_t period_size;	/* period size */
   1564          unsigned int periods;		/* periods */
   1565          snd_pcm_uframes_t buffer_size;	/* buffer size */
   1566          unsigned int tick_time;		/* tick time */
   1567          snd_pcm_uframes_t min_align;	/* Min alignment for the format */
   1568          size_t byte_align;
   1569          unsigned int frame_bits;
   1570          unsigned int sample_bits;
   1571          unsigned int info;
   1572          unsigned int rate_num;
   1573          unsigned int rate_den;
   1574  
   1575          /* -- SW params -- */
   1576          struct timespec tstamp_mode;	/* mmap timestamp is updated */
   1577          unsigned int period_step;
   1578          unsigned int sleep_min;		/* min ticks to sleep */
   1579          snd_pcm_uframes_t start_threshold;
   1580          snd_pcm_uframes_t stop_threshold;
   1581          snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
   1582                                                  noise is nearest than this */
   1583          snd_pcm_uframes_t silence_size;	/* Silence filling size */
   1584          snd_pcm_uframes_t boundary;	/* pointers wrap point */
   1585  
   1586          snd_pcm_uframes_t silenced_start;
   1587          snd_pcm_uframes_t silenced_size;
   1588  
   1589          snd_pcm_sync_id_t sync;		/* hardware synchronization ID */
   1590  
   1591          /* -- mmap -- */
   1592          volatile struct snd_pcm_mmap_status *status;
   1593          volatile struct snd_pcm_mmap_control *control;
   1594          atomic_t mmap_count;
   1595  
   1596          /* -- locking / scheduling -- */
   1597          spinlock_t lock;
   1598          wait_queue_head_t sleep;
   1599          struct timer_list tick_timer;
   1600          struct fasync_struct *fasync;
   1601
   1602          /* -- private section -- */
   1603          void *private_data;
   1604          void (*private_free)(struct snd_pcm_runtime *runtime);
   1605  
   1606          /* -- hardware description -- */
   1607          struct snd_pcm_hardware hw;
   1608          struct snd_pcm_hw_constraints hw_constraints;
   1609  
   1610          /* -- timer -- */
   1611          unsigned int timer_resolution;	/* timer resolution */
   1612  
   1613          /* -- DMA -- */           
   1614          unsigned char *dma_area;	/* DMA area */
   1615          dma_addr_t dma_addr;		/* physical bus address (not accessible from main CPU) */
   1616          size_t dma_bytes;		/* size of DMA area */
   1617  
   1618          struct snd_dma_buffer *dma_buffer_p;	/* allocated buffer */
   1619  
   1620  #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
   1621          /* -- OSS things -- */
   1622          struct snd_pcm_oss_runtime oss;
   1623  #endif
   1624  };
   1625
   1626
   1627For the operators (callbacks) of each sound driver, most of these
   1628records are supposed to be read-only. Only the PCM middle-layer changes
   1629/ updates them. The exceptions are the hardware description (hw) DMA
   1630buffer information and the private data. Besides, if you use the
   1631standard managed buffer allocation mode, you don't need to set the
   1632DMA buffer information by yourself.
   1633
   1634In the sections below, important records are explained.
   1635
   1636Hardware Description
   1637~~~~~~~~~~~~~~~~~~~~
   1638
   1639The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
   1640the fundamental hardware configuration. Above all, you'll need to define this
   1641in the `PCM open callback`_. Note that the runtime instance holds the copy of
   1642the descriptor, not the pointer to the existing descriptor. That is,
   1643in the open callback, you can modify the copied descriptor
   1644(``runtime->hw``) as you need. For example, if the maximum number of
   1645channels is 1 only on some chip models, you can still use the same
   1646hardware descriptor and change the channels_max later:
   1647
   1648::
   1649
   1650          struct snd_pcm_runtime *runtime = substream->runtime;
   1651          ...
   1652          runtime->hw = snd_mychip_playback_hw; /* common definition */
   1653          if (chip->model == VERY_OLD_ONE)
   1654                  runtime->hw.channels_max = 1;
   1655
   1656Typically, you'll have a hardware descriptor as below:
   1657
   1658::
   1659
   1660  static struct snd_pcm_hardware snd_mychip_playback_hw = {
   1661          .info = (SNDRV_PCM_INFO_MMAP |
   1662                   SNDRV_PCM_INFO_INTERLEAVED |
   1663                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
   1664                   SNDRV_PCM_INFO_MMAP_VALID),
   1665          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
   1666          .rates =            SNDRV_PCM_RATE_8000_48000,
   1667          .rate_min =         8000,
   1668          .rate_max =         48000,
   1669          .channels_min =     2,
   1670          .channels_max =     2,
   1671          .buffer_bytes_max = 32768,
   1672          .period_bytes_min = 4096,
   1673          .period_bytes_max = 32768,
   1674          .periods_min =      1,
   1675          .periods_max =      1024,
   1676  };
   1677
   1678-  The ``info`` field contains the type and capabilities of this
   1679   pcm. The bit flags are defined in ``<sound/asound.h>`` as
   1680   ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
   1681   the mmap is supported and which interleaved format is
   1682   supported. When the hardware supports mmap, add the
   1683   ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
   1684   interleaved or the non-interleaved formats,
   1685   ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
   1686   flag must be set, respectively. If both are supported, you can set
   1687   both, too.
   1688
   1689   In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
   1690   specified for the OSS mmap mode. Usually both are set. Of course,
   1691   ``MMAP_VALID`` is set only if the mmap is really supported.
   1692
   1693   The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
   1694   ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
   1695   supports the “pause” operation, while the ``RESUME`` bit means that
   1696   the pcm supports the full “suspend/resume” operation. If the
   1697   ``PAUSE`` flag is set, the ``trigger`` callback below must handle
   1698   the corresponding (pause push/release) commands. The suspend/resume
   1699   trigger commands can be defined even without the ``RESUME``
   1700   flag. See `Power Management`_ section for details.
   1701
   1702   When the PCM substreams can be synchronized (typically,
   1703   synchronized start/stop of a playback and a capture streams), you
   1704   can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
   1705   need to check the linked-list of PCM substreams in the trigger
   1706   callback. This will be described in the later section.
   1707
   1708-  ``formats`` field contains the bit-flags of supported formats
   1709   (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
   1710   format, give all or'ed bits. In the example above, the signed 16bit
   1711   little-endian format is specified.
   1712
   1713-  ``rates`` field contains the bit-flags of supported rates
   1714   (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
   1715   pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
   1716   provided only for typical rates. If your chip supports
   1717   unconventional rates, you need to add the ``KNOT`` bit and set up
   1718   the hardware constraint manually (explained later).
   1719
   1720-  ``rate_min`` and ``rate_max`` define the minimum and maximum sample
   1721   rate. This should correspond somehow to ``rates`` bits.
   1722
   1723-  ``channel_min`` and ``channel_max`` define, as you might already
   1724   expected, the minimum and maximum number of channels.
   1725
   1726-  ``buffer_bytes_max`` defines the maximum buffer size in
   1727   bytes. There is no ``buffer_bytes_min`` field, since it can be
   1728   calculated from the minimum period size and the minimum number of
   1729   periods. Meanwhile, ``period_bytes_min`` and define the minimum and
   1730   maximum size of the period in bytes. ``periods_max`` and
   1731   ``periods_min`` define the maximum and minimum number of periods in
   1732   the buffer.
   1733
   1734   The “period” is a term that corresponds to a fragment in the OSS
   1735   world. The period defines the size at which a PCM interrupt is
   1736   generated. This size strongly depends on the hardware. Generally,
   1737   the smaller period size will give you more interrupts, that is,
   1738   more controls. In the case of capture, this size defines the input
   1739   latency. On the other hand, the whole buffer size defines the
   1740   output latency for the playback direction.
   1741
   1742-  There is also a field ``fifo_size``. This specifies the size of the
   1743   hardware FIFO, but currently it is neither used in the driver nor
   1744   in the alsa-lib. So, you can ignore this field.
   1745
   1746PCM Configurations
   1747~~~~~~~~~~~~~~~~~~
   1748
   1749Ok, let's go back again to the PCM runtime records. The most
   1750frequently referred records in the runtime instance are the PCM
   1751configurations. The PCM configurations are stored in the runtime
   1752instance after the application sends ``hw_params`` data via
   1753alsa-lib. There are many fields copied from hw_params and sw_params
   1754structs. For example, ``format`` holds the format type chosen by the
   1755application. This field contains the enum value
   1756``SNDRV_PCM_FORMAT_XXX``.
   1757
   1758One thing to be noted is that the configured buffer and period sizes
   1759are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
   1760channels \* samples-size``. For conversion between frames and bytes,
   1761you can use the :c:func:`frames_to_bytes()` and
   1762:c:func:`bytes_to_frames()` helper functions.
   1763
   1764::
   1765
   1766  period_bytes = frames_to_bytes(runtime, runtime->period_size);
   1767
   1768Also, many software parameters (sw_params) are stored in frames, too.
   1769Please check the type of the field. ``snd_pcm_uframes_t`` is for the
   1770frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
   1771frames as signed integer.
   1772
   1773DMA Buffer Information
   1774~~~~~~~~~~~~~~~~~~~~~~
   1775
   1776The DMA buffer is defined by the following four fields, ``dma_area``,
   1777``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
   1778holds the buffer pointer (the logical address). You can call
   1779:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
   1780the physical address of the buffer. This field is specified only when
   1781the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
   1782in bytes. ``dma_private`` is used for the ALSA DMA allocator.
   1783
   1784If you use either the managed buffer allocation mode or the standard
   1785API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
   1786these fields are set by the ALSA middle layer, and you should *not*
   1787change them by yourself. You can read them but not write them. On the
   1788other hand, if you want to allocate the buffer by yourself, you'll
   1789need to manage it in hw_params callback. At least, ``dma_bytes`` is
   1790mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
   1791your driver doesn't support mmap, this field is not
   1792necessary. ``dma_addr`` is also optional. You can use dma_private as
   1793you like, too.
   1794
   1795Running Status
   1796~~~~~~~~~~~~~~
   1797
   1798The running status can be referred via ``runtime->status``. This is
   1799the pointer to the struct snd_pcm_mmap_status record.
   1800For example, you can get the current
   1801DMA hardware pointer via ``runtime->status->hw_ptr``.
   1802
   1803The DMA application pointer can be referred via ``runtime->control``,
   1804which points to the struct snd_pcm_mmap_control record.
   1805However, accessing directly to this value is not recommended.
   1806
   1807Private Data
   1808~~~~~~~~~~~~
   1809
   1810You can allocate a record for the substream and store it in
   1811``runtime->private_data``. Usually, this is done in the `PCM open
   1812callback`_. Don't mix this with ``pcm->private_data``. The
   1813``pcm->private_data`` usually points to the chip instance assigned
   1814statically at the creation of PCM, while the ``runtime->private_data``
   1815points to a dynamic data structure created at the PCM open
   1816callback.
   1817
   1818::
   1819
   1820  static int snd_xxx_open(struct snd_pcm_substream *substream)
   1821  {
   1822          struct my_pcm_data *data;
   1823          ....
   1824          data = kmalloc(sizeof(*data), GFP_KERNEL);
   1825          substream->runtime->private_data = data;
   1826          ....
   1827  }
   1828
   1829
   1830The allocated object must be released in the `close callback`_.
   1831
   1832Operators
   1833---------
   1834
   1835OK, now let me give details about each pcm callback (``ops``). In
   1836general, every callback must return 0 if successful, or a negative
   1837error number such as ``-EINVAL``. To choose an appropriate error
   1838number, it is advised to check what value other parts of the kernel
   1839return when the same kind of request fails.
   1840
   1841The callback function takes at least the argument with
   1842struct snd_pcm_substream pointer. To retrieve the chip
   1843record from the given substream instance, you can use the following
   1844macro.
   1845
   1846::
   1847
   1848  int xxx() {
   1849          struct mychip *chip = snd_pcm_substream_chip(substream);
   1850          ....
   1851  }
   1852
   1853The macro reads ``substream->private_data``, which is a copy of
   1854``pcm->private_data``. You can override the former if you need to
   1855assign different data records per PCM substream. For example, the
   1856cmi8330 driver assigns different ``private_data`` for playback and
   1857capture directions, because it uses two different codecs (SB- and
   1858AD-compatible) for different directions.
   1859
   1860PCM open callback
   1861~~~~~~~~~~~~~~~~~
   1862
   1863::
   1864
   1865  static int snd_xxx_open(struct snd_pcm_substream *substream);
   1866
   1867This is called when a pcm substream is opened.
   1868
   1869At least, here you have to initialize the ``runtime->hw``
   1870record. Typically, this is done by like this:
   1871
   1872::
   1873
   1874  static int snd_xxx_open(struct snd_pcm_substream *substream)
   1875  {
   1876          struct mychip *chip = snd_pcm_substream_chip(substream);
   1877          struct snd_pcm_runtime *runtime = substream->runtime;
   1878
   1879          runtime->hw = snd_mychip_playback_hw;
   1880          return 0;
   1881  }
   1882
   1883where ``snd_mychip_playback_hw`` is the pre-defined hardware
   1884description.
   1885
   1886You can allocate a private data in this callback, as described in
   1887`Private Data`_ section.
   1888
   1889If the hardware configuration needs more constraints, set the hardware
   1890constraints here, too. See Constraints_ for more details.
   1891
   1892close callback
   1893~~~~~~~~~~~~~~
   1894
   1895::
   1896
   1897  static int snd_xxx_close(struct snd_pcm_substream *substream);
   1898
   1899
   1900Obviously, this is called when a pcm substream is closed.
   1901
   1902Any private instance for a pcm substream allocated in the ``open``
   1903callback will be released here.
   1904
   1905::
   1906
   1907  static int snd_xxx_close(struct snd_pcm_substream *substream)
   1908  {
   1909          ....
   1910          kfree(substream->runtime->private_data);
   1911          ....
   1912  }
   1913
   1914ioctl callback
   1915~~~~~~~~~~~~~~
   1916
   1917This is used for any special call to pcm ioctls. But usually you can
   1918leave it as NULL, then PCM core calls the generic ioctl callback
   1919function :c:func:`snd_pcm_lib_ioctl()`.  If you need to deal with the
   1920unique setup of channel info or reset procedure, you can pass your own
   1921callback function here.
   1922
   1923hw_params callback
   1924~~~~~~~~~~~~~~~~~~~
   1925
   1926::
   1927
   1928  static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
   1929                               struct snd_pcm_hw_params *hw_params);
   1930
   1931This is called when the hardware parameter (``hw_params``) is set up
   1932by the application, that is, once when the buffer size, the period
   1933size, the format, etc. are defined for the pcm substream.
   1934
   1935Many hardware setups should be done in this callback, including the
   1936allocation of buffers.
   1937
   1938Parameters to be initialized are retrieved by
   1939:c:func:`params_xxx()` macros.
   1940
   1941When you set up the managed buffer allocation mode for the substream,
   1942a buffer is already allocated before this callback gets
   1943called. Alternatively, you can call a helper function below for
   1944allocating the buffer, too.
   1945
   1946::
   1947
   1948  snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
   1949
   1950:c:func:`snd_pcm_lib_malloc_pages()` is available only when the
   1951DMA buffers have been pre-allocated. See the section `Buffer Types`_
   1952for more details.
   1953
   1954Note that this and ``prepare`` callbacks may be called multiple times
   1955per initialization. For example, the OSS emulation may call these
   1956callbacks at each change via its ioctl.
   1957
   1958Thus, you need to be careful not to allocate the same buffers many
   1959times, which will lead to memory leaks! Calling the helper function
   1960above many times is OK. It will release the previous buffer
   1961automatically when it was already allocated.
   1962
   1963Another note is that this callback is non-atomic (schedulable) as
   1964default, i.e. when no ``nonatomic`` flag set. This is important,
   1965because the ``trigger`` callback is atomic (non-schedulable). That is,
   1966mutexes or any schedule-related functions are not available in
   1967``trigger`` callback. Please see the subsection Atomicity_ for
   1968details.
   1969
   1970hw_free callback
   1971~~~~~~~~~~~~~~~~~
   1972
   1973::
   1974
   1975  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
   1976
   1977This is called to release the resources allocated via
   1978``hw_params``.
   1979
   1980This function is always called before the close callback is called.
   1981Also, the callback may be called multiple times, too. Keep track
   1982whether the resource was already released.
   1983
   1984When you have set up the managed buffer allocation mode for the PCM
   1985substream, the allocated PCM buffer will be automatically released
   1986after this callback gets called.  Otherwise you'll have to release the
   1987buffer manually.  Typically, when the buffer was allocated from the
   1988pre-allocated pool, you can use the standard API function
   1989:c:func:`snd_pcm_lib_malloc_pages()` like:
   1990
   1991::
   1992
   1993  snd_pcm_lib_free_pages(substream);
   1994
   1995prepare callback
   1996~~~~~~~~~~~~~~~~
   1997
   1998::
   1999
   2000  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
   2001
   2002This callback is called when the pcm is “prepared”. You can set the
   2003format type, sample rate, etc. here. The difference from ``hw_params``
   2004is that the ``prepare`` callback will be called each time
   2005:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
   2006underruns, etc.
   2007
   2008Note that this callback is now non-atomic. You can use
   2009schedule-related functions safely in this callback.
   2010
   2011In this and the following callbacks, you can refer to the values via
   2012the runtime record, ``substream->runtime``. For example, to get the
   2013current rate, format or channels, access to ``runtime->rate``,
   2014``runtime->format`` or ``runtime->channels``, respectively. The
   2015physical address of the allocated buffer is set to
   2016``runtime->dma_area``. The buffer and period sizes are in
   2017``runtime->buffer_size`` and ``runtime->period_size``, respectively.
   2018
   2019Be careful that this callback will be called many times at each setup,
   2020too.
   2021
   2022trigger callback
   2023~~~~~~~~~~~~~~~~
   2024
   2025::
   2026
   2027  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
   2028
   2029This is called when the pcm is started, stopped or paused.
   2030
   2031Which action is specified in the second argument,
   2032``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
   2033and ``STOP`` commands must be defined in this callback.
   2034
   2035::
   2036
   2037  switch (cmd) {
   2038  case SNDRV_PCM_TRIGGER_START:
   2039          /* do something to start the PCM engine */
   2040          break;
   2041  case SNDRV_PCM_TRIGGER_STOP:
   2042          /* do something to stop the PCM engine */
   2043          break;
   2044  default:
   2045          return -EINVAL;
   2046  }
   2047
   2048When the pcm supports the pause operation (given in the info field of
   2049the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
   2050must be handled here, too. The former is the command to pause the pcm,
   2051and the latter to restart the pcm again.
   2052
   2053When the pcm supports the suspend/resume operation, regardless of full
   2054or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
   2055commands must be handled, too. These commands are issued when the
   2056power-management status is changed. Obviously, the ``SUSPEND`` and
   2057``RESUME`` commands suspend and resume the pcm substream, and usually,
   2058they are identical to the ``STOP`` and ``START`` commands, respectively.
   2059See the `Power Management`_ section for details.
   2060
   2061As mentioned, this callback is atomic as default unless ``nonatomic``
   2062flag set, and you cannot call functions which may sleep. The
   2063``trigger`` callback should be as minimal as possible, just really
   2064triggering the DMA. The other stuff should be initialized
   2065``hw_params`` and ``prepare`` callbacks properly beforehand.
   2066
   2067sync_stop callback
   2068~~~~~~~~~~~~~~~~~~
   2069
   2070::
   2071
   2072  static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
   2073
   2074This callback is optional, and NULL can be passed.  It's called after
   2075the PCM core stops the stream and changes the stream state
   2076``prepare``, ``hw_params`` or ``hw_free``.
   2077Since the IRQ handler might be still pending, we need to wait until
   2078the pending task finishes before moving to the next step; otherwise it
   2079might lead to a crash due to resource conflicts or access to the freed
   2080resources.  A typical behavior is to call a synchronization function
   2081like :c:func:`synchronize_irq()` here.
   2082
   2083For majority of drivers that need only a call of
   2084:c:func:`synchronize_irq()`, there is a simpler setup, too.
   2085While keeping NULL to ``sync_stop`` PCM callback, the driver can set
   2086``card->sync_irq`` field to store the valid interrupt number after
   2087requesting an IRQ, instead.   Then PCM core will look call
   2088:c:func:`synchronize_irq()` with the given IRQ appropriately.
   2089
   2090If the IRQ handler is released at the card destructor, you don't need
   2091to clear ``card->sync_irq``, as the card itself is being released.
   2092So, usually you'll need to add just a single line for assigning
   2093``card->sync_irq`` in the driver code unless the driver re-acquires
   2094the IRQ.  When the driver frees and re-acquires the IRQ dynamically
   2095(e.g. for suspend/resume), it needs to clear and re-set
   2096``card->sync_irq`` again appropriately.
   2097
   2098pointer callback
   2099~~~~~~~~~~~~~~~~
   2100
   2101::
   2102
   2103  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
   2104
   2105This callback is called when the PCM middle layer inquires the current
   2106hardware position on the buffer. The position must be returned in
   2107frames, ranging from 0 to ``buffer_size - 1``. 
   2108
   2109This is called usually from the buffer-update routine in the pcm
   2110middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
   2111is called in the interrupt routine. Then the pcm middle layer updates
   2112the position and calculates the available space, and wakes up the
   2113sleeping poll threads, etc.
   2114
   2115This callback is also atomic as default.
   2116
   2117copy_user, copy_kernel and fill_silence ops
   2118~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2119
   2120These callbacks are not mandatory, and can be omitted in most cases.
   2121These callbacks are used when the hardware buffer cannot be in the
   2122normal memory space. Some chips have their own buffer on the hardware
   2123which is not mappable. In such a case, you have to transfer the data
   2124manually from the memory buffer to the hardware buffer. Or, if the
   2125buffer is non-contiguous on both physical and virtual memory spaces,
   2126these callbacks must be defined, too.
   2127
   2128If these two callbacks are defined, copy and set-silence operations
   2129are done by them. The detailed will be described in the later section
   2130`Buffer and Memory Management`_.
   2131
   2132ack callback
   2133~~~~~~~~~~~~
   2134
   2135This callback is also not mandatory. This callback is called when the
   2136``appl_ptr`` is updated in read or write operations. Some drivers like
   2137emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
   2138internal buffer, and this callback is useful only for such a purpose.
   2139
   2140This callback is atomic as default.
   2141
   2142page callback
   2143~~~~~~~~~~~~~
   2144
   2145This callback is optional too. The mmap calls this callback to get the
   2146page fault address.
   2147
   2148Since the recent changes, you need no special callback any longer for
   2149the standard SG-buffer or vmalloc-buffer. Hence this callback should
   2150be rarely used.
   2151
   2152mmap calllback
   2153~~~~~~~~~~~~~~
   2154
   2155This is another optional callback for controlling mmap behavior.
   2156Once when defined, PCM core calls this callback when a page is
   2157memory-mapped instead of dealing via the standard helper.
   2158If you need special handling (due to some architecture or
   2159device-specific issues), implement everything here as you like.
   2160
   2161
   2162PCM Interrupt Handler
   2163---------------------
   2164
   2165The rest of pcm stuff is the PCM interrupt handler. The role of PCM
   2166interrupt handler in the sound driver is to update the buffer position
   2167and to tell the PCM middle layer when the buffer position goes across
   2168the prescribed period size. To inform this, call the
   2169:c:func:`snd_pcm_period_elapsed()` function.
   2170
   2171There are several types of sound chips to generate the interrupts.
   2172
   2173Interrupts at the period (fragment) boundary
   2174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2175
   2176This is the most frequently found type: the hardware generates an
   2177interrupt at each period boundary. In this case, you can call
   2178:c:func:`snd_pcm_period_elapsed()` at each interrupt.
   2179
   2180:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
   2181its argument. Thus, you need to keep the substream pointer accessible
   2182from the chip instance. For example, define ``substream`` field in the
   2183chip record to hold the current running substream pointer, and set the
   2184pointer value at ``open`` callback (and reset at ``close`` callback).
   2185
   2186If you acquire a spinlock in the interrupt handler, and the lock is used
   2187in other pcm callbacks, too, then you have to release the lock before
   2188calling :c:func:`snd_pcm_period_elapsed()`, because
   2189:c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
   2190inside.
   2191
   2192Typical code would be like:
   2193
   2194::
   2195
   2196
   2197      static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
   2198      {
   2199              struct mychip *chip = dev_id;
   2200              spin_lock(&chip->lock);
   2201              ....
   2202              if (pcm_irq_invoked(chip)) {
   2203                      /* call updater, unlock before it */
   2204                      spin_unlock(&chip->lock);
   2205                      snd_pcm_period_elapsed(chip->substream);
   2206                      spin_lock(&chip->lock);
   2207                      /* acknowledge the interrupt if necessary */
   2208              }
   2209              ....
   2210              spin_unlock(&chip->lock);
   2211              return IRQ_HANDLED;
   2212      }
   2213
   2214
   2215
   2216High frequency timer interrupts
   2217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2218
   2219This happens when the hardware doesn't generate interrupts at the period
   2220boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
   2221or ymfpci drivers). In this case, you need to check the current hardware
   2222position and accumulate the processed sample length at each interrupt.
   2223When the accumulated size exceeds the period size, call
   2224:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
   2225
   2226Typical code would be like the following.
   2227
   2228::
   2229
   2230
   2231      static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
   2232      {
   2233              struct mychip *chip = dev_id;
   2234              spin_lock(&chip->lock);
   2235              ....
   2236              if (pcm_irq_invoked(chip)) {
   2237                      unsigned int last_ptr, size;
   2238                      /* get the current hardware pointer (in frames) */
   2239                      last_ptr = get_hw_ptr(chip);
   2240                      /* calculate the processed frames since the
   2241                       * last update
   2242                       */
   2243                      if (last_ptr < chip->last_ptr)
   2244                              size = runtime->buffer_size + last_ptr
   2245                                       - chip->last_ptr;
   2246                      else
   2247                              size = last_ptr - chip->last_ptr;
   2248                      /* remember the last updated point */
   2249                      chip->last_ptr = last_ptr;
   2250                      /* accumulate the size */
   2251                      chip->size += size;
   2252                      /* over the period boundary? */
   2253                      if (chip->size >= runtime->period_size) {
   2254                              /* reset the accumulator */
   2255                              chip->size %= runtime->period_size;
   2256                              /* call updater */
   2257                              spin_unlock(&chip->lock);
   2258                              snd_pcm_period_elapsed(substream);
   2259                              spin_lock(&chip->lock);
   2260                      }
   2261                      /* acknowledge the interrupt if necessary */
   2262              }
   2263              ....
   2264              spin_unlock(&chip->lock);
   2265              return IRQ_HANDLED;
   2266      }
   2267
   2268
   2269
   2270On calling :c:func:`snd_pcm_period_elapsed()`
   2271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2272
   2273In both cases, even if more than one period are elapsed, you don't have
   2274to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
   2275once. And the pcm layer will check the current hardware pointer and
   2276update to the latest status.
   2277
   2278Atomicity
   2279---------
   2280
   2281One of the most important (and thus difficult to debug) problems in
   2282kernel programming are race conditions. In the Linux kernel, they are
   2283usually avoided via spin-locks, mutexes or semaphores. In general, if a
   2284race condition can happen in an interrupt handler, it has to be managed
   2285atomically, and you have to use a spinlock to protect the critical
   2286session. If the critical section is not in interrupt handler code and if
   2287taking a relatively long time to execute is acceptable, you should use
   2288mutexes or semaphores instead.
   2289
   2290As already seen, some pcm callbacks are atomic and some are not. For
   2291example, the ``hw_params`` callback is non-atomic, while ``trigger``
   2292callback is atomic. This means, the latter is called already in a
   2293spinlock held by the PCM middle layer. Please take this atomicity into
   2294account when you choose a locking scheme in the callbacks.
   2295
   2296In the atomic callbacks, you cannot use functions which may call
   2297:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
   2298mutexes can sleep, and hence they cannot be used inside the atomic
   2299callbacks (e.g. ``trigger`` callback). To implement some delay in such a
   2300callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
   2301
   2302All three atomic callbacks (trigger, pointer, and ack) are called with
   2303local interrupts disabled.
   2304
   2305The recent changes in PCM core code, however, allow all PCM operations
   2306to be non-atomic. This assumes that the all caller sides are in
   2307non-atomic contexts. For example, the function
   2308:c:func:`snd_pcm_period_elapsed()` is called typically from the
   2309interrupt handler. But, if you set up the driver to use a threaded
   2310interrupt handler, this call can be in non-atomic context, too. In such
   2311a case, you can set ``nonatomic`` filed of struct snd_pcm object
   2312after creating it. When this flag is set, mutex and rwsem are used internally
   2313in the PCM core instead of spin and rwlocks, so that you can call all PCM
   2314functions safely in a non-atomic
   2315context.
   2316
   2317Constraints
   2318-----------
   2319
   2320If your chip supports unconventional sample rates, or only the limited
   2321samples, you need to set a constraint for the condition.
   2322
   2323For example, in order to restrict the sample rates in the some supported
   2324values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
   2325call this function in the open callback.
   2326
   2327::
   2328
   2329      static unsigned int rates[] =
   2330              {4000, 10000, 22050, 44100};
   2331      static struct snd_pcm_hw_constraint_list constraints_rates = {
   2332              .count = ARRAY_SIZE(rates),
   2333              .list = rates,
   2334              .mask = 0,
   2335      };
   2336
   2337      static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
   2338      {
   2339              int err;
   2340              ....
   2341              err = snd_pcm_hw_constraint_list(substream->runtime, 0,
   2342                                               SNDRV_PCM_HW_PARAM_RATE,
   2343                                               &constraints_rates);
   2344              if (err < 0)
   2345                      return err;
   2346              ....
   2347      }
   2348
   2349
   2350
   2351There are many different constraints. Look at ``sound/pcm.h`` for a
   2352complete list. You can even define your own constraint rules. For
   2353example, let's suppose my_chip can manage a substream of 1 channel if
   2354and only if the format is ``S16_LE``, otherwise it supports any format
   2355specified in struct snd_pcm_hardware> (or in any other
   2356constraint_list). You can build a rule like this:
   2357
   2358::
   2359
   2360      static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
   2361                                            struct snd_pcm_hw_rule *rule)
   2362      {
   2363              struct snd_interval *c = hw_param_interval(params,
   2364                            SNDRV_PCM_HW_PARAM_CHANNELS);
   2365              struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
   2366              struct snd_interval ch;
   2367
   2368              snd_interval_any(&ch);
   2369              if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
   2370                      ch.min = ch.max = 1;
   2371                      ch.integer = 1;
   2372                      return snd_interval_refine(c, &ch);
   2373              }
   2374              return 0;
   2375      }
   2376
   2377
   2378Then you need to call this function to add your rule:
   2379
   2380::
   2381
   2382  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
   2383                      hw_rule_channels_by_format, NULL,
   2384                      SNDRV_PCM_HW_PARAM_FORMAT, -1);
   2385
   2386The rule function is called when an application sets the PCM format, and
   2387it refines the number of channels accordingly. But an application may
   2388set the number of channels before setting the format. Thus you also need
   2389to define the inverse rule:
   2390
   2391::
   2392
   2393      static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
   2394                                            struct snd_pcm_hw_rule *rule)
   2395      {
   2396              struct snd_interval *c = hw_param_interval(params,
   2397                    SNDRV_PCM_HW_PARAM_CHANNELS);
   2398              struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
   2399              struct snd_mask fmt;
   2400
   2401              snd_mask_any(&fmt);    /* Init the struct */
   2402              if (c->min < 2) {
   2403                      fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
   2404                      return snd_mask_refine(f, &fmt);
   2405              }
   2406              return 0;
   2407      }
   2408
   2409
   2410... and in the open callback:
   2411
   2412::
   2413
   2414  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
   2415                      hw_rule_format_by_channels, NULL,
   2416                      SNDRV_PCM_HW_PARAM_CHANNELS, -1);
   2417
   2418One typical usage of the hw constraints is to align the buffer size
   2419with the period size.  As default, ALSA PCM core doesn't enforce the
   2420buffer size to be aligned with the period size.  For example, it'd be
   2421possible to have a combination like 256 period bytes with 999 buffer
   2422bytes.
   2423
   2424Many device chips, however, require the buffer to be a multiple of
   2425periods.  In such a case, call
   2426:c:func:`snd_pcm_hw_constraint_integer()` for
   2427``SNDRV_PCM_HW_PARAM_PERIODS``.
   2428
   2429::
   2430
   2431  snd_pcm_hw_constraint_integer(substream->runtime,
   2432                                SNDRV_PCM_HW_PARAM_PERIODS);
   2433
   2434This assures that the number of periods is integer, hence the buffer
   2435size is aligned with the period size.
   2436
   2437The hw constraint is a very much powerful mechanism to define the
   2438preferred PCM configuration, and there are relevant helpers.
   2439I won't give more details here, rather I would like to say, “Luke, use
   2440the source.”
   2441
   2442Control Interface
   2443=================
   2444
   2445General
   2446-------
   2447
   2448The control interface is used widely for many switches, sliders, etc.
   2449which are accessed from user-space. Its most important use is the mixer
   2450interface. In other words, since ALSA 0.9.x, all the mixer stuff is
   2451implemented on the control kernel API.
   2452
   2453ALSA has a well-defined AC97 control module. If your chip supports only
   2454the AC97 and nothing else, you can skip this section.
   2455
   2456The control API is defined in ``<sound/control.h>``. Include this file
   2457if you want to add your own controls.
   2458
   2459Definition of Controls
   2460----------------------
   2461
   2462To create a new control, you need to define the following three
   2463callbacks: ``info``, ``get`` and ``put``. Then, define a
   2464struct snd_kcontrol_new record, such as:
   2465
   2466::
   2467
   2468
   2469      static struct snd_kcontrol_new my_control = {
   2470              .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
   2471              .name = "PCM Playback Switch",
   2472              .index = 0,
   2473              .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
   2474              .private_value = 0xffff,
   2475              .info = my_control_info,
   2476              .get = my_control_get,
   2477              .put = my_control_put
   2478      };
   2479
   2480
   2481The ``iface`` field specifies the control type,
   2482``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
   2483for global controls that are not logically part of the mixer. If the
   2484control is closely associated with some specific device on the sound
   2485card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
   2486and specify the device number with the ``device`` and ``subdevice``
   2487fields.
   2488
   2489The ``name`` is the name identifier string. Since ALSA 0.9.x, the
   2490control name is very important, because its role is classified from
   2491its name. There are pre-defined standard control names. The details
   2492are described in the `Control Names`_ subsection.
   2493
   2494The ``index`` field holds the index number of this control. If there
   2495are several different controls with the same name, they can be
   2496distinguished by the index number. This is the case when several
   2497codecs exist on the card. If the index is zero, you can omit the
   2498definition above. 
   2499
   2500The ``access`` field contains the access type of this control. Give
   2501the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
   2502there. The details will be explained in the `Access Flags`_
   2503subsection.
   2504
   2505The ``private_value`` field contains an arbitrary long integer value
   2506for this record. When using the generic ``info``, ``get`` and ``put``
   2507callbacks, you can pass a value through this field. If several small
   2508numbers are necessary, you can combine them in bitwise. Or, it's
   2509possible to give a pointer (casted to unsigned long) of some record to
   2510this field, too. 
   2511
   2512The ``tlv`` field can be used to provide metadata about the control;
   2513see the `Metadata`_ subsection.
   2514
   2515The other three are `Control Callbacks`_.
   2516
   2517Control Names
   2518-------------
   2519
   2520There are some standards to define the control names. A control is
   2521usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
   2522
   2523The first, ``SOURCE``, specifies the source of the control, and is a
   2524string such as “Master”, “PCM”, “CD” and “Line”. There are many
   2525pre-defined sources.
   2526
   2527The second, ``DIRECTION``, is one of the following strings according to
   2528the direction of the control: “Playback”, “Capture”, “Bypass Playback”
   2529and “Bypass Capture”. Or, it can be omitted, meaning both playback and
   2530capture directions.
   2531
   2532The third, ``FUNCTION``, is one of the following strings according to
   2533the function of the control: “Switch”, “Volume” and “Route”.
   2534
   2535The example of control names are, thus, “Master Capture Switch” or “PCM
   2536Playback Volume”.
   2537
   2538There are some exceptions:
   2539
   2540Global capture and playback
   2541~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2542
   2543“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
   2544global capture (input) source, switch and volume. Similarly, “Playback
   2545Switch” and “Playback Volume” are used for the global output gain switch
   2546and volume.
   2547
   2548Tone-controls
   2549~~~~~~~~~~~~~
   2550
   2551tone-control switch and volumes are specified like “Tone Control - XXX”,
   2552e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
   2553Center”.
   2554
   25553D controls
   2556~~~~~~~~~~~
   2557
   25583D-control switches and volumes are specified like “3D Control - XXX”,
   2559e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
   2560
   2561Mic boost
   2562~~~~~~~~~
   2563
   2564Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
   2565
   2566More precise information can be found in
   2567``Documentation/sound/designs/control-names.rst``.
   2568
   2569Access Flags
   2570------------
   2571
   2572The access flag is the bitmask which specifies the access type of the
   2573given control. The default access type is
   2574``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
   2575allowed to this control. When the access flag is omitted (i.e. = 0), it
   2576is considered as ``READWRITE`` access as default.
   2577
   2578When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
   2579instead. In this case, you don't have to define the ``put`` callback.
   2580Similarly, when the control is write-only (although it's a rare case),
   2581you can use the ``WRITE`` flag instead, and you don't need the ``get``
   2582callback.
   2583
   2584If the control value changes frequently (e.g. the VU meter),
   2585``VOLATILE`` flag should be given. This means that the control may be
   2586changed without `Change notification`_. Applications should poll such
   2587a control constantly.
   2588
   2589When the control is inactive, set the ``INACTIVE`` flag, too. There are
   2590``LOCK`` and ``OWNER`` flags to change the write permissions.
   2591
   2592Control Callbacks
   2593-----------------
   2594
   2595info callback
   2596~~~~~~~~~~~~~
   2597
   2598The ``info`` callback is used to get detailed information on this
   2599control. This must store the values of the given
   2600struct snd_ctl_elem_info object. For example,
   2601for a boolean control with a single element:
   2602
   2603::
   2604
   2605
   2606      static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
   2607                              struct snd_ctl_elem_info *uinfo)
   2608      {
   2609              uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
   2610              uinfo->count = 1;
   2611              uinfo->value.integer.min = 0;
   2612              uinfo->value.integer.max = 1;
   2613              return 0;
   2614      }
   2615
   2616
   2617
   2618The ``type`` field specifies the type of the control. There are
   2619``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
   2620``INTEGER64``. The ``count`` field specifies the number of elements in
   2621this control. For example, a stereo volume would have count = 2. The
   2622``value`` field is a union, and the values stored are depending on the
   2623type. The boolean and integer types are identical.
   2624
   2625The enumerated type is a bit different from others. You'll need to set
   2626the string for the currently given item index.
   2627
   2628::
   2629
   2630  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
   2631                          struct snd_ctl_elem_info *uinfo)
   2632  {
   2633          static char *texts[4] = {
   2634                  "First", "Second", "Third", "Fourth"
   2635          };
   2636          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
   2637          uinfo->count = 1;
   2638          uinfo->value.enumerated.items = 4;
   2639          if (uinfo->value.enumerated.item > 3)
   2640                  uinfo->value.enumerated.item = 3;
   2641          strcpy(uinfo->value.enumerated.name,
   2642                 texts[uinfo->value.enumerated.item]);
   2643          return 0;
   2644  }
   2645
   2646The above callback can be simplified with a helper function,
   2647:c:func:`snd_ctl_enum_info()`. The final code looks like below.
   2648(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
   2649it's a matter of taste.)
   2650
   2651::
   2652
   2653  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
   2654                          struct snd_ctl_elem_info *uinfo)
   2655  {
   2656          static char *texts[4] = {
   2657                  "First", "Second", "Third", "Fourth"
   2658          };
   2659          return snd_ctl_enum_info(uinfo, 1, 4, texts);
   2660  }
   2661
   2662
   2663Some common info callbacks are available for your convenience:
   2664:c:func:`snd_ctl_boolean_mono_info()` and
   2665:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
   2666is an info callback for a mono channel boolean item, just like
   2667:c:func:`snd_myctl_mono_info()` above, and the latter is for a
   2668stereo channel boolean item.
   2669
   2670get callback
   2671~~~~~~~~~~~~
   2672
   2673This callback is used to read the current value of the control and to
   2674return to user-space.
   2675
   2676For example,
   2677
   2678::
   2679
   2680
   2681      static int snd_myctl_get(struct snd_kcontrol *kcontrol,
   2682                               struct snd_ctl_elem_value *ucontrol)
   2683      {
   2684              struct mychip *chip = snd_kcontrol_chip(kcontrol);
   2685              ucontrol->value.integer.value[0] = get_some_value(chip);
   2686              return 0;
   2687      }
   2688
   2689
   2690
   2691The ``value`` field depends on the type of control as well as on the
   2692info callback. For example, the sb driver uses this field to store the
   2693register offset, the bit-shift and the bit-mask. The ``private_value``
   2694field is set as follows:
   2695
   2696::
   2697
   2698  .private_value = reg | (shift << 16) | (mask << 24)
   2699
   2700and is retrieved in callbacks like
   2701
   2702::
   2703
   2704  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
   2705                                    struct snd_ctl_elem_value *ucontrol)
   2706  {
   2707          int reg = kcontrol->private_value & 0xff;
   2708          int shift = (kcontrol->private_value >> 16) & 0xff;
   2709          int mask = (kcontrol->private_value >> 24) & 0xff;
   2710          ....
   2711  }
   2712
   2713In the ``get`` callback, you have to fill all the elements if the
   2714control has more than one elements, i.e. ``count > 1``. In the example
   2715above, we filled only one element (``value.integer.value[0]``) since
   2716it's assumed as ``count = 1``.
   2717
   2718put callback
   2719~~~~~~~~~~~~
   2720
   2721This callback is used to write a value from user-space.
   2722
   2723For example,
   2724
   2725::
   2726
   2727
   2728      static int snd_myctl_put(struct snd_kcontrol *kcontrol,
   2729                               struct snd_ctl_elem_value *ucontrol)
   2730      {
   2731              struct mychip *chip = snd_kcontrol_chip(kcontrol);
   2732              int changed = 0;
   2733              if (chip->current_value !=
   2734                   ucontrol->value.integer.value[0]) {
   2735                      change_current_value(chip,
   2736                                  ucontrol->value.integer.value[0]);
   2737                      changed = 1;
   2738              }
   2739              return changed;
   2740      }
   2741
   2742
   2743
   2744As seen above, you have to return 1 if the value is changed. If the
   2745value is not changed, return 0 instead. If any fatal error happens,
   2746return a negative error code as usual.
   2747
   2748As in the ``get`` callback, when the control has more than one
   2749elements, all elements must be evaluated in this callback, too.
   2750
   2751Callbacks are not atomic
   2752~~~~~~~~~~~~~~~~~~~~~~~~
   2753
   2754All these three callbacks are basically not atomic.
   2755
   2756Control Constructor
   2757-------------------
   2758
   2759When everything is ready, finally we can create a new control. To create
   2760a control, there are two functions to be called,
   2761:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
   2762
   2763In the simplest way, you can do like this:
   2764
   2765::
   2766
   2767  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
   2768  if (err < 0)
   2769          return err;
   2770
   2771where ``my_control`` is the struct snd_kcontrol_new object defined above,
   2772and chip is the object pointer to be passed to kcontrol->private_data which
   2773can be referred to in callbacks.
   2774
   2775:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
   2776:c:func:`snd_ctl_add()` assigns the given control component to the
   2777card.
   2778
   2779Change Notification
   2780-------------------
   2781
   2782If you need to change and update a control in the interrupt routine, you
   2783can call :c:func:`snd_ctl_notify()`. For example,
   2784
   2785::
   2786
   2787  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
   2788
   2789This function takes the card pointer, the event-mask, and the control id
   2790pointer for the notification. The event-mask specifies the types of
   2791notification, for example, in the above example, the change of control
   2792values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
   2793to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
   2794for hardware volume interrupts.
   2795
   2796Metadata
   2797--------
   2798
   2799To provide information about the dB values of a mixer control, use on of
   2800the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
   2801variable containing this information, set the ``tlv.p`` field to point to
   2802this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
   2803in the ``access`` field; like this:
   2804
   2805::
   2806
   2807  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
   2808
   2809  static struct snd_kcontrol_new my_control = {
   2810          ...
   2811          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
   2812                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
   2813          ...
   2814          .tlv.p = db_scale_my_control,
   2815  };
   2816
   2817
   2818The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
   2819about a mixer control where each step in the control's value changes the
   2820dB value by a constant dB amount. The first parameter is the name of the
   2821variable to be defined. The second parameter is the minimum value, in
   2822units of 0.01 dB. The third parameter is the step size, in units of 0.01
   2823dB. Set the fourth parameter to 1 if the minimum value actually mutes
   2824the control.
   2825
   2826The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
   2827about a mixer control where the control's value affects the output
   2828linearly. The first parameter is the name of the variable to be defined.
   2829The second parameter is the minimum value, in units of 0.01 dB. The
   2830third parameter is the maximum value, in units of 0.01 dB. If the
   2831minimum value mutes the control, set the second parameter to
   2832``TLV_DB_GAIN_MUTE``.
   2833
   2834API for AC97 Codec
   2835==================
   2836
   2837General
   2838-------
   2839
   2840The ALSA AC97 codec layer is a well-defined one, and you don't have to
   2841write much code to control it. Only low-level control routines are
   2842necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
   2843
   2844Full Code Example
   2845-----------------
   2846
   2847::
   2848
   2849      struct mychip {
   2850              ....
   2851              struct snd_ac97 *ac97;
   2852              ....
   2853      };
   2854
   2855      static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
   2856                                                 unsigned short reg)
   2857      {
   2858              struct mychip *chip = ac97->private_data;
   2859              ....
   2860              /* read a register value here from the codec */
   2861              return the_register_value;
   2862      }
   2863
   2864      static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
   2865                                       unsigned short reg, unsigned short val)
   2866      {
   2867              struct mychip *chip = ac97->private_data;
   2868              ....
   2869              /* write the given register value to the codec */
   2870      }
   2871
   2872      static int snd_mychip_ac97(struct mychip *chip)
   2873      {
   2874              struct snd_ac97_bus *bus;
   2875              struct snd_ac97_template ac97;
   2876              int err;
   2877              static struct snd_ac97_bus_ops ops = {
   2878                      .write = snd_mychip_ac97_write,
   2879                      .read = snd_mychip_ac97_read,
   2880              };
   2881
   2882              err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
   2883              if (err < 0)
   2884                      return err;
   2885              memset(&ac97, 0, sizeof(ac97));
   2886              ac97.private_data = chip;
   2887              return snd_ac97_mixer(bus, &ac97, &chip->ac97);
   2888      }
   2889
   2890
   2891AC97 Constructor
   2892----------------
   2893
   2894To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
   2895with an ``ac97_bus_ops_t`` record with callback functions.
   2896
   2897::
   2898
   2899  struct snd_ac97_bus *bus;
   2900  static struct snd_ac97_bus_ops ops = {
   2901        .write = snd_mychip_ac97_write,
   2902        .read = snd_mychip_ac97_read,
   2903  };
   2904
   2905  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
   2906
   2907The bus record is shared among all belonging ac97 instances.
   2908
   2909And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
   2910record together with the bus pointer created above.
   2911
   2912::
   2913
   2914  struct snd_ac97_template ac97;
   2915  int err;
   2916
   2917  memset(&ac97, 0, sizeof(ac97));
   2918  ac97.private_data = chip;
   2919  snd_ac97_mixer(bus, &ac97, &chip->ac97);
   2920
   2921where chip->ac97 is a pointer to a newly created ``ac97_t``
   2922instance. In this case, the chip pointer is set as the private data,
   2923so that the read/write callback functions can refer to this chip
   2924instance. This instance is not necessarily stored in the chip
   2925record. If you need to change the register values from the driver, or
   2926need the suspend/resume of ac97 codecs, keep this pointer to pass to
   2927the corresponding functions.
   2928
   2929AC97 Callbacks
   2930--------------
   2931
   2932The standard callbacks are ``read`` and ``write``. Obviously they
   2933correspond to the functions for read and write accesses to the
   2934hardware low-level codes.
   2935
   2936The ``read`` callback returns the register value specified in the
   2937argument.
   2938
   2939::
   2940
   2941  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
   2942                                             unsigned short reg)
   2943  {
   2944          struct mychip *chip = ac97->private_data;
   2945          ....
   2946          return the_register_value;
   2947  }
   2948
   2949Here, the chip can be cast from ``ac97->private_data``.
   2950
   2951Meanwhile, the ``write`` callback is used to set the register
   2952value
   2953
   2954::
   2955
   2956  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
   2957                       unsigned short reg, unsigned short val)
   2958
   2959
   2960These callbacks are non-atomic like the control API callbacks.
   2961
   2962There are also other callbacks: ``reset``, ``wait`` and ``init``.
   2963
   2964The ``reset`` callback is used to reset the codec. If the chip
   2965requires a special kind of reset, you can define this callback.
   2966
   2967The ``wait`` callback is used to add some waiting time in the standard
   2968initialization of the codec. If the chip requires the extra waiting
   2969time, define this callback.
   2970
   2971The ``init`` callback is used for additional initialization of the
   2972codec.
   2973
   2974Updating Registers in The Driver
   2975--------------------------------
   2976
   2977If you need to access to the codec from the driver, you can call the
   2978following functions: :c:func:`snd_ac97_write()`,
   2979:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
   2980:c:func:`snd_ac97_update_bits()`.
   2981
   2982Both :c:func:`snd_ac97_write()` and
   2983:c:func:`snd_ac97_update()` functions are used to set a value to
   2984the given register (``AC97_XXX``). The difference between them is that
   2985:c:func:`snd_ac97_update()` doesn't write a value if the given
   2986value has been already set, while :c:func:`snd_ac97_write()`
   2987always rewrites the value.
   2988
   2989::
   2990
   2991  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
   2992  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
   2993
   2994:c:func:`snd_ac97_read()` is used to read the value of the given
   2995register. For example,
   2996
   2997::
   2998
   2999  value = snd_ac97_read(ac97, AC97_MASTER);
   3000
   3001:c:func:`snd_ac97_update_bits()` is used to update some bits in
   3002the given register.
   3003
   3004::
   3005
   3006  snd_ac97_update_bits(ac97, reg, mask, value);
   3007
   3008Also, there is a function to change the sample rate (of a given register
   3009such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
   3010codec: :c:func:`snd_ac97_set_rate()`.
   3011
   3012::
   3013
   3014  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
   3015
   3016
   3017The following registers are available to set the rate:
   3018``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
   3019``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
   3020specified, the register is not really changed but the corresponding
   3021IEC958 status bits will be updated.
   3022
   3023Clock Adjustment
   3024----------------
   3025
   3026In some chips, the clock of the codec isn't 48000 but using a PCI clock
   3027(to save a quartz!). In this case, change the field ``bus->clock`` to
   3028the corresponding value. For example, intel8x0 and es1968 drivers have
   3029their own function to read from the clock.
   3030
   3031Proc Files
   3032----------
   3033
   3034The ALSA AC97 interface will create a proc file such as
   3035``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
   3036can refer to these files to see the current status and registers of
   3037the codec.
   3038
   3039Multiple Codecs
   3040---------------
   3041
   3042When there are several codecs on the same card, you need to call
   3043:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
   3044greater. The ``num`` field specifies the codec number.
   3045
   3046If you set up multiple codecs, you either need to write different
   3047callbacks for each codec or check ``ac97->num`` in the callback
   3048routines.
   3049
   3050MIDI (MPU401-UART) Interface
   3051============================
   3052
   3053General
   3054-------
   3055
   3056Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
   3057soundcard supports the standard MPU401-UART interface, most likely you
   3058can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
   3059``<sound/mpu401.h>``.
   3060
   3061Some soundchips have a similar but slightly different implementation of
   3062mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
   3063
   3064MIDI Constructor
   3065----------------
   3066
   3067To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
   3068
   3069::
   3070
   3071  struct snd_rawmidi *rmidi;
   3072  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
   3073                      irq, &rmidi);
   3074
   3075
   3076The first argument is the card pointer, and the second is the index of
   3077this component. You can create up to 8 rawmidi devices.
   3078
   3079The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
   3080it's not a special one, you can use ``MPU401_HW_MPU401``.
   3081
   3082The 4th argument is the I/O port address. Many backward-compatible
   3083MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
   3084PCI I/O region. It depends on the chip design.
   3085
   3086The 5th argument is a bitflag for additional information. When the I/O
   3087port address above is part of the PCI I/O region, the MPU401 I/O port
   3088might have been already allocated (reserved) by the driver itself. In
   3089such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
   3090mpu401-uart layer will allocate the I/O ports by itself.
   3091
   3092When the controller supports only the input or output MIDI stream, pass
   3093the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
   3094respectively. Then the rawmidi instance is created as a single stream.
   3095
   3096``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
   3097(via readb and writeb) instead of iob and outb. In this case, you have
   3098to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
   3099
   3100When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
   3101the default interrupt handler. The driver needs to call
   3102:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
   3103processing the output stream in the irq handler.
   3104
   3105If the MPU-401 interface shares its interrupt with the other logical
   3106devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
   3107`below <MIDI Interrupt Handler_>`__).
   3108
   3109Usually, the port address corresponds to the command port and port + 1
   3110corresponds to the data port. If not, you may change the ``cport``
   3111field of struct snd_mpu401 manually afterward.
   3112However, struct snd_mpu401 pointer is
   3113not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
   3114need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
   3115
   3116::
   3117
   3118  struct snd_mpu401 *mpu;
   3119  mpu = rmidi->private_data;
   3120
   3121and reset the ``cport`` as you like:
   3122
   3123::
   3124
   3125  mpu->cport = my_own_control_port;
   3126
   3127The 6th argument specifies the ISA irq number that will be allocated. If
   3128no interrupt is to be allocated (because your code is already allocating
   3129a shared interrupt, or because the device does not use interrupts), pass
   3130-1 instead. For a MPU-401 device without an interrupt, a polling timer
   3131will be used instead.
   3132
   3133MIDI Interrupt Handler
   3134----------------------
   3135
   3136When the interrupt is allocated in
   3137:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
   3138handler is automatically used, hence you don't have anything else to do
   3139than creating the mpu401 stuff. Otherwise, you have to set
   3140``MPU401_INFO_IRQ_HOOK``, and call
   3141:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
   3142interrupt handler when it has determined that a UART interrupt has
   3143occurred.
   3144
   3145In this case, you need to pass the private_data of the returned rawmidi
   3146object from :c:func:`snd_mpu401_uart_new()` as the second
   3147argument of :c:func:`snd_mpu401_uart_interrupt()`.
   3148
   3149::
   3150
   3151  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
   3152
   3153
   3154RawMIDI Interface
   3155=================
   3156
   3157Overview
   3158--------
   3159
   3160The raw MIDI interface is used for hardware MIDI ports that can be
   3161accessed as a byte stream. It is not used for synthesizer chips that do
   3162not directly understand MIDI.
   3163
   3164ALSA handles file and buffer management. All you have to do is to write
   3165some code to move data between the buffer and the hardware.
   3166
   3167The rawmidi API is defined in ``<sound/rawmidi.h>``.
   3168
   3169RawMIDI Constructor
   3170-------------------
   3171
   3172To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
   3173function:
   3174
   3175::
   3176
   3177  struct snd_rawmidi *rmidi;
   3178  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
   3179  if (err < 0)
   3180          return err;
   3181  rmidi->private_data = chip;
   3182  strcpy(rmidi->name, "My MIDI");
   3183  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
   3184                      SNDRV_RAWMIDI_INFO_INPUT |
   3185                      SNDRV_RAWMIDI_INFO_DUPLEX;
   3186
   3187The first argument is the card pointer, the second argument is the ID
   3188string.
   3189
   3190The third argument is the index of this component. You can create up to
   31918 rawmidi devices.
   3192
   3193The fourth and fifth arguments are the number of output and input
   3194substreams, respectively, of this device (a substream is the equivalent
   3195of a MIDI port).
   3196
   3197Set the ``info_flags`` field to specify the capabilities of the
   3198device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
   3199output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
   3200input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
   3201output and input at the same time.
   3202
   3203After the rawmidi device is created, you need to set the operators
   3204(callbacks) for each substream. There are helper functions to set the
   3205operators for all the substreams of a device:
   3206
   3207::
   3208
   3209  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
   3210  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
   3211
   3212The operators are usually defined like this:
   3213
   3214::
   3215
   3216  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
   3217          .open =    snd_mymidi_output_open,
   3218          .close =   snd_mymidi_output_close,
   3219          .trigger = snd_mymidi_output_trigger,
   3220  };
   3221
   3222These callbacks are explained in the `RawMIDI Callbacks`_ section.
   3223
   3224If there are more than one substream, you should give a unique name to
   3225each of them:
   3226
   3227::
   3228
   3229  struct snd_rawmidi_substream *substream;
   3230  list_for_each_entry(substream,
   3231                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
   3232                      list {
   3233          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
   3234  }
   3235  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
   3236
   3237RawMIDI Callbacks
   3238-----------------
   3239
   3240In all the callbacks, the private data that you've set for the rawmidi
   3241device can be accessed as ``substream->rmidi->private_data``.
   3242
   3243If there is more than one port, your callbacks can determine the port
   3244index from the struct snd_rawmidi_substream data passed to each
   3245callback:
   3246
   3247::
   3248
   3249  struct snd_rawmidi_substream *substream;
   3250  int index = substream->number;
   3251
   3252RawMIDI open callback
   3253~~~~~~~~~~~~~~~~~~~~~
   3254
   3255::
   3256
   3257      static int snd_xxx_open(struct snd_rawmidi_substream *substream);
   3258
   3259
   3260This is called when a substream is opened. You can initialize the
   3261hardware here, but you shouldn't start transmitting/receiving data yet.
   3262
   3263RawMIDI close callback
   3264~~~~~~~~~~~~~~~~~~~~~~
   3265
   3266::
   3267
   3268      static int snd_xxx_close(struct snd_rawmidi_substream *substream);
   3269
   3270Guess what.
   3271
   3272The ``open`` and ``close`` callbacks of a rawmidi device are
   3273serialized with a mutex, and can sleep.
   3274
   3275Rawmidi trigger callback for output substreams
   3276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3277
   3278::
   3279
   3280      static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
   3281
   3282
   3283This is called with a nonzero ``up`` parameter when there is some data
   3284in the substream buffer that must be transmitted.
   3285
   3286To read data from the buffer, call
   3287:c:func:`snd_rawmidi_transmit_peek()`. It will return the number
   3288of bytes that have been read; this will be less than the number of bytes
   3289requested when there are no more data in the buffer. After the data have
   3290been transmitted successfully, call
   3291:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
   3292substream buffer:
   3293
   3294::
   3295
   3296  unsigned char data;
   3297  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
   3298          if (snd_mychip_try_to_transmit(data))
   3299                  snd_rawmidi_transmit_ack(substream, 1);
   3300          else
   3301                  break; /* hardware FIFO full */
   3302  }
   3303
   3304If you know beforehand that the hardware will accept data, you can use
   3305the :c:func:`snd_rawmidi_transmit()` function which reads some
   3306data and removes them from the buffer at once:
   3307
   3308::
   3309
   3310  while (snd_mychip_transmit_possible()) {
   3311          unsigned char data;
   3312          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
   3313                  break; /* no more data */
   3314          snd_mychip_transmit(data);
   3315  }
   3316
   3317If you know beforehand how many bytes you can accept, you can use a
   3318buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
   3319
   3320The ``trigger`` callback must not sleep. If the hardware FIFO is full
   3321before the substream buffer has been emptied, you have to continue
   3322transmitting data later, either in an interrupt handler, or with a
   3323timer if the hardware doesn't have a MIDI transmit interrupt.
   3324
   3325The ``trigger`` callback is called with a zero ``up`` parameter when
   3326the transmission of data should be aborted.
   3327
   3328RawMIDI trigger callback for input substreams
   3329~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3330
   3331::
   3332
   3333      static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
   3334
   3335
   3336This is called with a nonzero ``up`` parameter to enable receiving data,
   3337or with a zero ``up`` parameter do disable receiving data.
   3338
   3339The ``trigger`` callback must not sleep; the actual reading of data
   3340from the device is usually done in an interrupt handler.
   3341
   3342When data reception is enabled, your interrupt handler should call
   3343:c:func:`snd_rawmidi_receive()` for all received data:
   3344
   3345::
   3346
   3347  void snd_mychip_midi_interrupt(...)
   3348  {
   3349          while (mychip_midi_available()) {
   3350                  unsigned char data;
   3351                  data = mychip_midi_read();
   3352                  snd_rawmidi_receive(substream, &data, 1);
   3353          }
   3354  }
   3355
   3356
   3357drain callback
   3358~~~~~~~~~~~~~~
   3359
   3360::
   3361
   3362      static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
   3363
   3364
   3365This is only used with output substreams. This function should wait
   3366until all data read from the substream buffer have been transmitted.
   3367This ensures that the device can be closed and the driver unloaded
   3368without losing data.
   3369
   3370This callback is optional. If you do not set ``drain`` in the struct
   3371snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
   3372instead.
   3373
   3374Miscellaneous Devices
   3375=====================
   3376
   3377FM OPL3
   3378-------
   3379
   3380The FM OPL3 is still used in many chips (mainly for backward
   3381compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
   3382is defined in ``<sound/opl3.h>``.
   3383
   3384FM registers can be directly accessed through the direct-FM API, defined
   3385in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
   3386accessed through the Hardware-Dependent Device direct-FM extension API,
   3387whereas in OSS compatible mode, FM registers can be accessed with the
   3388OSS direct-FM compatible API in ``/dev/dmfmX`` device.
   3389
   3390To create the OPL3 component, you have two functions to call. The first
   3391one is a constructor for the ``opl3_t`` instance.
   3392
   3393::
   3394
   3395  struct snd_opl3 *opl3;
   3396  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
   3397                  integrated, &opl3);
   3398
   3399The first argument is the card pointer, the second one is the left port
   3400address, and the third is the right port address. In most cases, the
   3401right port is placed at the left port + 2.
   3402
   3403The fourth argument is the hardware type.
   3404
   3405When the left and right ports have been already allocated by the card
   3406driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
   3407the opl3 module will allocate the specified ports by itself.
   3408
   3409When the accessing the hardware requires special method instead of the
   3410standard I/O access, you can create opl3 instance separately with
   3411:c:func:`snd_opl3_new()`.
   3412
   3413::
   3414
   3415  struct snd_opl3 *opl3;
   3416  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
   3417
   3418Then set ``command``, ``private_data`` and ``private_free`` for the
   3419private access function, the private data and the destructor. The
   3420``l_port`` and ``r_port`` are not necessarily set. Only the command
   3421must be set properly. You can retrieve the data from the
   3422``opl3->private_data`` field. 
   3423
   3424After creating the opl3 instance via :c:func:`snd_opl3_new()`,
   3425call :c:func:`snd_opl3_init()` to initialize the chip to the
   3426proper state. Note that :c:func:`snd_opl3_create()` always calls
   3427it internally.
   3428
   3429If the opl3 instance is created successfully, then create a hwdep device
   3430for this opl3.
   3431
   3432::
   3433
   3434  struct snd_hwdep *opl3hwdep;
   3435  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
   3436
   3437The first argument is the ``opl3_t`` instance you created, and the
   3438second is the index number, usually 0.
   3439
   3440The third argument is the index-offset for the sequencer client assigned
   3441to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
   3442always takes 0).
   3443
   3444Hardware-Dependent Devices
   3445--------------------------
   3446
   3447Some chips need user-space access for special controls or for loading
   3448the micro code. In such a case, you can create a hwdep
   3449(hardware-dependent) device. The hwdep API is defined in
   3450``<sound/hwdep.h>``. You can find examples in opl3 driver or
   3451``isa/sb/sb16_csp.c``.
   3452
   3453The creation of the ``hwdep`` instance is done via
   3454:c:func:`snd_hwdep_new()`.
   3455
   3456::
   3457
   3458  struct snd_hwdep *hw;
   3459  snd_hwdep_new(card, "My HWDEP", 0, &hw);
   3460
   3461where the third argument is the index number.
   3462
   3463You can then pass any pointer value to the ``private_data``. If you
   3464assign a private data, you should define the destructor, too. The
   3465destructor function is set in the ``private_free`` field.
   3466
   3467::
   3468
   3469  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
   3470  hw->private_data = p;
   3471  hw->private_free = mydata_free;
   3472
   3473and the implementation of the destructor would be:
   3474
   3475::
   3476
   3477  static void mydata_free(struct snd_hwdep *hw)
   3478  {
   3479          struct mydata *p = hw->private_data;
   3480          kfree(p);
   3481  }
   3482
   3483The arbitrary file operations can be defined for this instance. The file
   3484operators are defined in the ``ops`` table. For example, assume that
   3485this chip needs an ioctl.
   3486
   3487::
   3488
   3489  hw->ops.open = mydata_open;
   3490  hw->ops.ioctl = mydata_ioctl;
   3491  hw->ops.release = mydata_release;
   3492
   3493And implement the callback functions as you like.
   3494
   3495IEC958 (S/PDIF)
   3496---------------
   3497
   3498Usually the controls for IEC958 devices are implemented via the control
   3499interface. There is a macro to compose a name string for IEC958
   3500controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
   3501``<include/asound.h>``.
   3502
   3503There are some standard controls for IEC958 status bits. These controls
   3504use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
   3505fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
   3506callback, you don't specify the value field for this type (the count
   3507field must be set, though).
   3508
   3509“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
   3510status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
   3511returns the bitmask for professional mode. They are read-only controls.
   3512
   3513Meanwhile, “IEC958 Playback Default” control is defined for getting and
   3514setting the current default IEC958 bits.
   3515
   3516Due to historical reasons, both variants of the Playback Mask and the
   3517Playback Default controls can be implemented on either a
   3518``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
   3519Drivers should expose the mask and default on the same iface though.
   3520
   3521In addition, you can define the control switches to enable/disable or to
   3522set the raw bit mode. The implementation will depend on the chip, but
   3523the control should be named as “IEC958 xxx”, preferably using the
   3524:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
   3525
   3526You can find several cases, for example, ``pci/emu10k1``,
   3527``pci/ice1712``, or ``pci/cmipci.c``.
   3528
   3529Buffer and Memory Management
   3530============================
   3531
   3532Buffer Types
   3533------------
   3534
   3535ALSA provides several different buffer allocation functions depending on
   3536the bus and the architecture. All these have a consistent API. The
   3537allocation of physically-contiguous pages is done via
   3538:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
   3539type.
   3540
   3541The allocation of pages with fallback is
   3542:c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
   3543to allocate the specified pages but if the pages are not available, it
   3544tries to reduce the page sizes until enough space is found.
   3545
   3546The release the pages, call :c:func:`snd_free_xxx_pages()`
   3547function.
   3548
   3549Usually, ALSA drivers try to allocate and reserve a large contiguous
   3550physical space at the time the module is loaded for the later use. This
   3551is called “pre-allocation”. As already written, you can call the
   3552following function at pcm instance construction time (in the case of PCI
   3553bus).
   3554
   3555::
   3556
   3557  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
   3558                                        &pci->dev, size, max);
   3559
   3560where ``size`` is the byte size to be pre-allocated and the ``max`` is
   3561the maximum size to be changed via the ``prealloc`` proc file. The
   3562allocator will try to get an area as large as possible within the
   3563given size.
   3564
   3565The second argument (type) and the third argument (device pointer) are
   3566dependent on the bus. For normal devices, pass the device pointer
   3567(typically identical as ``card->dev``) to the third argument with
   3568``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
   3569bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
   3570You can pass NULL to the device pointer in that case, which is the
   3571default mode implying to allocate with ``GFP_KERNEL`` flag.
   3572If you need a different GFP flag, you can pass it by encoding the flag
   3573into the device pointer via a special macro
   3574:c:func:`snd_dma_continuous_data()`.
   3575For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
   3576device pointer (see the `Non-Contiguous Buffers`_ section).
   3577
   3578Once the buffer is pre-allocated, you can use the allocator in the
   3579``hw_params`` callback:
   3580
   3581::
   3582
   3583  snd_pcm_lib_malloc_pages(substream, size);
   3584
   3585Note that you have to pre-allocate to use this function.
   3586
   3587Most of drivers use, though, rather the newly introduced "managed
   3588buffer allocation mode" instead of the manual allocation or release.
   3589This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
   3590instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
   3591
   3592::
   3593
   3594  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
   3595                                 &pci->dev, size, max);
   3596
   3597where passed arguments are identical in both functions.
   3598The difference in the managed mode is that PCM core will call
   3599:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
   3600the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
   3601after the PCM ``hw_free`` callback automatically.  So the driver
   3602doesn't have to call these functions explicitly in its callback any
   3603longer.  This made many driver code having NULL ``hw_params`` and
   3604``hw_free`` entries.
   3605
   3606External Hardware Buffers
   3607-------------------------
   3608
   3609Some chips have their own hardware buffers and the DMA transfer from the
   3610host memory is not available. In such a case, you need to either 1)
   3611copy/set the audio data directly to the external hardware buffer, or 2)
   3612make an intermediate buffer and copy/set the data from it to the
   3613external hardware buffer in interrupts (or in tasklets, preferably).
   3614
   3615The first case works fine if the external hardware buffer is large
   3616enough. This method doesn't need any extra buffers and thus is more
   3617effective. You need to define the ``copy_user`` and ``copy_kernel``
   3618callbacks for the data transfer, in addition to ``fill_silence``
   3619callback for playback. However, there is a drawback: it cannot be
   3620mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
   3621
   3622The second case allows for mmap on the buffer, although you have to
   3623handle an interrupt or a tasklet to transfer the data from the
   3624intermediate buffer to the hardware buffer. You can find an example in
   3625the vxpocket driver.
   3626
   3627Another case is when the chip uses a PCI memory-map region for the
   3628buffer instead of the host memory. In this case, mmap is available only
   3629on certain architectures like the Intel one. In non-mmap mode, the data
   3630cannot be transferred as in the normal way. Thus you need to define the
   3631``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
   3632as in the cases above. The examples are found in ``rme32.c`` and
   3633``rme96.c``.
   3634
   3635The implementation of the ``copy_user``, ``copy_kernel`` and
   3636``silence`` callbacks depends upon whether the hardware supports
   3637interleaved or non-interleaved samples. The ``copy_user`` callback is
   3638defined like below, a bit differently depending whether the direction
   3639is playback or capture:
   3640
   3641::
   3642
   3643  static int playback_copy_user(struct snd_pcm_substream *substream,
   3644               int channel, unsigned long pos,
   3645               void __user *src, unsigned long count);
   3646  static int capture_copy_user(struct snd_pcm_substream *substream,
   3647               int channel, unsigned long pos,
   3648               void __user *dst, unsigned long count);
   3649
   3650In the case of interleaved samples, the second argument (``channel``) is
   3651not used. The third argument (``pos``) points the current position
   3652offset in bytes.
   3653
   3654The meaning of the fourth argument is different between playback and
   3655capture. For playback, it holds the source data pointer, and for
   3656capture, it's the destination data pointer.
   3657
   3658The last argument is the number of bytes to be copied.
   3659
   3660What you have to do in this callback is again different between playback
   3661and capture directions. In the playback case, you copy the given amount
   3662of data (``count``) at the specified pointer (``src``) to the specified
   3663offset (``pos``) on the hardware buffer. When coded like memcpy-like
   3664way, the copy would be like:
   3665
   3666::
   3667
   3668  my_memcpy_from_user(my_buffer + pos, src, count);
   3669
   3670For the capture direction, you copy the given amount of data (``count``)
   3671at the specified offset (``pos``) on the hardware buffer to the
   3672specified pointer (``dst``).
   3673
   3674::
   3675
   3676  my_memcpy_to_user(dst, my_buffer + pos, count);
   3677
   3678Here the functions are named as ``from_user`` and ``to_user`` because
   3679it's the user-space buffer that is passed to these callbacks.  That
   3680is, the callback is supposed to copy from/to the user-space data
   3681directly to/from the hardware buffer.
   3682
   3683Careful readers might notice that these callbacks receive the
   3684arguments in bytes, not in frames like other callbacks.  It's because
   3685it would make coding easier like the examples above, and also it makes
   3686easier to unify both the interleaved and non-interleaved cases, as
   3687explained in the following.
   3688
   3689In the case of non-interleaved samples, the implementation will be a bit
   3690more complicated.  The callback is called for each channel, passed by
   3691the second argument, so totally it's called for N-channels times per
   3692transfer.
   3693
   3694The meaning of other arguments are almost same as the interleaved
   3695case.  The callback is supposed to copy the data from/to the given
   3696user-space buffer, but only for the given channel.  For the detailed
   3697implementations, please check ``isa/gus/gus_pcm.c`` or
   3698"pci/rme9652/rme9652.c" as examples.
   3699
   3700The above callbacks are the copy from/to the user-space buffer.  There
   3701are some cases where we want copy from/to the kernel-space buffer
   3702instead.  In such a case, ``copy_kernel`` callback is called.  It'd
   3703look like:
   3704
   3705::
   3706
   3707  static int playback_copy_kernel(struct snd_pcm_substream *substream,
   3708               int channel, unsigned long pos,
   3709               void *src, unsigned long count);
   3710  static int capture_copy_kernel(struct snd_pcm_substream *substream,
   3711               int channel, unsigned long pos,
   3712               void *dst, unsigned long count);
   3713
   3714As found easily, the only difference is that the buffer pointer is
   3715without ``__user`` prefix; that is, a kernel-buffer pointer is passed
   3716in the fourth argument.  Correspondingly, the implementation would be
   3717a version without the user-copy, such as:
   3718
   3719::
   3720
   3721  my_memcpy(my_buffer + pos, src, count);
   3722
   3723Usually for the playback, another callback ``fill_silence`` is
   3724defined.  It's implemented in a similar way as the copy callbacks
   3725above:
   3726
   3727::
   3728
   3729  static int silence(struct snd_pcm_substream *substream, int channel,
   3730                     unsigned long pos, unsigned long count);
   3731
   3732The meanings of arguments are the same as in the ``copy_user`` and
   3733``copy_kernel`` callbacks, although there is no buffer pointer
   3734argument. In the case of interleaved samples, the channel argument has
   3735no meaning, as well as on ``copy_*`` callbacks.
   3736
   3737The role of ``fill_silence`` callback is to set the given amount
   3738(``count``) of silence data at the specified offset (``pos``) on the
   3739hardware buffer. Suppose that the data format is signed (that is, the
   3740silent-data is 0), and the implementation using a memset-like function
   3741would be like: 
   3742
   3743::
   3744
   3745  my_memset(my_buffer + pos, 0, count);
   3746
   3747In the case of non-interleaved samples, again, the implementation
   3748becomes a bit more complicated, as it's called N-times per transfer
   3749for each channel. See, for example, ``isa/gus/gus_pcm.c``.
   3750
   3751Non-Contiguous Buffers
   3752----------------------
   3753
   3754If your hardware supports the page table as in emu10k1 or the buffer
   3755descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
   3756provides an interface for handling SG-buffers. The API is provided in
   3757``<sound/pcm.h>``.
   3758
   3759For creating the SG-buffer handler, call
   3760:c:func:`snd_pcm_set_managed_buffer()` or
   3761:c:func:`snd_pcm_set_managed_buffer_all()` with
   3762``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
   3763pre-allocator. You need to pass ``&pci->dev``, where pci is
   3764the struct pci_dev pointer of the chip as
   3765well.
   3766
   3767::
   3768
   3769  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
   3770                                 &pci->dev, size, max);
   3771
   3772The ``struct snd_sg_buf`` instance is created as
   3773``substream->dma_private`` in turn. You can cast the pointer like:
   3774
   3775::
   3776
   3777  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
   3778
   3779Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
   3780handler will allocate the non-contiguous kernel pages of the given size
   3781and map them onto the virtually contiguous memory. The virtual pointer
   3782is addressed in runtime->dma_area. The physical address
   3783(``runtime->dma_addr``) is set to zero, because the buffer is
   3784physically non-contiguous. The physical address table is set up in
   3785``sgbuf->table``. You can get the physical address at a certain offset
   3786via :c:func:`snd_pcm_sgbuf_get_addr()`.
   3787
   3788If you need to release the SG-buffer data explicitly, call the
   3789standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
   3790
   3791Vmalloc'ed Buffers
   3792------------------
   3793
   3794It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
   3795example, for an intermediate buffer. In the recent version of kernel,
   3796you can simply allocate it via standard
   3797:c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
   3798buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
   3799
   3800::
   3801
   3802  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
   3803                                 NULL, 0, 0);
   3804
   3805The NULL is passed to the device pointer argument, which indicates
   3806that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
   3807allocated.
   3808
   3809Also, note that zero is passed to both the size and the max size
   3810arguments here.  Since each vmalloc call should succeed at any time,
   3811we don't need to pre-allocate the buffers like other continuous
   3812pages.
   3813
   3814If you need the 32bit DMA allocation, pass the device pointer encoded
   3815by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
   3816argument.
   3817
   3818::
   3819
   3820  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
   3821          snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
   3822
   3823Proc Interface
   3824==============
   3825
   3826ALSA provides an easy interface for procfs. The proc files are very
   3827useful for debugging. I recommend you set up proc files if you write a
   3828driver and want to get a running status or register dumps. The API is
   3829found in ``<sound/info.h>``.
   3830
   3831To create a proc file, call :c:func:`snd_card_proc_new()`.
   3832
   3833::
   3834
   3835  struct snd_info_entry *entry;
   3836  int err = snd_card_proc_new(card, "my-file", &entry);
   3837
   3838where the second argument specifies the name of the proc file to be
   3839created. The above example will create a file ``my-file`` under the
   3840card directory, e.g. ``/proc/asound/card0/my-file``.
   3841
   3842Like other components, the proc entry created via
   3843:c:func:`snd_card_proc_new()` will be registered and released
   3844automatically in the card registration and release functions.
   3845
   3846When the creation is successful, the function stores a new instance in
   3847the pointer given in the third argument. It is initialized as a text
   3848proc file for read only. To use this proc file as a read-only text file
   3849as it is, set the read callback with a private data via
   3850:c:func:`snd_info_set_text_ops()`.
   3851
   3852::
   3853
   3854  snd_info_set_text_ops(entry, chip, my_proc_read);
   3855
   3856where the second argument (``chip``) is the private data to be used in
   3857the callbacks. The third parameter specifies the read buffer size and
   3858the fourth (``my_proc_read``) is the callback function, which is
   3859defined like
   3860
   3861::
   3862
   3863  static void my_proc_read(struct snd_info_entry *entry,
   3864                           struct snd_info_buffer *buffer);
   3865
   3866In the read callback, use :c:func:`snd_iprintf()` for output
   3867strings, which works just like normal :c:func:`printf()`. For
   3868example,
   3869
   3870::
   3871
   3872  static void my_proc_read(struct snd_info_entry *entry,
   3873                           struct snd_info_buffer *buffer)
   3874  {
   3875          struct my_chip *chip = entry->private_data;
   3876
   3877          snd_iprintf(buffer, "This is my chip!\n");
   3878          snd_iprintf(buffer, "Port = %ld\n", chip->port);
   3879  }
   3880
   3881The file permissions can be changed afterwards. As default, it's set as
   3882read only for all users. If you want to add write permission for the
   3883user (root as default), do as follows:
   3884
   3885::
   3886
   3887 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
   3888
   3889and set the write buffer size and the callback
   3890
   3891::
   3892
   3893  entry->c.text.write = my_proc_write;
   3894
   3895For the write callback, you can use :c:func:`snd_info_get_line()`
   3896to get a text line, and :c:func:`snd_info_get_str()` to retrieve
   3897a string from the line. Some examples are found in
   3898``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
   3899
   3900For a raw-data proc-file, set the attributes as follows:
   3901
   3902::
   3903
   3904  static const struct snd_info_entry_ops my_file_io_ops = {
   3905          .read = my_file_io_read,
   3906  };
   3907
   3908  entry->content = SNDRV_INFO_CONTENT_DATA;
   3909  entry->private_data = chip;
   3910  entry->c.ops = &my_file_io_ops;
   3911  entry->size = 4096;
   3912  entry->mode = S_IFREG | S_IRUGO;
   3913
   3914For the raw data, ``size`` field must be set properly. This specifies
   3915the maximum size of the proc file access.
   3916
   3917The read/write callbacks of raw mode are more direct than the text mode.
   3918You need to use a low-level I/O functions such as
   3919:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
   3920
   3921::
   3922
   3923  static ssize_t my_file_io_read(struct snd_info_entry *entry,
   3924                              void *file_private_data,
   3925                              struct file *file,
   3926                              char *buf,
   3927                              size_t count,
   3928                              loff_t pos)
   3929  {
   3930          if (copy_to_user(buf, local_data + pos, count))
   3931                  return -EFAULT;
   3932          return count;
   3933  }
   3934
   3935If the size of the info entry has been set up properly, ``count`` and
   3936``pos`` are guaranteed to fit within 0 and the given size. You don't
   3937have to check the range in the callbacks unless any other condition is
   3938required.
   3939
   3940Power Management
   3941================
   3942
   3943If the chip is supposed to work with suspend/resume functions, you need
   3944to add power-management code to the driver. The additional code for
   3945power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
   3946with __maybe_unused attribute; otherwise the compiler will complain
   3947you.
   3948
   3949If the driver *fully* supports suspend/resume that is, the device can be
   3950properly resumed to its state when suspend was called, you can set the
   3951``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
   3952possible when the registers of the chip can be safely saved and restored
   3953to RAM. If this is set, the trigger callback is called with
   3954``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
   3955
   3956Even if the driver doesn't support PM fully but partial suspend/resume
   3957is still possible, it's still worthy to implement suspend/resume
   3958callbacks. In such a case, applications would reset the status by
   3959calling :c:func:`snd_pcm_prepare()` and restart the stream
   3960appropriately. Hence, you can define suspend/resume callbacks below but
   3961don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
   3962
   3963Note that the trigger with SUSPEND can always be called when
   3964:c:func:`snd_pcm_suspend_all()` is called, regardless of the
   3965``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
   3966behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
   3967``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
   3968callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
   3969to keep it for compatibility reasons.)
   3970
   3971In the earlier version of ALSA drivers, a common power-management layer
   3972was provided, but it has been removed. The driver needs to define the
   3973suspend/resume hooks according to the bus the device is connected to. In
   3974the case of PCI drivers, the callbacks look like below:
   3975
   3976::
   3977
   3978  static int __maybe_unused snd_my_suspend(struct device *dev)
   3979  {
   3980          .... /* do things for suspend */
   3981          return 0;
   3982  }
   3983  static int __maybe_unused snd_my_resume(struct device *dev)
   3984  {
   3985          .... /* do things for suspend */
   3986          return 0;
   3987  }
   3988
   3989The scheme of the real suspend job is as follows.
   3990
   39911. Retrieve the card and the chip data.
   3992
   39932. Call :c:func:`snd_power_change_state()` with
   3994   ``SNDRV_CTL_POWER_D3hot`` to change the power status.
   3995
   39963. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
   3997   each codec.
   3998
   39994. Save the register values if necessary.
   4000
   40015. Stop the hardware if necessary.
   4002
   4003A typical code would be like:
   4004
   4005::
   4006
   4007  static int __maybe_unused mychip_suspend(struct device *dev)
   4008  {
   4009          /* (1) */
   4010          struct snd_card *card = dev_get_drvdata(dev);
   4011          struct mychip *chip = card->private_data;
   4012          /* (2) */
   4013          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
   4014          /* (3) */
   4015          snd_ac97_suspend(chip->ac97);
   4016          /* (4) */
   4017          snd_mychip_save_registers(chip);
   4018          /* (5) */
   4019          snd_mychip_stop_hardware(chip);
   4020          return 0;
   4021  }
   4022
   4023
   4024The scheme of the real resume job is as follows.
   4025
   40261. Retrieve the card and the chip data.
   4027
   40282. Re-initialize the chip.
   4029
   40303. Restore the saved registers if necessary.
   4031
   40324. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
   4033
   40345. Restart the hardware (if any).
   4035
   40366. Call :c:func:`snd_power_change_state()` with
   4037   ``SNDRV_CTL_POWER_D0`` to notify the processes.
   4038
   4039A typical code would be like:
   4040
   4041::
   4042
   4043  static int __maybe_unused mychip_resume(struct pci_dev *pci)
   4044  {
   4045          /* (1) */
   4046          struct snd_card *card = dev_get_drvdata(dev);
   4047          struct mychip *chip = card->private_data;
   4048          /* (2) */
   4049          snd_mychip_reinit_chip(chip);
   4050          /* (3) */
   4051          snd_mychip_restore_registers(chip);
   4052          /* (4) */
   4053          snd_ac97_resume(chip->ac97);
   4054          /* (5) */
   4055          snd_mychip_restart_chip(chip);
   4056          /* (6) */
   4057          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
   4058          return 0;
   4059  }
   4060
   4061Note that, at the time this callback gets called, the PCM stream has
   4062been already suspended via its own PM ops calling
   4063:c:func:`snd_pcm_suspend_all()` internally.
   4064
   4065OK, we have all callbacks now. Let's set them up. In the initialization
   4066of the card, make sure that you can get the chip data from the card
   4067instance, typically via ``private_data`` field, in case you created the
   4068chip data individually.
   4069
   4070::
   4071
   4072  static int snd_mychip_probe(struct pci_dev *pci,
   4073                              const struct pci_device_id *pci_id)
   4074  {
   4075          ....
   4076          struct snd_card *card;
   4077          struct mychip *chip;
   4078          int err;
   4079          ....
   4080          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
   4081                             0, &card);
   4082          ....
   4083          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
   4084          ....
   4085          card->private_data = chip;
   4086          ....
   4087  }
   4088
   4089When you created the chip data with :c:func:`snd_card_new()`, it's
   4090anyway accessible via ``private_data`` field.
   4091
   4092::
   4093
   4094  static int snd_mychip_probe(struct pci_dev *pci,
   4095                              const struct pci_device_id *pci_id)
   4096  {
   4097          ....
   4098          struct snd_card *card;
   4099          struct mychip *chip;
   4100          int err;
   4101          ....
   4102          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
   4103                             sizeof(struct mychip), &card);
   4104          ....
   4105          chip = card->private_data;
   4106          ....
   4107  }
   4108
   4109If you need a space to save the registers, allocate the buffer for it
   4110here, too, since it would be fatal if you cannot allocate a memory in
   4111the suspend phase. The allocated buffer should be released in the
   4112corresponding destructor.
   4113
   4114And next, set suspend/resume callbacks to the pci_driver.
   4115
   4116::
   4117
   4118  static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
   4119
   4120  static struct pci_driver driver = {
   4121          .name = KBUILD_MODNAME,
   4122          .id_table = snd_my_ids,
   4123          .probe = snd_my_probe,
   4124          .remove = snd_my_remove,
   4125          .driver.pm = &snd_my_pm_ops,
   4126  };
   4127
   4128Module Parameters
   4129=================
   4130
   4131There are standard module options for ALSA. At least, each module should
   4132have the ``index``, ``id`` and ``enable`` options.
   4133
   4134If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
   4135cards), they should be arrays. The default initial values are defined
   4136already as constants for easier programming:
   4137
   4138::
   4139
   4140  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
   4141  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
   4142  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
   4143
   4144If the module supports only a single card, they could be single
   4145variables, instead. ``enable`` option is not always necessary in this
   4146case, but it would be better to have a dummy option for compatibility.
   4147
   4148The module parameters must be declared with the standard
   4149``module_param()``, ``module_param_array()`` and
   4150:c:func:`MODULE_PARM_DESC()` macros.
   4151
   4152The typical coding would be like below:
   4153
   4154::
   4155
   4156  #define CARD_NAME "My Chip"
   4157
   4158  module_param_array(index, int, NULL, 0444);
   4159  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
   4160  module_param_array(id, charp, NULL, 0444);
   4161  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
   4162  module_param_array(enable, bool, NULL, 0444);
   4163  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
   4164
   4165Also, don't forget to define the module description and the license.
   4166Especially, the recent modprobe requires to define the
   4167module license as GPL, etc., otherwise the system is shown as “tainted”.
   4168
   4169::
   4170
   4171  MODULE_DESCRIPTION("Sound driver for My Chip");
   4172  MODULE_LICENSE("GPL");
   4173
   4174
   4175Device-Managed Resources
   4176========================
   4177
   4178In the examples above, all resources are allocated and released
   4179manually.  But human beings are lazy in nature, especially developers
   4180are lazier.  So there are some ways to automate the release part; it's
   4181the (device-)managed resources aka devres or devm family.  For
   4182example, an object allocated via :c:func:`devm_kmalloc()` will be
   4183freed automatically at unbinding the device.
   4184
   4185ALSA core provides also the device-managed helper, namely,
   4186:c:func:`snd_devm_card_new()` for creating a card object.
   4187Call this functions instead of the normal :c:func:`snd_card_new()`,
   4188and you can forget the explicit :c:func:`snd_card_free()` call, as
   4189it's called automagically at error and removal paths.
   4190
   4191One caveat is that the call of :c:func:`snd_card_free()` would be put
   4192at the beginning of the call chain only after you call
   4193:c:func:`snd_card_register()`.
   4194
   4195Also, the ``private_free`` callback is always called at the card free,
   4196so be careful to put the hardware clean-up procedure in
   4197``private_free`` callback.  It might be called even before you
   4198actually set up at an earlier error path.  For avoiding such an
   4199invalid initialization, you can set ``private_free`` callback after
   4200:c:func:`snd_card_register()` call succeeds.
   4201
   4202Another thing to be remarked is that you should use device-managed
   4203helpers for each component as much as possible once when you manage
   4204the card in that way.  Mixing up with the normal and the managed
   4205resources may screw up the release order.
   4206
   4207
   4208How To Put Your Driver Into ALSA Tree
   4209=====================================
   4210
   4211General
   4212-------
   4213
   4214So far, you've learned how to write the driver codes. And you might have
   4215a question now: how to put my own driver into the ALSA driver tree? Here
   4216(finally :) the standard procedure is described briefly.
   4217
   4218Suppose that you create a new PCI driver for the card “xyz”. The card
   4219module name would be snd-xyz. The new driver is usually put into the
   4220alsa-driver tree, ``sound/pci`` directory in the case of PCI
   4221cards.
   4222
   4223In the following sections, the driver code is supposed to be put into
   4224Linux kernel tree. The two cases are covered: a driver consisting of a
   4225single source file and one consisting of several source files.
   4226
   4227Driver with A Single Source File
   4228--------------------------------
   4229
   42301. Modify sound/pci/Makefile
   4231
   4232   Suppose you have a file xyz.c. Add the following two lines
   4233
   4234::
   4235
   4236  snd-xyz-objs := xyz.o
   4237  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
   4238
   42392. Create the Kconfig entry
   4240
   4241   Add the new entry of Kconfig for your xyz driver. config SND_XYZ
   4242   tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
   4243   to include support for Foobar XYZ soundcard. To compile this driver
   4244   as a module, choose M here: the module will be called snd-xyz. the
   4245   line, select SND_PCM, specifies that the driver xyz supports PCM. In
   4246   addition to SND_PCM, the following components are supported for
   4247   select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
   4248   SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
   4249   SND_AC97_CODEC. Add the select command for each supported
   4250   component.
   4251
   4252   Note that some selections imply the lowlevel selections. For example,
   4253   PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
   4254   includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
   4255   the lowlevel selections again.
   4256
   4257   For the details of Kconfig script, refer to the kbuild documentation.
   4258
   4259Drivers with Several Source Files
   4260---------------------------------
   4261
   4262Suppose that the driver snd-xyz have several source files. They are
   4263located in the new subdirectory, sound/pci/xyz.
   4264
   42651. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
   4266   as below
   4267
   4268::
   4269
   4270  obj-$(CONFIG_SND) += sound/pci/xyz/
   4271
   4272
   42732. Under the directory ``sound/pci/xyz``, create a Makefile
   4274
   4275::
   4276
   4277         snd-xyz-objs := xyz.o abc.o def.o
   4278         obj-$(CONFIG_SND_XYZ) += snd-xyz.o
   4279
   42803. Create the Kconfig entry
   4281
   4282   This procedure is as same as in the last section.
   4283
   4284
   4285Useful Functions
   4286================
   4287
   4288:c:func:`snd_printk()` and friends
   4289----------------------------------
   4290
   4291.. note:: This subsection describes a few helper functions for
   4292   decorating a bit more on the standard :c:func:`printk()` & co.
   4293   However, in general, the use of such helpers is no longer recommended.
   4294   If possible, try to stick with the standard functions like
   4295   :c:func:`dev_err()` or :c:func:`pr_err()`.
   4296
   4297ALSA provides a verbose version of the :c:func:`printk()` function.
   4298If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
   4299prints the given message together with the file name and the line of the
   4300caller. The ``KERN_XXX`` prefix is processed as well as the original
   4301:c:func:`printk()` does, so it's recommended to add this prefix,
   4302e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
   4303
   4304There are also :c:func:`printk()`'s for debugging.
   4305:c:func:`snd_printd()` can be used for general debugging purposes.
   4306If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
   4307just like :c:func:`snd_printk()`. If the ALSA is compiled without
   4308the debugging flag, it's ignored.
   4309
   4310:c:func:`snd_printdd()` is compiled in only when
   4311``CONFIG_SND_DEBUG_VERBOSE`` is set.
   4312
   4313:c:func:`snd_BUG()`
   4314-------------------
   4315
   4316It shows the ``BUG?`` message and stack trace as well as
   4317:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
   4318fatal error happens there.
   4319
   4320When no debug flag is set, this macro is ignored.
   4321
   4322:c:func:`snd_BUG_ON()`
   4323----------------------
   4324
   4325:c:func:`snd_BUG_ON()` macro is similar with
   4326:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
   4327it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
   4328return -EINVAL;
   4329
   4330The macro takes an conditional expression to evaluate. When
   4331``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
   4332the warning message such as ``BUG? (xxx)`` normally followed by stack
   4333trace. In both cases it returns the evaluated value.
   4334
   4335Acknowledgments
   4336===============
   4337
   4338I would like to thank Phil Kerr for his help for improvement and
   4339corrections of this document.
   4340
   4341Kevin Conder reformatted the original plain-text to the DocBook format.
   4342
   4343Giuliano Pochini corrected typos and contributed the example codes in
   4344the hardware constraints section.