Added a table with descriptions of a few configuration instructions.

diff --git a/doc/other.sgml b/doc/other.sgml
index 6fd5905cfc3b161f5c9eeec60a56c0bc4916c331..1f4b3e49e099188f0139a67299700cdb4837e1ac 100644 (file)
--- a/doc/other.sgml
+++ b/doc/other.sgml
@@ -1,4 +1,4 @@
-<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> -->
+<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.3//EN"> -->
 
 
 <section id="acquisitionfunctions">
@@ -244,7 +244,7 @@ data structure:
 struct <anchor id="insn-data-structure">comedi_insn_struct{
   <anchor id="insn-data-structure-insn">unsigned int insn;      // integer encoding the type of acquisition
                           // (or configuration)
-  unsigned int n;         // number of samples
+  unsigned int n;         // number of elements in data array
   <link linkend="ref-type-lsampl-t">lsampl_t</link> <anchor id="insn-data-structure-data">*data;         // pointer to data buffer
   unsigned int subdev;    // subdevice
   unsigned int <anchor id="insn-data-structure-chanspec"><link linkend="ref-macro-CR-PACK">chanspec</link>; // encoded channel specification
@@ -344,7 +344,7 @@ Instructions for configuration
 <para>
 <xref linkend="instructions"> explains how instructions are used to do
 <emphasis>acquisition</emphasis> on channels. This section explains
-how they are used to <emphasis>configure</emphasis> a device.
+how they are used to <emphasis>configure</emphasis> a subdevice.
 There are various sorts of configurations, and the
 specific information for each different configuration possibility is
 to be specified via the
@@ -362,22 +362,118 @@ Using INSN_CONFIG as the
 indicates that the instruction will
 <emphasis>not perform acquisition</emphasis> on a
 channel, but will <emphasis>configure</emphasis> that channel.
-For example, the configuration of digital I/O channels is done as
-follows.  The
+The
 <link linkend="ref-macro-CR-PACK">chanspec</link> field in the
 <link linkend="insn-data-structure-chanspec">comedi_insn</link>
-data structure, contains the channel to be configured. And
-<link linkend="insn-data-structure-data">data</link>[0] contains
-either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired
-direction of the digital I/O lines.
-On typical devices, multiple channels are grouped together in blocks
-for determining their direction.  And configuring one channel in a
-block configures the entire block.
+data structure, contains the channel to be configured.
+The zeroth element of the data array
+is always an id that specifies
+what type of configuration instruction is being performed.  The
+meaning of rest of the elements in the data array
+depend on the configuration instruction id.
+Some of the
+possible ids are summarised in the table below, along with the
+meanings of the data array elements for
+each type of configuration instruction.
 </para>
 
+<informaltable>
+<tgroup cols='4' align='left'>
+<thead>
+<row>
+<entry>data[0]</entry>
+<entry>Description</entry>
+<entry>n (number of elements in data array)</entry>
+<entry>Meanings of data[1], ..., data[n-1]</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>INSN_CONFIG_DIO_INPUT</entry>
+<entry>
+Configure a dio line as input.  It is easier to use comedi_dio_config() than
+to use this configuration instruction directly.
+</entry>
+<entry>1</entry>
+<entry>
+n/a
+</entry>
+</row>
+<row>
+<entry>INSN_CONFIG_DIO_OUTPUT</entry>
+<entry>
+Configure a dio line as output.  It is easier to use comedi_dio_config() than
+to use this configuration instruction directly.
+</entry>
+<entry>1</entry>
+<entry>
+n/a
+</entry>
+</row>
+<row>
+<entry>INSN_CONFIG_ALT_SOURCE</entry>
+<entry>
+Select an alternate input source.  This instruction is
+used by comedi_calibrate to configure analog input channels
+which can be redirected to read internal calibration
+references.  You need to set the CR_ALT_SOURCE flag in the chanspec
+when reading to actually read from the configured alternate input source.
+If you are using comedi_data_read(), then the channel parameter can be
+bitwise or'd with the CR_ALT_SOURCE flag.
+</entry>
+<entry>2</entry>
+<entry>
+<simplelist type='vert' columns='1'>
+<member>
+data[1]: alternate input source.
+</member>
+</simplelist>
+</entry>
+</row>
+<row>
+<entry>INSN_CONFIG_BLOCK_SIZE</entry>
+<entry>
+Specify block size for asynchonous command data.
+When performing streaming input, many boards accumulate
+samples in internal fifos and transfer them to the host
+computer in chunks.  Some drivers let you suggest a size in bytes for how big a
+the chunks should be.  This lets you tune how often the host computer is
+interrupted with a new chunk of data.
+</entry>
+<entry>2</entry>
+<entry>
+<simplelist type='vert' columns='1'>
+<member>
+data[1]: The desired block size in bytes.  The actual configured block size is
+writen back to data[1] after the instruction completes.  This instruction
+acts purely as a query if the block size is set to zero.
+</member>
+</simplelist>
+</entry>
+</row>
+<row>
+<entry>INSN_CONFIG_DIO_QUERY</entry>
+<entry>
+Queries the configuration of a dio line to see if it is an input or output.
+It is probably easier to use the comedilib function comedi_dio_get_config()
+than to use this instruction directly.
+</entry>
+<entry>2</entry>
+<entry>
+<simplelist type='vert' columns='1'>
+<member>
+data[1]: The instruction sets this element to either COMEDI_INPUT or COMEDI_OUTPUT.
+</member>
+</simplelist>
+</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
 <para>
-Another example of an INSN_CONFIG instruction is the configuration of
-the <link linkend="trigother-event">TRIG_OTHER</link> event source.
+See the comedilib demo program demo/choose_clock.c for an example
+of using a configuration instruction.
 </para>
 
 </section>
@@ -1766,7 +1862,7 @@ clock.
 </entry>
 </row>
 <row>
-<entry>unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n)</entry>
+<entry><programlisting>unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n)</programlisting></entry>
 <entry>
 Only available for newer m-series boards.
 The function returns a clock source which will cause the board's
@@ -1856,7 +1952,7 @@ DAQ-STC Technical Reference Manual for more information.
 </entry>
 </row>
 <row>
-<entry>unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n)</entry>
+<entry><programlisting>unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n)</programlisting></entry>
 <entry>
 RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
 have various other signals routed to them in turn.  Currently, comedi