stv0g/comedilib
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Split function references into subsections. Always build docs in

Browse source 
$(srcdir).
This commit is contained in:
Frank Mori Hess 2008-01-14 22:15:07 +00:00
parent d1ff202fc4
commit 8e610500f3
9 changed files with 1098 additions and 1068 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
doc/Makefile.am
View file

@ -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

188
doc/calibration_funcref.txt Normal file
View file

@ -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 <parameter>file_path</parameter> 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 <parameter>calibration</parameter> 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(). <parameter>calibration</parameter>
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 <parameter>dev</parameter>. 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 <parameter>converter</parameter> 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 <parameter>subdevice</parameter>,
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
or comedi_from_physical().
This function initializes <parameter>converter</parameter> 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 <parameter>channel</parameter>
parameter if either comedi_range_is_chan_specific() or comedi_maxdata_is_chan_specific()
is true for the specified <parameter>subdevice</parameter>.
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 <parameter>converter</parameter> so it can be
passed to either comedi_to_physical() or comedi_from_physical(). The <parameter>converter</parameter>
parameter can then be used to
convert data from the specified <parameter>subdevice</parameter>,
<parameter>channel</parameter>, and <parameter>range</parameter>. The <parameter>direction</parameter>
parameter specifies whether <parameter>converter</parameter> will be passed to comedi_to_physical()
or comedi_from_physical(). The <parameter>parsed_calibration</parameter> 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 <parameter>channel</parameter>
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.

49
doc/comedilib.sgml
View file

@ -7,6 +7,11 @@
<!ENTITY drivers SYSTEM "drivers.sgml">
<!ENTITY reference SYSTEM "reference.sgml">
<!ENTITY funcref SYSTEM "funcref.sgml">
<!ENTITY calibration-funcref SYSTEM "calibration_funcref.sgml">
<!ENTITY command-funcref SYSTEM "command_funcref.sgml">
<!ENTITY dio-funcref SYSTEM "dio_funcref.sgml">
<!ENTITY deprecated-funcref SYSTEM "deprecated_funcref.sgml">
<!ENTITY error-funcref SYSTEM "error_funcref.sgml">
<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY comedi "<acronym>Comedi</acronym>">
<!ENTITY uuml "ue">
@ -26,27 +31,21 @@ handbook
<firstname>David</firstname>
<surname>Schleef</surname>
<affiliation>
<address>
ds@schleef.org
</address>
<address>ds@schleef.org</address>
</affiliation>
</author>
<author>
<firstname>Frank</firstname>
<surname>Hess</surname>
<affiliation>
<address>
fmhess@users.sourceforge.net
</address>
<address>fmhess@users.sourceforge.net</address>
</affiliation>
</author>
<author>
<firstname>Herman</firstname>
<surname>Bruyninckx</surname>
<affiliation>
<address>
Herman.Bruyninckx@mech.kuleuven.ac.be
</address>
<address>Herman.Bruyninckx@mech.kuleuven.ac.be</address>
</affiliation>
</author>
<copyright>
@ -54,7 +53,7 @@ handbook
<holder>David Schleef</holder>
</copyright>
<copyright>
<year>2001-2003, 2005</year>
<year>2001-2003, 2005, 2008</year>
<holder>Frank Mori Hess</holder>
</copyright>
<copyright>
@ -139,12 +138,36 @@ USA.
<!-- </section> -->
&funcref;
<section id="functionreference">
<title>Functions</title>
<section>
<title>Core Functions</title>
&funcref;
</section>
<section>
<title>Asyncronous Commands</title>
&command-funcref;
</section>
<section>
<title>Calibration</title>
&calibration-funcref;
</section>
<section>
<title>Digital I/O</title>
&dio-funcref;
</section>
<section>
<title>Error Reporting</title>
&error-funcref;
</section>
<section>
<title>Deprecated</title>
&deprecated-funcref;
</section>
</section>
</section>
&glossary;
</article>

232
doc/command_funcref.txt Normal file
View file

@ -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.

126
doc/deprecated_funcref.txt Normal file
View file

@ -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.

93
doc/dio_funcref.txt Normal file
View file

@ -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 <parameter>write_mask</parameter>
and the value pointed to by <parameter>bits</parameter>
are interpreted as bit fields, with the least significant bit
representing channel <parameter>base_channel</parameter>.
For each bit in <parameter>write_mask</parameter> that is
set to 1, the cooresponding bit in <parameter>*bits</parameter>
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
<parameter>*bits</parameter>. 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 <parameter>write_mask</parameter>.
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().

102
doc/error_funcref.txt Normal file
View file

@ -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.

1316
doc/funcref
View file

File diff suppressed because it is too large Load diff

7
doc/mkref
View file

@ -9,10 +9,6 @@ $refentry_end = "";
print
"<!--This file is autogenerated. Do not edit-->
<section id=\"functionreference\">
<title>
Comedi Function Reference
</title>
";
while($s = <>){
@ -114,9 +110,6 @@ while($s = <>){
print $end;
print $refentry_end;
print
"</section>
";
exit(0);