  Advanced Linux Sound Architecture - Driver
  Jaroslav Kysela <perex@suse.cz>
  v0.0.1, 12 May 1998

  This document describes, in full detail, the Advanced Linux Sound
  Architecture driver.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

     1.1 Source files
     1.2 Devices
     1.3 Memory allocation
     1.4 Basic coding
     1.5 Upper level (/cards)
     1.6 Private data/values
     1.7 CLI/STI & spin locking
     1.8 Examples

  2. Soundcard

     2.1 Variables and functions
        2.1.1 Examples
     2.2 Resources
        2.2.1 Examples
     2.3 ISA DMA
     2.4 PCI bus
        2.4.1 Examples

  3. File operations

     3.1 Variables and functions
     3.2 Examples

  4. Mixer

     4.1 Variables and functions
     4.2 Exaples

  5. PCM - Digital Audio

     5.1 Variables and functions
     5.2 Examples


  ______________________________________________________________________

  1.  Introduction

  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.



  1.1.  Source files

  Source files are separated to:

     /include
        Directory contains all header files which are included from more
        sources.

     /kernel
        Directory with kernel code and abstract layers (middle level
        code and library).

     /lowlevel
        Generic lowlevel code for chip(set)s.

     /cards
        Upper level for soundcards and specific lowlevel code.

     /detect
        Detection layer (/proc/asound/detect - to make installation
        easy).


  1.2.  Devices

  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.


  1.3.  Memory allocation


  o  void *snd_malloc( unsigned long size )

  o  void snd_free( void *ptr, unsigned long size )

  o  char *snd_malloc_strdup( char *string )

  o  void snd_free_str( char *string )

  These routines use their own memory allocation algoritm. It should be
  removed in the future and replaced with kmalloc and kfree calls, but
  for now I need to trace all allocation problems to make code clean...

  Note: ALSA driver heavily uses dynamic allocation for most things.

  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.


  1.4.  Basic coding

  All things are made as objects (which encapsulates data and functions)
  and are referenced in this way. I don't prefer to pass index to some
  array of structure or something like this. Objects contain both data
  and functions.  Pointers to these objects are passed around (like
  C++).

  All main structures should have snd_xxxx_new, snd_xxxx_free,
  snd_xxxx_register, snd_xxxx_unregister functions.


  o  snd_card_t is a basic structure which contains info about a
     soundcard, index and resource tracking variables. Look at
     include/driver.h for all things related to this structure.


  o  snd_pcm_t is a basic structure for a PCM device.

  o  snd_pcm_channel_t is a basic structure for a PCM channel
     (direction).

  o  struct snd_stru_pcm_hardware is a structure which must be filled by
     lowlevel code. Look at include/pcm.h for all things related to
     these structures.


  o  snd_kmixer_t is a basic structure for a MIXER device.

  o  snd_kmixer_channel_t is a basic structure for a MIXER channel.

  o  struct snd_stru_mixer_channel_hw is a structure which must be
     filled by lowlevel code. Look at include/mixer.h for all things
     related to these structures.


  1.5.  Upper level (/cards)

  Code for soundcards should contain these things:


  1. Support for more than one of the same soundcard (up to
     SND_CARDS)...

  o  it isn't really possible due to HW limitations

  2. Autodetection/autoconfiguration feature (if it's possible)...

  o  if lowlevel code is specific for soundcard type - it should be
     here, too..

  3. Initialization code for soundcard

  o  snd_card_new

  o  snd_card_free (frees all hardware resources)

  4. Allocate/free hardware resources for soundcard

  o  snd_register_ioport

  o  snd_unregister_ioports (frees all ioports)

  o  snd_register_interrupt

  o  snd_unregister_interrupts (frees all interrupts)

  o  snd_register_dma_channel

  o  snd_unregister_dma_channels (frees all DMA channels)

  5. Initialize other layers (PCMs, Mixers etc.)

  o  snd_pcm_new

  o  snd_pcm_free

  o  snd_pcm_register

  o  snd_pcm_unregister (calls snd_pcm_free)

  o  snd_mixer_new

  o  snd_mixer_free

  o  snd_mixer_register

  o  snd_mixer_unregister (calls snd_mixer_free)

  6. Register soundcard

  o  snd_card_register

  o  snd_card_unregister (doesn't call snd_card_free)

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


  1.6.  Private data/values

  Some structures have pointers to private data and values. These
  variables aren't used with the abstract layers and are intended for
  low-level code use only.


  ______________________________________________________________________
  snd_card_t -> private_data
  snd_card_t -> private_free (called from snd_card_free if not NULL)
  ______________________________________________________________________




  ______________________________________________________________________
  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)
  ______________________________________________________________________




  ______________________________________________________________________
  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)
  ______________________________________________________________________




  1.7.  CLI/STI & spin locking

  Good code shouldn't contain snd_cli()/snd_sti() calls.  Instead use
  spin locks snd_spin_lock()/snd_spin_unlock() for locking code. This
  method is much better for SMP machines.

  Note: Debugging code is available for locking.  Look in sndspinlock.h
  to enable it.

  1.8.  Examples

  You should look at the code for GUS soundcards to see how can be
  things done...

  Note: Code should be compiled cleanly under 2.0.X kernels and under
  latest 2.1.X kernels...




  2.  Soundcard

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


  2.1.  Variables and functions

  Functions list:


  o  snd_card_t *snd_card_new( int idx, char *id, void (*use_inc)(
     snd_card_t * ), void (*use_dec)( snd_card_t *) )

  o  idx soundcard index (order), 1-8 or -1 = first free

  o  id soundcard id, if NULL or '\0' -> default (card#)

  o  inc_use increment use of last soundcard module (to avoid remove)

  o  dec_use decrement use of last soundcard module (to allow remove)

  o  returns NULL if not enough memory is available

  o  int snd_card_free( snd_card_t *card )

  o  card pointer to soundcard structure to free

  o  frees all registered resources (ports, IRQs and DMAs), too

  o  returns negative value when error

  o  int snd_card_register( snd_card_t *card )

  o  card pointer to soundcard structure to register; applications
     should from this point use soundcard

  o  returns negative value when error

  o  int snd_card_unregister( snd_card_t *card )

  o  card pointer to soundcard structure to unregister; After this is
     called, applications no longer can use this soundcard.

  o  doesn't call snd_card_free

  o  returns negative value when error occurs


  Variables from snd_card_t structure which must be filled:



  o  type is a type identification from include/asoundid.h.

  o  abbreviation is an abbreviation for soundcard (for example 'GUS').

  o  shortname is a shortname for soundcard (for example 'Gravis
     UltraSound MAX').

  o  longname is a full identification for soundcard (for example
     'Gravis UltraSound MAX at 0x220, irq 5, dma 1&5').


  Variables from snd_card_t structure which should be filled:


  o  private_data should be used by soundcard driver for private data.

  o  private_free is called when private_data should be freed.


  2.1.1.  Examples



       ______________________________________________________________________
       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;
       }
       ______________________________________________________________________





  2.2.  Resources

  Functions list:



  o  int snd_register_ioport( snd_card_t *card, int port, int size, char
     *name )

  o  card pointer to soundcard structure

  o  port means first port from ioport region

  o  size means size of ioport region

  o  name ioport region name

  o  registers ioport region and assigns it to soundcard

  o  int snd_unregister_ioports( snd_card_t *card )

  o  card pointer to soundcard structure

  o  unregisters all ioport regions which are assigned to soundcard

  o  int snd_register_dma_channel( snd_card_t *card, char *name, int
     number, int type, int rsize, int *possible_numbers )

  o  card pointer to soundcard structure

  o  name name of dma channel

  o  number number of dma channel or SND_AUTO_DMA

  o  type type of dma buffer

  o  SND_DMA_TYPE_ISA limited dma buffer to low 16MB of RAM

  o  SND_DMA_TYPE_PCI unlimited dma buffer (should be anywhere in RAM)

  o  SND_DMA_TYPE_HARDWARE hardware dma buffer (is available on
     soundcard and directly mmaped to OS memory)

  o  rsize requested dma buffer size (in kB) or SND_AUTO_DMA_SIZE

  o  possible_numbers 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 SND_AUTO_DMA
     is specified to detect first useable dma channel

  o  int snd_unregister_dma_channels( snd_card_t *card )

  o  card pointer to soundcard structure

  o  unregisters all dma channels assigned to soundcard

  o  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 )

  o  card pointer to soundcard structure

  o  name name of interrupt line

  o  number number of interrupt line or SND_AUTO_IRQ

  o  type type of interrupt line

  o  SND_IRQ_TYPE_ISA ISA interrupt line (not shareable)

  o  SND_IRQ_TYPE_PCI PCI interrupt line (shareable)

  o  handler pointer to interrupt handler

  o  dev_id pointer to some private structure for interrupt handler

  o  possible_numbers pointer to int arrays which contain all possible
     dma numbers for this channel terminated by -1; function uses these
     values for verification of valid input from user or if SND_AUTO_IRQ
     is specified to detect first useable interrupt line

  o  returns index to card -> irqs array

  o  int snd_unregister_interrupts( snd_card_t *card )

  o  card pointer to soundcard structure

  o  disables and frees all interrupt lines assigned to soundcard

  o  int snd_enable_irq( snd_card_t *card, int irqnum )

  o  card pointer to soundcard structure

  o  irqnum index of interrupt line to be enabled

  o  int snd_disable_irq( snd_card_t *card, int irqnum )

  o  card pointer to soundcard structure

  o  irqnum index of interrupt line to be disabled

  Note 1: 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
  snd_dma_malloc and snd_dma_free when some device is opened/closed.

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


  2.2.1.  Examples























  ______________________________________________________________________
  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;
  }
  ______________________________________________________________________





  2.3.  ISA DMA

  Functions list:


  o  void snd_dma_program( int dma, const void *buf, unsigned int size,
     unsigned char mode )

  o  dma dma number (not index)

  o  buf dma buffer

  o  size dma buffer size (transfer length)

  o  mode dma transfer mode

  o  DMA_MODE_READ

  o  DMA_MODE_WRITE

  o  DMA_MODE_AUTOINIT - flag

  o  programs dma transfer

  o  unsigned int snd_dma_residue( int dma )

  o  dma dma number (not index)

  o  returns residue value for specified dma channel


  2.4.  PCI bus

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


  Read-only variables from struct snd_pci_dev structure which should be
  used:


  o  devfn encoded device & function index

  o  vendor - see PCI_VENDOR_ID_*

  o  device - see PCI_DEVICE_ID_*

  o  class - 3 bytes (base, sub, prog-if)

  o  master - set if device is master capable

  o  irq - irq generated by this device (remaped if needed)

  o  base_address - base registers for this device (remaped if needed)


  Functions list:


  o  int snd_pci_find_device( unsigned int vendor, unsigned int device,
     unsigned int index, struct snd_pci_dev *dev );

  o  vendor identification (see PCI_VENDOR_ID_*)

  o  device identification (see PCI_DEVICE_ID_*)

  o  index device index (0-X) for which is information requested

  o  dev pointer to PCI device structure (not same as in kernel)

  o  int snd_pci_read_config_byte( struct snd_pci_dev *dev, unsigned
     char where, unsigned char *val )

  o  int snd_pci_read_config_word( struct snd_pci_dev *dev, unsigned
     char where, unsigned short *val )

  o  int snd_pci_read_config_dword( struct snd_pci_dev *dev, unsigned
     char where, unsigned int *val )

  o  read byte/word/dword from PCI configuration registers

  o  int snd_pci_write_config_byte( struct snd_pci_dev *dev, unsigned
     char where, unsigned char val )

  o  int snd_pci_write_config_word( struct snd_pci_dev *dev, unsigned
     char where, unsigned short val )

  o  int snd_pci_write_config_dword( struct snd_pci_dev *dev, unsigned
     char where, unsigned int val )

  o  write byte/word/dword to PCI configuration registers


  2.4.1.  Examples



       ______________________________________________________________________
         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,
                                   &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( &pci_dev, PCI_COMMAND, &cmd );
         cmd |= PCI_COMMAND_IO | PCI_COMMAND_MASTER;
         snd_pci_write_config_word( &pci_dev, PCI_COMMAND, cmd );
       ______________________________________________________________________






  3.  File operations

  File operations related structures and functions are in
  include/driver.h header file. Basic structure for registering file
  operations for minor number is snd_minor_t. Minor constants are in
  include/minors.h header file.


  3.1.  Variables and functions

  Functions list:


  o  int snd_register_minor( unsigned short minor, snd_minor_t *reg )

  o  minor minor number

  o  reg pointer to registration structure with file operations

  o  returns negative value when error occured

  o  int snd_unregister_minor( unsigned short minor )

  o  minor minor number

  o  returns negative value when error occured

  Note: 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.


  3.2.  Examples




       ______________________________________________________________________
       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, &snd_pcm_reg )) < 0 )
           return err;
       ...
         snd_unregister_minor( SND_MINOR_PCM + device );
       ______________________________________________________________________







  4.  Mixer

  Mixer related structures and function is in include/mixer.h header
  file.


  4.1.  Variables and functions

  Variables from snd_kmixer_t structure which must be filled:


  o  name is name of mixer (for example 'AD1848').

  o  hw read-only variables dependend on hardware.


  Variables from snd_kmixer_t structure which should be filled:


  o  private_data pointer to private data for mixer.

  o  private_free should free private_data when called.

  Variables from struct snd_stru_mixer_hw structure which must be
  filled:


  o  caps mixer capabilities (see to SND_SND_MIXER_INFO_CAP_*).


  Variables from struct snd_stru_mixer_hw structure which should be
  filled:


  o  get_special

  o  set_special


  Variables from snd_kmixer_channel_t structure which must be filled:


  o  hw read-only variables dependend on hardware.


  Variables from snd_kmixer_channel_t structure which should be filled:


  o  private_value is unsigned int variable which isn't used by middle-
     level code.

  o  private_data is pointer to some private data associated with
     appropriate channel. This data isn't freed by middle-level code.
     NOTE - Where should it be freed from then?


  Variables from struct snd_stru_mixer_channel_hw structure which must
  be filled:


  o  priority priority (identificator) - see SND_MIXER_PRI_*

  o  parent_priority parent mixer channel priority or
     SND_MIXER_PRI_PARENT

  o  name name of this mixer channel - see SND_MIXER_ID_*

  o  ossdev OSS (Open Sound System) device - see SND_MIXER_OSS_*

  o  mute if hardware mute is supported

  o  stereo if stereo is supported

  o  record is recording is possible from this channel

  o  digital is this channel is digitaly (not analog) mixed

  o  input is channel is input channel

  o  min, max specifies exact linear range from min to max

  o  min_dB, max_dB, step_dB range and step size for decibel * 100

  o  void (*set_record_source)( snd_kmixer_t *mixer,
     snd_kmixer_channel_t *channel, int enable )

  o  mixer pointer to mixer structure


  o  channel pointer to channel structure

  o  enable if non-zero - record source must be enabled

  o  must be set, if channel supports recording

  o  void (*set_mute)( snd_kmixer_t *mixer, snd_kmixer_channel_t
     *channel, unsigned int mute )

  o  mixer pointer to mixer structure

  o  channel pointer to channel structure

  o  mute should be zero (no mute) or SND_MIX_MUTE*

  o  must be set, if channel supports hardware muting

  o  void (*set_volume_level)( snd_kmixer_t *mixer, snd_kmixer_channel_t
     *channel, int left, int right )

  o  mixer pointer to mixer structure

  o  channel pointer to channel structure

  o  left volume level in exact range

  o  right volume level in exact range

  o  handler which sets volume level for this channel


  Variables from struct snd_stru_mixer_channel_hw structure which should
  be filled:


  o  int (*compute_linear)( snd_kmixer_t *mixer, snd_kmixer_channel_t
     *channel, int dB )

  o  input = dB from application, output = min...max (linear volume)

  o  int (*compute_dB)( snd_kmixer_t *mixer, snd_kmixer_channel_t
     *channel, int volume )

  o  input = min...max (linear volume), output = dB to application


  Functions list:


  o  void snd_mixer_set_kernel_mute( snd_kmixer_t *mixer, unsigned int
     priority, unsigned short mute )

  o  mixer pointer to mixer structure

  o  priority specifies mixer channel

  o  mute zero or SND_MIX_MUTE*

  o  should be use as mute control from kernel

  o  this settings are never overriden by application

  o  snd_kmixer_t *snd_mixer_new( snd_card_t *card, char *id )

  o  card pointer to soundcard structure

  o  id is identification of code (for example 'AD1848').

  o  int snd_mixer_free( snd_kmixer_t *mixer )

  o  mixer pointer to mixer structure

  o  frees mixer structure and private data

  o  snd_kmixer_channel_t *snd_mixer_new_channel( snd_kmixer_t *mixer,
     struct snd_stru_mixer_channel_hw *hw )

  o  mixer pointer to mixer structure

  o  hw pointer to mixer channel variables and operations

  o  creates new mixer channel

  o  void snd_mixer_reorder_channel( snd_kmixer_t *mixer,
     snd_kmixer_channel_t *channel )

  o  mixer pointer to mixer structure

  o  channel pointer to mixer channel

  o  reorders mixer channels if channel -> priority was changed

  o  int snd_mixer_register( snd_kmixer_t *mixer, int device )

  o  mixer pointer to mixer structure

  o  device device number (0-1)

  o  registers specified mixer

  o  int snd_mixer_unregister( snd_mixer_t *mixer )

  o  mixer pointer to mixer structure

  o  unregisters and frees specified mixer


  4.2.  Exaples
























  ______________________________________________________________________
  #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, &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;
  }
  ______________________________________________________________________





  Do you need modify some default mixer channel assignment?











  ______________________________________________________________________
    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 );
  ______________________________________________________________________





  Do you need add some mixer channel to generic mixer?



       ______________________________________________________________________
         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, &master );
         if ( !channel ) return -ENOMEM;
       ______________________________________________________________________




  Mixer device registering:





  ______________________________________________________________________
    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 );
  ______________________________________________________________________






  5.  PCM - Digital Audio

  Digital Audio related structures and functions are in include/pcm.h
  header file.


  5.1.  Variables and functions

  Variables from snd_pcm_t structure which must be filled:


  o  info_flags look in SND_PCM_INFO_*

  o  name of pcm device (for example 'CS4231')

  o  playback variables for playback direction

  o  record variables for record direction


  Variables from snd_pcm_t structure which should be filled:


  o  private_data should contain pointer to private data

  o  private_free should free private data when called


  Variables from struct snd_stru_pcm_hardware which must be filled:


  o  flags

  o  SND_PCM_HW_BATCH - hardware does double buffering

  o  SND_PCM_HW_8BITONLY - hardware supports only 8-bit data (be careful
     - look at sb16.c)
  o  SND_PCM_HW_16BITONLY - hardware supports only 16-bit data (be
     careful - look at sb16.c)

  o  SND_PCM_HW_AUTODMA - hardware supports auto init dma transfer
     (unterminated loop)

  o  formats list of supported formats SND_PCM_FMT_*

  o  if hardware doesn't support Mu-Law - it _must_ be emulated
     (converted), but it can't be listed here

  o  align - if transfer block must be aligned to some value - set this
     mask

  o  min_fragment - minimal fragment in 2^x

  o  min_rate - minimal rate in Hz

  o  max_rate - maximal rate in Hz

  o  max_voices - maximal number of voices

  o  int (*open)( snd_pcm_t *pcm )

  o  pcm pointer to pcm structure

  o  opens pcm direction and allocates dma buffer with snd_pcm_dma_alloc

  o  int (*close)( snd_pcm_t *pcm )

  o  closes pcm direction and frees dma buffer with snd_pcm_dma_free

  o  void (*compute_rate)( snd_pcm_t *pcm )

  o  computes snd_pcm_channel_t -> real_rate from snd_pcm_channel_t ->
     rate

  o  void (*prepare)( snd_pcm_t *pcm, unsigned char *buffer, unsigned
     int size, unsigned int offset, unsigned int count )

  o  pcm pointer to pcm structure

  o  buffer pointer to dma buffer

  o  size used size of dma buffer

  o  offset offset in bytes to dma buffer

  o  this value is always zero if hardware supports auto init dma
     transfer mode

  o  count of bytes to transfer (block size)

  o  prepares pcm direction to output/input

  o  void (*trigger)( snd_pcm_t *pcm, int up )

  o  pcm pointer to pcm structure

  o  up if zero - trigger down (turn off), if nonzero - trigger up (turn
     on)

  o  starts or stops pcm direction

  o  unsigned int (*pointer)( snd_pcm_t *pcm, unsigned int used_size )

  o  pcm pointer to pcm structure

  o  used_size - used size of dma buffer

  o  returns actual byte pointer from pcm direction

  o  void (*dma)( snd_pcm_t *pcm, unsigned char *buffer, unsigned int
     offset, unsigned char *user, unsigned int count )

  o  pcm pointer to pcm structure

  o  buffer pointer to dma buffer

  o  offset destonation/source offset in bytes to/from dma buffer

  o  user pointer to buffer in user space

  o  count transfer count in bytes

  o  copies data from or to user space to or from kernel dma buffer

  o  void (*dma_move)( snd_pcm_t *pcm, unsigned char *buffer, unsigned
     int dest_offset, unsigned int src_offset, unsigned int count )

  o  pcm pointer to pcm structure

  o  buffer pointer to dma buffer

  o  dest_offset destonation offset in bytes to dma buffer

  o  src_offset source offset in bytes from dma buffer

  o  count transfer count

  o  transfer areas can never be overlapped

  o  void (*dma_neutral)( snd_pcm_t *pcm, unsigned char *buffer,
     unsigned offset, unsigned int count, unsigned char neutral_byte )

  o  pcm pointer to pcm structure

  o  buffer pointer to dma buffer

  o  offset destonation offset in bytes to dma buffer

  o  count count in bytes

  o  neutral_byte - neutral byte

  o  fills specified area of dma buffer with neutral byte


  Variables from struct snd_stru_pcm_hardware which should be filled:


  o  private_data should contains pointer to private data for specified
     direction

  o  private_free should free private data


  Functions list:


  o  void snd_pcm_playback_dma( snd_pcm_t *pcm, unsigned char *buffer,
     unsigned int offset, unsigned char *user, unsigned int count )
  o  standard function for playback snd_pcm_channel_t -> hw.dma

  o  void snd_pcm_playback_dma_ulaw( snd_pcm_t *pcm, unsigned char
     *buffer, unsigned int offset, unsigned char *user, unsigned int
     count )

  o  standard function for playback snd_pcm_channel_t -> hw.dma if
     hardware doesn't supports Mu-Law compression

  o  void snd_pcm_playback_dma_neutral( snd_pcm_t *pcm, unsigned char
     *buffer, unsigned int of unsigned int count, unsigned char
     neutral_byte )

  o  standard function for playback snd_pcm_channel_t -> hw.dma_neutral

  o  void snd_pcm_record_dma( snd_pcm_t *pcm, unsigned char *buffer,
     unsigned int offset, unsigned char *user, unsigned int count )

  o  standard function for record snd_pcm_channel_t -> hw.dma

  o  void snd_pcm_record_dma_ulaw( snd_pcm_t *pcm, unsigned char
     *buffer, unsigned int offset, unsigned char *user, unsigned int
     count )

  o  standard function for record snd_pcm_channel_t -> hw.dma if
     hardware doesn't supports Mu-Law compression

  o  void snd_pcm_dma_move( snd_pcm_t *pcm, unsigned char *buffer,
     unsigned int dest_offset, unsigned int src_offset, unsigned int
     count )

  o  standard function for snd_pcm_channel_t -> hw.dma_move


  Functions for dma allocation:


  o  int snd_pcm_dma_alloc( snd_pcm_t *pcm, int direction, int dmanum,
     char *ident )

  o  pcm pointer to pcm structure

  o  direction pcm direction - SND_PCM_PLAYBACK or SND_PCM_RECORD

  o  dmanum dma index

  o  ident identification for dma owner

  o  allocates pcm dma buffer

  o  int snd_pcm_dma_free( snd_pcm_t *pcm, int direction, int dmanum )

  o  pcm pointer to pcm structure

  o  direction pcm direction

  o  dmanum dma index

  o  frees pcm dma buffer


  Functions for allocation and registering:


  o  snd_pcm_t *snd_pcm_new_device( snd_card_t *card, char *id )

  o  card pointer to soundcard structure

  o  id identification for pcm device (for example 'AD1848')

  o  int snd_pcm_free( snd_pcm_t *pcm )

  o  pcm pointer to pcm structure

  o  frees pcm structure and associated private data

  o  int snd_pcm_register( snd_pcm_t *pcm, int pcm_device )

  o  pcm pointer to pcm structure

  o  pcm_device number of pcm device (0-3)

  o  registers pcm device

  o  int snd_pcm_unregister( snd_pcm_t *pcm )

  o  pcm pointer to pcm structure

  o  unregisters and frees pcm structure


  5.2.  Examples








































  ______________________________________________________________________
  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( &pcm -> playback.hw, &snd_es1688_playback, sizeof( snd_es1688_playback ) );
    memcpy( &pcm -> record.hw, &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;
  }
  ______________________________________________________________________




  PCM device registering:



       ______________________________________________________________________
         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 );
       ______________________________________________________________________
















