Advanced Linux Sound Architecture - Driver: Soundcard

Next Previous Contents

## 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:

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

Variables from snd_card_t structure which must be filled:

- type is a type identification from include/asoundid.h.
- abbreviation is an abbreviation for soundcard (for example 'GUS').
- shortname is a shortname for soundcard (for example 'Gravis UltraSound MAX').
- 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:

- private_data should be used by soundcard driver for private data.
- private_free is called when private_data should be freed.

### 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:

- int snd_register_ioport( snd_card_t *card, int port, int size, char *name )
  - card pointer to soundcard structure
  - port means first port from ioport region
  - size means size of ioport region
  - name ioport region name
  - registers ioport region and assigns it to soundcard
- int snd_unregister_ioports( snd_card_t *card )
  - card pointer to soundcard structure
  - unregisters all ioport regions which are assigned to soundcard
- int snd_register_dma_channel( snd_card_t *card, char *name, int number, int type, int rsize, int *possible_numbers )
  - card pointer to soundcard structure
  - name name of dma channel
  - number number of dma channel or SND_AUTO_DMA
  - type type of dma buffer
    - SND_DMA_TYPE_ISA limited dma buffer to low 16MB of RAM
    - SND_DMA_TYPE_PCI unlimited dma buffer (should be anywhere in RAM)
    - SND_DMA_TYPE_HARDWARE hardware dma buffer (is available on soundcard and directly mmaped to OS memory)
  - rsize requested dma buffer size (in kB) or SND_AUTO_DMA_SIZE
  - 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
- int snd_unregister_dma_channels( snd_card_t *card )
  - card pointer to soundcard structure
  - unregisters all dma channels assigned to soundcard
- 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 )
  - card pointer to soundcard structure
  - name name of interrupt line
  - number number of interrupt line or SND_AUTO_IRQ
  - type type of interrupt line
    - SND_IRQ_TYPE_ISA ISA interrupt line (not shareable)
    - SND_IRQ_TYPE_PCI PCI interrupt line (shareable)
  - handler pointer to interrupt handler
  - dev_id pointer to some private structure for interrupt handler
  - 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
  - returns index to card -> irqs array
- int snd_unregister_interrupts( snd_card_t *card )
  - card pointer to soundcard structure
  - disables and frees all interrupt lines assigned to soundcard
- int snd_enable_irq( snd_card_t *card, int irqnum )
  - card pointer to soundcard structure
  - irqnum index of interrupt line to be enabled
- int snd_disable_irq( snd_card_t *card, int irqnum )
  - card pointer to soundcard structure
  - 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.

### 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:

- void snd_dma_program( int dma, const void *buf, unsigned int size, unsigned char mode )
  - dma dma number (not index)
  - buf dma buffer
  - size dma buffer size (transfer length)
  - mode dma transfer mode
    - DMA_MODE_READ
    - DMA_MODE_WRITE
    - DMA_MODE_AUTOINIT - flag
  - programs dma transfer
- unsigned int snd_dma_residue( int dma )
  - dma dma number (not index)
  - 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:

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

Functions list:

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

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

> `

Next Previous Contents