From owner-svn-doc-head@FreeBSD.ORG Wed Jul 24 02:40:00 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 425968AD; Wed, 24 Jul 2013 02:40:00 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 3140422E8; Wed, 24 Jul 2013 02:40:00 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6O2e0iO067346; Wed, 24 Jul 2013 02:40:00 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6O2e0rZ067344; Wed, 24 Jul 2013 02:40:00 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307240240.r6O2e0rZ067344@svn.freebsd.org> From: Warren Block Date: Wed, 24 Jul 2013 02:40:00 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42407 - head/en_US.ISO8859-1/books/arch-handbook/sound X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 24 Jul 2013 02:40:00 -0000 Author: wblock Date: Wed Jul 24 02:39:59 2013 New Revision: 42407 URL: http://svnweb.freebsd.org/changeset/doc/42407 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml Modified: head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml Wed Jul 24 02:20:36 2013 (r42406) +++ head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml Wed Jul 24 02:39:59 2013 (r42407) @@ -9,7 +9,7 @@ - Jean-Francois + Jean-Francois Dockes Contributed by @@ -35,31 +35,35 @@ - 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 @@ -75,8 +79,7 @@ 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 @@ -92,7 +95,6 @@ while the pci/, isa/ and usb/ directories have the drivers for PCI and ISA boards, and for USB audio devices. - @@ -107,13 +109,13 @@ 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) @@ -122,77 +124,80 @@ 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. @@ -200,7 +205,7 @@ 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 @@ -216,86 +221,84 @@ 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. - - 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. - - - + 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. + + 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. + + - 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) { @@ -305,46 +308,43 @@ 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 - - xxxchannel_setformat() should set - up the hardware for the specified channel for the specified - sound format. + channel_setformat + + 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; @@ -352,51 +352,49 @@ 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 + 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. + 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 + static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; @@ -404,26 +402,24 @@ 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; @@ -431,120 +427,115 @@ 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. - - - - - - 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. - + + + 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_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 - - 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;. + 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_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); @@ -560,29 +551,28 @@ 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) { @@ -591,31 +581,32 @@ 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. - + + + 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. - - + + 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); @@ -626,62 +617,61 @@ 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 - - xxxmixer_reinit() should ensure - that the mixer hardware is powered up and any settings not - controlled by mixer_set() or - mixer_setrecsrc() are restored. - + mixer_uninit, mixer_reinit + + 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. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***