diff --git a/doc/other.xml b/doc/other.xml
index cbac5f3..16b6885 100644
--- a/doc/other.xml
+++ b/doc/other.xml
@@ -56,19 +56,20 @@ digital subdevices on a particular board.
Individual bits on a digital I/O device can be read and written using
-the functions
+the functions comedi_dio_read
+and comedi_dio_write:
-int comedi_dio_read
-comedi_t *device
+int comedi_dio_read
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int *bit
-int comedi_dio_write
-comedi_t *device
+int comedi_dio_write
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int bit
@@ -84,12 +85,12 @@ acquisition. The integer bit
contains the value of the acquired bit.
-The direction of bidirectional lines can be configured using
-the function
+The direction of bidirectional lines can be configured using the function
+comedi_dio_config:
-int comedi_dio_config
-comedi_t *device
+int comedi_dio_config
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int dir
@@ -105,11 +106,11 @@ the entire block.
Multiple channels can be read and written simultaneously using the
-function
+function comedi_dio_bitfield2:
-int comedi_dio_bitfield2
-comedi_t *device
+int comedi_dio_bitfield2
+comedi_t *deviceunsigned int subdeviceunsigned int write_maskunsigned int *bits
@@ -160,56 +161,76 @@ Single analog acquisition
Analog &comedi; channels can produce data values that are
samples from continuous analog signals.
These samples are integers with a significant content in
-the range of, typically, 8, 10,
-12, or 16 bits.
+the range of, typically, 8, 10, 12, or 16 bits.
-The function
+Single samples can be read from an analog channel using the function
+comedi_data_read:
-int comedi_data_read
-comedi_t *device
+int comedi_data_read
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int rangeunsigned int aref
-lsampl_t *data
+lsampl_t *data
-reads one such data value from a &comedi; channel, and puts it in
-the user-specified data buffer. The function
+This reads one such data value from a &comedi; channel, and puts it in
+the user-specified data buffer.
+
+
+
+In the opposite direction, single samples can be written to an analog output
+channel using the function
+comedi_data_write:
-int comedi_data_write
-comedi_t *device
+int comedi_data_write
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int rangeunsigned int aref
-lsampl_t data
+lsampl_t data
+
-works in the opposite direction. Data values returned by this function
+
+Raw data values read or written by the above functions
are unsigned integers less than, or equal to, the maximum sample value
of the channel, which can be determined using the function
+comedi_get_maxdata:
-lsampl_t comedi_get_maxdata
-comedi_t *device
+lsampl_t comedi_get_maxdata
+comedi_t *deviceunsigned int subdeviceunsigned int channel
-Conversion of data values to physical units can be performed by the
-function
+Conversion between raw data values and uncalibrated physical units can
+be performed by the functions
+comedi_to_phys
+and comedi_from_phys:
-double comedi_to_phys
-lsampl_t data
-comedi_range *range
-lsampl_t maxdata
+double comedi_to_phys
+lsampl_t data
+comedi_range *range
+lsampl_t maxdata
+
+lsampl_t comedi_from_phys
+double data
+comedi_range *range
+lsampl_t maxdata
+
+
+
+
There are two data structures in these commands that are not fully
self-explanatory:
@@ -245,16 +266,17 @@ Each single acquisition by, for example,
requires quite some overhead, because all the arguments of the
function call are checked. If multiple acquisitions must be done on
the same channel, this overhead can be avoided by using a function
-that can read more than one sample:
+that can read more than one sample,
+comedi_data_read_n:
-int comedi_data_read_n
-comedi_t *device
+int comedi_data_read_n
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int rangeunsigned int aref
-lsampl_t *data
+lsampl_t *dataunsigned int n
@@ -263,20 +285,23 @@ limited by the &comedi; implementation (to a maximum of 100 samples),
because the call is blocking.
-The start of the data acquisition can also be delayed by a specified
-number of nano-seconds:
+The start of the a single data acquisition can also be delayed by a specified
+number of nano-seconds using the function
+comedi_data_read_delayed:
-int comedi_data_read_delayed
-comedi_t *device
+int comedi_data_read_delayed
+comedi_t *deviceunsigned int subdeviceunsigned int channelunsigned int rangeunsigned int aref
-lsampl_t *data
+lsampl_t *dataunsigned int nano_sec
+
+
All these read and write acquisition functions are implemented on top
of the generic instruction
command.
@@ -320,7 +345,7 @@ All the information needed to execute an instruction is stored in the
comedi_insn
data structure:
-struct comedi_insn_struct {
+typedef struct comedi_insn_struct {
unsigned int insn; // integer encoding the type of acquisition
// (or configuration)
unsigned int n; // number of elements in data array
@@ -393,29 +418,42 @@ Instruction execution
Once an instruction data structure has been filled in, the
corresponding instruction is executed with the function
+comedi_do_insn:
-int comedi_do_insn
-comedi_t *device
-comedi_insn *instruction
+int comedi_do_insn
+comedi_t *device
+comedi_insn *instruction
Many &comedi; instructions are shortcuts that relieve the programmer
from explicitly filling in the data structure and calling the
-comedi_do_insn
+comedi_do_insn
function.
-The function
+A list of instructions can be executed in one function call using the function
+comedi_do_insnlist:
-int comedi_do_insnlist
-comedi_t *device
-comedi_insnlist *list
+int comedi_do_insnlist
+comedi_t *device
+comedi_insnlist *list
-allows to perform a list of instructions in one function
-call. The number of instructions in the list is limited in the
+The parameter list is a pointer to a
+comedi_insnlist
+data structure holding a pointer to an array of comedi_insn
+and the number of instructions in the list:
+
+typedef struct comedi_insnlist_struct {
+ unsigned int n_insns;
+ comedi_insn *insns;
+} comedi_insnlist;
+
+
+
+The number of instructions in the list is limited in the
implementation, because instructions are executed
synchronously, i.e., the call blocks until the
whole instruction (list) has finished.
@@ -484,8 +522,9 @@ each type of configuration instruction.
INSN_CONFIG_DIO_INPUT
-Configure a dio line as input. It is easier to use comedi_dio_config() than
-to use this configuration instruction directly.
+Configure a DIO line as input. It is easier to use
+comedi_dio_config()
+than to use this configuration instruction directly.
1
@@ -495,8 +534,9 @@ n/a
INSN_CONFIG_DIO_OUTPUT
-Configure a dio line as output. It is easier to use comedi_dio_config() than
-to use this configuration instruction directly.
+Configure a DIO line as output. It is easier to use
+comedi_dio_config()
+than to use this configuration instruction directly.
1
@@ -506,13 +546,13 @@ n/a
INSN_CONFIG_ALT_SOURCE
-Select an alternate input source. This instruction is
-used by comedi_calibrate to configure analog input channels
+Select an alternate input source. This instruction is used by calibration
+programs 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
+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.
+If you are using comedi_data_read(), then the channel parameter can be
+bitwise or'd with the CR_ALT_SOURCE flag.
2
@@ -539,8 +579,9 @@ acts purely as a query if the block size is set to zero.
INSN_CONFIG_DIO_QUERY
-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()
+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.
2
@@ -554,7 +595,7 @@ data[1]: The instruction sets this element to either
-See the comedilib demo program demo/choose_clock.c for an example
+See the comedilib demo program demo/choose_clock.c for an example
of using a configuration instruction.
@@ -664,23 +705,24 @@ Executing a command
-A command is executed by the following &comedi; function:
+A command is executed by the function
+comedi_command:
-int comedi_command
-comedi_t *device
-comedi_cmd *command
+int comedi_command
+comedi_t *device
+comedi_cmd *command
The following sections explain the meaning of the
-comedi_cmd data structure.
+comedi_cmd data structure.
Filling in this structure can be quite complicated, and
requires good knowledge about the exact functionalities of the DAQ
card. So, before launching a command, the application programmer is
adviced to check whether this complex command data structure can be
successfully parsed. So, the typical sequence for executing a command is
to first send the command through
-comedi_command_test()
+comedi_command_test()
once or twice. The test will check that the command is valid for the
particular device, and often makes some adjustments to the command
arguments, which can then be read back by the user to see the actual
@@ -689,7 +731,7 @@ values used.
A &comedi; program can find out on-line what the command capabilities
of a specific device are, by means of the
-comedi_get_cmd_src_mask()
+comedi_get_cmd_src_mask()
function.
@@ -703,7 +745,7 @@ The command data structure
The command executes according to the information about the requested
acquisition, which is stored in the
-comedi_cmd
+comedi_cmddata structure:
typedef struct comedi_cmd_struct comedi_cmd;
@@ -745,16 +787,16 @@ so-called event. More on these in
The subdev member of the
-comedi_cmd structure is
+comedi_cmd structure is
the index of the subdevice the command is intended for. The
-comedi_find_subdevice_by_type()
+comedi_find_subdevice_by_type()
function can be useful in discovering the index of your desired subdevice.
The chanlist
member of the
-comedi_cmd data
+comedi_cmd data
structure should point to an array whose number of elements is
specificed by
chanlist_len
@@ -767,9 +809,7 @@ that should be stepped through for each scan. The elements of the
chanlist array should be
initialized by packing the channel, range and reference
information together with the
-
- CR_PACK()
-
+CR_PACK()
macro.
@@ -785,7 +825,7 @@ the buffer where the driver should write/read its data to/from.
The final member of the
-comedi_cmd structure is the
+comedi_cmd structure is the
flags field,
i.e., bits in a word that can be bitwise-or'd together. The meaning of
these bits are explained in a
@@ -813,10 +853,10 @@ start a scan, start a
the acquisition. Each event can be given its own
source
(the *_src members in the
-comedi_cmd data
+comedi_cmd data
structure). And each event source can have a corresponding
argument (the *_arg members of
-the comedi_cmd data
+the comedi_cmd data
structure) whose meaning depends on the type of source trigger.
For example, to specify an external digital line 3 as a
source (in general, any of the five event
@@ -842,10 +882,8 @@ The available options are:
start_src
event occurs
start_arg
-nanoseconds after the
-comedi_cmd
-is called. Currently, only
-start_arg=0 is
+nanoseconds after the command is set up. Currently, only
+start_arg=0 is
supported.
@@ -1048,7 +1086,7 @@ Not all event sources are applicable to all events. Supported
trigger sources for specific events depend significantly on your
particular device, and even more on the current state of its device
driver. The
-comedi_get_cmd_src_mask()
+comedi_get_cmd_src_mask()
function is useful for determining what trigger sources a subdevice
supports.
@@ -1174,7 +1212,7 @@ device that could do either input or output.
TRIG_CONFIG: perform configuration, not triggering.
This is a legacy of the deprecated
-comedi_trig_struct
+comedi_trig_struct
data structure, and has no function at present.
@@ -1228,7 +1266,7 @@ Sometimes, your input channels change slowly enough that
you are able to average many successive input values to get a
more accurate measurement of the actual value. In general,
the more samples you average, the better your estimate
-gets, roughly by a factor of sqrt(number_of_samples).
+gets, roughly by a factor of sqrt(number_of_samples).
Obviously, there are limitations to this:
@@ -1282,18 +1320,18 @@ to help you in your quest to accurately measure slowly varying
inputs:
-int comedi_sv_init
-comedi_sv_t *sv
-comedi_t *device
+int comedi_sv_init
+comedi_sv_t *sv
+comedi_t *deviceunsigned int subdeviceunsigned int channel
-This function initializes the
-comedi_sv_t data structure, used
+The above function comedi_sv_init initializes the
+comedi_sv_t data structure, used
to do the averaging acquisition:
-struct comedi_sv_struct {
+typedef struct comedi_sv_struct {
comedi_t *dev;
unsigned int subdevice;
unsigned int chan;
@@ -1306,19 +1344,20 @@ struct comedi_sv_struct {
int n;
lsampl_t maxdata;
-};
+} comedi_sv_t;
The actual acquisition is done with the function
+comedi_sv_measure:
-int comedi_sv_measure
-comedi_sv_t *sv
+int comedi_sv_measure
+comedi_sv_t *svdouble *data
-The number of samples over which the
-comedi_sv_measure() averages is limited by the
+The number of samples over which the function
+comedi_sv_measure() averages is limited by the
implementation (currently the limit is 100 samples).
@@ -1927,11 +1966,13 @@ Each of these signal lines
can be configured as an input or output, and the signal appearing on the output
of each line can be configured to one of several internal board timing signals
(although on older boards RTSI line 7 can only be used for the clock signal).
-The ni_pcimio, ni_atmio, and ni_mio_cs drivers expose the RTSI bus
+The ni_pcimio, ni_atmio, and
+ni_mio_cs drivers expose the RTSI bus
as a digital I/O subdevice (subdevice number 10).
-The functions comedi_dio_config() and comedi_dio_get_config() can be used on
+The functions comedi_dio_config() and
+comedi_dio_get_config() can be used on
the RTSI subdevice to
set/query the direction (input or output) of each of the RTSI lines individually.
@@ -1941,7 +1982,7 @@ The subdevice also supports the
INSN_CONFIG_GET_CLOCK_SRC configuration
instructions, which can be
used to configure/query what source the board uses to synchronize its
-master clock to. The various possibilities are defined in the comedi.h
+master clock to. The various possibilities are defined in the comedi.h
header file:
@@ -1964,7 +2005,7 @@ Use the board's internal oscillator.
Use the RTSI line 7 as the master clock. This source is
only supported on pre-m-series boards. The newer m-series boards
-use NI_MIO_PLL_RTSI_CLOCK() instead.
+use NI_MIO_PLL_RTSI_CLOCK() instead.
@@ -2010,7 +2051,7 @@ Finally, the configuration instructions
INSN_CONFIG_SET_ROUTING and
INSN_CONFIG_GET_ROUTING
can be used to select/query which internal signal
-will appear on a given RTSI output line. The header file comedi.h defines
+will appear on a given RTSI output line. The header file comedi.h defines
the following signal sources which can be routed to an RTSI line:
@@ -2107,8 +2148,8 @@ signal.
The RTSI bus pins may be used as trigger inputs for many of the
&comedi; trigger functions. To use the RTSI bus pins, set the source to be
TRIG_EXT and the source argument using the return values
-from the NI_EXT_RTSI() function (or similarly the
-NI_EXT_PFI() function if you want
+from the NI_EXT_RTSI() function (or similarly the
+NI_EXT_PFI() function if you want
to trigger from a PFI line). The CR_EDGE and
CR_INVERT flags may
also be set on the trigger source argument to specify edge and