diff --git a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml index 5b6ae42863..aca69c4450 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml @@ -1,687 +1,677 @@ - Jean-Francois + Jean-Francois Dockes Contributed by Sound Subsystem Introduction sound subsystem The FreeBSD sound subsystem cleanly separates generic sound handling issues from device-specific ones. This makes it easier to add support for new hardware. The &man.pcm.4; framework is the central piece of the sound subsystem. It mainly implements the following elements: system call interface - A system call interface (read, write, ioctls) to - digitized sound and mixer functions. The ioctl command set - is compatible with the legacy OSS or - Voxware interface, allowing common - multimedia applications to be ported without - modification. + A system call interface (read, write, ioctls) to + digitized sound and mixer functions. The ioctl command set + is compatible with the legacy OSS or + Voxware interface, allowing common + multimedia applications to be ported without + modification. + - Common code for processing sound data (format - conversions, virtual channels). + Common code for processing sound data (format + conversions, virtual channels). + - A uniform software interface to hardware-specific audio - interface modules. + A uniform software interface to hardware-specific audio + interface modules. + - Additional support for some common hardware interfaces - (ac97), or shared hardware-specific code (ex: ISA DMA - routines). + Additional support for some common hardware interfaces + (ac97), or shared hardware-specific code (ex: ISA DMA + routines). The support for specific sound cards is implemented by - hardware-specific drivers, which provide channel and mixer interfaces - to plug into the generic pcm code. + hardware-specific drivers, which provide channel and mixer + interfaces to plug into the generic pcm + code. In this chapter, the term pcm will refer to the central, common part of the sound driver, as opposed to the hardware-specific modules. The prospective driver writer will of course want to start from an existing module and use the code as the ultimate reference. But, while the sound code is nice and clean, it is also mostly devoid of comments. This document tries to give an overview of the framework interface and answer some questions that may arise while adapting the existing code. As an alternative, or in addition to starting from a working example, you can find a commented driver template at - http://people.FreeBSD.org/~cg/template.c - + http://people.FreeBSD.org/~cg/template.c Files All the relevant code lives in /usr/src/sys/dev/sound/, except for the public ioctl interface definitions, found in /usr/src/sys/sys/soundcard.h Under /usr/src/sys/dev/sound/, the pcm/ directory holds the central code, while the pci/, isa/ and usb/ directories have the drivers for PCI and ISA boards, and for USB audio devices. - Probing, Attaching, etc. Sound drivers probe and attach in almost the same way as any hardware driver module. You might want to look at the ISA or PCI specific sections of the handbook for more information. However, sound drivers differ in some ways: - - They declare themselves as pcm - class devices, with a struct - snddev_info device private structure: + They declare themselves as pcm + class devices, with a + struct snddev_info device private + structure: - static driver_t xxx_driver = { + static driver_t xxx_driver = { "pcm", xxx_methods, sizeof(struct snddev_info) }; DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER); - Most sound driversdevice drivers - sound need to store additional private - information about their device. A private data structure is - usually allocated in the attach routine. Its address is - passed to pcm by the calls to - pcm_register() and - mixer_init(). - pcm later passes back this address - as a parameter in calls to the sound driver - interfaces. + Most sound driversdevice + driverssound + need to store additional private information about their + device. A private data structure is usually allocated in + the attach routine. Its address is passed to + pcm by the calls to + pcm_register() and + mixer_init(). + pcm later passes back this address + as a parameter in calls to the sound driver + interfaces. - The sound driver attach routine should declare its MIXER - or AC97 interface to pcm by calling - mixer_init(). For a MIXER interface, - this causes in turn a call to - xxxmixer_init(). + The sound driver attach routine should declare its MIXER + or AC97 interface to pcm by calling + mixer_init(). For a MIXER interface, + this causes in turn a call to xxxmixer_init(). - The sound driver attach routine declares its general - CHANNEL configuration to pcm by - calling pcm_register(dev, sc, nplay, - nrec), where sc is the address - for the device data structure, used in further calls from - pcm, and nplay - and nrec are the number of play and - record channels. + The sound driver attach routine declares its general + CHANNEL configuration to pcm by + calling pcm_register(dev, sc, nplay, + nrec), where sc is the address + for the device data structure, used in further calls from + pcm, and nplay + and nrec are the number of play and + record channels. - The sound driver attach routine declares each of its - channel objects by calls to - pcm_addchan(). This sets up the - channel glue in pcm and causes in - turn a call to - - xxxchannel_init(). + The sound driver attach routine declares each of its + channel objects by calls to + pcm_addchan(). This sets up the + channel glue in pcm and causes in + turn a call to + + xxxchannel_init(). - The sound driver detach routine should call - pcm_unregister() before releasing its - resources. + The sound driver detach routine should call + pcm_unregister() before releasing its + resources. - There are two possible methods to handle non-PnP devices: + There are two possible methods to handle non-PnP + devices: + - Use a device_identify() method - (example: sound/isa/es1888.c). The - device_identify() method probes for the - hardware at known addresses and, if it finds a supported - device, creates a new pcm device which is then passed to - probe/attach. + Use a device_identify() method + (example: sound/isa/es1888.c). The + device_identify() method probes for the + hardware at known addresses and, if it finds a supported + device, creates a new pcm device which is then passed to + probe/attach. + - Use a custom kernel configuration with appropriate hints - for pcm devices (example: - sound/isa/mss.c). + Use a custom kernel configuration with appropriate hints + for pcm devices (example: + sound/isa/mss.c). pcm drivers should implement - device_suspend, - device_resume and - device_shutdown routines, so that power - management and module unloading function correctly. - + device_suspend, + device_resume and + device_shutdown routines, so that power + management and module unloading function correctly. Interfaces The interface between the pcm core and the sound drivers is defined in terms of kernel objects. + linkend="kernel-objects">kernel objects. There are two main interfaces that a sound driver will usually provide: CHANNEL and either MIXER or AC97. The AC97 interface is a very small hardware access (register read/write) interface, implemented by drivers for hardware with an AC97 codec. In this case, the actual MIXER interface is provided by the shared AC97 code in pcm. The CHANNEL Interface - Common Notes for Function Parameters - - Sound drivers usually have a private data structure to - describe their device, and one structure for each play and - record data channel that it supports. + Common Notes for Function Parameters - For all CHANNEL interface functions, the first parameter - is an opaque pointer. + Sound drivers usually have a private data structure to + describe their device, and one structure for each play and + record data channel that it supports. - The second parameter is a pointer to the private - channel data structure, except for - channel_init() which has a pointer to the - private device structure (and returns the channel pointer - for further use by pcm). + For all CHANNEL interface functions, the first parameter + is an opaque pointer. + The second parameter is a pointer to the private + channel data structure, except for + channel_init() which has a pointer to + the private device structure (and returns the channel + pointer for further use by + pcm). - Overview of Data Transfer Operations - - For sound data transfers, the - pcm core and the sound drivers - communicate through a shared memory area, described by a - struct snd_dbuf. - - struct snd_dbuf is private to - pcm, and sound drivers obtain - values of interest by calls to accessor functions - (sndbuf_getxxx()). - - The shared memory area has a size of - sndbuf_getsize() and is divided into - fixed size blocks of sndbuf_getblksz() - bytes. - - When playing, the general transfer mechanism is as - follows (reverse the idea for recording): - - - - pcm initially fills up the - buffer, then calls the sound driver's - xxxchannel_trigger() - function with a parameter of PCMTRIG_START. - - - - The sound driver then arranges to repeatedly - transfer the whole memory area - (sndbuf_getbuf(), - sndbuf_getsize()) to the device, in - blocks of sndbuf_getblksz() bytes. - It calls back the chn_intr() - pcm function for each - transferred block (this will typically happen at - interrupt time). - - - - chn_intr() arranges to copy new - data to the area that was transferred to the device (now - free), and make appropriate updates to the - snd_dbuf structure. - - - - + Overview of Data Transfer Operations + + For sound data transfers, the + pcm core and the sound drivers + communicate through a shared memory area, described by a + struct snd_dbuf. + + struct snd_dbuf is private to + pcm, and sound drivers obtain + values of interest by calls to accessor functions + (sndbuf_getxxx()). + + The shared memory area has a size of + sndbuf_getsize() and is divided into + fixed size blocks of sndbuf_getblksz() + bytes. + + When playing, the general transfer mechanism is as + follows (reverse the idea for recording): + + + + pcm initially fills up the + buffer, then calls the sound driver's + xxxchannel_trigger() + function with a parameter of PCMTRIG_START. + + + + The sound driver then arranges to repeatedly + transfer the whole memory area + (sndbuf_getbuf(), + sndbuf_getsize()) to the device, in + blocks of sndbuf_getblksz() bytes. + It calls back the chn_intr() + pcm function for each + transferred block (this will typically happen at + interrupt time). + + + + chn_intr() arranges to copy new + data to the area that was transferred to the device (now + free), and make appropriate updates to the + snd_dbuf structure. + + - channel_init + channel_init - xxxchannel_init() is called to - initialize each of the play or record channels. The calls - are initiated from the sound driver attach routine. (See - the probe and attach - section). + xxxchannel_init() is called to + initialize each of the play or record channels. The calls + are initiated from the sound driver attach routine. (See + the probe and attach + section). - static void * + static void * xxxchannel_init(kobj_t obj, void *data, struct snd_dbuf *b, struct pcm_channel *c, int dir) { struct xxx_info *sc = data; struct xxx_chinfo *ch; ... return ch; } - - - - b is the address for the channel - struct snd_dbuf. It should be - initialized in the function by calling - sndbuf_alloc(). The buffer size to - use is normally a small multiple of the 'typical' unit - transfer size for your device. - - c is the - pcm channel control structure - pointer. This is an opaque object. The function should - store it in the local channel structure, to be used in - later calls to pcm (ie: - chn_intr(c)). - - dir indicates the channel - direction (PCMDIR_PLAY or - PCMDIR_REC). - - - - The function should return a pointer to the private - area used to control this channel. This will be passed - as a parameter to other channel interface calls. - - - - + + + b is the address for the channel + struct snd_dbuf. It should be + initialized in the function by calling + sndbuf_alloc(). The buffer size to + use is normally a small multiple of the 'typical' unit + transfer size for your device. + + c is the + pcm channel control structure + pointer. This is an opaque object. The function should + store it in the local channel structure, to be used in + later calls to pcm (ie: + chn_intr(c)). + + dir indicates the channel + direction (PCMDIR_PLAY or + PCMDIR_REC). + + + + The function should return a pointer to the private + area used to control this channel. This will be passed + as a parameter to other channel interface calls. + + - channel_setformat + channel_setformat - xxxchannel_setformat() should set - up the hardware for the specified channel for the specified - sound format. + xxxchannel_setformat() should set + up the hardware for the specified channel for the specified + sound format. - static int + static int xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) { struct xxx_chinfo *ch = data; ... return 0; } - - - format is specified as an - AFMT_XXX value - (soundcard.h). - - - + + + format is specified as an + AFMT_XXX value + (soundcard.h). + + - channel_setspeed + channel_setspeed - xxxchannel_setspeed() sets up the - channel hardware for the specified sampling speed, and - returns the possibly adjusted speed. + xxxchannel_setspeed() sets up the + channel hardware for the specified sampling speed, and + returns the possibly adjusted speed. - static int + static int xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) { struct xxx_chinfo *ch = data; ... return speed; } - - channel_setblocksize - - xxxchannel_setblocksize() sets the - block size, which is the size of unit transactions between - pcm and the sound driver, and - between the sound driver and the device. Typically, this - would be the number of bytes transferred before an interrupt - occurs. During a transfer, the sound driver should call - pcm's - chn_intr() every time this size has - been transferred. - - Most sound drivers only take note of the block size - here, to be used when an actual transfer will be - started. - - static int + channel_setblocksize + + xxxchannel_setblocksize() sets the + block size, which is the size of unit transactions between + pcm and the sound driver, and + between the sound driver and the device. Typically, this + would be the number of bytes transferred before an interrupt + occurs. During a transfer, the sound driver should call + pcm's + chn_intr() every time this size has + been transferred. + + Most sound drivers only take note of the block size + here, to be used when an actual transfer will be + started. + + static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; ... return blocksize; } - - - The function returns the possibly adjusted block - size. In case the block size is indeed changed, - sndbuf_resize() should be called to - adjust the buffer. - - - - + + + The function returns the possibly adjusted block + size. In case the block size is indeed changed, + sndbuf_resize() should be called to + adjust the buffer. + + - channel_trigger + channel_trigger - xxxchannel_trigger() is called by - pcm to control data transfer - operations in the driver. + xxxchannel_trigger() is called by + pcm to control data transfer + operations in the driver. - static int + static int xxxchannel_trigger(kobj_t obj, void *data, int go) { struct xxx_chinfo *ch = data; ... return 0; } - - - go defines the action for the - current call. The possible values are: - - - - PCMTRIG_START: the driver - should start a data transfer from or to the channel - buffer. If needed, the buffer base and size can be - retrieved through - sndbuf_getbuf() and - sndbuf_getsize(). - - - - PCMTRIG_EMLDMAWR / - PCMTRIG_EMLDMARD: this tells the - driver that the input or output buffer may have been - updated. Most drivers just ignore these - calls. - - - - PCMTRIG_STOP / - PCMTRIG_ABORT: the driver should - stop the current transfer. - - - - - - - If the driver uses ISA DMA, - sndbuf_isadma() should be called before - performing actions on the device, and will take care of the - DMA chip side of things. - - + + + go defines the action for the + current call. The possible values are: + + + + PCMTRIG_START: the driver + should start a data transfer from or to the channel + buffer. If needed, the buffer base and size can be + retrieved through + sndbuf_getbuf() and + sndbuf_getsize(). + + + + PCMTRIG_EMLDMAWR / + PCMTRIG_EMLDMARD: this tells the + driver that the input or output buffer may have been + updated. Most drivers just ignore these + calls. + + + + PCMTRIG_STOP / + PCMTRIG_ABORT: the driver should + stop the current transfer. + + + + + + + If the driver uses ISA DMA, + sndbuf_isadma() should be called + before performing actions on the device, and will take + care of the DMA chip side of things. + - channel_getptr - - xxxchannel_getptr() returns the - current offset in the transfer buffer. This will typically - be called by chn_intr(), and this is how - pcm knows where it can transfer - new data. + channel_getptr + xxxchannel_getptr() returns the + current offset in the transfer buffer. This will typically + be called by chn_intr(), and this is + how pcm knows where it can transfer + new data. - channel_free - - xxxchannel_free() is called to free - up channel resources, for example when the driver is - unloaded, and should be implemented if the channel data - structures are dynamically allocated or if - sndbuf_alloc() was not used for buffer - allocation. - + channel_free + + xxxchannel_free() is called to free + up channel resources, for example when the driver is + unloaded, and should be implemented if the channel data + structures are dynamically allocated or if + sndbuf_alloc() was not used for buffer + allocation. - channel_getcaps + channel_getcaps - struct pcmchan_caps * + struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { return &xxx_caps; } - - - - The routine returns a pointer to a (usually - statically-defined) pcmchan_caps - structure (defined in - sound/pcm/channel.h. The structure holds - the minimum and maximum sampling frequencies, and the - accepted sound formats. Look at any sound driver for an - example. - - - - + + + + The routine returns a pointer to a (usually + statically-defined) + pcmchan_caps structure (defined + in sound/pcm/channel.h. The + structure holds the minimum and maximum sampling + frequencies, and the accepted sound formats. Look at + any sound driver for an example. + + - More Functions + More Functions - channel_reset(), - channel_resetdone(), and - channel_notify() are for special purposes - and should not be implemented in a driver without discussing - it on the &a.multimedia;. + channel_reset(), + channel_resetdone(), and + channel_notify() are for special + purposes and should not be implemented in a driver without + discussing it on the &a.multimedia;. - channel_setdir() is deprecated. + channel_setdir() is + deprecated. - The MIXER Interface - mixer_init + mixer_init - xxxmixer_init() initializes the - hardware and tells pcm what mixer - devices are available for playing and recording + xxxmixer_init() initializes the + hardware and tells pcm what mixer + devices are available for playing and recording - static int + static int xxxmixer_init(struct snd_mixer *m) { struct xxx_info *sc = mix_getdevinfo(m); u_int32_t v; [Initialize hardware] [Set appropriate bits in v for play mixers] mix_setdevs(m, v); [Set appropriate bits in v for record mixers] mix_setrecdevs(m, v) return 0; } - - - Set bits in an integer value and call - mix_setdevs() and - mix_setrecdevs() to tell - pcm what devices exist. - - - - Mixer bits definitions can be found in - soundcard.h - (SOUND_MASK_XXX values and - SOUND_MIXER_XXX bit shifts). - + + + Set bits in an integer value and call + mix_setdevs() and + mix_setrecdevs() to tell + pcm what devices exist. + + + + Mixer bits definitions can be found in + soundcard.h + (SOUND_MASK_XXX values and + SOUND_MIXER_XXX bit shifts). - mixer_set + mixer_set - xxxmixer_set() sets the volume - level for one mixer device. + xxxmixer_set() sets the volume + level for one mixer device. - static int + static int xxxmixer_set(struct snd_mixer *m, unsigned dev, unsigned left, unsigned right) { struct sc_info *sc = mix_getdevinfo(m); [set volume level] return left | (right << 8); } - - - The device is specified as a SOUND_MIXER_XXX - value The volume values are specified in - range [0-100]. A value of zero should mute the - device. - - - - As the hardware levels probably will not match the - input scale, and some rounding will occur, the routine - returns the actual level values (in range 0-100) as - shown. - - + + + The device is specified as a + SOUND_MIXER_XXX value + + The volume values are specified in range [0-100]. + A value of zero should mute the device. + + + + As the hardware levels probably will not match the + input scale, and some rounding will occur, the routine + returns the actual level values (in range 0-100) as + shown. + + - mixer_setrecsrc + mixer_setrecsrc - xxxmixer_setrecsrc() sets the - recording source device. + xxxmixer_setrecsrc() sets the + recording source device. - static int + static int xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) { struct xxx_info *sc = mix_getdevinfo(m); [look for non zero bit(s) in src, set up hardware] [update src to reflect actual action] return src; } - - - The desired recording devices are specified as a - bit field - - - - The actual devices set for recording are returned. - Some drivers can only set one device for recording. The - function should return -1 if an error occurs. - - + + + The desired recording devices are specified as a + bit field + + + + The actual devices set for recording are returned. + Some drivers can only set one device for recording. The + function should return -1 if an error occurs. + + - mixer_uninit, mixer_reinit - - xxxmixer_uninit() should ensure - that all sound is muted and if possible mixer hardware - should be powered down + mixer_uninit, mixer_reinit - xxxmixer_reinit() should ensure - that the mixer hardware is powered up and any settings not - controlled by mixer_set() or - mixer_setrecsrc() are restored. + xxxmixer_uninit() should ensure + that all sound is muted and if possible mixer hardware + should be powered down + xxxmixer_reinit() should ensure + that the mixer hardware is powered up and any settings not + controlled by mixer_set() or + mixer_setrecsrc() are restored. The AC97 Interface - AC97 + AC97 The AC97 interface is implemented - by drivers with an AC97 codec. It only has three methods: + by drivers with an AC97 codec. It only has three + methods: - - xxxac97_init() returns - the number of ac97 codecs found. - - - ac97_read() and - ac97_write() read or write a specified - register. - - + + xxxac97_init() returns the number + of ac97 codecs found. + + + + ac97_read() and + ac97_write() read or write a + specified register. + The AC97 interface is used by the - AC97 code in pcm to perform higher - level operations. Look at - sound/pci/maestro3.c or many others under - sound/pci/ for an example. - + AC97 code in pcm to perform higher + level operations. Look at + sound/pci/maestro3.c or many others under + sound/pci/ for an example.