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 *device unsigned int subdevice unsigned int channel unsigned int *bit -int comedi_dio_write -comedi_t *device +int comedi_dio_write +comedi_t *device unsigned int subdevice unsigned int channel unsigned 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 *device unsigned int subdevice unsigned int channel unsigned 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 *device unsigned int subdevice unsigned int write_mask unsigned 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 *device unsigned int subdevice unsigned int channel unsigned int range unsigned 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 *device unsigned int subdevice unsigned int channel unsigned int range unsigned 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 *device unsigned int subdevice unsigned 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 *device unsigned int subdevice unsigned int channel unsigned int range unsigned int aref -lsampl_t *data +lsampl_t *data unsigned 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 *device unsigned int subdevice unsigned int channel unsigned int range unsigned int aref -lsampl_t *data +lsampl_t *data unsigned 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_cmd data 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 *device unsigned int subdevice unsigned 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 *sv double *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