diff --git a/doc/other.sgml b/doc/other.sgml index d417fae..6fd5905 100644 --- a/doc/other.sgml +++ b/doc/other.sgml @@ -7,7 +7,7 @@ Acquisition and configuration functions -This Section gives an overview of all &comedi; functions with which +This Section gives an overview of all &comedi; functions with which application programmers can implement their data acquisition. (With acquisition we mean all possible kinds of interfacing with the cards: input, output, configuration, streaming, etc.) @@ -73,7 +73,7 @@ the function comedi_dio_config(device,subdevice,channel,unsigned int dir); The parameter dir should be -either COMEDI_INPUT or +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 @@ -93,7 +93,7 @@ bitfield. If a bit in write_mask is set, the corresponding bit in *bits will be written to the corresponding digital output line. -Each digital line is then read and placed into +Each digital line is then read and placed into *bits. The value of bits in *bits corresponding to digital output lines is undefined and device-specific. Channel @@ -125,15 +125,15 @@ the range of, typically, 8, 10, 12, or 16 bits. -The +The - int comedi_data_read(comedi_t * device, unsigned int subdevice, unsigned int channel, + 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, + 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 @@ -163,7 +163,7 @@ the device. -lsampl_t: this +lsampl_t: this data structure represents one single sample. On most architectures, it's nothing more than a 32 bits value. Internally, &comedi; does some conversion from raw sample data to @@ -184,7 +184,7 @@ 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, + 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) The number of samples, n, is @@ -195,7 +195,7 @@ 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, +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) All these read and write acquisition functions are implemented on top @@ -210,7 +210,7 @@ command.
-Instructions for multiple acquisitions +Instructions for multiple acquisitions The instruction is one of the most generic, @@ -254,14 +254,14 @@ struct comedi_insn_struct{ Because of the large flexibility of the instruction function, many types of instruction do not need to fill in all fields, or attach different meanings to the same field. But the current implementation -of &comedi; requires the +of &comedi; requires the data field to be at least one byte long. -The insn flag of the -instruction data structure +The insn flag of the +instruction data structure determines the type of acquisition executed in the corresponding instruction: @@ -274,10 +274,10 @@ 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 @@ -333,7 +333,7 @@ whole instruction (list) has finished.
- + @@ -365,7 +365,7 @@ channel, but will configure that channel. For example, the configuration of digital I/O channels is done as follows. The chanspec field in the -comedi_insn +comedi_insn data structure, contains the channel to be configured. And data[0] contains either COMEDI_INPUT or COMEDI_OUTPUT, depending on the desired @@ -388,7 +388,7 @@ the TRIG_OTHER event source. Instruction for internal triggering -This special instruction has +This special instruction has INSN_INTTRIG as the insn flag in its instruction data structure. @@ -399,7 +399,7 @@ or to stop an ongoing acquisition. The exact meaning of the triggering depends on the card and its particular driver. -The +The data[0] field of the INSN_INTTRIG instruction is reserved for future use, and should be set to 0. @@ -428,20 +428,20 @@ a possibly infinite sequence of acquisitions, accompanied with various callback functionalities -(DMA, interrupts, driver-specific callback functions), +(DMA, interrupts, driver-specific callback functions), -for any number of channels, +for any number of channels, with an arbitrary order of channels in each scan -(possibly even with repeated channels per scan), +(possibly even with repeated channels per scan), @@ -449,7 +449,7 @@ with an arbitrary order of channels in each scan and with various scan triggering sources, external (i.e., hardware pulses) as well as internal (i.e., pulses -generated on the DAQ card itself, or generated by a +generated on the DAQ card itself, or generated by a software trigger instruction). @@ -462,7 +462,7 @@ off-board timers and triggers. -A command specifies a particular data +A command specifies a particular data acquisition sequence, which consists of a number of scans, and each scan is comprised of a number of conversions, which @@ -474,7 +474,7 @@ intervals of 1 millisecond apart. The command function is complementary to the configuration instruction -function: each channel in the command's +function: each channel in the command's chanlist should first be configured by an appropriate instruction. @@ -510,7 +510,7 @@ of a specific device are, by means of the comedi_get_cmd_src_mask() function. - + @@ -521,14 +521,14 @@ The command data structure The command executes according to the information about the requested acquisition, which is stored in the -comedi_cmd +comedi_cmd data structure: typedef struct comedi_cmd_struct comedi_cmd; struct comedi_cmd_struct{ unsigned int subdev; // which subdevice to sample - unsigned int flags; // encode some configuration possibilities + unsigned int flags; // encode some configuration possibilities // of the command execution; e.g., // whether a callback routine is to be // called at the end of the command @@ -606,7 +606,7 @@ The final member of 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 +these bits are explained in a later section. @@ -624,9 +624,9 @@ that it offers lots of possibilities to let different hardware and software sources determine when acquisitions are started, performed, and stopped. More specifically, the command data structure -has five types of events: start the +has five types of events: start the acquisition, -start a scan, start a +start a scan, start a conversion, stop a scan, and stop the acquisition. Each event can be given its own source @@ -635,7 +635,7 @@ the acquisition. Each event can be given its own structure). And each event source can have a corresponding argument (the *_arg members of the comedi_cmd data -structure) whose meaning depends on the type of source trigger. +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 @@ -657,12 +657,12 @@ The available options are: TRIG_NOW: the -start_src -event occurs -start_arg +start_src +event occurs +start_arg nanoseconds after the -comedi_cmd -is called. Currently, only +comedi_cmd +is called. Currently, only start_arg=0 is supported. @@ -671,7 +671,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. @@ -681,7 +681,7 @@ 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. +occurs; e.g., a rising edge of a digital line. start_arg chooses the particular digital line. @@ -691,7 +691,7 @@ chooses the particular digital line. TRIG_INT: the start event occurs on a &comedi; internal signal, which -is typically caused by an +is typically caused by an INSN_INTTRIG instruction. @@ -706,12 +706,12 @@ The available options are: -TRIG_TIMER: -scan_begin +TRIG_TIMER: +scan_begin events occur periodically. The time between -scan_begin +scan_begin events is -convert_arg +convert_arg nanoseconds. @@ -730,24 +730,24 @@ 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. +occurs; e.g., a rising edge of a digital line. scan_begin_arg chooses the particular digital line. -The +The scan_begin_arg used here may not be supported exactly by the device, but it -will be adjusted to the nearest supported value by +will be adjusted to the nearest supported value by comedi_command_test(). -The timing between each sample in a +The timing between each sample in a scan is controlled by the convert_* fields: @@ -758,7 +758,7 @@ fields: TRIG_TIMER: the conversion events occur periodically. The time -between convert events is +between convert events is convert_arg nanoseconds. @@ -769,7 +769,7 @@ nanoseconds. TRIG_EXT: the conversion events occur when an external trigger signal -occurs, e.g., a rising edge of a digital line. +occurs, e.g., a rising edge of a digital line. convert_arg chooses the particular digital line. @@ -779,19 +779,19 @@ chooses the particular digital line. -TRIG_NOW: All conversion events in a +TRIG_NOW: All conversion events in a scan occur simultaneously. The end of each scan is almost always specified -using +using 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. +be strange. The end of an @@ -805,7 +805,7 @@ and stop_arg: -TRIG_COUNT: stop the acquisition after +TRIG_COUNT: stop the acquisition after stop_arg scans. @@ -863,7 +863,7 @@ The argument is reserved and should be set to 0. 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 +driver. The comedi_get_cmd_src_mask() function is useful for determining what trigger sources a subdevice supports. @@ -1123,7 +1123,7 @@ The actual acquisition is done with: The number of samples over which the comedi_sv_measure() averages is limited by the -implementation (currently the limit is 100 samples). +implementation (currently the limit is 100 samples). @@ -1201,7 +1201,7 @@ bits defined as follows: 10: accumulator is decremented, or output is cleared. - + 11: reserved. @@ -1245,7 +1245,7 @@ this yet).) -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1289,7 +1289,7 @@ Analog Output Waveform Generation this yet).) -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1321,7 +1321,7 @@ Extended Triggering -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1344,7 +1344,7 @@ application will use configuration instructions to configure an extended trigger, and a command, -specifying +specifying TRIG_OTHER as one of the trigger sources. @@ -1369,7 +1369,7 @@ only be allowed with a properly configured extended trigger. -Extended triggers must use +Extended triggers must use data[1] as flags. The upper 16 bits are reserved and used only for flags that are common to all extended triggers. The lower 16 bits may be defined by the @@ -1377,7 +1377,7 @@ particular type of extended trigger. -Various types of extended triggers must use +Various types of extended triggers must use data[1] to know which event the extended trigger will be assigned to in the command structure. The possible values are an OR'd mask of the following: @@ -1425,7 +1425,7 @@ implements this feature.) -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1502,7 +1502,7 @@ Bitfield Pattern Matching Extended Trigger -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1530,7 +1530,7 @@ data[3]: pattern. -The pattern matching trigger issues a trigger when all of a specifed +The pattern matching trigger issues a trigger when all of a specifed set of input lines match a specified pattern. If the device allows, the input lines should correspond to the input lines of a digital input subdevice, however, this will necessarily be device dependent. Each @@ -1564,7 +1564,7 @@ Counter configuration -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1611,9 +1611,9 @@ encoders, etc. Counters can be operated either in synchronous mode (using INSN_READ) -or asynchronous mode (using +or asynchronous mode (using commands), similar to analog -input subdevices. +input subdevices. The input signal for both modes is the accumulator. Commands on counter subdevices are almost always specified using scan_begin_src @@ -1647,7 +1647,7 @@ One source plus auxiliary counter configuration -The insn field of the +The insn field of the instruction data structure has not been assigned yet. @@ -1678,8 +1678,8 @@ transitions of the source signals. data[3], data[4]: determine the primary source for the counter, -similar to the -_src and the +similar to the +_src and the _arg fields used in the command data structure. @@ -1700,140 +1700,177 @@ should get latched? National instruments RTSI trigger bus -A number of NI boards support the RTSI bus. The RTSI Bus consists of an 48 pin -IDC connector on the PCI-6143 and special bus signal lines on PXI boards. -It's primary use is to synchronise multiple DAQ cards together. -There are 8 digital signal lines that are bi-directional. Each of these signal lines -can be configured as an input or output also the signal appearing on the output -can be configured to one of many internal board timing signals. We have added -basic RSTI support to enable a board to be set as a master and other boards to -be set as slaves. To simplify the API and code we have hard-coded the actual -set of internal timing signals that appear on the RTSI lines and just provide -the ability to set the I/O direction of the lines. It would be good to add a -new configure command to set up this routing to a different setup. The COMEDI -API is provided as a Digital I/O subdevice number 10 with an extra config -command to set up the master clock mode. This provides a number of configure -commands through the COMEDI config API which can be accessed using the -comedi_do_insn(), comedi_dio_config() and comedi_dio_get_config() functions. -The config API calls are: +A number of NI boards support the RTSI (Real Time System Integration) bus. +It's primary use is to synchronize multiple DAQ cards. +On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7. PCI +boards use cables to connect to their RTSI ports. +The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional. +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 +as a digital I/O subdevice (subdevice number 10). + + +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. + + +The subdevice also supports the +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 +header file: -API Command +Clock Source Description -INSN_CONFIG_SET_RTSI_CLOCK_MODE +NI_MIO_INTERNAL_CLOCK -This sets the boards main clock -mode. The argument defines the setting as one of: -COMEDI_RTSI_CLOCK_MODE_INTERNAL - Internal Clock. -COMEDI_RTSI_CLOCK_MODE_OUTPUT - Run from internal clock and output this -on the RTSI bus bit as RTSI_7. -COMEDI_RTSI_CLOCK_MODE_SLAVE - Run from the clock on the RTSI bus bit -RTSI_7. -COMEDI_RTSI_CLOCK_MODE_MASTER - Output the clock on the RTSI bus bit as -RTSI_7 and run from this external clock. +Use the board's internal oscillator. -INSN_CONFIG_DIO_OUTPUT +NI_MIO_RTSI_CLOCK -Configure the "channel" bit as -an output. Channel is one of NI_RTSI_[0-6] +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. -INSN_CONFIG_DIO_INPUT +NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK -Configure the "channel" bit as -an input. Channel is one of NI_RTSI_[0-6]. +Only available for newer m-series PXI boards. Synchronizes the board's +phased-locked loop (which runs at 80MHz) to the PXI star trigger +line. -INSN_CONFIG_DIO_QUERY +NI_MIO_PLL_PXI10_CLOCK -Find the direction of one of the -RTSI "channels". Channel is one of NI_RTSI_[0-6]. +Only available for newer m-series PXI boards. +Synchronizes the board's +phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane +clock. + + + +unsigned NI_MIO_PLL_RTSI_CLOCK(unsigned n) + +Only available for newer m-series boards. +The function returns a clock source which will cause the board's +phased-locked loop (which runs at 80MHz) to syncronize to the RTSI +line specified in the function argument. + -The RTSI bus pins and default output routing is: +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. + + +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: -Name -Standard Routing -Pin +Signal Source +Description -RTSI_0 - -NI_RTSI_STD_AI_START1 - -20 +NI_RTSI_OUTPUT_ADR_START1 + +ADR_START1, an analog input start signal. See the NI's +DAQ-STC Technical Reference Manual for more information. -RTSI_1 -NI_RTSI_STD_AI_START2 - -22 +NI_RTSI_OUTPUT_ADR_START2 + +ADR_START2, an analog input stop signal. See the NI's +DAQ-STC Technical Reference Manual for more information. -RTSI_2 -NI_RTSI_STD_AI_CONV - -24 +NI_RTSI_OUTPUT_SCLKG + +SCLKG, a sample clock signal. See the NI's +DAQ-STC Technical Reference Manual for more information. -RTSI_3 -NI_RTSI_STD_CT1_SRC - -26 +NI_RTSI_OUTPUT_DACUPDN + +DACUPDN, a dac update signal. See the NI's +DAQ-STC Technical Reference Manual for more information. -RTSI_4 -NI_RTSI_STD_CT1_GATE - -28 +NI_RTSI_OUTPUT_DA_START1 + +DA_START1, an analog output start signal. See the NI's +DAQ-STC Technical Reference Manual for more information. -RTSI_5 -NI_RTSI_STD_AO_SAMP_CLOCK - -30 +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. -RTSI_6 -NI_RTSI_STD_AO_START_TRIG - -32 +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. -RTSI_7 or RTSI_CLK +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. -Master Clock + + +unsigned NI_RTSI_OUTPUT_RTSI_BRD(unsigned n) + +RTSI_BRD0 though RTSI_BRD3 are four internal signals which can +have various other signals routed to them in turn. Currently, comedi +provides no way to configure the signals routed to the RTSI_BRD lines. +See the NI's DAQ-STC Technical Reference Manual for more information. -34 + + +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 +m-series boards, any RTSI line can be configured to output the clock +signal. @@ -1841,108 +1878,183 @@ The RTSI bus pins and default output routing is: -The RTSI bus pins are available to 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 to be a value between 10 and 16 corresponding -to RTSI_0 through RTSI_6. We have provided the defines NI_EXT_PFI_[0-9] and -NI_EXT_RTSI_[0-6] to define all the available external trigger sources. +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 +also be set on the trigger source argument to specify edge and +falling edge/low level triggering. + -A simple example to set up a device as a master is given below. +An example to set up a device as a master is given below. -An example to slave a device from this master follows: +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 +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).