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.
+ 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 default loglevel can be set by using the environment variable
- COMEDI_LOGLEVEL. The default loglevel is 1.
+ 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.
- In order to conserve resources, some debugging information is
- disabled by default when Comedilib is compiled.
+ 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().
- The meaning of the loglevels is as follows:
+ On sucess, comedi_data_read() returns 1 (the number of samples
+ read). If there is an error, -1 is returned.
- COMEDI_LOGLEVEL=0 Comedilib prints nothing.
+ 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=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.
-
-Function: comedi_errno -- number of last Comedilib error
+Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time
Retval: int
-Param: void
+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:
- 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().
+ 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.
- 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.
+ Although the settling time is specified in nanoseconds, the
+ actual settling time will be rounded up to the nearest
+ microsecond.
- 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().
+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.
- Note that comedi_errno() is deliberately different than the
- variable errno. This is to overcome difficulties in making
- errno thread-safe.
+ 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_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.
+
+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.
+
+ 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.
+
+ 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,61 +163,22 @@ Description:
pointer, the function returns -1 and sets the appropriate
Comedilib error value.
-Function: comedi_get_n_subdevices -- number of subdevices
-Retval: int
-Param: comedi_t * device
-Description:
- Returns the number of subdevices belonging to the Comedi
- device referenced by the parameter device.
-
-Function: comedi_get_version_code -- Comedi version code
-Retval: int
-Param: comedi_t * device
-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 version code is encoded as a bitfield of three 8-bit
- numbers. For example, 0x00073d is the version code for
- version 0.7.61.
-
- 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_get_driver_name -- Comedi driver name
-Retval: char *
-Param: comedi_t * device
-Description:
- The function comedi_get_driver_name returns a pointer
- to a string containing the name of the driver being used by comedi
- for the comedi device represented by device. This pointer is
- 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 *
-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_subdevice_type -- type of subdevice
+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_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_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_find_subdevice_by_type -- search for subdevice type
Retval: int
@@ -202,23 +195,97 @@ Description:
XXX "subdevice not found". If there is an error, the function
returns -1 and sets the appropriate error.
-Function: comedi_get_read_subdevice -- find streaming input subdevice
-Retval: int
-Param: comedi_t * device
+Function: comedi_from_physical -- convert physical units to sample
+Retval: lsampl_t
+Param: double data
+Param: const comedi_polynomial_t *conversion_polynomial
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".
+ 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.
-Function: comedi_get_write_subdevice -- find streaming output subdevice
+ 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 *
+Param: comedi_t * device
+Description:
+ The function comedi_get_driver_name returns a pointer
+ to a string containing the name of the driver being used by comedi
+ for the comedi device represented by device. This pointer is
+ valid until the device is closed. This function returns NULL
+ if there is an error.
+
+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_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_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_n_subdevices -- number of subdevices
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".
+ Returns the number of subdevices belonging to the Comedi
+ device referenced by the parameter device.
+
+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_get_subdevice_flags -- properties of subdevice
Retval: int
@@ -362,169 +429,35 @@ Description:
-Function: comedi_get_n_channels -- number of subdevice channels
+Function: comedi_get_subdevice_type -- type of subdevice
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.
+ 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_range_is_chan_specific -- range information depends on channel
+ XXX Subdevice type table
+
+Function: comedi_get_version_code -- Comedi version code
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.
+ 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.
-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.
+ 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_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
-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_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.
-
-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.
-
- 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.
-
- 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_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:
- 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.
+ 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.
- 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_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.
- If there is an error, NAN is returned.
+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_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
-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.
-
- 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
+Function: comedi_unlock -- subdevice reservation
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.
+ The function comedi_unlock() released a subdevice lock acquired
+ by comedi_lock(). If sucessful, 0 is returned, otherwise -1.
- 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);