From: Frank Mori Hess Date: Mon, 14 Jan 2008 22:15:07 +0000 (+0000) Subject: Split function references into subsections. Always build docs in X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=8e610500f3bb93a28739b3c633a03c6522208889;p=comedilib.git Split function references into subsections. Always build docs in $(srcdir). --- diff --git a/doc/Makefile.am b/doc/Makefile.am index cee18bb..6fed4b7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,21 +1,25 @@ -SGML = drivers.sgml funcref.sgml glossary.sgml \ +SGML = calibration_funcref.sgml command_funcref.sgml dio_funcref.sgml \ + deprecated_funcref.sgml error_funcref.sgml \ + drivers.sgml funcref.sgml glossary.sgml \ install.sgml intro.sgml other.sgml reference.sgml tutorial.sgml \ driverwriting.sgml comedilib.sgml -EXTRA_DIST = $(SGML) funcref mkref drivers.txt mkdr FAQ \ +EXTRA_DIST = $(SGML) calibration_funcref.txt command_funcref.txt dio_funcref.txt \ + deprecated_funcref.txt error_funcref.txt funcref mkref drivers.txt mkdr FAQ \ comedilib.pdf acq-seq.gif doc_html man -BUILT_SOURCES = funcref.sgml drivers.sgml +BUILT_SOURCES = calibration_funcref.sgml command_funcref.sgml dio_funcref.sgml \ + deprecated_funcref.sgml error_funcref.sgml funcref.sgml drivers.sgml if HAVE_DOCBOOK2PDF -pdf_DATA = comedilib.pdf +pdf_DATA = $(srcdir)/comedilib.pdf else pdf_DATA = endif if HAVE_DOCBOOK2HTML -all_html = doc_html +all_html = $(srcdir)/doc_html install_html = install_html uninstall_html = uninstall_html else @@ -25,7 +29,7 @@ uninstall_html = endif if HAVE_DOCBOOK2MAN -all_man = man +all_man = $(srcdir)/man install_man = install_man uninstall_man = uninstall_man else @@ -42,8 +46,8 @@ uninstall-local: $(uninstall_html) $(uninstall_man) #named this doc_html to avoid phony html target that is automatically generated #(at least by automake1.8) -doc_html: $(SGML) - { $(DOCBOOK2HTML) -o doc_html $(srcdir)/comedilib.sgml && touch doc_html; } || { $(RM) -r doc_html; exit 1; } +$(srcdir)/doc_html: $(SGML) + { $(DOCBOOK2HTML) -o $(srcdir)/doc_html $(srcdir)/comedilib.sgml && touch $(srcdir)/doc_html; } || { $(RM) -r $(srcdir)/doc_html; exit 1; } install_html: $(mkdir_p) $(DESTDIR)$(htmldir)/html @@ -55,29 +59,44 @@ uninstall_html: for each in $(srcdir)/doc_html/*.html $(srcdir)/*.gif ; do \ $(RM) $(DESTDIR)$(htmldir)/html/`basename $$each` ; done -man: $(SGML) - { $(DOCBOOK2MAN) -o man $(srcdir)/comedilib.sgml && touch man; } || { $(RM) -r man; exit 1; } +$(srcdir)/man: $(SGML) + { $(DOCBOOK2MAN) -o $(srcdir)/man $(srcdir)/comedilib.sgml && touch $(srcdir)/man; } || { $(RM) -r $(srcdir)/man; exit 1; } install_man: $(mkdir_p) -m 755 $(DESTDIR)$(mandir)/man3 chmod u+w $(DESTDIR)$(mandir)/man3 - for each in $(srcdir)/man/*.3 ; do $(INSTALL_DATA) $$each $(DESTDIR)$(mandir)/man3 ; done + for each in `find $(srcdir)/man/ -name '*.3'`; do $(INSTALL_DATA) $$each $(DESTDIR)$(mandir)/man3 ; done uninstall_man: - for each in $(srcdir)/man/*.3 ; do $(RM) $(DESTDIR)$(mandir)/man3/`basename $$each` ; done + for each in `find $(srcdir)/man/ -name '*.3'`; do $(RM) $(DESTDIR)$(mandir)/man3/`basename $$each` ; done -comedilib.pdf: $(SGML) - $(DOCBOOK2PDF) $(srcdir)/comedilib.sgml +$(srcdir)/comedilib.pdf: $(SGML) + $(DOCBOOK2PDF) -o $(srcdir) $(srcdir)/comedilib.sgml funcref.sgml: funcref mkref $(srcdir)/mkref $(srcdir)/funcref >$(srcdir)/funcref.sgml +calibration_funcref.sgml: calibration_funcref.txt mkref + $(srcdir)/mkref $(srcdir)/calibration_funcref.txt >$(srcdir)/calibration_funcref.sgml + +command_funcref.sgml: command_funcref.txt mkref + $(srcdir)/mkref $(srcdir)/command_funcref.txt >$(srcdir)/command_funcref.sgml + +dio_funcref.sgml: dio_funcref.txt mkref + $(srcdir)/mkref $(srcdir)/dio_funcref.txt >$(srcdir)/dio_funcref.sgml + +deprecated_funcref.sgml: deprecated_funcref.txt mkref + $(srcdir)/mkref $(srcdir)/deprecated_funcref.txt >$(srcdir)/deprecated_funcref.sgml + +error_funcref.sgml: error_funcref.txt mkref + $(srcdir)/mkref $(srcdir)/error_funcref.txt >$(srcdir)/error_funcref.sgml + drivers.sgml: drivers.txt mkdr $(srcdir)/mkdr $(srcdir)/drivers.txt >$(srcdir)/drivers.sgml maintainer-clean-local: - $(RM) -r doc_html man - $(RM) comedilib.pdf + $(RM) -r $(srcdir)/doc_html $(srcdir)/man + $(RM) $(srcdir)/comedilib.pdf locales = de @@ -88,5 +107,3 @@ messages: .phony mkdir -p locale/$$i/LC_MESSAGES; \ msgfmt $$i.po -o locale/$$i/LC_MESSAGES/comedilib.mo; \ done - - diff --git a/doc/calibration_funcref.txt b/doc/calibration_funcref.txt new file mode 100644 index 0000000..5bc32b2 --- /dev/null +++ b/doc/calibration_funcref.txt @@ -0,0 +1,188 @@ +Function: comedi_apply_calibration -- set hardware calibration from file +Retval: int +Param: comedi_t *device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: const char *file_path +Status: alpha +Description: + This function sets the calibration of the specified subdevice + so that it is in proper calibration when using the specified + channel, range and aref. It does so by performing writes + to the appropriate channels of the board's calibration + subdevice(s). Depending on the hardware, the + calibration settings used may or may not depend on the channel, + range, or aref. Furthermore, the calibrations appropriate + for different channel, range, and aref parameters + may not be able to be applied simultaneously. + For example, some boards cannot have their analog inputs calibrated + for more than one input range simultaneously. Applying a calibration for range 1 may + blow away a previously applied calibration for range 0. Or, applying + a calibration for analog input channel 0 may cause the same + calibration to be applied to all the + other analog input channels as well. + Your only guarantee is that calls to comedi_apply_calibration() + on different subdevices will not interfere with each other. + + In practice, their are some rules of thumb on how + calibrations behave. No calibrations depend on the aref. + A multiplexed analog input will have calibration settings that + do not depend on the channel, and applying a setting for one + channel will affect + all channels equally. Analog outputs, and analog inputs + with independent a/d converters for each input channel, will have + calibrations settings which do depend on the channel, and the + settings for each channel will be independent of the other + channels. + + If you wish to investigate exactly what comedi_apply_calibration() + is doing, you can perform reads on your board's calibration + subdevice to see which calibration channels it is changing. + You can also try to decipher the calibration file directly (it's a + text file). + + The file_path parameter can be used + to specify the file which contains the calibration information. + If file_path is NULL, then comedilib + will use a default + file location. The calibration information used by this function + is generated by the comedi_calibrate program (see its man page). + + The functions comedi_parse_calibration_file(), + comedi_apply_parsed_calibration(), and comedi_cleanup_calibration() + provide the same functionality at a slightly lower level. +Returns: + Zero on success, a negative number on failure. + +Function: comedi_apply_parsed_calibration -- set calibration from memory +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: const comedi_calibration_t *calibration +Status: alpha +Description: + This function is similar to comedi_apply_calibration() + except the calibration information is read from memory + instead of a file. This function can be more + efficient than comedi_apply_calibration() since the + calibration file does not need to be reparsed with + every call. The calibration is + obtained by a call to comedi_parse_calibration_file(). + +Returns: + Zero on success, a negative number on failure. + +Function: comedi_cleanup_calibration -- free calibration resources +Retval: void +Param: comedi_calibration_t *calibration +Status: alpha +Description: + This function frees the resources associated with a + comedi_calibration_t obtained from + comedi_parse_calibration_file(). calibration + can not be used again after calling this function. + +Function: comedi_get_default_calibration_path -- get default calibration file path +Retval: char* +Param: comedi_t *dev +Status: alpha +Description: + This function returns a string containing a default calibration file + path appropriate for dev. Memory for the + string is allocated by the function, and should be freed when + the string is no longer needed. +Returns: + A string which contains a file path useable by + comedi_parse_calibration_file(). On error, NULL is returned. + +Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice +Retval: int +Param: comedi_t *dev +Param: unsigned subdevice +Param: unsigned channel +Param: unsigned range +Param: enum comedi_conversion_direction direction +Param: comedi_polynomial_t *converter +Status: alpha +Description: + comedi_get_hardcal_converter() initializes converter so it can be + passed to either comedi_to_physical() or comedi_from_physical(). The result can be used to + convert data from the specified subdevice, + channel, and range. The direction + parameter specifies whether converter will be passed to comedi_to_physical() + or comedi_from_physical(). + + This function initializes converter as a simple linear function with no + calibration information, appropriate + for boards which do their gain/offset/nonlinearity corrections in hardware. If your board + needs calibration to be performed in software by the host computer, use comedi_get_softcal_converter() + instead. A subdevice will advertise the fact that it depends on a software calibration + with the SDF_SOFT_CALIBRATED subdevice flag. + + The result of this function will only depend on the channel + parameter if either comedi_range_is_chan_specific() or comedi_maxdata_is_chan_specific() + is true for the specified subdevice. +Returns: + Zero on success or -1 on failure. + +Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice +Retval: int +Param: unsigned subdevice +Param: unsigned channel +Param: unsigned range +Param: enum comedi_conversion_direction direction +Param: const comedi_calibration_t *parsed_calibration +Param: comedi_polynomial_t *converter +Status: alpha +Description: + comedi_get_softcal_converter() initializes converter so it can be + passed to either comedi_to_physical() or comedi_from_physical(). The converter + parameter can then be used to + convert data from the specified subdevice, + channel, and range. The direction + parameter specifies whether converter will be passed to comedi_to_physical() + or comedi_from_physical(). The parsed_calibration parameter contains the + software calibration values for your device, and may be obtained by calling comedi_parse_calibration_file() + on a calibration file generated by the comedi_soft_calibrate program. + + This function is only useful for boards that perform their calibrations in software on the host + computer. A subdevice will advertise the fact that it depends on a software calibration + with the SDF_SOFT_CALIBRATED subdevice flag. + + Whether or not the result of this function actually depends on the channel + parameter is + hardware dependent. For example, a multiplexed analog input will typically use the same + calibration for all input channels. Analog outputs will typically use different calibrations + for each output channel. + + Software calibrations are implemented as polynomials (up to third order). Since the inverse + of polynomials of order higher than one can't be represented exactly as another polynomial, you + may not be able to get converters for the "reverse" direction. For example, you may be + able to get a converter for an analog input in the COMEDI_TO_PHYSICAL direction, but not + in the COMEDI_FROM_PHYSICAL direction. +Returns: + Zero on success or -1 on failure. + +Function: comedi_parse_calibration_file -- load contents of calibration file +Retval: comedi_calibration_t* +Param: const char *file_path +Status: alpha +Description: + This function parses a calibration file (produced by the + comedi_calibrate or comedi_soft_calibrate programs) and returns a pointer + to a comedi_calibration_t which can be passed to the + comedi_apply_parsed_calibration() or comedi_get_softcal_converter() + functions. When you are + finished using the comedi_calibration_t, you should + call comedi_cleanup_calibration() to free the resources + associated with the comedi_calibration_t. + + The comedi_get_default_calibration_path() function may + be useful in conjunction with this function. +Returns: + A pointer to parsed calibration information on success, or NULL on failure. diff --git a/doc/comedilib.sgml b/doc/comedilib.sgml index 28fc36c..70b9258 100644 --- a/doc/comedilib.sgml +++ b/doc/comedilib.sgml @@ -7,6 +7,11 @@ + + + + + Comedi"> @@ -26,27 +31,21 @@ handbook David Schleef -
- ds@schleef.org -
+
ds@schleef.org
 Frank Hess -
- fmhess@users.sourceforge.net -
+
fmhess@users.sourceforge.net
 Herman Bruyninckx -
- Herman.Bruyninckx@mech.kuleuven.ac.be -
+
Herman.Bruyninckx@mech.kuleuven.ac.be
 @@ -54,7 +53,7 @@ handbook David Schleef - 2001-2003, 2005 + 2001-2003, 2005, 2008 Frank Mori Hess @@ -139,12 +138,36 @@ USA. - &funcref; - +
+ Functions +
+ Core Functions + &funcref; +
+
+ Asyncronous Commands + &command-funcref; +
+
+ Calibration + &calibration-funcref; +
+
+ Digital I/O + &dio-funcref; +
+
+ Error Reporting + &error-funcref; +
+
+ Deprecated + &deprecated-funcref; +
+
&glossary; - diff --git a/doc/command_funcref.txt b/doc/command_funcref.txt new file mode 100644 index 0000000..e152d12 --- /dev/null +++ b/doc/command_funcref.txt @@ -0,0 +1,232 @@ +Function: comedi_cancel -- stop streaming input/output in progress +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_cancel() can be used to stop a Comedi command + previously started by comedi_command() that is still in progress + on the subdevice indicated by the parameters device and subdevice. + This may not return the subdevice to a ready state, since there may + be samples in the buffer that need to be read. + + If sucessful, 0 is returned, otherwise -1. + +Function: comedi_command -- start streaming input/output +Retval: int +Param: comedi_t * device +Param: comedi_cmd * command +Description: + The function comedi_command() starts streaming input or output. The + command structure pointed to by the parameter command specifies the + acquisition. The command must be able to pass comedi_command_test() + with a return value of 0, or comedi_command() will fail. + For input subdevices, sample values are read using the + function read(). For output subdevices, sample values are written + using the function write(). + + If sucessful, 0 is returned, otherwise -1. + +Function: comedi_command_test -- test streaming input/output configuration +Retval: int +Param: comedi_t * device +Param: comedi_cmd * command +Description: + The function comedi_command_test() tests the command structure pointed + to by the parameter command and returns an integer describing the + testing stages that were sucessfully passed. In addition, if elements + of the command structure are invalid, they may be modified. Source + elements are modified to remove invalid source triggers. Argument + elements are adjusted or rounded to the nearest valid value. + + The meanings of the return value are as follows. + + 0 indicates a valid command. + + 1 indicates that one of the *_src + members of the command contained an + unsupported trigger. The bits corresponding to the unsupported + triggers are zeroed. + + 2 indicates that the particular combination + of *_src settings is not supported by the driver, or that + one of the *_src members has the bit corresponding to + multiple trigger sources set at the same time. + + 3 indicates that one of the *_arg members + of the command is set outside the range of allowable values. + For instance, an argument for a TRIG_TIMER source which + exceeds the board's maximum speed. The invalid *_arg + members will be adjusted to valid values. + + 4 indicates that one of the *_arg members + required adjustment. For instance, the argument of a + TRIG_TIMER source may have been rounded to the nearest + timing period supported by the board. + + 5 indicates that some aspect of the + command's chanlist is unsupported by the board. For example, + some board's require that all channels in the chanlist + use the same range. + +Function: comedi_get_buffer_contents -- streaming buffer status +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_get_buffer_contents() is used on a subdevice + that has a Comedi command in progress. The number of bytes that + are available in the streaming buffer is returned. If there is + an error, -1 is returned. + +Function: comedi_get_buffer_offset -- streaming buffer status +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_get_buffer_offset() is used on a subdevice + that has a Comedi command in progress. This function returns + the offset in bytes of the read pointer in the streaming buffer. + This offset is only useful for memory mapped buffers. + If there is an error, -1 is returned. + +Function: comedi_get_buffer_size -- streaming buffer size of subdevice +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_get_buffer_size() returns the size (in bytes) + of the streaming buffer for the subdevice specified by device and + subdevice. On error, -1 is returned. + +Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: comedi_cmd * command +Param: unsigned int chanlist_len +Param: unsigned int scan_period_ns +Description: + The command capabilities of the subdevice indicated by the parameters + device and subdevice are probed, and the results placed in the + command structure pointed to by the parameter command. The command + structure pointed to by the parameter command is modified to be a + valid command that can be used as a parameter to comedi_command() + (after the command has been assigned a valid chanlist array). + The command measures scans consisting of chanlist_len channels + at a scan rate that corresponds to the + period scan_period_ns. The rate is adjusted to a rate that the device + can handle. If sucessful, 0 is returned, otherwise -1. + +Function: comedi_get_cmd_src_mask -- streaming input/output capabilities +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: comedi_cmd * command +Description: + The command capabilities of the subdevice indicated by the parameters + device and subdevice are probed, and the results placed in the + command structure pointed to by the parameter command. The trigger + source elements of the command structure are set to the logical OR + value of possible trigger sources. Other elements in the structure + are undefined. If sucessful, 0 is returned, otherwise -1. + +Function: comedi_get_max_buffer_size -- maximum streaming buffer size +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_get_max_buffer_size() returns the maximum + allowable size (in bytes) of the streaming buffer for the subdevice + specified by device and subdevice. Changing the maximum buffer + size requires appropriate privileges. On error, -1 is returned. + +Function: comedi_get_read_subdevice -- find streaming input subdevice +Retval: int +Param: comedi_t * device +Description: + The function comedi_get_read_subdevice() returns the subdevice + that allows streaming input for device dev. If no subdevice + supports streaming input, -1 is returned and the Comedilib error + number is set to XXX "subdevice not found". + +Function: comedi_get_write_subdevice -- find streaming output subdevice +Retval: int +Param: comedi_t * device +Description: + The function comedi_get_write_subdevice() returns the subdevice + that allows streaming output for device dev. If no subdevice + supports streaming output, -1 is returned and the Comedilib error + number is set to XXX "subdevice not found". + +Function: comedi_mark_buffer_read -- streaming buffer control +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int num_bytes +Description: + The function comedi_mark_buffer_read() is used on a subdevice + that has a Comedi input command in progress. It should only be used + if you are using a mmap() (as opposed + to calling read() on the device file) to read data from Comedi's buffer, + since Comedi will automatically keep track of how many bytes have been + transferred via read() calls. This function is + used to indicate that the next num_bytes bytes in the buffer + are no longer needed and may be discarded. +Returns: + A return value ret greater than 0 indicates that the read offset in + the streaming buffer, as returned by comedi_get_buffer_offset, has been + incremented by ret bytes. If there is an error, -1 is returned. + +Function: comedi_mark_buffer_written -- streaming buffer control +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int num_bytes +Description: + The function comedi_mark_buffer_written() is used on a subdevice + that has a Comedi output command in progress. It should only be used + if you are using a mmap() (as opposed to calling write() on the device + file) to write data to Comedi's buffer, since Comedi + will automatically keep track of how many bytes have been + transferred via write() calls. This function is + used to indicate that the next num_bytes bytes in the buffer + are valid and may be sent to the device. + If there is an error, -1 is returned. + +Function: comedi_poll -- force updating of streaming buffer +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Description: + The function comedi_poll() is used on a subdevice that has a + Comedi command in progress in order to update the streaming buffer. + If supported by the driver, all available samples are copied to + the streaming buffer. These samples may be pending in DMA buffers + or device FIFOs. If sucessful, the number of additional bytes + available is returned. If there is an error, -1 is returned. + +Function: comedi_set_buffer_size -- streaming buffer size of subdevice +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int size +Description: + The function comedi_set_buffer_size() changes the size of the + streaming buffer for the subdevice specified by device and subdevice. + The parameter size must be a multiple of the virtual memory page + size. + + The virtual memory page size can be determined using + sysconf(_SC_PAGE_SIZE). + +Function: comedi_set_max_buffer_size -- streaming buffer size of subdevice +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int max_size +Description: + The function comedi_set_max_buffer_size() changes the maximum + allowable size (in bytes) of the streaming buffer for the subdevice + specified by device and subdevice. Changing the maximum buffer + size requires appropriate privileges. If sucessful, the old buffer + size is returned. On error, -1 is returned. diff --git a/doc/deprecated_funcref.txt b/doc/deprecated_funcref.txt new file mode 100644 index 0000000..6232018 --- /dev/null +++ b/doc/deprecated_funcref.txt @@ -0,0 +1,126 @@ +Function: comedi_dio_bitfield -- read/write multiple digital channels +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int write_mask +Param: unsigned int * bits +Status: deprecated +Description: + This function is deprecated. Use comedi_dio_bitfield2() instead. + +Function: comedi_from_phys -- convert physical units to sample +Retval: lsampl_t +Param: double data +Param: comedi_range * range +Param: lsampl_t maxdata +Status: deprecated +Description: + Converts data given in physical units (data) into sample values + (lsampl_t, between 0 and maxdata). 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 will be written to. + + Conversion is not affected by out-of-range behavior. Out-of-range + data parameters are silently truncated to the range 0 to maxdata. + +Function: comedi_get_timer -- timer information (deprecated) +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: double frequency +Param: unsigned int * trigvar +Param: double * actual_frequency +Status: deprecated +Description: + The function comedi_get_timer converts the frequency frequency + to a number suitable to send to the driver in a comedi_trig + structure. This function remains for compatibility with very + old versions of Comedi, that converted sampling rates to timer + values in the libary. This conversion is now done in the kernel, + and every device has the timer type nanosec_timer, indicating + that timer values are simply a time specified in nanoseconds. + +Function: comedi_sv_init -- slowly-varying inputs +Retval: int +Param: comedi_sv_t * sv +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Status: deprecated +Description: + The function comedi_sv_init() initializes the slow varying Comedi + structure sv to use the device device, the analog input subdevice + subdevice, and the channel channel. The slow varying Comedi + structure is used by comedi_sv_measure() to accurately measure + an analog input by averaging over many samples. The default + number of samples is 100. This function returns 0 on success, + -1 on error. + +Function: comedi_sv_measure -- slowly-varying inputs +Retval: int +Param: comedi_sv_t * sv +Param: double * data +Status: deprecated +Description: + The function comedi_sv_measure() uses the slowly varying Comedi + structure sv to measure a slowly varying signal. If sucessful, + the result (in physical units) is stored in the location pointed + to by data, and the number of samples is returned. On error, -1 + is returned. + +Function: comedi_sv_update -- slowly-varying inputs +Retval: int +Param: comedi_sv_t * sv +Status: deprecated +Description: + The function comedi_sv_update() updates internal parameters of + the slowly varying Comedi structure sv. + +Function: comedi_timed_1chan -- streaming input (deprecated) +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: double frequency +Param: unsigned int num_samples +Param: double * data +Status: deprecated +Description: + Not documented. + +Function: comedi_to_phys -- convert sample to physical units +Retval: double +Param: lsampl_t data +Param: comedi_range * range +Param: lsampl_t maxdata +Status: deprecated +Description: + Converts data given in sample values (lsampl_t, between 0 and + maxdata) into physical units (double). The parameter range + represents the conversion information to use, and the parameter + maxdata represents the maximum possible data value for the + channel that the data was read. + + Conversion of endpoint sample values, that is, sample values + equal to 0 or maxdata, is affected by the Comedilib out-of-range + behavior. If the out-of-range behavior is set to COMEDI_OOR_NAN, + endpoint values are converted to NAN. If the out-of-range + behavior is set to COMEDI_OOR_NUMBER, the endpoint values are + converted similarly to other values. + + If there is an error, NAN is returned. + +Function: comedi_trigger -- perform streaming input/output (deprecated) +Retval: int +Param: comedi_t * device +Param: comedi_trig * trig +Status: deprecated +Description: + The function comedi_trigger() instructs Comedi to + perform the command specified by the trigger structure trig. + The return value depends on + the particular trig being issued. If there is an + error, -1 is returned. diff --git a/doc/dio_funcref.txt b/doc/dio_funcref.txt new file mode 100644 index 0000000..239b07c --- /dev/null +++ b/doc/dio_funcref.txt @@ -0,0 +1,93 @@ +Function: comedi_dio_bitfield2 -- read/write multiple digital channels +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int write_mask +Param: unsigned int * bits +Param: unsigned int base_channel +Description: + The function comedi_dio_bitfield2() allows multiple channels to + be read or written together on a digital input, output, + or configurable digital I/O device. + The parameter write_mask + and the value pointed to by bits + are interpreted as bit fields, with the least significant bit + representing channel base_channel. + For each bit in write_mask that is + set to 1, the cooresponding bit in *bits + is written to the digital + output channel. After writing all the output channels, each + channel is read, and the result placed in the approprate bits in + *bits. The result of + reading an output channel is the last + value written to the output channel. + + All the channels may not be read or written at the exact same time. + For example, the driver may need to sequentially write to + several ports in order to set all the digital channels specified + by the write_mask. + +Function: comedi_dio_config -- change input/output properties of channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int direction +Description: + The function comedi_dio_config() configures individual channels + in a digital I/O subdevice to be either input or output, depending + on the value of parameter direction. Valid directions are + COMEDI_INPUT or COMEDI_OUTPUT. + + Depending on the capabilities of the hardware device, multiple + channels may be grouped together to determine direction. In this + case, a single call to comedi_dio_config() for any channel in the + group will affect the entire group. + + If sucessful, 1 is returned, otherwise -1. + +Function: comedi_dio_get_config -- query input/output properties of channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int * direction +Description: + The function comedi_dio_get_config() querys the configuration of + an individual channel + in a digital I/O subdevice (see comedi_dio_config()). + On success, the variable specified by the "direction" pointer will + be set to either COMEDI_INPUT or COMEDI_OUTPUT. + + If sucessful, 0 is returned, otherwise -1. + +Function: comedi_dio_read -- read single bit from digital channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int * bit +Description: + The function reads the channel channel belonging to the + subdevice subdevice of device device. The data value that is + read is stored in the location pointed to by bit. This function + is equivalent to comedi_data_read(device,subdevice,channel,0,0,bit). + This function does not require a digital subdevice or a subdevice + with a maximum data value of 1 to work properly. + + Return values and errors are the same as comedi_data_read(). + +Function: comedi_dio_write -- write single bit to digital channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int bit +Description: + The function writes the value bit to the channel channel belonging + to the subdevice subdevice of device device. This function + is equivalent to comedi_data_write(device,subdevice,channel,0,0,bit). + This function does not require a digital subdevice or a subdevice + with a maximum data value of 1 to work properly. + + Return values and errors are the same as comedi_data_write(). diff --git a/doc/error_funcref.txt b/doc/error_funcref.txt new file mode 100644 index 0000000..1a3fa4d --- /dev/null +++ b/doc/error_funcref.txt @@ -0,0 +1,102 @@ +Function: comedi_errno -- number of last Comedilib error +Retval: int +Param: void +Description: + 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_errno() returns an integer describing + the most recent comedilib error. This integer may be used + as the errnum parameter for comedi_strerror(). + + Note that comedi_errno() is deliberately different than the + variable errno. This is to overcome difficulties in making + errno thread-safe. + +Function: comedi_loglevel -- change Comedilib logging properties +Retval: int +Param: int loglevel +Description: + This function affects the output of debugging and error messages + from Comedilib. By increasing the loglevel, additional debugging + information will be printed. Error and debugging messages are + printed to the stream stderr. + + The default loglevel can be set by using the environment variable + COMEDI_LOGLEVEL. The default loglevel is 1. + + In order to conserve resources, some debugging information is + disabled by default when Comedilib is compiled. + + The meaning of the loglevels is as follows: + + COMEDI_LOGLEVEL=0 Comedilib prints nothing. + + COMEDI_LOGLEVEL=1 (default) Comedilib prints error messages when + there is a self-consistency error (i.e., an internal bug.) + + COMEDI_LOGLEVEL=2 Comedilib prints an error message when an invalid + parameter is passed. + + COMEDI_LOGLEVEL=3 Comedilib prints an error message whenever an + error is generated in the Comedilib library or in the C library, + when called by Comedilib. + + COMEDI_LOGLEVEL=4 Comedilib prints a lot of junk. +Returns: + This function returns the previous loglevel. + +Function: comedi_perror -- print a Comedilib error message +Retval: void +Param: const char * s +Description: + 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. + +Function: comedi_strerror -- return string describing Comedilib error code +Retval: char * +Param: int errnum +Description: + 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_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. diff --git a/doc/funcref b/doc/funcref index d77d15d..b4358fc 100644 --- a/doc/funcref +++ b/doc/funcref @@ -6,118 +6,150 @@ Description: Returns: If sucessful, comedi_close returns 0. On failure, -1 is returned. -Function: comedi_open -- open a Comedi device -Retval: comedi_t * -Param: const char * filename -Description: - Open a Comedi device specified by the file filename. -Returns: - If sucessful, comedi_open returns a pointer to a valid comedi_t - structure. This structure is transparent; the pointer should not - be dereferenced by the application. NULL is returned on failure. - -Function: comedi_loglevel -- change Comedilib logging properties +Function: comedi_data_read -- read single sample from channel Retval: int -Param: int loglevel +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: lsampl_t * data Description: - This function affects the output of debugging and error messages - from Comedilib. By increasing the loglevel, additional debugging - information will be printed. Error and debugging messages are - printed to the stream stderr. - - The default loglevel can be set by using the environment variable - COMEDI_LOGLEVEL. The default loglevel is 1. - - In order to conserve resources, some debugging information is - disabled by default when Comedilib is compiled. + Reads a single sample on the channel specified by the Comedi + device device, the subdevice subdevice, and the channel channel. + For the A/D conversion (if appropriate), + 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 meaning of the loglevels is as follows: + The function comedi_data_read() reads one data value from + the specified channel and places the data value in the + location pointed to by data. - COMEDI_LOGLEVEL=0 Comedilib prints nothing. + WARNING: comedi_data_read() does not do any pausing to + allow multiplexed analog inputs to settle before + performing an analog to digital conversion. If you are + switching between different channels and need to allow + your analog input to settle for an accurate reading, + use comedi_data_read_delayed(), or set the + input channel at an earlier time with + comedi_data_read_hint(). - COMEDI_LOGLEVEL=1 (default) Comedilib prints error messages when - there is a self-consistency error (i.e., an internal bug.) + On sucess, comedi_data_read() returns 1 (the number of samples + read). If there is an error, -1 is returned. - COMEDI_LOGLEVEL=2 Comedilib prints an error message when an invalid - parameter is passed. + 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 comedi_get_maxdata(). + Conversion of data values to physical units can be performed + by the function comedi_to_phys(). - COMEDI_LOGLEVEL=3 Comedilib prints an error message whenever an - error is generated in the Comedilib library or in the C library, - when called by Comedilib. +Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: lsampl_t * data +Param: unsigned int nanosec +Description: + Similar to comedi_data_read() except it will wait for the + specified number of nanoseconds between setting the input + channel and taking a sample. For analog inputs, most + boards have a single + analog to digital converter which is multiplexed to be + able to read multiple channels. If the input is not allowed + to settle after the multiplexer switches channels, the + reading will be inaccurate. This function is useful + for allowing a multiplexed analog input to settle + when switching channels. - COMEDI_LOGLEVEL=4 Comedilib prints a lot of junk. -Returns: - This function returns the previous loglevel. + Although the settling time is specified in nanoseconds, the + actual settling time will be rounded up to the nearest + microsecond. -Function: comedi_perror -- print a Comedilib error message -Retval: void -Param: const char * s +Function: comedi_data_read_hint -- tell driver which channel/range/aref you are going to read from next +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref Description: - 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. + Used to prepare an analog input for a subsequent call to + comedi_data_read(). It is not necessary to use this + function, but it can be useful for eliminating inaccuaracies + caused by insufficient settling times when switching the + channel + or gain on an analog input. This function sets an analog input + to the channel, range, and aref specified but does not + perform an actual analog to digital conversion. - 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. + Alternatively, one can simply use comedi_data_read_delayed(), + which sets up the + input, pauses to allow settling, then performs a conversion. -Function: comedi_strerror -- return string describing Comedilib error code -Retval: char * -Param: int errnum +Function: comedi_data_write -- write single sample to channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Param: unsigned int aref +Param: lsampl_t data Description: - 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(). + Writes a single sample on the channel that is specified by the + Comedi device device, the subdevice subdevice, and the channel + channel. If appropriate, the device is configured to use range + specification range and analog reference type aref. Analog + reference types that are not supported by the device are + silently ignored. - 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_data_write() writes the data value specified + by the parameter data to the specified channel. - 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. + On sucess, comedi_data_write() returns 1 (the number of samples + written). If there is an error, -1 is returned. -Function: comedi_errno -- number of last Comedilib error +Function: comedi_do_insn -- perform instruction Retval: int -Param: void +Param: comedi_t * device +Param: comedi_insn * instruction Description: - 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(). + The function comedi_do_insn() performs a single instruction. + If sucessful, comedi_do_insn() returns the number of samples + measured, which may be less than the number of requested + samples. Comedi limits the number of requested samples in + order to enforce fairness among processes. If there is an + error, -1 is returned. - 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. +Function: comedi_do_insnlist -- perform multiple instructions +Retval: int +Param: comedi_t * device +Param: comedi_insnlist * list +Description: + The function comedi_do_insnlist() performs multiple Comedi + instructions as part of one system call. In addition, Comedi + attempts to perform the instructions atomically, that is, on + standard Linux kernels, no process preemption should occur + during the instructions. However, the process may be preempted + before or after the group of instructions. - 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(). + This function can be used to avoid the overhead of multiple + system calls, or to ensure that multiple instructions occur + without significant delay between them. - Note that comedi_errno() is deliberately different than the - variable errno. This is to overcome difficulties in making - errno thread-safe. + Preemption may occur if any of the instructions or the data + arrays of any of the instructions exist in non-resident or + copy-on-write pages. +Returns: + The function comedi_do_insnlist() returns the number of + sucessfully completed instructions. Error information for + the unsucessful instruction is not available. If there is + an error before the first instruction can be executed, -1 + is returned. Function: comedi_fileno -- integer descriptor of Comedilib device Retval: int @@ -131,30 +163,66 @@ Description: pointer, the function returns -1 and sets the appropriate Comedilib error value. -Function: comedi_get_n_subdevices -- number of subdevices +Function: comedi_find_range -- search for range Retval: int Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int unit +Param: double min +Param: double max Description: - Returns the number of subdevices belonging to the Comedi - device referenced by the parameter device. + The function comedi_find_range() tries to + locate the optimal (smallest) range for the channel chan + belonging to a subdevice of the comedi device device, + that includes both min and max in units. + If a matching range is found, the index of the matching range is + returned. If no matching range is available, the function returns + -1. -Function: comedi_get_version_code -- Comedi version code +Function: comedi_find_subdevice_by_type -- search for subdevice type Retval: int Param: comedi_t * device +Param: int type +Param: unsigned int start_subdevice Description: - Returns the Comedi kernel module version code. A valid Comedi - device referenced by the parameter device is necessary to - communicate with the kernel module. On error, -1 is returned. + The function comedi_find_subdevice_by_type() tries to + locate a subdevice belonging to comedi device device, + having type type, starting with the subdevice + start_subdevice. If it finds a subdevice with the requested + type, it returns its index. If it does not locate the requested + subdevice, it returns -1 and sets the Comedilib error number to + XXX "subdevice not found". If there is an error, the function + returns -1 and sets the appropriate error. - The version code is encoded as a bitfield of three 8-bit - numbers. For example, 0x00073d is the version code for - version 0.7.61. +Function: comedi_from_physical -- convert physical units to sample +Retval: lsampl_t +Param: double data +Param: const comedi_polynomial_t *conversion_polynomial +Description: + Converts data given in physical units into Comedi's + integer sample values + (lsampl_t, between 0 and maxdata). The conversion_polynomial + parameter is obtained from either comedi_get_hardcal_converter() + or comedi_get_softcal_converter(). The result will be rounded + using the C library's current rounding direction. + No range checking of the input + data is performed. It is up to you to insure + your data is within the limits of the output range you are using. - This function is of limited usefulness. A typical - mis-application of this function is to use it to determine - if a certain feature is supported. If the application needs - to know of the existence of a particular feature, an existence - test function should be written and put in the Comedilib source. + This function is intended to supplant comedi_from_phys(), and was + introduced in order to support software calibrations. +Returns: + Comedi sample value corresponding to input physical value. + +Function: comedi_get_board_name -- Comedi device name +Retval: const char * +Param: comedi_t * device +Description: + 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. Function: comedi_get_driver_name -- Comedi driver name Retval: char * @@ -166,60 +234,59 @@ Description: valid until the device is closed. This function returns NULL if there is an error. -Function: comedi_get_board_name -- Comedi device name -Retval: char * +Function: comedi_get_maxdata -- maximum sample of channel +Retval: lsampl_t Param: comedi_t * device +Param: unsigned int subdevice +Param: unsigned int channel Description: - 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. + The function comedi_get_maxdata() returns the maximum + valid data value for channel channel of subdevice + subdevice belonging to the comedi device + device. +Returns: + The maximum valid sample value, or 0 on error. -Function: comedi_get_subdevice_type -- type of subdevice +Function: comedi_get_n_channels -- number of subdevice channels Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - The function comedi_get_subdevice_type() returns an - integer describing the type of subdevice that belongs to the comedi - device device and has the index subdevice. The - function returns -1 if there is an error. - - XXX Subdevice type table + The function comedi_get_n_channels() returns the number + of channels of the subdevice belonging to the comedi device device + and having index subdevice. This function returns -1 on error and + the Comedilib error value is set. -Function: comedi_find_subdevice_by_type -- search for subdevice type +Function: comedi_get_n_ranges -- number of ranges of channel Retval: int Param: comedi_t * device -Param: int type -Param: unsigned int start_subdevice +Param: unsigned int subdevice +Param: unsigned int channel Description: - The function comedi_find_subdevice_by_type() tries to - locate a subdevice belonging to comedi device device, - having type type, starting with the subdevice - start_subdevice. If it finds a subdevice with the requested - type, it returns its index. If it does not locate the requested - subdevice, it returns -1 and sets the Comedilib error number to - XXX "subdevice not found". If there is an error, the function - returns -1 and sets the appropriate error. + The function comedi_get_n_ranges() returns the number + of ranges of the channel chan belonging to the subdevice + of the comedi device device. This function returns -1 on error. -Function: comedi_get_read_subdevice -- find streaming input subdevice +Function: comedi_get_n_subdevices -- number of subdevices Retval: int Param: comedi_t * device Description: - The function comedi_get_read_subdevice() returns the subdevice - that allows streaming input for device dev. If no subdevice - supports streaming input, -1 is returned and the Comedilib error - number is set to XXX "subdevice not found". + Returns the number of subdevices belonging to the Comedi + device referenced by the parameter device. -Function: comedi_get_write_subdevice -- find streaming output subdevice -Retval: int +Function: comedi_get_range -- range information of channel +Retval: comedi_range * Param: comedi_t * device -Description: - The function comedi_get_write_subdevice() returns the subdevice - that allows streaming output for device dev. If no subdevice - supports streaming output, -1 is returned and the Comedilib error - number is set to XXX "subdevice not found". - +Param: unsigned int subdevice +Param: unsigned int channel +Param: unsigned int range +Description: + 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 device is closed. If there is an + error, NULL is returned. + Function: comedi_get_subdevice_flags -- properties of subdevice Retval: int Param: comedi_t * device @@ -362,169 +429,35 @@ Description: -Function: comedi_get_n_channels -- number of subdevice channels -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_get_n_channels() returns the number - of channels of the subdevice belonging to the comedi device device - and having index subdevice. This function returns -1 on error and - the Comedilib error value is set. - -Function: comedi_range_is_chan_specific -- range information depends on channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - If each channel of the specified subdevice has different range - information, this function returns 1. Otherwise, this function - returns 0. On error, this function returns -1. - -Function: comedi_maxdata_is_chan_specific -- maximum sample depends on channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - If each channel of the specified subdevice has different maximum - sample values, this function returns 1. Otherwise, this function - returns 0. On error, this function returns -1. - -Function: comedi_get_maxdata -- maximum sample of channel -Retval: lsampl_t -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Description: - The function comedi_get_maxdata() returns the maximum - valid data value for channel channel of subdevice - subdevice belonging to the comedi device - device. -Returns: - The maximum valid sample value, or 0 on error. - -Function: comedi_get_n_ranges -- number of ranges of channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Description: - The function comedi_get_n_ranges() returns the number - of ranges of the channel chan belonging to the subdevice - of the comedi device device. This function returns -1 on error. - -Function: comedi_get_range -- range information of channel -Retval: comedi_range * -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Description: - 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 device is closed. If there is an - error, NULL is returned. - -Function: comedi_find_range -- search for range -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int unit -Param: double min -Param: double max -Description: - The function comedi_find_range() tries to - locate the optimal (smallest) range for the channel chan - belonging to a subdevice of the comedi device device, - that includes both min and max in units. - If a matching range is found, the index of the matching range is - returned. If no matching range is available, the function returns - -1. - -Function: comedi_get_buffer_size -- streaming buffer size of subdevice -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_get_buffer_size() returns the size (in bytes) - of the streaming buffer for the subdevice specified by device and - subdevice. On error, -1 is returned. - -Function: comedi_get_max_buffer_size -- maximum streaming buffer size -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_get_max_buffer_size() returns the maximum - allowable size (in bytes) of the streaming buffer for the subdevice - specified by device and subdevice. Changing the maximum buffer - size requires appropriate privileges. On error, -1 is returned. - -Function: comedi_set_buffer_size -- streaming buffer size of subdevice +Function: comedi_get_subdevice_type -- type of subdevice Retval: int Param: comedi_t * device Param: unsigned int subdevice -Param: unsigned int size Description: - The function comedi_set_buffer_size() changes the size of the - streaming buffer for the subdevice specified by device and subdevice. - The parameter size must be a multiple of the virtual memory page - size. - - The virtual memory page size can be determined using - sysconf(_SC_PAGE_SIZE). + The function comedi_get_subdevice_type() returns an + integer describing the type of subdevice that belongs to the comedi + device device and has the index subdevice. The + function returns -1 if there is an error. -Function: comedi_trigger -- perform streaming input/output (deprecated) -Retval: int -Param: comedi_t * device -Param: comedi_trig * trig -Status: deprecated -Description: - The function comedi_trigger() instructs Comedi to - perform the command specified by the trigger structure trig. - The return value depends on - the particular trig being issued. If there is an - error, -1 is returned. + XXX Subdevice type table -Function: comedi_do_insnlist -- perform multiple instructions +Function: comedi_get_version_code -- Comedi version code Retval: int Param: comedi_t * device -Param: comedi_insnlist * list Description: - The function comedi_do_insnlist() performs multiple Comedi - instructions as part of one system call. In addition, Comedi - attempts to perform the instructions atomically, that is, on - standard Linux kernels, no process preemption should occur - during the instructions. However, the process may be preempted - before or after the group of instructions. - - This function can be used to avoid the overhead of multiple - system calls, or to ensure that multiple instructions occur - without significant delay between them. + Returns the Comedi kernel module version code. A valid Comedi + device referenced by the parameter device is necessary to + communicate with the kernel module. On error, -1 is returned. - Preemption may occur if any of the instructions or the data - arrays of any of the instructions exist in non-resident or - copy-on-write pages. -Returns: - The function comedi_do_insnlist() returns the number of - sucessfully completed instructions. Error information for - the unsucessful instruction is not available. If there is - an error before the first instruction can be executed, -1 - is returned. + The version code is encoded as a bitfield of three 8-bit + numbers. For example, 0x00073d is the version code for + version 0.7.61. -Function: comedi_do_insn -- perform instruction -Retval: int -Param: comedi_t * device -Param: comedi_insn * instruction -Description: - The function comedi_do_insn() performs a single instruction. - If sucessful, comedi_do_insn() returns the number of samples - measured, which may be less than the number of requested - samples. Comedi limits the number of requested samples in - order to enforce fairness among processes. If there is an - error, -1 is returned. + This function is of limited usefulness. A typical + mis-application of this function is to use it to determine + if a certain feature is supported. If the application needs + to know of the existence of a particular feature, an existence + test function should be written and put in the Comedilib source. Function: comedi_lock -- subdevice reservation Retval: int @@ -541,34 +474,48 @@ Returns: If sucessful, 0 is returned. If there is an error, -1 is returned. -Function: comedi_unlock -- subdevice reservation +Function: comedi_maxdata_is_chan_specific -- maximum sample depends on channel Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - The function comedi_unlock() released a subdevice lock acquired - by comedi_lock(). If sucessful, 0 is returned, otherwise -1. + If each channel of the specified subdevice has different maximum + sample values, this function returns 1. Otherwise, this function + returns 0. On error, this function returns -1. -Function: comedi_to_phys -- convert sample to physical units -Retval: double -Param: lsampl_t data -Param: comedi_range * range -Param: lsampl_t maxdata +Function: comedi_open -- open a Comedi device +Retval: comedi_t * +Param: const char * filename +Description: + Open a Comedi device specified by the file filename. +Returns: + If sucessful, comedi_open returns a pointer to a valid comedi_t + structure. This structure is transparent; the pointer should not + be dereferenced by the application. NULL is returned on failure. + +Function: comedi_range_is_chan_specific -- range information depends on channel +Retval: int +Param: comedi_t * device +Param: unsigned int subdevice Description: - Converts data given in sample values (lsampl_t, between 0 and - maxdata) into physical units (double). The parameter range - represents the conversion information to use, and the parameter - maxdata represents the maximum possible data value for the - channel that the data was read. + If each channel of the specified subdevice has different range + information, this function returns 1. Otherwise, this function + returns 0. On error, this function returns -1. - Conversion of endpoint sample values, that is, sample values - equal to 0 or maxdata, is affected by the Comedilib out-of-range - behavior. If the out-of-range behavior is set to COMEDI_OOR_NAN, - endpoint values are converted to NAN. If the out-of-range - behavior is set to COMEDI_OOR_NUMBER, the endpoint values are - converted similarly to other values. +Function: comedi_set_global_oor_behavior -- out-of-range behavior +Retval: int +Param: enum comedi_oor_behavior behavior +Status: alpha +Description: + This function changes the Comedilib out-of-range behavior. + This currently affects the behavior of comedi_to_phys() when + converting endpoint sample values, that is, sample values + equal to 0 or maxdata. If the out-of-range behavior is set to + COMEDI_OOR_NAN, endpoint values are converted to NAN. If the + out-of-range behavior is set to COMEDI_OOR_NUMBER, the endpoint + values are converted similarly to other values. - If there is an error, NAN is returned. + The previous out-of-range behavior is returned. Function: comedi_to_physical -- convert sample to physical units Retval: double @@ -590,702 +537,11 @@ Description: Returns: Physical value corresponding to the input sample value. -Function: comedi_from_phys -- convert physical units to sample -Retval: lsampl_t -Param: double data -Param: comedi_range * range -Param: lsampl_t maxdata -Description: - Converts data given in physical units (data) into sample values - (lsampl_t, between 0 and maxdata). 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 will be written to. - - Conversion is not affected by out-of-range behavior. Out-of-range - data parameters are silently truncated to the range 0 to maxdata. - -Function: comedi_from_physical -- convert physical units to sample -Retval: lsampl_t -Param: double data -Param: const comedi_polynomial_t *conversion_polynomial -Description: - Converts data given in physical units into Comedi's - integer sample values - (lsampl_t, between 0 and maxdata). The conversion_polynomial - parameter is obtained from either comedi_get_hardcal_converter() - or comedi_get_softcal_converter(). The result will be rounded - using the C library's current rounding direction. - No range checking of the input - data is performed. It is up to you to insure - your data is within the limits of the output range you are using. - - This function is intended to supplant comedi_from_phys(), and was - introduced in order to support software calibrations. -Returns: - Comedi sample value corresponding to input physical value. - -Function: comedi_data_read -- read single sample from channel +Function: comedi_unlock -- subdevice reservation Retval: int Param: comedi_t * device Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: lsampl_t * data Description: - Reads a single sample on the channel specified by the Comedi - device device, the subdevice subdevice, and the channel channel. - For the A/D conversion (if appropriate), - 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 in the - location pointed to by data. - - WARNING: comedi_data_read() does not do any pausing to - allow multiplexed analog inputs to settle before - performing an analog to digital conversion. If you are - switching between different channels and need to allow - your analog input to settle for an accurate reading, - use comedi_data_read_delayed(), or set the - input channel at an earlier time with - comedi_data_read_hint(). - - On sucess, comedi_data_read() returns 1 (the number of samples - read). If there is an error, -1 is returned. + The function comedi_unlock() released a subdevice lock acquired + by comedi_lock(). If sucessful, 0 is returned, otherwise -1. - 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 comedi_get_maxdata(). - Conversion of data values to physical units can be performed - by the function comedi_to_phys(). - -Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: lsampl_t * data -Param: unsigned int nanosec -Description: - Similar to comedi_data_read() except it will wait for the - specified number of nanoseconds between setting the input - channel and taking a sample. For analog inputs, most - boards have a single - analog to digital converter which is multiplexed to be - able to read multiple channels. If the input is not allowed - to settle after the multiplexer switches channels, the - reading will be inaccurate. This function is useful - for allowing a multiplexed analog input to settle - when switching channels. - - Although the settling time is specified in nanoseconds, the - actual settling time will be rounded up to the nearest - microsecond. - -Function: comedi_data_read_hint -- tell driver which channel/range/aref you are going to read from next -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Description: - Used to prepare an analog input for a subsequent call to - comedi_data_read(). It is not necessary to use this - function, but it can be useful for eliminating inaccuaracies - caused by insufficient settling times when switching the - channel - or gain on an analog input. This function sets an analog input - to the channel, range, and aref specified but does not - perform an actual analog to digital conversion. - - Alternatively, one can simply use comedi_data_read_delayed(), - which sets up the - input, pauses to allow settling, then performs a conversion. - -Function: comedi_data_write -- write single sample to channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: lsampl_t data -Description: - Writes a single sample on the channel that is specified by the - Comedi device device, the subdevice subdevice, and the channel - channel. If appropriate, the device is configured to use range - specification range and analog reference type aref. Analog - reference types that are not supported by the device are - silently ignored. - - The function comedi_data_write() writes the data value specified - by the parameter data to the specified channel. - - On sucess, comedi_data_write() returns 1 (the number of samples - written). If there is an error, -1 is returned. - -Function: comedi_dio_config -- change input/output properties of channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int direction -Description: - The function comedi_dio_config() configures individual channels - in a digital I/O subdevice to be either input or output, depending - on the value of parameter direction. Valid directions are - COMEDI_INPUT or COMEDI_OUTPUT. - - Depending on the capabilities of the hardware device, multiple - channels may be grouped together to determine direction. In this - case, a single call to comedi_dio_config() for any channel in the - group will affect the entire group. - - If sucessful, 1 is returned, otherwise -1. - -Function: comedi_dio_get_config -- query input/output properties of channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int * direction -Description: - The function comedi_dio_get_config() querys the configuration of - an individual channel - in a digital I/O subdevice (see comedi_dio_config()). - On success, the variable specified by the "direction" pointer will - be set to either COMEDI_INPUT or COMEDI_OUTPUT. - - If sucessful, 0 is returned, otherwise -1. - - -Function: comedi_dio_read -- read single bit from digital channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int * bit -Description: - The function reads the channel channel belonging to the - subdevice subdevice of device device. The data value that is - read is stored in the location pointed to by bit. This function - is equivalent to comedi_data_read(device,subdevice,channel,0,0,bit). - This function does not require a digital subdevice or a subdevice - with a maximum data value of 1 to work properly. - - Return values and errors are the same as comedi_data_read(). - -Function: comedi_dio_write -- write single bit to digital channel -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int bit -Description: - The function writes the value bit to the channel channel belonging - to the subdevice subdevice of device device. This function - is equivalent to comedi_data_write(device,subdevice,channel,0,0,bit). - This function does not require a digital subdevice or a subdevice - with a maximum data value of 1 to work properly. - - Return values and errors are the same as comedi_data_write(). - -Function: comedi_dio_bitfield -- read/write multiple digital channels -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int write_mask -Param: unsigned int * bits -Status: deprecated -Description: - This function is deprecated. Use comedi_dio_bitfield2() instead. - -Function: comedi_dio_bitfield2 -- read/write multiple digital channels -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int write_mask -Param: unsigned int * bits -Param: unsigned int base_channel -Description: - The function comedi_dio_bitfield2() allows multiple channels to - be read or written together on a digital input, output, - or configurable digital I/O device. - The parameter write_mask - and the value pointed to by bits - are interpreted as bit fields, with the least significant bit - representing channel base_channel. - For each bit in write_mask that is - set to 1, the cooresponding bit in *bits - is written to the digital - output channel. After writing all the output channels, each - channel is read, and the result placed in the approprate bits in - *bits. The result of - reading an output channel is the last - value written to the output channel. - - All the channels may not be read or written at the exact same time. - For example, the driver may need to sequentially write to - several ports in order to set all the digital channels specified - by the write_mask. - -Function: comedi_sv_init -- slowly-varying inputs -Retval: int -Param: comedi_sv_t * sv -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Status: deprecated -Description: - The function comedi_sv_init() initializes the slow varying Comedi - structure sv to use the device device, the analog input subdevice - subdevice, and the channel channel. The slow varying Comedi - structure is used by comedi_sv_measure() to accurately measure - an analog input by averaging over many samples. The default - number of samples is 100. This function returns 0 on success, - -1 on error. - -Function: comedi_sv_update -- slowly-varying inputs -Retval: int -Param: comedi_sv_t * sv -Status: deprecated -Description: - The function comedi_sv_update() updates internal parameters of - the slowly varying Comedi structure sv. - -Function: comedi_sv_measure -- slowly-varying inputs -Retval: int -Param: comedi_sv_t * sv -Param: double * data -Status: deprecated -Description: - The function comedi_sv_measure() uses the slowly varying Comedi - structure sv to measure a slowly varying signal. If sucessful, - the result (in physical units) is stored in the location pointed - to by data, and the number of samples is returned. On error, -1 - is returned. - -Function: comedi_get_cmd_src_mask -- streaming input/output capabilities -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: comedi_cmd * command -Description: - The command capabilities of the subdevice indicated by the parameters - device and subdevice are probed, and the results placed in the - command structure pointed to by the parameter command. The trigger - source elements of the command structure are set to the logical OR - value of possible trigger sources. Other elements in the structure - are undefined. If sucessful, 0 is returned, otherwise -1. - -Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: comedi_cmd * command -Param: unsigned int chanlist_len -Param: unsigned int scan_period_ns -Description: - The command capabilities of the subdevice indicated by the parameters - device and subdevice are probed, and the results placed in the - command structure pointed to by the parameter command. The command - structure pointed to by the parameter command is modified to be a - valid command that can be used as a parameter to comedi_command() - (after the command has been assigned a valid chanlist array). - The command measures scans consisting of chanlist_len channels - at a scan rate that corresponds to the - period scan_period_ns. The rate is adjusted to a rate that the device - can handle. If sucessful, 0 is returned, otherwise -1. - -Function: comedi_cancel -- stop streaming input/output in progress -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_cancel() can be used to stop a Comedi command - previously started by comedi_command() that is still in progress - on the subdevice indicated by the parameters device and subdevice. - This may not return the subdevice to a ready state, since there may - be samples in the buffer that need to be read. - - If sucessful, 0 is returned, otherwise -1. - -Function: comedi_command -- start streaming input/output -Retval: int -Param: comedi_t * device -Param: comedi_cmd * command -Description: - The function comedi_command() starts streaming input or output. The - command structure pointed to by the parameter command specifies the - acquisition. The command must be able to pass comedi_command_test() - with a return value of 0, or comedi_command() will fail. - For input subdevices, sample values are read using the - function read(). For output subdevices, sample values are written - using the function write(). - - If sucessful, 0 is returned, otherwise -1. - -Function: comedi_command_test -- test streaming input/output configuration -Retval: int -Param: comedi_t * device -Param: comedi_cmd * command -Description: - The function comedi_command_test() tests the command structure pointed - to by the parameter command and returns an integer describing the - testing stages that were sucessfully passed. In addition, if elements - of the command structure are invalid, they may be modified. Source - elements are modified to remove invalid source triggers. Argument - elements are adjusted or rounded to the nearest valid value. - - The meanings of the return value are as follows. - - 0 indicates a valid command. - - 1 indicates that one of the *_src - members of the command contained an - unsupported trigger. The bits corresponding to the unsupported - triggers are zeroed. - - 2 indicates that the particular combination - of *_src settings is not supported by the driver, or that - one of the *_src members has the bit corresponding to - multiple trigger sources set at the same time. - - 3 indicates that one of the *_arg members - of the command is set outside the range of allowable values. - For instance, an argument for a TRIG_TIMER source which - exceeds the board's maximum speed. The invalid *_arg - members will be adjusted to valid values. - - 4 indicates that one of the *_arg members - required adjustment. For instance, the argument of a - TRIG_TIMER source may have been rounded to the nearest - timing period supported by the board. - - 5 indicates that some aspect of the - command's chanlist is unsupported by the board. For example, - some board's require that all channels in the chanlist - use the same range. - -Function: comedi_poll -- force updating of streaming buffer -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_poll() is used on a subdevice that has a - Comedi command in progress in order to update the streaming buffer. - If supported by the driver, all available samples are copied to - the streaming buffer. These samples may be pending in DMA buffers - or device FIFOs. If sucessful, the number of additional bytes - available is returned. If there is an error, -1 is returned. - -Function: comedi_set_max_buffer_size -- streaming buffer size of subdevice -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int max_size -Description: - The function comedi_set_max_buffer_size() changes the maximum - allowable size (in bytes) of the streaming buffer for the subdevice - specified by device and subdevice. Changing the maximum buffer - size requires appropriate privileges. If sucessful, the old buffer - size is returned. On error, -1 is returned. - -Function: comedi_get_buffer_contents -- streaming buffer status -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_get_buffer_contents() is used on a subdevice - that has a Comedi command in progress. The number of bytes that - are available in the streaming buffer is returned. If there is - an error, -1 is returned. - -Function: comedi_mark_buffer_read -- streaming buffer control -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int num_bytes -Description: - The function comedi_mark_buffer_read() is used on a subdevice - that has a Comedi input command in progress. It should only be used - if you are using a mmap() (as opposed - to calling read() on the device file) to read data from Comedi's buffer, - since Comedi will automatically keep track of how many bytes have been - transferred via read() calls. This function is - used to indicate that the next num_bytes bytes in the buffer - are no longer needed and may be discarded. -Returns: - A return value ret greater than 0 indicates that the read offset in - the streaming buffer, as returned by comedi_get_buffer_offset, has been - incremented by ret bytes. If there is an error, -1 is returned. - -Function: comedi_mark_buffer_written -- streaming buffer control -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int num_bytes -Description: - The function comedi_mark_buffer_written() is used on a subdevice - that has a Comedi output command in progress. It should only be used - if you are using a mmap() (as opposed to calling write() on the device - file) to write data to Comedi's buffer, since Comedi - will automatically keep track of how many bytes have been - transferred via write() calls. This function is - used to indicate that the next num_bytes bytes in the buffer - are valid and may be sent to the device. - If there is an error, -1 is returned. - -Function: comedi_get_buffer_offset -- streaming buffer status -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Description: - The function comedi_get_buffer_offset() is used on a subdevice - that has a Comedi command in progress. This function returns - the offset in bytes of the read pointer in the streaming buffer. - This offset is only useful for memory mapped buffers. - If there is an error, -1 is returned. - -Function: comedi_get_timer -- timer information (deprecated) -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: double frequency -Param: unsigned int * trigvar -Param: double * actual_frequency -Status: deprecated -Description: - The function comedi_get_timer converts the frequency frequency - to a number suitable to send to the driver in a comedi_trig - structure. This function remains for compatibility with very - old versions of Comedi, that converted sampling rates to timer - values in the libary. This conversion is now done in the kernel, - and every device has the timer type nanosec_timer, indicating - that timer values are simply a time specified in nanoseconds. - -Function: comedi_timed_1chan -- streaming input (deprecated) -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: double frequency -Param: unsigned int num_samples -Param: double * data -Status: deprecated -Description: - Not documented. - -Function: comedi_set_global_oor_behavior -- out-of-range behavior -Retval: int -Param: enum comedi_oor_behavior behavior -Status: alpha -Description: - This function changes the Comedilib out-of-range behavior. - This currently affects the behavior of comedi_to_phys() when - converting endpoint sample values, that is, sample values - equal to 0 or maxdata. If the out-of-range behavior is set to - COMEDI_OOR_NAN, endpoint values are converted to NAN. If the - out-of-range behavior is set to COMEDI_OOR_NUMBER, the endpoint - values are converted similarly to other values. - - The previous out-of-range behavior is returned. - -Function: comedi_apply_calibration -- set hardware calibration from file -Retval: int -Param: comedi_t *device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: const char *file_path -Status: alpha -Description: - This function sets the calibration of the specified subdevice - so that it is in proper calibration when using the specified - channel, range and aref. It does so by performing writes - to the appropriate channels of the board's calibration - subdevice(s). Depending on the hardware, the - calibration settings used may or may not depend on the channel, - range, or aref. Furthermore, the calibrations appropriate - for different channel, range, and aref parameters - may not be able to be applied simultaneously. - For example, some boards cannot have their analog inputs calibrated - for more than one input range simultaneously. Applying a calibration for range 1 may - blow away a previously applied calibration for range 0. Or, applying - a calibration for analog input channel 0 may cause the same - calibration to be applied to all the - other analog input channels as well. - Your only guarantee is that calls to comedi_apply_calibration() - on different subdevices will not interfere with each other. - - In practice, their are some rules of thumb on how - calibrations behave. No calibrations depend on the aref. - A multiplexed analog input will have calibration settings that - do not depend on the channel, and applying a setting for one - channel will affect - all channels equally. Analog outputs, and analog inputs - with independent a/d converters for each input channel, will have - calibrations settings which do depend on the channel, and the - settings for each channel will be independent of the other - channels. - - If you wish to investigate exactly what comedi_apply_calibration() - is doing, you can perform reads on your board's calibration - subdevice to see which calibration channels it is changing. - You can also try to decipher the calibration file directly (it's a - text file). - - The file_path parameter can be used - to specify the file which contains the calibration information. - If file_path is NULL, then comedilib - will use a default - file location. The calibration information used by this function - is generated by the comedi_calibrate program (see its man page). - - The functions comedi_parse_calibration_file(), - comedi_apply_parsed_calibration(), and comedi_cleanup_calibration() - provide the same functionality at a slightly lower level. -Returns: - Zero on success, a negative number on failure. - -Function: comedi_apply_parsed_calibration -- set calibration from memory -Retval: int -Param: comedi_t * device -Param: unsigned int subdevice -Param: unsigned int channel -Param: unsigned int range -Param: unsigned int aref -Param: const comedi_calibration_t *calibration -Status: alpha -Description: - This function is similar to comedi_apply_calibration() - except the calibration information is read from memory - instead of a file. This function can be more - efficient than comedi_apply_calibration() since the - calibration file does not need to be reparsed with - every call. The calibration is - obtained by a call to comedi_parse_calibration_file(). - -Returns: - Zero on success, a negative number on failure. - -Function: comedi_cleanup_calibration -- free calibration resources -Retval: void -Param: comedi_calibration_t *calibration -Status: alpha -Description: - This function frees the resources associated with a - comedi_calibration_t obtained from - comedi_parse_calibration_file(). calibration - can not be used again after calling this function. - -Function: comedi_get_default_calibration_path -- get default calibration file path -Retval: char* -Param: comedi_t *dev -Status: alpha -Description: - This function returns a string containing a default calibration file - path appropriate for dev. Memory for the - string is allocated by the function, and should be freed when - the string is no longer needed. -Returns: - A string which contains a file path useable by - comedi_parse_calibration_file(). On error, NULL is returned. - -Function: comedi_parse_calibration_file -- load contents of calibration file -Retval: comedi_calibration_t* -Param: const char *file_path -Status: alpha -Description: - This function parses a calibration file (produced by the - comedi_calibrate or comedi_soft_calibrate programs) and returns a pointer - to a comedi_calibration_t which can be passed to the - comedi_apply_parsed_calibration() or comedi_get_softcal_converter() - functions. When you are - finished using the comedi_calibration_t, you should - call comedi_cleanup_calibration() to free the resources - associated with the comedi_calibration_t. - - The comedi_get_default_calibration_path() function may - be useful in conjunction with this function. -Returns: - A pointer to parsed calibration information on success, or NULL on failure. - -Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice -Retval: int -Param: comedi_t *dev -Param: unsigned subdevice -Param: unsigned channel -Param: unsigned range -Param: enum comedi_conversion_direction direction -Param: comedi_polynomial_t *converter -Status: alpha -Description: - comedi_get_hardcal_converter() initializes converter so it can be - passed to either comedi_to_physical() or comedi_from_physical(). The result can be used to - convert data from the specified subdevice, - channel, and range. The direction - parameter specifies whether converter will be passed to comedi_to_physical() - or comedi_from_physical(). - - This function initializes converter as a simple linear function with no - calibration information, appropriate - for boards which do their gain/offset/nonlinearity corrections in hardware. If your board - needs calibration to be performed in software by the host computer, use comedi_get_softcal_converter() - instead. A subdevice will advertise the fact that it depends on a software calibration - with the SDF_SOFT_CALIBRATED subdevice flag. - - The result of this function will only depend on the channel - parameter if either comedi_range_is_chan_specific() or comedi_maxdata_is_chan_specific() - is true for the specified subdevice. -Returns: - Zero on success or -1 on failure. - -Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice -Retval: int -Param: unsigned subdevice -Param: unsigned channel -Param: unsigned range -Param: enum comedi_conversion_direction direction -Param: const comedi_calibration_t *parsed_calibration -Param: comedi_polynomial_t *converter -Status: alpha -Description: - comedi_get_softcal_converter() initializes converter so it can be - passed to either comedi_to_physical() or comedi_from_physical(). The converter - parameter can then be used to - convert data from the specified subdevice, - channel, and range. The direction - parameter specifies whether converter will be passed to comedi_to_physical() - or comedi_from_physical(). The parsed_calibration parameter contains the - software calibration values for your device, and may be obtained by calling comedi_parse_calibration_file() - on a calibration file generated by the comedi_soft_calibrate program. - - This function is only useful for boards that perform their calibrations in software on the host - computer. A subdevice will advertise the fact that it depends on a software calibration - with the SDF_SOFT_CALIBRATED subdevice flag. - - Whether or not the result of this function actually depends on the channel - parameter is - hardware dependent. For example, a multiplexed analog input will typically use the same - calibration for all input channels. Analog outputs will typically use different calibrations - for each output channel. - - Software calibrations are implemented as polynomials (up to third order). Since the inverse - of polynomials of order higher than one can't be represented exactly as another polynomial, you - may not be able to get converters for the "reverse" direction. For example, you may be - able to get a converter for an analog input in the COMEDI_TO_PHYSICAL direction, but not - in the COMEDI_FROM_PHYSICAL direction. -Returns: - Zero on success or -1 on failure. diff --git a/doc/mkref b/doc/mkref index 08f3216..39520aa 100755 --- a/doc/mkref +++ b/doc/mkref @@ -9,10 +9,6 @@ $refentry_end = ""; print " -
- - Comedi Function Reference - "; while($s = <>){ @@ -114,9 +110,6 @@ while($s = <>){ print $end; print $refentry_end; -print -"
-"; exit(0);