From 1d351bfa0472b1fe7090b480edf367934e63aad7 Mon Sep 17 00:00:00 2001 From: Ian Abbott Date: Tue, 1 May 2012 15:42:07 +0100 Subject: [PATCH] doc/other.xml: Some DocBook markup changes. --- doc/other.xml | 421 +++++++++++++++++++++++++++++++------------------- 1 file changed, 260 insertions(+), 161 deletions(-) diff --git a/doc/other.xml b/doc/other.xml index 1d83b10..9486205 100644 --- a/doc/other.xml +++ b/doc/other.xml @@ -57,12 +57,23 @@ digital subdevices on a particular board. Individual bits on a digital I/O device can be read and written using the functions - -int comedi_dio_read(comedi_t *device, unsigned int subdevice, unsigned int channel, - unsigned int *bit); -int comedi_dio_write(comedi_t *device, unsigned int subdevice, unsigned int channel, - unsigned int bit); - + + +int comedi_dio_read +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int *bit + + + +int comedi_dio_write +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int bit + + The device parameter is a pointer to a successfully opened &comedi; device. @@ -75,13 +86,18 @@ contains the value of the acquired bit. The direction of bidirectional lines can be configured using the function - -int comedi_dio_config(comedi_t *device, unsigned int subdevice, unsigned int channel, - unsigned int dir); - + + +int comedi_dio_config +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int dir + + The parameter dir should be -either COMEDI_INPUT or -COMEDI_OUTPUT. +either COMEDI_INPUT or +COMEDI_OUTPUT. Many digital I/O subdevices group channels into blocks for configuring direction. Changing one channel in a block changes the entire block. @@ -90,10 +106,15 @@ the entire block. Multiple channels can be read and written simultaneously using the function - -int comedi_dio_bitfield(comedi_t *device, unsigned int subdevice, - unsigned int write_mask, unsigned int *bits); - + + +int comedi_dio_bitfield +comedi_t *device +unsigned int subdevice +unsigned int write_mask +unsigned int *bits + + Each channel is assigned to a bit in the write_mask and bits @@ -133,29 +154,52 @@ the range of, typically, 8, 10, 12, or 16 bits. -The - -int comedi_data_read(comedi_t *device, unsigned int subdevice, unsigned int channel, - unsigned int range, unsigned int aref, lsampl_t * data); - -function reads one such data value from a &comedi; channel, and puts it in -the user-specified data buffer. The - -int comedi_data_write(comedi_t *device, unsigned int subdevice, unsigned int channel, - unsigned int range, unsigned int aref, lsampl_t data); - +The function + + +int comedi_data_read +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int range +unsigned int aref +lsampl_t *data + + +reads one such data value from a &comedi; channel, and puts it in +the user-specified data buffer. The function + + +int comedi_data_write +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int range +unsigned int aref +lsampl_t data + + works in the opposite direction. Data values returned by this function are unsigned integers less than, or equal to, the maximum sample value of the channel, which can be determined using the function - -lsampl_t comedi_get_maxdata(comedi_t *device, unsigned int subdevice, - unsigned int channel); - + + +lsampl_t comedi_get_maxdata +comedi_t *device +unsigned int subdevice +unsigned int channel + + Conversion of data values to physical units can be performed by the function - -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 + + There are two data structures in these commands that are not fully self-explanatory: @@ -192,10 +236,18 @@ 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: - -int comedi_data_read_n(comedi_t *it, unsigned int subdev, unsigned int chan, - unsigned int range, unsigned int aref, lsampl_t *data, unsigned int n); - + + +int comedi_data_read_n +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int range +unsigned int aref +lsampl_t *data +unsigned int n + + The number of samples, n, is limited by the &comedi; implementation (to a maximum of 100 samples), because the call is blocking. @@ -203,11 +255,18 @@ because the call is blocking. The start of the data acquisition can also be delayed by a specified number of nano-seconds: - -int comedi_data_read_delayed(comedi_t *it, unsigned int subdev, unsigned int chan, - unsigned int range, unsigned int aref, lsampl_t *data, - unsigned int nano_sec); - + + +int comedi_data_read_delayed +comedi_t *device +unsigned int subdevice +unsigned int channel +unsigned int range +unsigned int aref +lsampl_t *data +unsigned int nano_sec + + All these read and write acquisition functions are implemented on top of the generic instruction command. @@ -278,34 +337,36 @@ instruction: -INSN_READ: the instruction executes a read on an analog channel. +INSN_READ: the instruction executes a read on an +analog channel. -INSN_WRITE: the instruction executes a write on an analog channel. +INSN_WRITE: the instruction executes a write on an +analog channel. -INSN_BITS: indicates that the instruction must +INSN_BITS: indicates that the instruction must read or write values on multiple digital I/O channels. -INSN_GTOD: the instruction performs a Get Time Of Day -acquisition. +INSN_GTOD: the instruction performs a +Get Time Of Day acquisition. -INSN_WAIT: the instruction blocks for a specified number of -nanoseconds. +INSN_WAIT: the instruction blocks for a specified +number of nanoseconds. @@ -321,21 +382,29 @@ Instruction execution Once an instruction data structure has been filled in, the -corresponding instruction is executed as follows: - -int comedi_do_insn(comedi_t *it, comedi_insn *instruction); - +corresponding instruction is executed with the function + + +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 function. -The - -int comedi_do_insnlist(comedi_t *it, comedi_insnlist *list) - -instruction allows to perform a list of instructions in one function +The function + + +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 implementation, because instructions are executed synchronously, i.e., the call blocks until the @@ -366,7 +435,7 @@ is misused as a pointer to an array with board-specific information.) -Using INSN_CONFIG as the +Using INSN_CONFIG as the insn flag in an instruction data structure indicates that the instruction will @@ -403,7 +472,7 @@ each type of configuration instruction. -INSN_CONFIG_DIO_INPUT +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. @@ -414,7 +483,7 @@ n/a -INSN_CONFIG_DIO_OUTPUT +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. @@ -425,7 +494,7 @@ n/a -INSN_CONFIG_ALT_SOURCE +INSN_CONFIG_ALT_SOURCE Select an alternate input source. This instruction is used by comedi_calibrate to configure analog input channels @@ -441,7 +510,7 @@ data[1]: alternate input source. -INSN_CONFIG_BLOCK_SIZE +INSN_CONFIG_BLOCK_SIZE Specify block size for asynchonous command data. When performing streaming input, many boards accumulate @@ -458,7 +527,7 @@ acts purely as a query if the block size is set to zero. -INSN_CONFIG_DIO_QUERY +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() @@ -466,7 +535,8 @@ than to use this instruction directly. 2 -data[1]: The instruction sets this element to either COMEDI_INPUT or COMEDI_OUTPUT. +data[1]: The instruction sets this element to either +COMEDI_INPUT or COMEDI_OUTPUT. @@ -487,7 +557,7 @@ Instruction for internal triggering This special instruction has -INSN_INTTRIG as the +INSN_INTTRIG as the insn flag in its instruction data structure. Its execution causes an @@ -499,8 +569,8 @@ depends on the card and its particular driver. The data[0] field of the -INSN_INTTRIG instruction is reserved for future use, and should be set -to 0. +INSN_INTTRIG instruction is reserved for future use, +and should be set to 0. @@ -584,10 +654,14 @@ Executing a command -A commands is executed by the following &comedi; function: - -int comedi_command(comedi_t *device, comedi_cmd *command); - +A command is executed by the following &comedi; function: + + +int comedi_command +comedi_t *device +comedi_cmd *command + + The following sections explain the meaning of the comedi_cmd data structure. Filling in this structure can be quite complicated, and @@ -695,7 +769,7 @@ The data and members can be safely ignored when issueing commands from a user-space program. They only have meaning when a command is sent from a kernel module using the -kcomedilib interface, in which case they specify +kcomedilib interface, in which case they specify the buffer where the driver should write/read its data to/from. @@ -737,8 +811,8 @@ 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 sources), you would use -src=TRIG_EXT and -arg=3. +src=TRIG_EXT +and arg=3. The following paragraphs discuss in somewhat more detail the trigger @@ -754,7 +828,7 @@ The available options are: -TRIG_NOW: the +TRIG_NOW: the start_src event occurs start_arg @@ -769,7 +843,7 @@ supported. -TRIG_FOLLOW: (For an output device.) The +TRIG_FOLLOW: (For an output device.) The start_src event occurs when data is written to the buffer. @@ -778,8 +852,8 @@ event occurs when data is written to the buffer. -TRIG_EXT: the start event occurs when an external trigger signal -occurs; e.g., a rising edge of a digital line. +TRIG_EXT: the start event occurs when an +external trigger signal occurs; e.g., a rising edge of a digital line. start_arg chooses the particular digital line. @@ -788,9 +862,10 @@ chooses the particular digital line. -TRIG_INT: the start event occurs on a &comedi; internal signal, which -is typically caused by an -INSN_INTTRIG instruction. +TRIG_INT: the start event occurs on a &comedi; +internal signal, which is typically caused by an +INSN_INTTRIG +instruction. @@ -804,7 +879,7 @@ The available options are: -TRIG_TIMER: +TRIG_TIMER: scan_begin events occur periodically. The time between scan_begin @@ -817,7 +892,7 @@ nanoseconds. -TRIG_FOLLOW: The +TRIG_FOLLOW: The scan_begin event occurs immediately after a scan_end @@ -828,7 +903,7 @@ event occurs. -TRIG_EXT: the +TRIG_EXT: the scan_begin event occurs when an external trigger signal occurs; e.g., a rising edge of a digital line. @@ -855,8 +930,8 @@ fields: -TRIG_TIMER: the conversion events occur periodically. The time -between convert events is +TRIG_TIMER: the conversion events occur periodically. +The time between convert events is convert_arg nanoseconds. @@ -866,8 +941,8 @@ nanoseconds. -TRIG_EXT: the conversion events occur when an external trigger signal -occurs, e.g., a rising edge of a digital line. +TRIG_EXT: the conversion events occur when an +external trigger signal occurs, e.g., a rising edge of a digital line. convert_arg chooses the particular digital line. @@ -877,7 +952,7 @@ chooses the particular digital line. -TRIG_NOW: All conversion events in a +TRIG_NOW: All conversion events in a scan occur simultaneously. @@ -885,8 +960,8 @@ TRIG_NOW: All conversion events in a The end of each scan is almost always specified using -TRIG_COUNT, with the argument being -the same as the number of channels in the +TRIG_COUNT, +with the argument being the same as the number of channels in the chanlist. You could probably find a device that allows something else, but it would be strange. @@ -903,7 +978,7 @@ and stop_arg: -TRIG_COUNT: stop the acquisition after +TRIG_COUNT: stop the acquisition after stop_arg scans. @@ -913,14 +988,15 @@ scans. -TRIG_NONE: perform continuous acquisition, until stopped using +TRIG_NONE: perform continuous acquisition, +until stopped using comedi_cancel(). -Its argument is reserved and should be set to 0. +Its argument is reserved and should be set to 0. (Reserved means that unspecified things could happen if it is set to something -else but 0.) +else but 0.) @@ -931,7 +1007,7 @@ There are a couple of less usual or not yet implemented events: -TRIG_TIME: +TRIG_TIME: cause an event to occur at a particular time. @@ -942,18 +1018,18 @@ cause an event to occur at a particular time. -TRIG_OTHER: driver specific event trigger. +TRIG_OTHER: driver specific event trigger. This event can be useful as any of the trigger sources. Its exact meaning is driver specific, because it implements a feature that otherwise does not fit into the generic &comedi; command interface. -Configuration of TRIG_OTHER features are done by -INSN_CONFIG +Configuration of TRIG_OTHER features are done by +INSN_CONFIG instructions. -The argument is reserved and should be set to 0. +The argument is reserved and should be set to 0. @@ -988,7 +1064,7 @@ The meaning of the field is as follows: -TRIG_RT: ask the driver to use a +TRIG_RT: ask the driver to use a hard real-time interrupt handler. This will reduce latency in handling interrupts from your data aquisition @@ -1004,7 +1080,7 @@ nothing. -TRIG_WAKE_EOS: +TRIG_WAKE_EOS: where EOS stands for End of Scan. Some drivers will change their behaviour when this flag is set, trying to transfer data at the end of every scan (instead of, for example, @@ -1018,7 +1094,7 @@ frequent event than the filling up of the data buffer. -TRIG_ROUND_NEAREST: +TRIG_ROUND_NEAREST: round to nearest supported timing period, the default. This flag (as well as the following three), indicates how timing arguments should be rounded if the hardware cannot achieve the exact @@ -1029,21 +1105,21 @@ timing requested. -TRIG_ROUND_DOWN: round period down. +TRIG_ROUND_DOWN: round period down. -TRIG_ROUND_UP: round period up. +TRIG_ROUND_UP: round period up. -TRIG_ROUND_UP_NEXT: +TRIG_ROUND_UP_NEXT: this one doesn't do anything, and I don't know what it was intended to do…? @@ -1052,23 +1128,24 @@ to do…? -TRIG_DITHER: enable dithering? Dithering is a software technique to -smooth the influence of discretization noise. +TRIG_DITHER: enable dithering? Dithering is +a software technique to smooth the influence of discretization +noise. -TRIG_DEGLITCH: enable deglitching? Another noise -smoothing technique. +TRIG_DEGLITCH: enable deglitching? +Another noise smoothing technique. -TRIG_WRITE: +TRIG_WRITE: write to bidirectional devices. Could be useful, in principle, if someone wrote a driver that supported commands for a digital I/O device that could do either input or output. @@ -1078,15 +1155,15 @@ device that could do either input or output. -TRIG_BOGUS: do the motions? +TRIG_BOGUS: do the motions? -TRIG_CONFIG: perform configuration, not triggering. This is a legacy -of the deprecated +TRIG_CONFIG: perform configuration, not triggering. +This is a legacy of the deprecated comedi_trig_struct data structure, and has no function at present. @@ -1193,10 +1270,15 @@ seconds. As you might have guessed, the &comedi; library has functions to help you in your quest to accurately measure slowly varying inputs: - -int comedi_sv_init(comedi_sv_t *sv, comedi_t *device, unsigned int subdevice, - unsigned int channel); - + + +int comedi_sv_init +comedi_sv_t *sv +comedi_t *device +unsigned int subdevice +unsigned int channel + + This function initializes the comedi_sv_t data structure, used to do the averaging acquisition: @@ -1216,10 +1298,15 @@ struct comedi_sv_struct { lsampl_t maxdata; }; -The actual acquisition is done with: - -int comedi_sv_measure(comedi_sv_t *sv, double *data); - + +The actual acquisition is done with the function + + +int comedi_sv_measure +comedi_sv_t *sv +double *data + + The number of samples over which the comedi_sv_measure() averages is limited by the implementation (currently the limit is 100 samples). @@ -1445,8 +1532,8 @@ application will use to configure an extended trigger, and a command, specifying -TRIG_OTHER as one of the trigger -sources. +TRIG_OTHER +as one of the trigger sources. @@ -1486,27 +1573,27 @@ structure. The possible values are an OR'd mask of the following: -COMEDI_EV_START +COMEDI_EV_START -COMEDI_EV_SCAN_BEGIN +COMEDI_EV_SCAN_BEGIN -COMEDI_EV_CONVERT +COMEDI_EV_CONVERT -COMEDI_EV_SCAN_END +COMEDI_EV_SCAN_END -COMEDI_EV_STOP +COMEDI_EV_STOP @@ -1572,7 +1659,7 @@ than the secondary analog comparator level. If only one analog comparator signal is used, the combining machine for the secondary input should be set to ignored, and the secondary -analog level should be set to 0. +analog level should be set to 0. @@ -1655,7 +1742,8 @@ which to match a pattern. Discovery: The number of bits can be discovered by setting the mask -to all 1's. The driver must modify this value and return -EAGAIN. +to all 1's. The driver must modify this value and return +-EAGAIN. @@ -1723,15 +1811,15 @@ encoders, etc. Counters can be operated either in synchronous mode (using -INSN_READ) +INSN_READ) or asynchronous mode (using commands), similar to analog input subdevices. The input signal for both modes is the accumulator. Commands on counter subdevices are almost always specified using scan_begin_src -= TRIG_OTHER, with the -counter configuration also serving as the extended configuration for += TRIG_OTHER, +with the counter configuration also serving as the extended configuration for the scan begin source. @@ -1839,7 +1927,8 @@ set/query the direction (input or output) of each of the RTSI lines individually The subdevice also supports the -INSN_CONFIG_SET_CLOCK_SRC and INSN_CONFIG_GET_CLOCK_SRC configuration +INSN_CONFIG_SET_CLOCK_SRC and +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 @@ -1855,13 +1944,13 @@ header file: -NI_MIO_INTERNAL_CLOCK +NI_MIO_INTERNAL_CLOCK Use the board's internal oscillator. -NI_MIO_RTSI_CLOCK +NI_MIO_RTSI_CLOCK Use the RTSI line 7 as the master clock. This source is only supported on pre-m-series boards. The newer m-series boards @@ -1869,7 +1958,7 @@ use NI_MIO_PLL_RTSI_CLOCK() instead. -NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK +NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK Only available for newer m-series PXI boards. Synchronizes the board's phased-locked loop (which runs at 80MHz) to the PXI star trigger @@ -1877,7 +1966,7 @@ line. -NI_MIO_PLL_PXI10_CLOCK +NI_MIO_PLL_PXI10_CLOCK Only available for newer m-series PXI boards. Synchronizes the board's @@ -1886,7 +1975,9 @@ clock. -unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n) + +NI_MIO_PLL_RTSI_CLOCKn + Only available for newer m-series boards. The function returns a clock source which will cause the board's @@ -1899,13 +1990,16 @@ line specified in the function argument. -For all clock sources except NI_MIO_INTERNAL_CLOCK and NI_MIO_PLL_PXI10_CLOCK, +For all clock sources except NI_MIO_INTERNAL_CLOCK +and NI_MIO_PLL_PXI10_CLOCK, you should pass the period of the clock your are feeding to the board when -using INSN_CONFIG_SET_CLOCK_SRC. +using INSN_CONFIG_SET_CLOCK_SRC. -Finally, the configuration instructions INSN_CONFIG_SET_ROUTING and -INSN_CONFIG_GET_ROUTING can be used to select/query which internal signal +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 the following signal sources which can be routed to an RTSI line: @@ -1920,63 +2014,65 @@ the following signal sources which can be routed to an RTSI line: -NI_RTSI_OUTPUT_ADR_START1 +NI_RTSI_OUTPUT_ADR_START1 ADR_START1, an analog input start signal. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_ADR_START2 +NI_RTSI_OUTPUT_ADR_START2 ADR_START2, an analog input stop signal. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_SCLKG +NI_RTSI_OUTPUT_SCLKG SCLKG, a sample clock signal. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_DACUPDN +NI_RTSI_OUTPUT_DACUPDN DACUPDN, a dac update signal. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_DA_START1 +NI_RTSI_OUTPUT_DA_START1 DA_START1, an analog output start signal. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_G_SRC0 +NI_RTSI_OUTPUT_G_SRC0 G_SRC0, the source signal to general purpose counter 0. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_G_GATE0 +NI_RTSI_OUTPUT_G_GATE0 G_GATE0, the gate signal to general purpose counter 0. See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_RGOUT0 +NI_RTSI_OUTPUT_RGOUT0 RGOUT0, the output signal of general purpose counter 0. See the NI's DAQ-STC Technical Reference Manual for more information. -unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n) + +NI_RTSI_OUTPUT_RTSI_BRDn + RTSI_BRD0 though RTSI_BRD3 are four internal signals which can have various other signals routed to them in turn. Currently, comedi @@ -1985,7 +2081,7 @@ See the NI's DAQ-STC Technical Reference Manual for more information. -NI_RTSI_OUTPUT_RTSI_OSC +NI_RTSI_OUTPUT_RTSI_OSC The RTSI clock signal. On pre-m-series boards, this signal is always routed to RTSI line 7, and cannot be routed to lines 0 through 6. On @@ -1999,10 +2095,12 @@ 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 -to trigger from a PFI line). The CR_EDGE and CR_INVERT flags may +&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 +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 falling edge/low level triggering. @@ -2089,7 +2187,8 @@ void comediEnableMaster(comedi_t *dev){ An example to slave a m-series device from this master follows. A pre-m-series -device would need to use NI_MIO_RTSI_CLOCK for the clock source instead. In +device would need to use NI_MIO_RTSI_CLOCK for +the clock source instead. In your code, you may also wish to configure the master device to use the external clock source instead of using its internal clock directly (for best syncronization). -- 2.26.2