Date: Wed, 24 Jul 2013 02:40:00 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201307240240.r6O2e0rZ067344@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 @@ <chapterinfo> <authorgroup> <author> - <firstname>Jean-Francois</firstname> + <firstname>Jean-Francois</firstname> <surname>Dockes</surname> <contrib>Contributed by </contrib> </author> @@ -35,31 +35,35 @@ <itemizedlist> <listitem> - <para>A system call interface (read, write, ioctls) to - digitized sound and mixer functions. The ioctl command set - is compatible with the legacy <emphasis>OSS</emphasis> or - <emphasis>Voxware</emphasis> interface, allowing common - multimedia applications to be ported without - modification.</para> + <para>A system call interface (read, write, ioctls) to + digitized sound and mixer functions. The ioctl command set + is compatible with the legacy <emphasis>OSS</emphasis> or + <emphasis>Voxware</emphasis> interface, allowing common + multimedia applications to be ported without + modification.</para> </listitem> + <listitem> - <para>Common code for processing sound data (format - conversions, virtual channels).</para> + <para>Common code for processing sound data (format + conversions, virtual channels).</para> </listitem> + <listitem> - <para>A uniform software interface to hardware-specific audio - interface modules.</para> + <para>A uniform software interface to hardware-specific audio + interface modules.</para> </listitem> + <listitem> - <para>Additional support for some common hardware interfaces - (ac97), or shared hardware-specific code (ex: ISA DMA - routines).</para> + <para>Additional support for some common hardware interfaces + (ac97), or shared hardware-specific code (ex: ISA DMA + routines).</para> </listitem> </itemizedlist> <para>The support for specific sound cards is implemented by - hardware-specific drivers, which provide channel and mixer interfaces - to plug into the generic <devicename>pcm</devicename> code.</para> + hardware-specific drivers, which provide channel and mixer + interfaces to plug into the generic <devicename>pcm</devicename> + code.</para> <para>In this chapter, the term <devicename>pcm</devicename> will refer to the central, common part of the sound driver, as @@ -75,8 +79,7 @@ <para>As an alternative, or in addition to starting from a working example, you can find a commented driver template at <ulink url="http://people.FreeBSD.org/~cg/template.c">; - http://people.FreeBSD.org/~cg/template.c</ulink></para>; - + http://people.FreeBSD.org/~cg/template.c</ulink></para>; </sect1> <sect1 id="oss-files"> @@ -92,7 +95,6 @@ while the <filename>pci/</filename>, <filename>isa/</filename> and <filename>usb/</filename> directories have the drivers for PCI and ISA boards, and for USB audio devices.</para> - </sect1> <sect1 id="pcm-probe-and-attach"> @@ -107,13 +109,13 @@ <para>However, sound drivers differ in some ways:</para> <itemizedlist> - <listitem> - <para>They declare themselves as <devicename>pcm</devicename> - class devices, with a <structname>struct - snddev_info</structname> device private structure:</para> + <para>They declare themselves as <devicename>pcm</devicename> + class devices, with a + <structname>struct snddev_info</structname> device private + structure:</para> - <programlisting> static driver_t xxx_driver = { + <programlisting> 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);</programlisting> - <para>Most sound drivers<indexterm><primary>device drivers</primary> - <secondary>sound</secondary></indexterm> 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 <devicename>pcm</devicename> by the calls to - <function>pcm_register()</function> and - <function>mixer_init()</function>. - <devicename>pcm</devicename> later passes back this address - as a parameter in calls to the sound driver - interfaces.</para> + <para>Most sound drivers<indexterm><primary>device + drivers</primary><secondary>sound</secondary></indexterm> + 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 + <devicename>pcm</devicename> by the calls to + <function>pcm_register()</function> and + <function>mixer_init()</function>. + <devicename>pcm</devicename> later passes back this address + as a parameter in calls to the sound driver + interfaces.</para> </listitem> <listitem> - <para>The sound driver attach routine should declare its MIXER - or AC97 interface to <devicename>pcm</devicename> by calling - <function>mixer_init()</function>. For a MIXER interface, - this causes in turn a call to <link linkend="xxxmixer-init"> - <function>xxxmixer_init()</function></link>.</para> + <para>The sound driver attach routine should declare its MIXER + or AC97 interface to <devicename>pcm</devicename> by calling + <function>mixer_init()</function>. For a MIXER interface, + this causes in turn a call to <link + linkend="xxxmixer-init"><function>xxxmixer_init()</function></link>.</para> </listitem> <listitem> - <para>The sound driver attach routine declares its general - CHANNEL configuration to <devicename>pcm</devicename> by - calling <function>pcm_register(dev, sc, nplay, - nrec)</function>, where <varname>sc</varname> is the address - for the device data structure, used in further calls from - <devicename>pcm</devicename>, and <varname>nplay</varname> - and <varname>nrec</varname> are the number of play and - record channels.</para> + <para>The sound driver attach routine declares its general + CHANNEL configuration to <devicename>pcm</devicename> by + calling <function>pcm_register(dev, sc, nplay, + nrec)</function>, where <varname>sc</varname> is the address + for the device data structure, used in further calls from + <devicename>pcm</devicename>, and <varname>nplay</varname> + and <varname>nrec</varname> are the number of play and + record channels.</para> </listitem> <listitem> - <para>The sound driver attach routine declares each of its - channel objects by calls to - <function>pcm_addchan()</function>. This sets up the - channel glue in <devicename>pcm</devicename> and causes in - turn a call to - <link linkend="xxxchannel-init"> - <function>xxxchannel_init()</function></link>.</para> + <para>The sound driver attach routine declares each of its + channel objects by calls to + <function>pcm_addchan()</function>. This sets up the + channel glue in <devicename>pcm</devicename> and causes in + turn a call to + <link linkend="xxxchannel-init"> + <function>xxxchannel_init()</function></link>.</para> </listitem> <listitem> - <para>The sound driver detach routine should call - <function>pcm_unregister()</function> before releasing its - resources.</para> + <para>The sound driver detach routine should call + <function>pcm_unregister()</function> before releasing its + resources.</para> </listitem> </itemizedlist> - <para>There are two possible methods to handle non-PnP devices:</para> + <para>There are two possible methods to handle non-PnP + devices:</para> + <itemizedlist> <listitem> - <para>Use a <function>device_identify()</function> method - (example: <filename>sound/isa/es1888.c</filename>). The - <function>device_identify()</function> 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.</para> + <para>Use a <function>device_identify()</function> method + (example: <filename>sound/isa/es1888.c</filename>). The + <function>device_identify()</function> 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.</para> </listitem> + <listitem> - <para>Use a custom kernel configuration with appropriate hints - for pcm devices (example: - <filename>sound/isa/mss.c</filename>).</para> + <para>Use a custom kernel configuration with appropriate hints + for pcm devices (example: + <filename>sound/isa/mss.c</filename>).</para> </listitem> </itemizedlist> <para><devicename>pcm</devicename> drivers should implement - <function>device_suspend</function>, - <function>device_resume</function> and - <function>device_shutdown</function> routines, so that power - management and module unloading function correctly.</para> - + <function>device_suspend</function>, + <function>device_resume</function> and + <function>device_shutdown</function> routines, so that power + management and module unloading function correctly.</para> </sect1> <sect1 id="oss-interfaces"> @@ -200,7 +205,7 @@ <para>The interface between the <devicename>pcm</devicename> core and the sound drivers is defined in terms of <link - linkend="kernel-objects">kernel objects</link>.</para> + linkend="kernel-objects">kernel objects</link>.</para> <para>There are two main interfaces that a sound driver will usually provide: <emphasis>CHANNEL</emphasis> and either @@ -216,86 +221,84 @@ <title>The CHANNEL Interface</title> <sect3> - <title>Common Notes for Function Parameters</title> - - <para>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.</para> - - <para>For all CHANNEL interface functions, the first parameter - is an opaque pointer.</para> - - <para>The second parameter is a pointer to the private - channel data structure, except for - <function>channel_init()</function> which has a pointer to the - private device structure (and returns the channel pointer - for further use by <devicename>pcm</devicename>).</para> - - </sect3> - - <sect3> - <title>Overview of Data Transfer Operations</title> - - <para>For sound data transfers, the - <devicename>pcm</devicename> core and the sound drivers - communicate through a shared memory area, described by a - <structname>struct snd_dbuf</structname>.</para> - - <para><structname>struct snd_dbuf</structname> is private to - <devicename>pcm</devicename>, and sound drivers obtain - values of interest by calls to accessor functions - (<function>sndbuf_getxxx()</function>).</para> - - <para>The shared memory area has a size of - <function>sndbuf_getsize()</function> and is divided into - fixed size blocks of <function>sndbuf_getblksz()</function> - bytes.</para> - - <para>When playing, the general transfer mechanism is as - follows (reverse the idea for recording):</para> - - <itemizedlist> - <listitem> - <para><devicename>pcm</devicename> initially fills up the - buffer, then calls the sound driver's <link - linkend="channel-trigger"> - <function>xxxchannel_trigger()</function></link> - function with a parameter of PCMTRIG_START.</para> - </listitem> - - <listitem> - <para>The sound driver then arranges to repeatedly - transfer the whole memory area - (<function>sndbuf_getbuf()</function>, - <function>sndbuf_getsize()</function>) to the device, in - blocks of <function>sndbuf_getblksz()</function> bytes. - It calls back the <function>chn_intr()</function> - <devicename>pcm</devicename> function for each - transferred block (this will typically happen at - interrupt time).</para> - </listitem> - - <listitem> - <para><function>chn_intr()</function> arranges to copy new - data to the area that was transferred to the device (now - free), and make appropriate updates to the - <structname>snd_dbuf</structname> structure.</para> - </listitem> - - </itemizedlist> + <title>Common Notes for Function Parameters</title> + <para>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.</para> + + <para>For all CHANNEL interface functions, the first parameter + is an opaque pointer.</para> + + <para>The second parameter is a pointer to the private + channel data structure, except for + <function>channel_init()</function> which has a pointer to + the private device structure (and returns the channel + pointer for further use by + <devicename>pcm</devicename>).</para> + </sect3> + + <sect3> + <title>Overview of Data Transfer Operations</title> + + <para>For sound data transfers, the + <devicename>pcm</devicename> core and the sound drivers + communicate through a shared memory area, described by a + <structname>struct snd_dbuf</structname>.</para> + + <para><structname>struct snd_dbuf</structname> is private to + <devicename>pcm</devicename>, and sound drivers obtain + values of interest by calls to accessor functions + (<function>sndbuf_getxxx()</function>).</para> + + <para>The shared memory area has a size of + <function>sndbuf_getsize()</function> and is divided into + fixed size blocks of <function>sndbuf_getblksz()</function> + bytes.</para> + + <para>When playing, the general transfer mechanism is as + follows (reverse the idea for recording):</para> + + <itemizedlist> + <listitem> + <para><devicename>pcm</devicename> initially fills up the + buffer, then calls the sound driver's <link + linkend="channel-trigger"> + <function>xxxchannel_trigger()</function></link> + function with a parameter of PCMTRIG_START.</para> + </listitem> + + <listitem> + <para>The sound driver then arranges to repeatedly + transfer the whole memory area + (<function>sndbuf_getbuf()</function>, + <function>sndbuf_getsize()</function>) to the device, in + blocks of <function>sndbuf_getblksz()</function> bytes. + It calls back the <function>chn_intr()</function> + <devicename>pcm</devicename> function for each + transferred block (this will typically happen at + interrupt time).</para> + </listitem> + + <listitem> + <para><function>chn_intr()</function> arranges to copy new + data to the area that was transferred to the device (now + free), and make appropriate updates to the + <structname>snd_dbuf</structname> structure.</para> + </listitem> + </itemizedlist> </sect3> <sect3 id="xxxchannel-init"> - <title>channel_init</title> + <title>channel_init</title> - <para><function>xxxchannel_init()</function> is called to - initialize each of the play or record channels. The calls - are initiated from the sound driver attach routine. (See - the <link linkend="pcm-probe-and-attach">probe and attach - section</link>).</para> + <para><function>xxxchannel_init()</function> is called to + initialize each of the play or record channels. The calls + are initiated from the sound driver attach routine. (See + the <link linkend="pcm-probe-and-attach">probe and attach + section</link>).</para> - <programlisting> static void * + <programlisting> static void * xxxchannel_init(kobj_t obj, void *data, struct snd_dbuf *b, struct pcm_channel *c, int dir)<co id="co-chinit-params"/> { @@ -305,46 +308,43 @@ return ch;<co id="co-chinit-return"/> }</programlisting> - <calloutlist> - - <callout arearefs="co-chinit-params"> - <para><varname>b</varname> is the address for the channel - <structname>struct snd_dbuf</structname>. It should be - initialized in the function by calling - <function>sndbuf_alloc()</function>. The buffer size to - use is normally a small multiple of the 'typical' unit - transfer size for your device.</para> - - <para><varname>c</varname> is the - <devicename>pcm</devicename> 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 <devicename>pcm</devicename> (ie: - <function>chn_intr(c)</function>).</para> - - <para><varname>dir</varname> indicates the channel - direction (<literal>PCMDIR_PLAY</literal> or - <literal>PCMDIR_REC</literal>).</para> - </callout> - - <callout arearefs="co-chinit-return"> - <para>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.</para> - </callout> - - </calloutlist> - + <calloutlist> + <callout arearefs="co-chinit-params"> + <para><varname>b</varname> is the address for the channel + <structname>struct snd_dbuf</structname>. It should be + initialized in the function by calling + <function>sndbuf_alloc()</function>. The buffer size to + use is normally a small multiple of the 'typical' unit + transfer size for your device.</para> + + <para><varname>c</varname> is the + <devicename>pcm</devicename> 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 <devicename>pcm</devicename> (ie: + <function>chn_intr(c)</function>).</para> + + <para><varname>dir</varname> indicates the channel + direction (<literal>PCMDIR_PLAY</literal> or + <literal>PCMDIR_REC</literal>).</para> + </callout> + + <callout arearefs="co-chinit-return"> + <para>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.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>channel_setformat</title> - - <para><function>xxxchannel_setformat()</function> should set - up the hardware for the specified channel for the specified - sound format.</para> + <title>channel_setformat</title> + + <para><function>xxxchannel_setformat()</function> should set + up the hardware for the specified channel for the specified + sound format.</para> - <programlisting> static int + <programlisting> static int xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co id="co-chsetformat-params"/> { struct xxx_chinfo *ch = data; @@ -352,51 +352,49 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-chsetformat-params"> - <para><varname>format</varname> is specified as an - <literal>AFMT_XXX value</literal> - (<filename>soundcard.h</filename>).</para> - </callout> - - </calloutlist> + <calloutlist> + <callout arearefs="co-chsetformat-params"> + <para><varname>format</varname> is specified as an + <literal>AFMT_XXX value</literal> + (<filename>soundcard.h</filename>).</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>channel_setspeed</title> + <title>channel_setspeed</title> - <para><function>xxxchannel_setspeed()</function> sets up the - channel hardware for the specified sampling speed, and - returns the possibly adjusted speed.</para> + <para><function>xxxchannel_setspeed()</function> sets up the + channel hardware for the specified sampling speed, and + returns the possibly adjusted speed.</para> - <programlisting> static int + <programlisting> static int xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) { struct xxx_chinfo *ch = data; ... return speed; }</programlisting> - </sect3> <sect3> - <title>channel_setblocksize</title> + <title>channel_setblocksize</title> - <para><function>xxxchannel_setblocksize()</function> sets the - block size, which is the size of unit transactions between - <devicename>pcm</devicename> 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 - <devicename>pcm</devicename>'s - <function>chn_intr()</function> every time this size has - been transferred.</para> - - <para>Most sound drivers only take note of the block size - here, to be used when an actual transfer will be - started.</para> + <para><function>xxxchannel_setblocksize()</function> sets the + block size, which is the size of unit transactions between + <devicename>pcm</devicename> 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 + <devicename>pcm</devicename>'s + <function>chn_intr()</function> every time this size has + been transferred.</para> + + <para>Most sound drivers only take note of the block size + here, to be used when an actual transfer will be + started.</para> - <programlisting> static int + <programlisting> static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; @@ -404,26 +402,24 @@ return blocksize;<co id="co-chsetblocksize-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-chsetblocksize-return"> - <para>The function returns the possibly adjusted block - size. In case the block size is indeed changed, - <function>sndbuf_resize()</function> should be called to - adjust the buffer.</para> - - </callout> - </calloutlist> - + <calloutlist> + <callout arearefs="co-chsetblocksize-return"> + <para>The function returns the possibly adjusted block + size. In case the block size is indeed changed, + <function>sndbuf_resize()</function> should be called to + adjust the buffer.</para> + </callout> + </calloutlist> </sect3> <sect3 id="channel-trigger"> - <title>channel_trigger</title> + <title>channel_trigger</title> - <para><function>xxxchannel_trigger()</function> is called by - <devicename>pcm</devicename> to control data transfer - operations in the driver.</para> + <para><function>xxxchannel_trigger()</function> is called by + <devicename>pcm</devicename> to control data transfer + operations in the driver.</para> - <programlisting> static int + <programlisting> static int xxxchannel_trigger(kobj_t obj, void *data, int go)<co id="co-chtrigger-params"/> { struct xxx_chinfo *ch = data; @@ -431,120 +427,115 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-chtrigger-params"> - <para><varname>go</varname> defines the action for the - current call. The possible values are:</para> - <itemizedlist> - - <listitem> - <para><literal>PCMTRIG_START</literal>: the driver - should start a data transfer from or to the channel - buffer. If needed, the buffer base and size can be - retrieved through - <function>sndbuf_getbuf()</function> and - <function>sndbuf_getsize()</function>.</para> - </listitem> - - <listitem> - <para><literal>PCMTRIG_EMLDMAWR</literal> / - <literal>PCMTRIG_EMLDMARD</literal>: this tells the - driver that the input or output buffer may have been - updated. Most drivers just ignore these - calls.</para> - </listitem> - - <listitem> - <para><literal>PCMTRIG_STOP</literal> / - <literal>PCMTRIG_ABORT</literal>: the driver should - stop the current transfer.</para> - </listitem> - </itemizedlist> - - </callout> - </calloutlist> - - <note><para>If the driver uses ISA DMA, - <function>sndbuf_isadma()</function> should be called before - performing actions on the device, and will take care of the - DMA chip side of things.</para> - </note> - - </sect3> - - <sect3> - <title>channel_getptr</title> - - <para><function>xxxchannel_getptr()</function> returns the - current offset in the transfer buffer. This will typically - be called by <function>chn_intr()</function>, and this is how - <devicename>pcm</devicename> knows where it can transfer - new data.</para> - - </sect3> - - <sect3> - <title>channel_free</title> - - <para><function>xxxchannel_free()</function> 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 - <function>sndbuf_alloc()</function> was not used for buffer - allocation.</para> - + <calloutlist> + <callout arearefs="co-chtrigger-params"> + <para><varname>go</varname> defines the action for the + current call. The possible values are:</para> + + <itemizedlist> + <listitem> + <para><literal>PCMTRIG_START</literal>: the driver + should start a data transfer from or to the channel + buffer. If needed, the buffer base and size can be + retrieved through + <function>sndbuf_getbuf()</function> and + <function>sndbuf_getsize()</function>.</para> + </listitem> + + <listitem> + <para><literal>PCMTRIG_EMLDMAWR</literal> / + <literal>PCMTRIG_EMLDMARD</literal>: this tells the + driver that the input or output buffer may have been + updated. Most drivers just ignore these + calls.</para> + </listitem> + + <listitem> + <para><literal>PCMTRIG_STOP</literal> / + <literal>PCMTRIG_ABORT</literal>: the driver should + stop the current transfer.</para> + </listitem> + </itemizedlist> + </callout> + </calloutlist> + + <note> + <para>If the driver uses ISA DMA, + <function>sndbuf_isadma()</function> should be called + before performing actions on the device, and will take + care of the DMA chip side of things.</para> + </note> + </sect3> + + <sect3> + <title>channel_getptr</title> + + <para><function>xxxchannel_getptr()</function> returns the + current offset in the transfer buffer. This will typically + be called by <function>chn_intr()</function>, and this is + how <devicename>pcm</devicename> knows where it can transfer + new data.</para> + </sect3> + + <sect3> + <title>channel_free</title> + + <para><function>xxxchannel_free()</function> 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 + <function>sndbuf_alloc()</function> was not used for buffer + allocation.</para> </sect3> <sect3> - <title>channel_getcaps</title> + <title>channel_getcaps</title> - <programlisting> struct pcmchan_caps * + <programlisting> struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { return &xxx_caps;<co id="co-chgetcaps-return"/> }</programlisting> - <calloutlist> - - <callout arearefs="co-chgetcaps-return"> - <para>The routine returns a pointer to a (usually - statically-defined) <structname>pcmchan_caps</structname> - structure (defined in - <filename>sound/pcm/channel.h</filename>. The structure holds - the minimum and maximum sampling frequencies, and the - accepted sound formats. Look at any sound driver for an - example.</para> - </callout> - - </calloutlist> + <calloutlist> + <callout arearefs="co-chgetcaps-return"> + <para>The routine returns a pointer to a (usually + statically-defined) + <structname>pcmchan_caps</structname> structure (defined + in <filename>sound/pcm/channel.h</filename>. The + structure holds the minimum and maximum sampling + frequencies, and the accepted sound formats. Look at + any sound driver for an example.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>More Functions</title> - - <para><function>channel_reset()</function>, - <function>channel_resetdone()</function>, and - <function>channel_notify()</function> are for special purposes - and should not be implemented in a driver without discussing - it on the &a.multimedia;.</para> + <title>More Functions</title> + + <para><function>channel_reset()</function>, + <function>channel_resetdone()</function>, and + <function>channel_notify()</function> are for special + purposes and should not be implemented in a driver without + discussing it on the &a.multimedia;.</para> - <para><function>channel_setdir()</function> is deprecated.</para> + <para><function>channel_setdir()</function> is + deprecated.</para> </sect3> - </sect2> <sect2> <title>The MIXER Interface</title> <sect3 id="xxxmixer-init"> - <title>mixer_init</title> + <title>mixer_init</title> - <para><function>xxxmixer_init()</function> initializes the - hardware and tells <devicename>pcm</devicename> what mixer - devices are available for playing and recording</para> + <para><function>xxxmixer_init()</function> initializes the + hardware and tells <devicename>pcm</devicename> what mixer + devices are available for playing and recording</para> - <programlisting> static int + <programlisting> static int xxxmixer_init(struct snd_mixer *m) { struct xxx_info *sc = mix_getdevinfo(m); @@ -560,29 +551,28 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-mxini-sd"> - <para>Set bits in an integer value and call - <function>mix_setdevs()</function> and - <function>mix_setrecdevs()</function> to tell - <devicename>pcm</devicename> what devices exist.</para> - </callout> - </calloutlist> - - <para>Mixer bits definitions can be found in - <filename>soundcard.h</filename> - (<literal>SOUND_MASK_XXX</literal> values and - <literal>SOUND_MIXER_XXX</literal> bit shifts).</para> + <calloutlist> + <callout arearefs="co-mxini-sd"> + <para>Set bits in an integer value and call + <function>mix_setdevs()</function> and + <function>mix_setrecdevs()</function> to tell + <devicename>pcm</devicename> what devices exist.</para> + </callout> + </calloutlist> + <para>Mixer bits definitions can be found in + <filename>soundcard.h</filename> + (<literal>SOUND_MASK_XXX</literal> values and + <literal>SOUND_MIXER_XXX</literal> bit shifts).</para> </sect3> <sect3> - <title>mixer_set</title> + <title>mixer_set</title> - <para><function>xxxmixer_set()</function> sets the volume - level for one mixer device.</para> + <para><function>xxxmixer_set()</function> sets the volume + level for one mixer device.</para> - <programlisting> static int + <programlisting> static int xxxmixer_set(struct snd_mixer *m, unsigned dev, unsigned left, unsigned right)<co id="co-mxset-params"/> { @@ -591,31 +581,32 @@ return left | (right << 8);<co id="co-mxset-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-mxset-params"> - <para>The device is specified as a <literal>SOUND_MIXER_XXX</literal> - value</para> <para>The volume values are specified in - range [0-100]. A value of zero should mute the - device.</para> - </callout> + <calloutlist> + <callout arearefs="co-mxset-params"> + <para>The device is specified as a + <literal>SOUND_MIXER_XXX</literal> value</para> + + <para>The volume values are specified in range [0-100]. + A value of zero should mute the device.</para> + </callout> - <callout arearefs="co-mxset-return"> - <para>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.</para> - </callout> - </calloutlist> + <callout arearefs="co-mxset-return"> + <para>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.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>mixer_setrecsrc</title> + <title>mixer_setrecsrc</title> - <para><function>xxxmixer_setrecsrc()</function> sets the - recording source device.</para> + <para><function>xxxmixer_setrecsrc()</function> sets the + recording source device.</para> - <programlisting> static int + <programlisting> static int xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co id="co-mxsr-params"/> { struct xxx_info *sc = mix_getdevinfo(m); @@ -626,62 +617,61 @@ return src;<co id="co-mxsr-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-mxsr-params"> - <para>The desired recording devices are specified as a - bit field</para> - </callout> - - <callout arearefs="co-mxsr-return"> - <para>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.</para> - </callout> - </calloutlist> + <calloutlist> + <callout arearefs="co-mxsr-params"> + <para>The desired recording devices are specified as a + bit field</para> + </callout> + + <callout arearefs="co-mxsr-return"> + <para>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.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>mixer_uninit, mixer_reinit</title> - - <para><function>xxxmixer_uninit()</function> should ensure - that all sound is muted and if possible mixer hardware - should be powered down </para> - - <para><function>xxxmixer_reinit()</function> should ensure - that the mixer hardware is powered up and any settings not - controlled by <function>mixer_set()</function> or - <function>mixer_setrecsrc()</function> are restored.</para> - + <title>mixer_uninit, mixer_reinit</title> + + <para><function>xxxmixer_uninit()</function> should ensure + that all sound is muted and if possible mixer hardware + should be powered down </para> + + <para><function>xxxmixer_reinit()</function> should ensure + that the mixer hardware is powered up and any settings not + controlled by <function>mixer_set()</function> or + <function>mixer_setrecsrc()</function> are restored.</para> </sect3> </sect2> <sect2> <title>The AC97 Interface</title> - <indexterm><primary>AC97</primary></indexterm> + <indexterm><primary>AC97</primary></indexterm> <para>The <emphasis>AC97</emphasis> interface is implemented - by drivers with an AC97 codec. It only has three methods:</para> + by drivers with an AC97 codec. It only has three + methods:</para> <itemizedlist> - - <listitem><para><function>xxxac97_init()</function> returns - the number of ac97 codecs found.</para> - </listitem> - - <listitem><para><function>ac97_read()</function> and - <function>ac97_write()</function> read or write a specified - register.</para> - </listitem> - + <listitem> + <para><function>xxxac97_init()</function> returns the number + of ac97 codecs found.</para> + </listitem> + + <listitem> + <para><function>ac97_read()</function> and + <function>ac97_write()</function> read or write a + specified register.</para> + </listitem> </itemizedlist> <para>The <emphasis>AC97</emphasis> interface is used by the - AC97 code in <devicename>pcm</devicename> to perform higher - level operations. Look at - <filename>sound/pci/maestro3.c</filename> or many others under - <filename>sound/pci/</filename> for an example.</para> - + AC97 code in <devicename>pcm</devicename> to perform higher + level operations. Look at + <filename>sound/pci/maestro3.c</filename> or many others under + <filename>sound/pci/</filename> for an example.</para> </sect2> </sect1> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307240240.r6O2e0rZ067344>