<!doctype linuxdoc system>

<!-- Advanced Linux Sound Architecture - Driver -->

<article>

<!-- Title information -->

<title>Advanced Linux Sound Architecture - Driver
<author>Jaroslav Kysela
<htmlurl url="mailto:perex@jcu.cz" name="&lt;perex@jcu.cz&gt;">
<!-- with assistance from Alan Robinson -->
<date>v0.0.1, 12 May 1998
<abstract>
This document describes, in full detail, the Advanced Linux Sound
Architecture driver.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Introduction

<p>
This document describes the ALSA driver and kernel API. Application
programmers should use the library API rather than kernel API.
The ALSA Library offers 100% of the functionally of the kernel API, but add
next major improvements in usability, making the application code simpler and
better looking. In addition, some of the some fixes/compatibility code in,
may be placed in the library code instead of the kernel driver.


<sect1>Source files

<p>
Source files are separated to:

<p>
<descrip>
<tag>/include</tag>
  Directory contains all header files which are included from more sources.
<tag>/kernel</tag>
  Directory with kernel code and abstract layers (middle level code and library).
<tag>/lowlevel</tag>
  Generic lowlevel code for chip(set)s.
<tag>/cards</tag>
  Upper level for soundcards and specific lowlevel code.
<tag>/detect</tag>
  Detection layer (<it>/proc/sound/detect</it> - to make installation easy).
</descrip>

<sect1>Devices

<p>
Devices should use abstract code from sound kernel, but it should use
own code and register minors separetely (with snd_minor_register and
snd_minor_unregister functions). This method totaly bypass all abstract
code, so code for these soundcards must handle all things.

<sect1>Memory allocation

<p>
<itemize>
<item><bf>void *snd_malloc( unsigned long size )</bf>
<item><bf>void snd_free( void *ptr, unsigned long size )</bf>
<item><bf>char *snd_malloc_strdup( char *string )</bf>
<item><bf>void snd_free_str( char *string )</bf>
</itemize>
<p>
Routines uses it's own memory allocation algoritm. It should be removed
in future and replaced with kmalloc and kfree calls, but I need trace
all allocation problems to make code clean...
<p>
Note: ALSA driver heavy uses dynamic allocation for most things.
<p>
For debugging you should use command './configure --with-debug=full' for
configuration. This enables trace of allocated memory with above functions
and this makes debugging a little bit easier.

<sect1>Basic coding

<p>
All things are made as object (which encapsulates data and functions) and are
referenced in this way. I don't preferr pass index to some array of structure
or something this. Pointer to object which contains data and functions should
be passed rather (like C++).
<p>
All main structures should have snd_xxxx_new, snd_xxxx_free, snd_xxxx_register,
snd_xxxx_unregister functions.
<p>
<itemize>
<item>
<bf>snd_card_t</bf> is basic structure which contains info about soundcard,
index and resource tracking variables. You should look to <it>include/driver.h</it>
for all things related to this structure.
</itemize>
<p>
<itemize>
<item><bf>snd_pcm_t</bf> is basic structure for PCM device.
<item><bf>snd_pcm_channel_t</bf> is basic structure for PCM channel (direction).
<item><bf>struct snd_stru_pcm_hardware</bf> is structure which must be filled
by lowlevel code. You should look to <it>include/pcm.h</it> for all things
related to these structures.
</itemize>
<p>
<itemize>
<item><bf>snd_kmixer_t</bf> is basic structure for MIXER device.
<item><bf>snd_kmixer_channel_t</bf> is basic structure for MIXER channel.
<item><bf>struct snd_stru_mixer_channel_hw</bf> is structure which must be filled
by lowlevel code. You should look to <it>include/mixer.h</it> for all things
related to these structures.
</itemize>

<sect1>Upper level (/cards)

<p>
Code for soundcards should contain these things:

<enum>
<item>Support for more same soundcards (up to SND_CARDS)...
  <itemize>
     <item>it isn't really possible due to HW limitations
  </itemize>
<item>Autodetection/autoconfiguration feature (if it's possible)...
  <itemize>
     <item>if lowlevel code is specific for soundcard type - it should be here, too..
  </itemize>
<item>Initialization code for soundcard
  <itemize>
    <item>snd_card_new
    <item>snd_card_free (frees all hardware resources)
  </itemize>
<item>Allocate/free hardware resources for soundcard
  <itemize>
     <item>snd_register_ioport
    <item>snd_unregister_ioports (frees all ioports)
    <item>snd_register_interrupt
    <item>snd_unregister_interrupts (frees all interrupts)
    <item>snd_register_dma_channel
    <item>snd_unregister_dma_channels (frees all DMA channels)
  </itemize>
<item>Initialize other layers (PCMs, Mixers etc.)
  <itemize>
    <item>snd_pcm_new
    <item>snd_pcm_free
    <item>snd_pcm_register
    <item>snd_pcm_unregister (calls snd_pcm_free)
    <item>snd_mixer_new
    <item>snd_mixer_free
    <item>snd_mixer_register
    <item>snd_mixer_unregister (calls snd_mixer_free)
  </itemize>
<item>Register soundcard
  <itemize>
    <item>snd_card_register
    <item>snd_card_unregister (doesn't calls snd_card_free)
  </itemize>
</enum>

<bf>Note:</bf>
Due to module dependency you should separate code for soundcards
from same manufacture which have slightly different hardware.
Example: GUS Extreme have ESS ES-1688 chip. This chip isn't in GUS
Classic. For GUS Classic isn't generic code in snd-es1688.o module
needed, so there is two upper level modules (snd-gusextreme.o and
snd-gusclassic.o).

<sect1>Private data/values

<p>
Some structures have pointers on private data and values. These variables
aren't used with abstract layers and use is intended for low-level code. 

<code>
snd_card_t -> private_data
snd_card_t -> private_free (called from snd_card_free if not NULL)
</code>
<p>
<code>
struct snd_stru_pcm_hardware -> private_data
struct snd_stru_pcm_hardware -> private_free (called from snd_pcm_free if not NULL)
snd_pcm_t -> private_data
snd_pcm_t -> private_free (called from snd_pcm_free if not NULL)
</code>
<p>
<code>
struct snd_stru_mixer_channel_hw -> private_value
snd_kmixer_channel_t -> private_data
snd_kmixer_channel_t -> private_free (called from snd_mixer_free if not NULL)
snd_kmixer_t -> private_value
snd_kmixer_t -> private_data
snd_kmixer_t -> private_free (called from snd_mixer_free if not NULL)
</code>

<sect1>CLI/STI & spin locking

<p>
Good code shouldn't contains <it>snd_cli()</it>/<it>snd_sti()</it> calls.
Use rather spin locks <it>snd_spin_lock()</it>/<it>snd_spin_unlock()</it>
for locking some code. This code is much better for SMP machines.
<p>
<bf>Note:</bf> Debugging code is available and it should be enabled in
<it>sndspinlock.h</it>.

<sect1>Examples

<p>
You should look to code for GUS soundcards how can be things done...

<bf>Note:</bf> Code should be compiled cleanly under 2.0.X kernels and under
      latest 2.1.X kernels...


<!-- ******************************************************************* -->
<!-- ************************** SoundCard ****************************** -->
<!-- ******************************************************************* -->

<sect>Soundcard

<p>
Soundcard related structures and functions are in <it>include/driver.h</it>
header file. Structure <it>snd_card_t</it> must be allocated by
<it>snd_card_new</it> function and freed by <it>snd_card_free</it>
function (whis isn't called from <it>snd_card_unregister</it>).

<sect1>Variables and functions

<p>
Functions list:

<itemize>
<item><bf>snd_card_t *snd_card_new( int idx, char *id, void (*use_inc)( snd_card_t * ), void (*use_dec)( snd_card_t *) )</bf>
  <itemize>
  <item><bf>idx</bf> soundcard index (order), 1-8 or -1 = first free
  <item><bf>id</bf> soundcard id, if NULL or '\0' -> default (card#)
  <item><bf>inc_use</bf> increment use of last soundcard module (to avoid remove)
  <item><bf>dec_use</bf> decrement use of last soundcard module (to allow remove)
  <item>returns NULL if not enough memory is available
  </itemize>
<item><bf>int snd_card_free( snd_card_t *card )</bf>
  <itemize>
  <item><bf>card</bf> pointer to soundcard structure to free
  <item>frees all registered resources (ports, IRQs and DMAs), too
  <item>returns negative value when error
  </itemize>
<item><bf>int snd_card_register( snd_card_t *card )</bf>
  <itemize>
  <item><bf>card</bf> pointer to soundcard structure to register; applications
        should from this point use soundcard
  <item>returns negative value when error
  </itemize>
<item><bf>int snd_card_unregister( snd_card_t *card )</bf>
  <itemize>
  <item><bf>card</bf> pointer to soundcard structure to unregister; applications
        aren't able from this point use soundcard
  <item>doesn't call <it>snd_card_free</it>
  <item>returns negative value when error
  </itemize>
</itemize>

<p>
Variables from <it>snd_card_t</it> structure which must be filled:

<itemize>
<item><bf>type</bf> is type identification from <it>include/sounddetect.h</it>.
<item><bf>abbreviation</bf> is abbreviation for soundcard (for example 'GUS').
<item><bf>shortname</bf> is shortname for soundcard (for example 'Gravis UltraSound MAX').
<item><bf>longname</bf> is full identification for soundcard (for example 'Gravis UltraSound MAX at 0x220, irq 5, dma 1&5').
</itemize>

<p>
Variables from <it>snd_card_t</it> structure which should be filled:

<itemize>
<item><bf>private_data</bf> should be used by soundcard driver for private data.
<item><bf>private_free</bf> is called when <it>private_data</it> should be freed.
</itemize>

<sect2>Examples

<p>
<tscreen><code>
static void snd_soundcard_use_inc( snd_card_t *card )
{
  MOD_INC_USE_COUNT;
}

static void snd_soundcard_use_dec( snd_card_t *card )
{
  MOD_DEC_USE_COUNT;
}

int snd_soundcard_init( void )
{
  snd_card_t *card;

  card = snd_card_new( -1, NULL, snd_soundcard_use_inc, snd_soundcard_dec_inc );
  if ( !card ) return -ENOMEM;
  card -> type = SND_CARD_TYPE_SOUNDCARD;	/* can be changed later */

  ... resource initialization, detection, device creation and registration ...

  strcpy( card -> abbreviation, "SoundCard" );
  strcpy( card -> shortname, "3-D SoundCard" );
  strcpy( card -> longname, "3-D SoundCard at 0x500, irq 5, dma 5&6" );

  if ( !snd_card_register( card ) )
    return 0;
  snd_card_free( card );

  return -ENXIO;
}
</code></tscreen>

<sect1>Resources

<p>
Functions list:

<itemize>
  <item><bf>int snd_register_ioport( snd_card_t *card, int port, int size, char *name )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>port</bf> means first port from ioport region
    <item><bf>size</bf> means size of ioport region
    <item><bf>name</bf> ioport region name
    <item>registers ioport region and assigns it to soundcard
  </itemize>
  <item><bf>int snd_unregister_ioports( snd_card_t *card )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item>unregisters all ioport regions which are assigned to soundcard
  </itemize>
  <item><bf>int snd_register_dma_channel( snd_card_t *card, char *name, int number, int type, int rsize, int *possible_numbers )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>name</bf> name of dma channel
    <item><bf>number</bf> number of dma channel or <bf>SND_AUTO_DMA</bf>
    <item><bf>type</bf> type of dma buffer
      <itemize>
        <item><bf>SND_DMA_TYPE_ISA</bf> limited dma buffer to low 16MB of RAM
        <item><bf>SND_DMA_TYPE_PCI</bf> unlimited dma buffer
              (should be anywhere in RAM)
        <item><bf>SND_DMA_TYPE_HARDWARE</bf> hardware dma buffer
              (is available on soundcard and directly mmaped to OS memory)
      </itemize>
    <item><bf>rsize</bf> requested dma buffer size (in kB) or <bf>SND_AUTO_DMA_SIZE</bf>
    <item><bf>possible_numbers</bf> pointer to int array which contains all
          possible dma numbers for this channel terminated by -1; function
          uses these values for verification of valid input from user or
          if <bf>SND_AUTO_DMA</bf> is specified to detect first useable
          dma channel
  </itemize>
  <item><bf>int snd_unregister_dma_channels( snd_card_t *card )</bf>
  <itemize>
     <item><bf>card</bf> pointer to soundcard structure
     <item>unregisters all dma channels assigned to soundcard
  </itemize>
  <item><bf>int snd_register_interrupt( snd_card_t *card, char *name, int number, int type, snd_irq_handler_t *handler, void *dev_id, int *possible_numbers )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>name</bf> name of interrupt line
    <item><bf>number</bf> number of interrupt line or <bf>SND_AUTO_IRQ</bf>
    <item><bf>type</bf> type of interrupt line
      <itemize>
      <item><bf>SND_IRQ_TYPE_ISA</bf> ISA interrupt line (not shareable)
      <item><bf>SND_IRQ_TYPE_PCI</bf> PCI interrupt line (shareable)
      </itemize>
    <item><bf>handler</bf> pointer to interrupt handler
    <item><bf>dev_id</bf> pointer to some private structure for interrupt handler
    <item><bf>possible_numbers</bf> pointer to int arrays which contains all
          possible dma numbers for this channel terminated by -1; function
          uses these values for verification of valid input from user or
          if <bf>SND_AUTO_IRQ</bf> is specified to detect first useable
          interrupt line
    <item>returns index to card -> irqs array
  </itemize>
  <item><bf>int snd_unregister_interrupts( snd_card_t *card )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item>disables and frees all interrupt lines assigned to soundcard
  </itemize>
  <item><bf>int snd_enable_irq( snd_card_t *card, int irqnum )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>irqnum</bf> index of interrupt line to be enabled
  </itemize>
  <item><bf>int snd_disable_irq( snd_card_t *card, int irqnum )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>irqnum</bf> index of interrupt line to be disabled
  </itemize>
</itemize>

<bf>Note 1:</bf> dma buffer must be assigned for all (PCI and other than ISA)
soundcards, too. ALSA kernel and OSS PCM midlevel code contains mechanism
for correct free when mmaped access was used. Buffer isn't allocated at
register time. Buffer is managed with functions <it>snd_dma_malloc</it>
and <it>snd_dma_free</it> when some device is opened/closed.

<bf>Note 2:</bf> routines for interrupt line and dma channel registering
returns index do <it>snd_card_t -> irqs</it> and <it>snd_card_t -> dmas</it>
arrays. This value isn't equal to interrupt number or dma channel number,
but in driver <it>irqnum</it> or <it>dmanum</it> means irq or dma index 
(internal driver resource identification) and <it>irq</it> or <it>dma</it>
means real irq or dma number.

<sect2>Examples
  
<p>
<tscreen><code>
int snd_irq = SND_DEFAULT_IRQ1;
int snd_dma1 = SND_DEFAULT_DMA1;
int snd_dma1_size = SND_DEFAULT_DMA_SIZE1;

static snd_card_t *snd_card = NULL;
static int snd_irqnum = SND_IRQ_DISABLE;

static void snd_soundcard_interrupt1( int irq, void *dev_id, struct pt_regs *regs )
{
  ... interrupt handler ...
}

void snd_soundcard_init_resources( void )
{
#ifdef EXAMPLE_FOR_ISA_BUS
  static int possible_irqs[] = { 9, 10, 11, 7, -1 };
  static int possible_dmas[] = { 1, 3, 0, -1 };
 
  if ( (snd_irqnum = snd_register_interrupt( snd_card, "SoundCard", snd_irq, SND_IRQ_TYPE_ISA, snd_soundcard_interrupt, NULL, possible_irqs )) < 0 )
    return snd_irqnum;
  if ( (snd_dma1num = snd_register_dma_channel( snd_card, "SoundCard", snd_dma1, SND_DMA_TYPE_ISA, snd_dma1_size, possible_dmas )) < 0 )
    return snd_dma1num;
#else /* EXAMPLE_FOR_PCI_BUS */
  if ( (snd_irqnum = snd_register_interrupt( snd_card, "SoundCard", snd_irq, SND_IRQ_TYPE_PCI, snd_soundcard_interrupt, NULL, NULL )) < 0 )
    return snd_irqnum;
  if ( (snd_dma1num = snd_register_dma_channel( snd_card, "SoundCard", snd_dma1, SND_DMA_TYPE_PCI, snd_dma1_size, NULL )) < 0 )
    return snd_dma1num;
#endif
}

int snd_soundcard_probe( unsigned short port )
{
  if ( snd_register_ioport( snd_card, port, 8, "SoundCard - Codec" ) < 0 )
    return -EBUSY;
  if ( snd_register_ioport( snd_card, port + 0x100, 16, "SoundCard - Synthesizer" ) < 0 ) {
    snd_unregister_ioports( snd_card );
    return -EBUSY;
  }

  ... hardware probe here - if fails - snd_unregister_ioports!!! ...

  return 0;
}
</code></tscreen>

<sect1>ISA DMA

<p>
Functions list:

<itemize>
  <item><bf>void snd_dma_program( int dma, const void *buf, unsigned int size, unsigned char mode )</bf>
  <itemize>
    <item><bf>dma</bf> dma number (not index)
    <item><bf>buf</bf> dma buffer
    <item><bf>size</bf> dma buffer size (transfer length)
    <item><bf>mode</bf> dma transfer mode
      <itemize>
      <item><bf>DMA_MODE_READ</bf>
      <item><bf>DMA_MODE_WRITE</bf>
      <item><bf>DMA_MODE_AUTOINIT</bf> - flag
      </itemize>
    <item>programs dma transfer
  </itemize>
  <item><bf>unsigned int snd_dma_residue( int dma )</bf>
  <itemize>
    <item><bf>dma</bf> dma number (not index)
    <item>returns residue value for specified dma channel
  </itemize>
</itemize>

<sect1>PCI bus
<p>
PCI bus related structures and functions are in <it>include/sndpci.h</it>
header file. Functions are designated for use with both type of kernels
(2.0 and 2.1).

<p>
Read-only variables from <it>struct snd_pci_dev</it> structure which should
be used:

<itemize>
  <item><bf>devfn</bf> encoded device & function index
  <item><bf>vendor</bf> - see to <bf>PCI_VENDOR_ID_*</bf>
  <item><bf>device</bf> - see to <bf>PCI_DEVICE_ID_*</bf>
  <item><bf>class</bf> - 3 bytes (base, sub, prog-if)
  <item><bf>master</bf> - set if device is master capable
  <item><bf>irq</bf> - irq generated by this device (remaped if needed)
  <item><bf>base_address</bf> - base registers for this device (remaped if needed)
</itemize>

<p>
Functions list:

<itemize>
  <item><bf>int snd_pci_find_device( unsigned int vendor, unsigned int device, unsigned int index, struct snd_pci_dev *dev );</bf>
  <itemize>
    <item><bf>vendor</bf> identification (see to <bf>PCI_VENDOR_ID_*</bf>)
    <item><bf>device</bf> identification (see to <bf>PCI_DEVICE_ID_*</bf>)
    <item><bf>index</bf> device index (0-X) for which is information requested
    <item><bf>dev</bf> pointer to PCI device structure (not same as in kernel)
  </itemize>
  <item><bf>int snd_pci_read_config_byte( struct snd_pci_dev *dev, unsigned char where, unsigned char *val )</bf>
  <item><bf>int snd_pci_read_config_word( struct snd_pci_dev *dev, unsigned char where, unsigned short *val )</bf>
  <item><bf>int snd_pci_read_config_dword( struct snd_pci_dev *dev, unsigned char where, unsigned int *val )</bf>
  <itemize>
    <item>read byte/word/dword from PCI configuration registers
  </itemize>
  <item><bf>int snd_pci_write_config_byte( struct snd_pci_dev *dev, unsigned char where, unsigned char val )</bf>
  <item><bf>int snd_pci_write_config_word( struct snd_pci_dev *dev, unsigned char where, unsigned short val )</bf>
  <item><bf>int snd_pci_write_config_dword( struct snd_pci_dev *dev, unsigned char where, unsigned int val )</bf>
  <itemize>
    <item>write byte/word/dword to PCI configuration registers
  </itemize>
</itemize>

<sect2>Examples

<p>
<tscreen><code>
  struct snd_pci_dev pci_dev;	/* use heap for this variable */
  unsigned short cmd;

  if ( snd_pci_find_device( PCI_VENDOR_ID_ENSONIQ,
                            PCI_DEVICE_ID_ENSONIQ_AUDIOPCI,
                            0,
                            &amp;pci_dev ) < 0 )
    return -ENODEV;
  snd_printk( "First Ensoniq PCI soundcard found at 0x%x and irq %i\n",
		pci_dev -> base_address[ 0 ] & ~3,
		pci_dev -> irq );
  snd_printk( "enabling Master..\n" );
  snd_pci_read_config_word( &amp;pci_dev, PCI_COMMAND, &amp;cmd );
  cmd |= PCI_COMMAND_IO | PCI_COMMAND_MASTER;
  snd_pci_write_config_word( &amp;pci_dev, PCI_COMMAND, cmd );
</code></tscreen>

<!-- ******************************************************************* -->
<!-- *********************** File Operations *************************** -->
<!-- ******************************************************************* -->

<sect>File operations

<p>
File operations related structures and function is in <it>include/driver.h</it>
header file. Basic structure for registering fileoperations for minor number
is <it>snd_minor_t</it>. Minor constants are in <it>include/minors.h</it>
header file.

<sect1>Variables and functions

<p>
Functions list:

<itemize>
  <item><bf>int snd_register_minor( unsigned short minor, snd_minor_t *reg )</bf>
  <itemize>
    <item><bf>minor</bf> minor number
    <item><bf>reg</bf> pointer to registration structure with file operations
    <item>returns negative value when error occured
  </itemize>
  <item><bf>int snd_unregister_minor( unsigned short minor )</bf>
  <itemize>
    <item><bf>minor</bf> minor number
    <item>returns negative value when error occured
  </itemize>
</itemize>

<bf>Note:</bf> Devices (minor numbers) are registered only if device is
present in the system. It isn't preffered do some pre-registration from
some middle-level code for each possible devices per interface.

<sect1>Examples

<p>

<tscreen><code>
static snd_minor_t snd_pcm_reg = {
  "digital audio",

  NULL,                         /* unregister */

  NULL,                         /* lseek */
  snd_pcm_read,                 /* read */
  snd_pcm_write,                /* write */
  snd_pcm_open,                 /* open */
  snd_pcm_release,              /* release */
#ifdef SND_POLL
  snd_pcm_poll,                 /* poll */
#else
  snd_pcm_select,               /* select */
#endif
  snd_pcm_ioctl,                /* ioctl */
  NULL,                         /* mmap */
};

...
  if ( (err = snd_register_minor( SND_MINOR_PCM + device, &amp;snd_pcm_reg )) < 0 )
    return err;
...
  snd_unregister_minor( SND_MINOR_PCM + device );
</code></tscreen>

<!-- ******************************************************************* -->
<!-- **************************** MIXER ******************************** -->
<!-- ******************************************************************* -->


<sect>Mixer

<p>
Mixer related structures and function is in <it>include/mixer.h</it> header
file.

<sect1>Variables and functions

<p>
Variables from <it>snd_kmixer_t</it> structure which must be filled:

<itemize>
<item><bf>name</bf> is name of mixer (for example 'AD1848').
<item><bf>hw</bf> read-only variables dependend on hardware.
</itemize>

<p>
Variables from <it>snd_kmixer_t</it> structure which should be filled:

<itemize>
<item><bf>private_data</bf> should contains private data for mixer.
<item><bf>private_free</bf> should free private data.
</itemize>

<p>
Variables from <it>struct snd_stru_mixer_hw</it> structure which must be filled:

<itemize>
<item><bf>caps</bf> mixer capabilities (see to <bf>SND_SND_MIXER_INFO_CAP_*</bf>).
</itemize>

<p>
Variables from <it>struct snd_stru_mixer_hw</it> structure which should be filled:

<itemize>
<item><bf>get_special</bf>
<item><bf>set_special</bf>
</itemize>

<p>
Variables from <it>snd_kmixer_channel_t</it> structure which must be filled:

<itemize>
<item><bf>hw</bf> read-only variables dependend on hardware.
</itemize>

<p>
Variables from <it>snd_kmixer_channel_t</it> structure which should be filled:

<itemize>
<item><bf>private_value</bf> is <it>unsigned int</it> variable which isn't used 
      by middle-level code.
<item><bf>private_data</bf> is pointer to some private data associated with
      appropriate channel. These data aren't freed by middle-level code.
</itemize>

<p>
Variables from <it>struct snd_stru_mixer_channel_hw</it> structure which must
be filled:

<itemize>
<item><bf>priority</bf> priority (identificator) - see to <bf>SND_MIXER_PRI_*</bf>
<item><bf>parent_priority</bf> parent mixer channel priority or <bf>SND_MIXER_PRI_PARENT</bf>
<item><bf>name</bf> name of this mixer channel - see to <bf>SND_MIXER_ID_*</bf>
<item><bf>ossdev</bf> OSS (Open Sound System) device - see to <bf>SND_MIXER_OSS_*</bf>
<item><bf>mute</bf> if hardware mute is supported
<item><bf>stereo</bf> if stereo is supported
<item><bf>record</bf> is recording is possible from this channel
<item><bf>digital</bf> is this channel is digitaly (not analog) mixed
<item><bf>input</bf> is channel is input channel
<item><bf>min, max</bf> specifies exact linear range from <it>min</it> to <it>max</it>
<item><bf>min_dB, max_dB, step_dB</bf> range and step size for decibel * 100
<item><bf>void (*set_record_source)( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel, int enable )</bf>
  <itemize>
  <item><bf>mixer</bf> pointer to mixer structure
  <item><bf>channel</bf> pointer to channel structure
  <item><bf>enable</bf> if non-zero - record source must be enabled
  <item>must be set, if channel supports recording
  </itemize>
<item><bf>void (*set_mute)( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel, unsigned int mute )</bf>
  <itemize>
  <item><bf>mixer</bf> pointer to mixer structure
  <item><bf>channel</bf> pointer to channel structure
  <item><bf>mute</bf> should be zero (no mute) or <bf>SND_MIX_MUTE*</bf>
  <item>must be set, if channel supports hardware muting
  </itemize>
<item><bf>void (*set_volume_level)( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel, int left, int right )</bf>
  <itemize>
  <item><bf>mixer</bf> pointer to mixer structure
  <item><bf>channel</bf> pointer to channel structure
  <item><bf>left</bf> volume level in exact range
  <item><bf>right</bf> volume level in exact range
  <item>handler which sets volume level for this channel
  </itemize>
</itemize>

<p>
Variables from <it>struct snd_stru_mixer_channel_hw</it> structure which should
be filled:

<itemize>
<item><bf>int (*compute_linear)( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel, int dB )</bf>
  <itemize>
  <item>input = dB from application, output = min...max (linear volume)
  </itemize>
<item><bf>int (*compute_dB)( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel, int volume )</bf>
  <itemize>
  <item>input = min...max (linear volume), output = dB to application
  </itemize>
</itemize>

<p>
Functions list:

<itemize>
  <item><bf>void snd_mixer_set_kernel_mute( snd_kmixer_t *mixer, unsigned int priority, unsigned short mute )</bf>
  <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item><bf>priority</bf> specifies mixer channel
    <item><bf>mute</bf> zero or <bf>SND_MIX_MUTE*</bf>
    <item>should be use as mute control from kernel
    <item>this settings is never overriden by application
  </itemize>
  <item><bf>snd_kmixer_t *snd_mixer_new( snd_card_t *card, char *id )</bf>
    <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>id</bf> is identification of code (for example 'AD1848').
    </itemize>
  <item><bf>int snd_mixer_free( snd_kmixer_t *mixer )</bf>
    <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item>frees mixer structure and private data
    </itemize>
  <item><bf>snd_kmixer_channel_t *snd_mixer_new_channel( snd_kmixer_t *mixer, struct snd_stru_mixer_channel_hw *hw )</bf>
    <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item><bf>hw</bf> pointer to mixer channel variables and operations
    <item>creates new mixer channel
    </itemize>
  <item><bf>void snd_mixer_reorder_channel( snd_kmixer_t *mixer, snd_kmixer_channel_t *channel )</bf>
    <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item><bf>channel</bf> pointer to mixer channel
    <item>reorders mixer channels if channel -> priority was changed
    </itemize>
  <item><bf>int snd_mixer_register( snd_kmixer_t *mixer, int device )</bf>
    <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item><bf>device</bf> device number (0-1)
    <item>registers specified mixer
    </itemize>
  <item><bf>int snd_mixer_unregister( snd_mixer_t *mixer )</bf>
    <itemize>
    <item><bf>mixer</bf> pointer to mixer structure
    <item>unregisters and <bf>frees</bf> specified mixer
    </itemize>
  </item>  
</itemize>

<sect1>Exaples

<p>

<tscreen><code>
#define CS4231_MIXS (sizeof(snd_cs4231_mixs)/sizeof(struct snd_stru_mixer_channel_hw))
#define CS4231_PRIVATE( left, right, shift, mute ) ((left << 24)|(right << 16)|(shift<<8)|mute)

static struct snd_stru_mixer_channel_hw snd_cs4231_mixs[] = {
  {
    SND_MIXER_PRI_GAIN,         /* priority */
    SND_MIXER_PRI_PARENT,       /* parent priority */
    SND_MIXER_ID_GAIN,          /* device name */
    SND_MIXER_OSS_IMIX,         /* OSS device # */
    0, 1, 0, 0, 1,              /* mute/stereo/record/digital/input */
    0, 15,                      /* min, max value */
    0, 2250, 150,               /* min, max, step - dB */
    CS4231_PRIVATE( CS4231_LEFT_INPUT, CS4231_RIGHT_INPUT, 0, 0x00 ) | 0x2000,
    NULL,                       /* compute dB -> linear */
    NULL,                       /* compute linear -> dB */
    NULL,                       /* record source */
    NULL,                       /* set mute */
    snd_cs4231_volume_level,    /* set volume level */
  },
  ....
};

snd_kmixer_t *snd_cs4231_new_mixer( snd_pcm_t *pcm )
{
  int idx;
  cs4231_t *codec;
  snd_kmixer_t *mixer;
  snd_kmixer_channel_t *channel;

  if ( !pcm || !pcm -> card ) return NULL;
  codec = (cs4231_t *)pcm -> private_data;
  if ( !codec ) return NULL;
  mixer = snd_mixer_new( pcm -> card, pcm -> id );
  if ( !mixer ) return NULL;
  strcpy( mixer -> name, pcm -> name );
  for ( idx = 0; idx < CS4231_MIXS; idx++ ) {
    channel = snd_mixer_new_channel( mixer, &amp;snd_cs4231_mixs[ idx ] );
    if ( !channel ) {
      snd_mixer_free( mixer );
      return NULL;
    }
  }
  mixer -> hw.caps = SND_MIXER_INFO_CAP_EXCL_RECORD;
  mixer -> private_data = codec;
  codec -> mixer = mixer;
  return mixer;
}
</code></tscreen>

<p>
Do you need modify some default mixer channel assignment?

<tscreen><code>
  snd_kmixer_channel_t *channel;

  /* ok. InterWave have MIC different (stereo) */
  channel = snd_mixer_find_channel( mixer, SND_MIXER_PRI_MIC );
  channel -> hw.stereo = 1;
  channel -> hw.max = 31;
  channel -> hw.private_value = CS4231_PRIVATE( CS4231_LEFT_MIC_INPUT, CS4231_RIGHT_MIC_INPUT, 0, 0x80 );

  /* reassign AUXA to SYNTHESIZER */
  channel = snd_mixer_find_channel( mixer, SND_MIXER_PRI_AUXA );
  channel -> hw.priority = SND_MIXER_PRI_SYNTHESIZER;
  channel -> hw.ossdev = SND_MIXER_OSS_SYNTH;
  strcpy( channel -> hw.name, SND_MIXER_ID_SYNTHESIZER );
  snd_mixer_reorder_channel( mixer, channel );
</code></tscreen>

<p>
Do you need add some mixer channel to generic mixer?

<tscreen><code>
  static struct snd_stru_mixer_channel_hw master = {
    SND_MIXER_PRI_MASTER,               /* priority */
    SND_MIXER_PRI_PARENT,               /* parent priority */
    SND_MIXER_ID_MASTER,                /* device name */
    SND_MIXER_OSS_VOLUME,               /* OSS device # */
    1, 1, 1, 0, 0,                      /* mute/stereo/record/digital */
    0, 31,                              /* max. value */
    -3450, 1200, 150,                   /* min, max, step - dB */
    CS4231_PRIVATE( CS4231_LINE_LEFT_OUTPUT, CS4231_LINE_RIGHT_OUTPUT, 0, 0x80
    NULL,                               /* compute dB -> linear */
    NULL,                               /* compute linear -> dB */
    NULL,                               /* record source */
    NULL,                               /* set mute */
    NULL,                               /* set volume level */
  };
  int idx;

  /* make master as parent */
  for ( idx = 0; idx < mixer -> channels_count; idx++ ) {
    channel = mixer -> channels[ idx ];
    if ( !channel -> hw.input )
      channel -> hw.parent_priority = SND_MIXER_PRI_MASTER;
  }
  /* add master volume control */
  master.set_record_source = channel -> hw.set_record_source;
  master.set_mute = channel -> hw.set_mute;
  master.set_volume_level = channel -> hw.set_volume_level;
  channel = snd_mixer_new_channel( mixer, &amp;master );
  if ( !channel ) return -ENOMEM;
</code></tscreen>

Mixer device registering:

<tscreen><code>
  snd_card_t *card;
  snd_pcm_t *pcm.
  snd_kmixer_t *mixer;

  ...
  mixer = snd_es1688_new_mixer( pcm );
  if ( !mixer ) {
    snd_pcm_free( pcm );
    snd_card_free( card );
    return -NXIO;
  }
  ...
  if ( snd_mixer_register( mixer, 0 ) ) {
    ... unregister already registered devices ...
    snd_mixer_free( mixer );
    snd_pcm_free( pcm );
    snd_card_free( card );
    return -ENXIO;
  }
  ...
  snd_mixer_unregister( mixer );
</code></tscreen>

<!-- ******************************************************************* -->
<!-- ***************************** PCM ********************************* -->
<!-- ******************************************************************* -->

<sect>PCM - Digital Audio

<p>
Digital Audio related structures and function is in <it>include/pcm.h</it>
header file.

<sect1>Variables and functions

<p>
Variables from <it>snd_pcm_t</it> structure which must be filled:

<itemize>
<item><bf>info_flags</bf> look to <bf>SND_PCM_INFO_*</bf> 
<item><bf>name</bf> of pcm device (for example 'CS4231')
<item><bf>playback</bf> variables for playback direction
<item><bf>record</bf> variables for record direction
</itemize>

<p>
Variables from <it>snd_pcm_t</it> structure which should be filled:

<itemize>
<item><bf>private_data</bf> should contains pointer to private data
<item><bf>private_free</bf> should free private data
</itemize>

<p>
Variables from <it>struct snd_stru_pcm_hardware</it> which must be filled:

<itemize>
<item><bf>flags</bf>
  <itemize>
  <item><bf>SND_PCM_HW_BATCH</bf> - hardware does double buffering
  <item><bf>SND_PCM_HW_8BITONLY</bf> - hardware supports only 8-bit data (be careful - look to sb16.c)
  <item><bf>SND_PCM_HW_16BITONLY</bf> - hardware supports only 16-bit data (be careful - look to sb16.c)
  <item><bf>SND_PCM_HW_AUTODMA</bf> - hardware supports auto init dma transfer (unterminated loop)
  </itemize>
<item><bf>formats</bf> list of supported formats <bf>SND_PCM_FMT_*</bf>
  <itemize>
    <item>if hardware doesn't support Mu-Law - it _must_ be emulated (converted), but it can't be listed here
  </itemize>
<item><bf>align</bf> - if transfer block must be aligned to some value - set this mask
<item><bf>min_fragment</bf> - minimal fragment in 2^x
<item><bf>min_rate</bf> - minimal rate in Hz
<item><bf>max_rate</bf> - maximal rate in Hz
<item><bf>max_voices</bf> - maximal number of voices
<item><bf>int (*open)( snd_pcm_t *pcm )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item>opens pcm direction and allocates dma buffer with <it>snd_pcm_dma_alloc</it>
  </itemize>
<item><bf>int (*close)( snd_pcm_t *pcm )</bf>
  <itemize>
  <item>closes pcm direction and frees dma buffer with <it>snd_pcm_dma_free</it>
  </itemize>
<item><bf>void (*compute_rate)( snd_pcm_t *pcm )</bf>
  <itemize>
  <item>computes <it>snd_pcm_channel_t -> real_rate</it> from <it>snd_pcm_channel_t -> rate</it>
  </itemize>
<item><bf>void (*prepare)( snd_pcm_t *pcm, unsigned char *buffer, unsigned int size, unsigned int offset, unsigned int count )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>buffer</bf> pointer to dma buffer
  <item><bf>size</bf> used size of dma buffer
  <item><bf>offset</bf> offset in bytes to dma buffer
    <itemize>
      <item>this value is always zero if hardware supports auto init dma transfer mode
    </itemize>
  <item><bf>count</bf> of bytes to transfer (block size)
  <item>prepares pcm direction to output/input
  </itemize>
<item><bf>void (*trigger)( snd_pcm_t *pcm, int up )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>up</bf> if zero - trigger down (turn off), if nonzero - trigger up (turn on)
  <item>starts or stops pcm direction
  </itemize>
<item><bf>unsigned int (*pointer)( snd_pcm_t *pcm, unsigned int used_size )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>used_size</bf> - used size of dma buffer
  <item>returns actual byte pointer from pcm direction
  </itemize>
<item><bf>void (*dma)( snd_pcm_t *pcm, unsigned char *buffer, unsigned int offset, unsigned char *user, unsigned int count )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>buffer</bf> pointer to dma buffer
  <item><bf>offset</bf> destonation/source offset in bytes to/from dma buffer
  <item><bf>user</bf> pointer to buffer in user space
  <item><bf>count</bf> transfer count in bytes
  <item>copies data from or to user space to or from kernel dma buffer
  </itemize>
<item><bf>void (*dma_move)( snd_pcm_t *pcm, unsigned char *buffer, unsigned int dest_offset, unsigned int src_offset, unsigned int count )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>buffer</bf> pointer to dma buffer
  <item><bf>dest_offset</bf> destonation offset in bytes to dma buffer
  <item><bf>src_offset</bf> source offset in bytes from dma buffer
  <item><bf>count</bf> transfer count
  <item>transfer areas can never be overlapped
  </itemize>
<item><bf>void (*dma_neutral)( snd_pcm_t *pcm, unsigned char *buffer, unsigned offset, unsigned int count, unsigned char neutral_byte )</bf>
  <itemize>
  <item><bf>pcm</bf> pointer to pcm structure
  <item><bf>buffer</bf> pointer to dma buffer
  <item><bf>offset</bf> destonation offset in bytes to dma buffer
  <item><bf>count</bf> count in bytes
  <item><bf>neutral_byte</bf> - neutral byte
  <item>fills specified area of dma buffer with neutral byte
  </itemize>
</itemize>

<p>
Variables from <it>struct snd_stru_pcm_hardware</it> which should be filled:

<itemize>
<item><bf>private_data</bf> should contains pointer to private data for specified direction
<item><bf>private_free</bf> should free private data
</itemize>

<p>
Functions list:

<itemize>
<item><bf>void snd_pcm_playback_dma( snd_pcm_t *pcm,
                                     unsigned char *buffer, unsigned int offset,
                                     unsigned char *user, unsigned int count )</bf>
  <itemize>
    <item>standard function for playback snd_pcm_channel_t -> hw.dma
  </itemize>
<item><bf>void snd_pcm_playback_dma_ulaw( snd_pcm_t *pcm,
                                          unsigned char *buffer, unsigned int offset,
                                          unsigned char *user, unsigned int count )</bf>
  <itemize>
    <item>standard function for playback snd_pcm_channel_t -> hw.dma
          if hardware doesn't supports Mu-Law compression
  </itemize>
<item><bf>void snd_pcm_playback_dma_neutral( snd_pcm_t *pcm,
                                             unsigned char *buffer, unsigned int of
                                             unsigned int count,
                                             unsigned char neutral_byte )</bf>
  <itemize>
    <item>standard function for playback snd_pcm_channel_t -> hw.dma_neutral
  </itemize>
<item><bf>void snd_pcm_record_dma( snd_pcm_t *pcm,
                                   unsigned char *buffer, unsigned int offset,
                                   unsigned char *user, unsigned int count )</bf>
  <itemize>
    <item>standard function for record snd_pcm_channel_t -> hw.dma
  </itemize>
<item><bf>void snd_pcm_record_dma_ulaw( snd_pcm_t *pcm,
                                     unsigned char *buffer, unsigned int offset,
                                     unsigned char *user, unsigned int count )</bf>
  <itemize>
    <item>standard function for record snd_pcm_channel_t -> hw.dma
          if hardware doesn't supports Mu-Law compression
  </itemize>
<item><bf>void snd_pcm_dma_move( snd_pcm_t *pcm,
                                 unsigned char *buffer,
                                 unsigned int dest_offset, unsigned int src_offset,
                                 unsigned int count )</bf>
  <itemize>
    <item>standard function for snd_pcm_channel_t -> hw.dma_move
  </itemize>
</itemize>

<p>
Functions for dma allocation:

<itemize>
<item><bf>int snd_pcm_dma_alloc( snd_pcm_t *pcm, int direction, int dmanum, char *ident )</bf>
  <itemize>
    <item><bf>pcm</bf> pointer to pcm structure
    <item><bf>direction</bf> pcm direction - <bf>SND_PCM_PLAYBACK</bf> or <bf>SND_PCM_RECORD</bf>
    <item><bf>dmanum</bf> dma index
    <item><bf>ident</bf> identification for dma owner
    <item>allocates pcm dma buffer
  </itemize>
<item><bf>int snd_pcm_dma_free( snd_pcm_t *pcm, int direction, int dmanum )</bf>
  <itemize>
    <item><bf>pcm</bf> pointer to pcm structure
    <item><bf>direction</bf> pcm direction
    <item><bf>dmanum</bf> dma index
    <item>frees pcm dma buffer
  </itemize>
</itemize>

<p>
Functions for allocation and registering:

<itemize>
<item><bf>snd_pcm_t *snd_pcm_new_device( snd_card_t *card, char *id )</bf>
  <itemize>
    <item><bf>card</bf> pointer to soundcard structure
    <item><bf>id</bf> identification for pcm device (for example 'AD1848')
  </itemize>
<item><bf>int snd_pcm_free( snd_pcm_t *pcm )</bf>
  <itemize>
    <item><bf>pcm</bf> pointer to pcm structure
    <item>frees pcm structure and associated private data
  </itemize>
<item><bf>int snd_pcm_register( snd_pcm_t *pcm, int pcm_device )</bf>
  <itemize>
    <item><bf>pcm</bf> pointer to pcm structure
    <item><bf>pcm_device</bf> number of pcm device (0-3)
    <item>registers pcm device
  </itemize>
<item><bf>int snd_pcm_unregister( snd_pcm_t *pcm )</bf>
  <itemize>
    <item><bf>pcm</bf> pointer to pcm structure
    <item>unregisters and frees pcm structure
  </itemize>
</itemize>

<sect1>Examples

<p>

<tscreen><code>
static struct snd_stru_pcm_hardware snd_es1688_playback = {
  NULL,                         /* private data */
  NULL,                         /* private_free */
  SND_PCM_HW_AUTODMA,           /* flags */
  SND_PCM_FMT_U8 | SND_PCM_FMT_S16_LE,  /* formats */
  0,                            /* align value */
  6,                            /* minimal fragment */
  4000,                         /* min. rate */
  48000,                        /* max. rate */
  2,                            /* max. voices */
  snd_es1688_playback_open,
  snd_es1688_playback_close,
  snd_es1688_playback_compute_rate,
  snd_es1688_playback_prepare,
  snd_es1688_playback_trigger,
  snd_es1688_playback_pointer,
  snd_pcm_playback_dma_ulaw,
  snd_pcm_dma_move,
  snd_pcm_playback_dma_neutral
};

static struct snd_stru_pcm_hardware snd_es1688_record = {
  NULL,                         /* private data */
  NULL,                         /* private free */
  SND_PCM_HW_AUTODMA,           /* flags */
  SND_PCM_FMT_U8 | SND_PCM_FMT_S16_LE,  /* formats */
  0,                            /* align value */
  6,                            /* minimal fragment */
  4000,                         /* min. rate */
  48000,                        /* max. rate */
  2,                            /* max. voices */
  snd_es1688_record_open,
  snd_es1688_record_close,
  snd_es1688_record_compute_rate,
  snd_es1688_record_prepare,
  snd_es1688_record_trigger,
  snd_es1688_record_pointer,
  snd_pcm_record_dma_ulaw,
  snd_pcm_dma_move,
  NULL
};

static void snd_es1688_free( void *private_data )
{
  snd_free( private_data, sizeof( es1688_t ) );
}

snd_pcm_t *snd_es1688_new_device( snd_card_t *card,
                                  unsigned short port,
                                  unsigned short mpu_port,
                                  unsigned short irqnum,
                                  unsigned short mpu_irqnum,
                                  unsigned short dma8num,
                                  unsigned short hardware )
{
  snd_pcm_t *pcm;
  es1688_t *codec;

  pcm = snd_pcm_new_device( card, "ESx688" );
  if ( !pcm ) return NULL;
  codec = (es1688_t *)snd_malloc( sizeof( es1688_t ) );
  if ( !codec ) return NULL;
  memset( codec, 0, sizeof( es1688_t ) );
  snd_spin_prepare( codec, reg );
  snd_spin_prepare( codec, mixer );
  codec -> pcm = pcm;
  codec -> card = pcm -> card;
  codec -> port = port;
  codec -> mpu_port = mpu_port;
  codec -> irqnum = irqnum;
  codec -> irq = pcm -> card -> irqs[ irqnum ] -> irq;
  codec -> mpu_irqnum = mpu_irqnum;
  if ( mpu_irqnum != SND_IRQ_DISABLE )
    codec -> mpu_irq = pcm -> card -> irqs[ mpu_irqnum ] -> irq;
  codec -> dma8num = dma8num;
  codec -> dma8 = pcm -> card -> dmas[ dma8num ] -> dma;
  codec -> hardware = hardware;
  memcpy( &amp;pcm -> playback.hw, &amp;snd_es1688_playback, sizeof( snd_es1688_playback ) );
  memcpy( &amp;pcm -> record.hw, &amp;snd_es1688_record, sizeof( snd_es1688_record ) );
  pcm -> private_data = codec;
  pcm -> private_free = snd_es1688_free;
  pcm -> info_flags = SND_PCM_INFO_CODEC | SND_PCM_INFO_MMAP |
                      SND_PCM_INFO_PLAYBACK | SND_PCM_INFO_RECORD;
  sprintf( pcm -> name, "ES%s688 rev %i", codec -> hardware == ES1688_HW_688 ?"" : "1", codec -> version & 0x0f );
  if ( snd_es1688_probe( pcm ) < 0 ) {
    snd_pcm_free( pcm );
    return NULL;
  }
  return pcm;
}
</code></tscreen>

PCM device registering:

<tscreen><code>
  snd_card_t *card;
  snd_pcm_t *pcm;

  pcm = snd_es1688_new_device( card, port, mpu_port, irqnum, mpu_irqnum, dma8num, ES1688_HW_AUTO );
  if ( !pcm ) return NULL;
  ...
  if ( snd_pcm_register( pcm, 0 ) ) {
    ... unregister already registered devices ...
    snd_pcm_free( pcm );
    snd_card_free( card );
    return -ENXIO;
  }
  ...
  snd_pcm_unregister( pcm );
</code></tscreen>

</article>
