diff --git a/doc/comedilib.sgml b/doc/comedilib.sgml index da0ebd9..7f54c29 100644 --- a/doc/comedilib.sgml +++ b/doc/comedilib.sgml @@ -473,9 +473,36 @@ output subdevice, bidirectional digital lines will be grouped into a digital I/O subdevice. Thus, there can be multiple digital subdevices on a particular board. +Individual digital lines can be read and written using the +functions + + Timed Input/Output -

Slowly-varying inputs @@ -529,398 +556,59 @@ perform a part-per-million calibration to a standard that is only accurate to part-per-thousand. - +

+Commands

-Comedilib reference -

-Reference of structures: +Many data acquisition devices have the capability to directly +control acquisition using either an on-board timer or an external +triggering input. Comedi commands are used to control this kind +of acquisition. The same structure (comedi_cmd) used to control +acquisition is used to query the capabilities of a device. - -typedef struct comedi_t_struct comedi_t; +Commands specify a particular data acquisition sequence, which +is comprised of a number of scans. Each scan is comprised of +a number of conversions, which usually corresponds to a single +A/D or D/A conversion. The start and end of the sequence, and +the start and end of each scan, and each conversion is called an +event. -typedef struct{ - double min; - double max; - unsigned int unit; -}comedi_range; - -typedef struct comedi_sv_struct{ - comedi_t *dev; - unsigned int subdevice; - unsigned int chan; - - /* range policy */ - int range; - int aref; - - /* number of measurements to average (for ai) */ - int n; - - lsampl_t maxdata; -}comedi_sv_t; - - -comedi_loglevel() - -

- -int comedi_loglevel(int loglevel); - -

- -This function affects the output of debugging and error messages -from comedlib. By increasing the loglevel, additional debugging -information will be printed. This function returns the previous -loglevel. Some debugging information will only be printed if -comedilib was compiled with this debugging information included. -The loglevel can also be affected by the environment -variable COMEDI_LOGLEVEL. The meaning of the loglevels is as -follows: - -COMEDILIB_LOGLEVEL=0 - -Comedilib prints nothing. - -COMEDILIB_LOGLEVEL=1 (default) - -Comedilib only prints error messages when there is a -self-consistency error. - -COMEDILIB_LOGLEVEL=2 - -Comedilib prints an error message whenever an invalid -parameter is passed to comedilib. - -COMEDILIB_LOGLEVEL=3 - -Comedilib prints an error message whenever an error is generated -in the comedilib library or is generated in the C library when -called by comedilib. - -COMEDILIB_LOGLEVEL=4 - -Comedilib prints a lot of debugging messages. - -

- -comedi_open - -

- -comedi_t *comedi_open(char *fn); - -Opens a comedi device specified by the filename fn. Returns NULL -on error. Returns a handle that is given as a parameter to other -comedilib functions. - -You are not supposed to have access to the structure comedi_t. - -void comedi_close(comedi_t *it); - -Closes a device previously opened by comedi_open(). - -void comedi_perror(const char *s); -char *comedi_strerror(int errnum); -int comedi_errno(void); - -When a comedilib function fails, it usually returns -1 or -NULL, depending on the return type. An internal library -variable stores an error number, which can be retrieved with -comedi_errno(). This error number can be -converted to a human-readable form by the functions -comedi_perror() and comedi_strerror(). - -These functions are intended to mimic the behavior of the -standard C library functions perror(), -strerror, and errno(). In particular, -comedilib functions sometimes return an error that is generated -inside the C library; the comedi error message in this case -is the same as the C library. - -The function comedi_perror() prints an error -message to stderr. The error message consists of the -argument string, a colon, a space, a description of the error -condition, and a new line. - -The function comedi_strerror() returns a pointer to a -character string -describing the comedilib error errnum. The persistence -of the returned pointer is undefined, and should not be trusted -after the next comedilib call. An unrecognized error number will -return a pointer to the string "undefined error", or similar. - -The function comedi_errno() -returns an integer describing the most recent comedilib error. This -integer may be used as the errnum parameter for -comedi_strerror(). - -

-comedi_fileno() - -

- -int comedi_fileno(comedi_t *it); - -The function comedi_fileno -returns the integer descriptor for the handle it. If -it is an invalid comedi_t pointer, the function -returns -1 and sets the appropriate comedilib error value. - - -

-comedi_get_n_subdevices() -

- -int comedi_get_n_subdevices(comedi_t *it); - -The function comedi_get_n_subdevices returns the -number of subdevices associated with the comedi descriptor -it, or -1 if there is an error. - -

-comedi_get_version_code() -

- -int comedi_get_version_code(comedi_t *it); - -The function comedi_get_version_code() returns the -version code of the currently running comedi module. The version -code is of the form 0x010203, which is the version code for -version 1.2.3. - -

-comedi_get_driver_name() -

- -char *comedi_get_driver_name(comedi_t *it); - -The function comedi_get_driver_name returns a pointer -to a string containing the name of the driver being used by comedi -for the comedi device represented by it. This pointer is -valid until the comedi descriptor it is closed. This -function returns NULL if there is an error. - -

-comedi_get_board_name() -

- -char *comedi_get_board_name(comedi_t *it); - -The function comedi_get_board_name returns a pointer -to a string containing the name of the device. This pointer is -valid until the comedi descriptor it is closed. This -function returns NULL if there is an error. - -

-comedi_get_subdevice_type() -

- -int comedi_get_subdevice_type(comedi_t *it,unsigned int subdevice); - -The function comedi_get_subdevice_type() returns an -integer describing the type of subdevice that belongs to the comedi -device it and has the index subdevice. The -function returns -1 is there is an error. - -Valid subdevice types are: +Each of these 5 types of events are caused by a triggering +source. The source types are: -COMEDI_SUBD_UNUSED -Subdevice has no functionality, i.e., a place-holder. -COMEDI_SUBD_AI Analog input -COMEDI_SUBD_AO Analog output -COMEDI_SUBD_DI Digital input -COMEDI_SUBD_DO Digital output -COMEDI_SUBD_DIO -Digital input/output. Channels are configurable as to whether they -are inputs or outputs. -COMEDI_SUBD_COUNTER Counter -COMEDI_SUBD_TIMER Timer -COMEDI_SUBD_MEMORY -Memory, e.g., EEPROM or dual-ported RAM -COMEDI_SUBD_CALIB -Calibration DACs -COMEDI_SUBD_PROC -Processor or DSP +TRIG_NONE don't ever cause event +TRIG_NOW cause event to occur immediately +TRIG_FOLLOW (see notes below) +TRIG_TIME cause event to occur at a particular time +TRIG_TIMER cause event to occur repeatedly at a specific rate +TRIG_COUNT cause event when count reaches specific value +TRIG_EXT external signal causes event +TRIG_INT internal signal causes event +Not all triggers are applicable to all events. Supported triggers +for specific events depends significantly on your particular +device. In addition, for every trigger type, there is a cooresponding +argument that specifies the rate, the count, which external signal, +etc. -

-comedi_find_subdevice_by_type() -

+TRIG_FOLLOW is a special type of trigger for scan_begin events that +triggers on the next lower level trigger, in this case, the trigger +for convert events. It may or may not be supported. Later, it may +also be used for start events if you want to chain multiple commands. -int comedi_find_subdevice_by_type(comedi_t *it,int type,unsigned int start_subdevice) - -The function comedi_find_subdevice_by_type tries to -locate a subdevice belonging to comedi device it, -having type type, starting with the subdevice -start_subdevice. If it finds the requested subdevice, -it returns its index. If it does not locate the requested -subdevice, it returns -1 and sets the comedi error number to -"subdevice not found". If there is an error, the function -returns -1 and sets the appropriate error. - -For subdevice types, see the manual page for the function -comedi_get_subdevice_type(). - -

-comedi_get_n_channels() -

+In particular, scan_end events will almost always be triggered on +TRIG_COUNT, with the argument being the number of channels in the +scan. (Actually, samples in the scan, since on most boards you can +measure a single channel multiple times in a scan.) Also, until +otherwise supported, start events can only be TRIG_NOW. -int comedi_get_n_channels(comedi_t *it,unsigned int subdevice); -The function comedi_get_n_channels() returns the number -of channels of the subdevice belonging to the comedi device it -and having index subdevice. This function returns -1 on error. - -

-comedi_get_maxdata() -

- -lsampl_t comedi_get_maxdata(comedi_t *it,unsigned int subdevice,unsigned int chan); - -The function comedi_get_maxdata() returns the maximum -valid data value for channel chan of subdevice -subdevice belonging to the comedi device it -This function returns 0 on error. - -

-comedi_get_rangetype() -

- -int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int chan); - -The function comedi_get_rangetype() returns an integer -that represents the number of range specifications available for a -particular channel, as well as a conversion table to convert sample -values to/from physical units. The macro -RANGE_LENGTH(rangetype) -can be used to determine the number of range specifications for a given -range type. - -

-comedi_get_range() -

- -comedi_range * comedi_get_range(comedi_t *it,unsigned int subdevice,unsigned int chan,unsigned int range); - -The function comedi_get_range returns a pointer to a -comedi_range structure that contains information that can be used to -convert sample values to or from physical units. The pointer is valid -until the comedi device it is closed. If there is an -error, NULL is returned. - -

-comedi_trigger() -

- -int comedi_trigger(comedi_t *it,comedi_trig *trig); - -The function comedi_trigger() instructs comedi to -perform the command specified by the trigger structure -trig. Results depend on the particular command -being issued. If there is an error, -1 is returned. - -Complete information about comedi commands is given in the -manual page comedi(8). - -double comedi_to_phys(lsampl_t data,comedi_range *rng,lsampl_t maxdata); -lsampl_t comedi_from_phys(double data,comedi_range *rng,lsampl_t maxdata); - -The functions comedi_to_phys() and -comedi_from_phys() convert sample values to/from physical -units. The parameter rng represents the conversion -information to use, and the parameter maxdata represents -the maximum possible data value for the channel that the data was read/ -will be written to.

-comedi_data_read() -

- -int comedi_data_read(comedi_t *it,unsigned int subd,unsigned int chan, - unsigned int range,unsigned int aref,lsampl_t *data); -int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan, - unsigned int range,unsigned int aref,lsampl_t data); - -These functions read or write a single sample on the channel that -is specified by the comedi device it, the -subdevice subd, and the channel chan. -For the operation, -the device is configured to use range specification -range and (if appropriate) analog reference type -aref. Analog reference types that are not supported -by the device are silently ignored. - -The function comedi_data_read() reads one data value from -the specified channel and places the -data value that is read in the location pointed to by -data. - -The function comedi_data_write() writes the data value -specified by the argument data to -the specified channel. - -On sucess, these functions return 0. If there is an error, -1 is -returned. - -Valid analog reference numbers are: - - -AREF_GROUND Reference to analog ground -AREF_COMMON Reference to analog common -AREF_DIFF Differential reference -AREF_OTHER Board-specific meaning - - -Valid data values used by these functions is an unsigned integer -less than or equal to maxdata, which is channel-dependent. -Conversion of these data values to physical units can be performed -by comedi_to_phys() and comedi_from_phys(). - - -

-comedi_sv_init() -

- - -int comedi_sv_init(comedi_sv_t *it,comedi_t *dev,unsigned int subd,unsigned int chan); -int comedi_sv_update(comedi_sv_t *it); -int comedi_sv_measure(comedi_sv_t *it,double *data); - - -The special functions comedi_sv_*() are designed to -make it easy to accurately measure slowly varying analog inputs. -A slowly -varying input is one that is effectively constant over the course -of approximately 100 A/D conversions. However, since these -conversions can sometimes be pre-empted by scheduling, for most -purposes, a slowly varying signal should be effectively constant -for greater than 20 ms (the default Linux timeslice). - -By averaging many A/D conversions of a relatively constant -signal, it is possible to get a better measurement of the signal -than a single A/D conversion. In general, the uncertainty of the -measurement decreases as the square root of the number of samples. -This is limited by the rate that which the signal varies, and -ultimately by the spurious free dynamic range of the A/D converter. - - -

-comedi_get_timer() -

- - -int comedi_get_timer(comedi_t *it,unsigned int subdev,double freq,unsigned int *trigvar, - double *actual_freq); - - - -

- diff --git a/doc/comedilib_reference.sgml b/doc/comedilib_reference.sgml index 7298334..f936baf 100644 --- a/doc/comedilib_reference.sgml +++ b/doc/comedilib_reference.sgml @@ -49,7 +49,7 @@ device. A valid @@ -99,9 +99,11 @@ struct comedi_trig_struct{ The +This structure is defined as part of the Comedi kernel interface.

comedi_sv_t @@ -131,6 +133,41 @@ slowly varying inputs. See the relevant section for more details. +

+comedi_cmd +

+ +undocumented + +

+Related functions are described in section XXX. + +

+This structure is defined as part of the Comedi kernel interface. + +

+comedi_insn +

+ +undocumented + +

+Related functions are described in section XXX. + +

+This structure is defined as part of the Comedi kernel interface. + + +

+comedi_range +

+ +undocumented + + Functions

@@ -539,7 +576,7 @@ error, NULL is returned. Source: /lib/get.c

-comedi_get_rangetype() +comedi_get_rangetype() int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int @@ -555,6 +592,9 @@ values to/from physical units. can be used to determine the number of range specifications for a given range type. +

+This function is deprecated and should not be used in new code. + Source: /lib/get.c

@@ -851,28 +891,108 @@ Lifetime: removal at 1.0. Source: /lib/comedi.c +

+comedi_get_subdevice_flags() +

+ +This function returns a bitfield describing the capabilities of the +specified subdevice. If there is an error, -1 is returned. +

The bits are: - - - - + +SDF_BUSY subdevice is running a command +SDF_BUSY_OWNER subdevice is running a command started by +the file descriptor used by SDF_LOCKED subdevice is locked +SDF_LOCKED_OWNER subdevice is locked by the file descriptor used +by SDF_MAXDATA maximum data values are channel dependent +SDF_FLAGS channel flags are channel dependent +SDF_RANGETYPE range types are channel dependent +SDF_MODE0 deprecated +SDF_MODE1 deprecated +SDF_MODE2 deprecated +SDF_MODE3 deprecated +SDF_MODE4 deprecated +SDF_CMD subdevice supports commands +SDF_READABLE subdevice can be read from +SDF_WRITEABLE subdevice can be written to +SDF_RT deprecated +SDF_GROUND subdevice is capable of ground analog reference +SDF_COMMON subdevice is capable of common analog reference +SDF_DIFF subdevice is capable of differential analog reference +SDF_OTHER subdevice is capable of other analog reference +SDF_DITHER subdevice recognizes dither flag +SDF_DEGLITCH subdevice recognizes deglitch flag +SDF_MMAP deprecated +SDF_RUNNING subdevice is acquiring data (i.e., command has not +completed) +SDF_LSAMPL subdevice uses samples of type lsampl_t (otherwise +sampl_t) +SDF_PACKED subdevice uses bitfield samples (otherwise it uses +one sample per channel) +

-comedi_get_timer() -

- - -int comedi_get_timer(comedi_t *it,unsigned int subdev,double freq,unsigned int *trigvar, - double *actual_freq); - +The bit definitions are part of the Comedi kernel interface.

+comedi_range_is_chan_specific() +

+ + +If each channel of the specified subdevice has a different range +specification, this function returns 1. Otherwise, this function +returns 0. On error, this function returns -1. + + +

+Undocumented functions +

+ + + +comedi_maxdata_is_chan_specific() +comedi_get_buffer_size() +comedi_get_max_buffer_size() +comedi_set_buffer_size() +comedi_set_max_buffer_size() +comedi_do_insnlist() +comedi_do_insn() +comedi_lock() +comedi_unlock() +comedi_get_cmd_src_mask() +comedi_get_cmd_generic_timed() +comedi_cancel() +comedi_command() +comedi_command_test() +comedi_poll() +comedi_get_buffer_contents() +comedi_mark_buffer_read() +comedi_get_buffer_offset() +comedi_set_global_oor_behavior() + + + + + + + + + +