doc/calibration_funcref.txt: Some DocBook mark-up changes.

This commit is contained in:
Ian Abbott 2012-05-08 18:08:56 +01:00
parent 09106917de
commit c1cd802546

View file

@ -1,22 +1,28 @@
Calibration
Function: comedi_apply_calibration -- set hardware calibration from file
Retval: int
Param: comedi_t *device
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
Param: const char * file_path
Status: alpha
Description:
This function sets the hardware calibration for the specified subdevice
so that it is in proper calibration when using the specified
channel, range and aref. It does so by performing writes
The function <function>comedi_apply_calibration</function> sets the
hardware calibration for the subdevice specified by
<parameter class="function">device</parameter> and
<parameter class="function">subdevice</parameter>
so that it is in proper calibration when using the channel specified by
<parameter class="function">channel</parameter>,
range index specified by <parameter class="function">range</parameter> and
analog reference specified by <parameter class="function">aref</parameter>.
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
range, or analog reference. Furthermore, the calibrations appropriate
for different channel, range, and analog reference 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
@ -24,40 +30,46 @@ Description:
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()
Your only guarantee is that calls to
<function>comedi_apply_calibration</function>
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.
calibrations behave. No calibrations depend on the analog reference.
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
calibration 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()
If you wish to investigate exactly what
<function>comedi_apply_calibration</function>
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
The <parameter class="function">file_path</parameter> parameter can be used
to specify the file which contains the calibration information.
If <parameter>file_path</parameter> is NULL, then comedilib
If <parameter class="function">file_path</parameter> is
<constant>NULL</constant>, 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).
is generated by the <command>comedi_calibrate</command> program (see its man page).
The functions
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>,
<link linkend="func-ref-comedi-apply-parsed-calibration"><function>comedi_apply_parsed_calibration</function></link>,
and <link linkend="func-ref-comedi-cleanup-calibration"><function>comedi_cleanup_calibration_file</function></link>
<function><link
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>,
<function><link
linkend="func-ref-comedi-apply-parsed-calibration">comedi_apply_parsed_calibration</link></function>,
and <function><link
linkend="func-ref-comedi-cleanup-calibration">comedi_cleanup_calibration_file</link></function>
provide the same functionality at a slightly lower level.
Returns:
Zero on success, a negative number on failure.
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
Function: comedi_apply_parsed_calibration -- set calibration from memory
Retval: int
@ -66,81 +78,99 @@ Param: unsigned int subdevice
Param: unsigned int channel
Param: unsigned int range
Param: unsigned int aref
Param: const comedi_calibration_t *calibration
Param: const comedi_calibration_t * calibration
Status: alpha
Description:
This function is similar to
<link linkend="func-ref-comedi-apply-calibration"><function>comedi_apply_calibration</function></link>,
<function><link
linkend="func-ref-comedi-apply-calibration">comedi_apply_calibration</link></function>,
except the calibration information is read from memory
instead of a file. This function can be more
efficient than comedi_apply_calibration() since the
efficient than <function>comedi_apply_calibration</function> since the
calibration file does not need to be reparsed with
every call. The <parameter>calibration</parameter> is
every call. The value of parameter <parameter class="function">calibration</parameter> is
obtained by a call to
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
<function><link
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
Returns:
Zero on success, a negative number on failure.
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
Function: comedi_cleanup_calibration -- free calibration resources
Retval: void
Param: comedi_calibration_t *calibration
Param: comedi_calibration_t * calibration
Status: alpha
Description:
This function frees the resources associated with a
comedi_calibration_t obtained from
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
*<parameter>calibration</parameter>
<type>comedi_calibration_t</type> obtained from
<function><link
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
The <type>comedi_calibration_t</type> pointed to by
<parameter class="function">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
Retval: char *
Param: comedi_t * device
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
This function returns a pointer to a string containing a default calibration file
path appropriate for the Comedi device specified by
<parameter class="function">device</parameter>. Memory for the
string is allocated by the function, and should be freed with the C library
function <function>free</function> when
the string is no longer needed.
Returns:
A string which contains a file path useable by
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>.
On error, NULL is returned.
<function><link
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>.
On error, <constant>NULL</constant> is returned.
Function: comedi_get_hardcal_converter -- get converter for hardware-calibrated subdevice
Retval: int
Param: comedi_t *dev
Param: comedi_t * device
Param: unsigned subdevice
Param: unsigned channel
Param: unsigned range
Param: enum comedi_conversion_direction direction
Param: comedi_polynomial_t *converter
Param: comedi_polynomial_t * converter
Status: alpha
Description:
comedi_get_hardcal_converter() initializes *<parameter>converter</parameter> so it can be
The function <function>comedi_get_hardcal_converter</function> initializes
the <type>comedi_polynomial_t</type> pointed to by
<parameter class="function">converter</parameter> so it can be
passed to either
<link linkend="func-ref-comedi-to-physical"><function>comedi_to_physical</function></link>,
or <link linkend="func-ref-comedi-from-physical"><function>comedi_from_physical</function></link>.
<function><link
linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>,
or <function><link
linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>.
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().
convert data from the specified <parameter class="function">subdevice</parameter>,
<parameter class="function">channel</parameter>, and <parameter
class="function">range</parameter>. The <parameter class="function">direction</parameter>
parameter specifies whether <parameter class="function">converter</parameter>
will be passed to <function>comedi_to_physical</function>
or <function>comedi_from_physical</function>.
This function initializes *<parameter>converter</parameter> as a simple linear function with no
This function initializes the <type>comedi_polynomial_t</type> pointed to by
<parameter class="function">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()
needs calibration to be performed in software by the host computer,
use <function>comedi_get_softcal_converter</function>
instead. A subdevice will advertise the fact that it depends on a software calibration
with the SDF_SOFT_CALIBRATED subdevice flag.
with the <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
The result of this function will only depend on the <parameter>channel</parameter>
The result of this function will only depend on the
<parameter class="function">channel</parameter>
parameter if either
<link linkend="func-ref-comedi-range-is-chan-specific"><function>comedi_range_is_chan_specific</function></link>
or <link linkend="func-ref-comedi-maxdata-is-chan-specific"><function>comedi_maxdata_is_chan_specific</function></link>
returns true for the specified <parameter>subdevice</parameter>.
<function><link
linkend="func-ref-comedi-range-is-chan-specific">comedi_range_is_chan_specific</link></function>
or <function><link
linkend="func-ref-comedi-maxdata-is-chan-specific">comedi_maxdata_is_chan_specific</link></function>
returns true for the specified <parameter class="function">subdevice</parameter>.
Returns:
Zero on success or -1 on failure.
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
Function: comedi_get_softcal_converter -- get converter for software-calibrated subdevice
Retval: int
@ -148,29 +178,42 @@ 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
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
The function <function>comedi_get_softcal_converter</function> initializes
the <type>comedi_polynomial_t</type> pointed to by
<parameter class="function">converter</parameter> so it can be
passed to either
<link linkend="func-ref-comedi-to-physical"><function>comedi_to_physical</function></link>
or <link linkend="func-ref-comedi-from-physical"><function>comedi_from_physical</function></link>.
The *<parameter>converter</parameter>
struct 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
<function><link
linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function>
or <function><link
linkend="func-ref-comedi-from-physical">comedi_from_physical</link></function>.
The <type>comedi_polynomial_t</type> pointed to by
<parameter class="function">converter</parameter>
can then be used to
convert data for the specified <parameter class="function">subdevice</parameter>,
<parameter class="function">channel</parameter>, and
<parameter class="function">range</parameter>.
The <parameter class="function">direction</parameter>
parameter specifies whether <parameter class="function">converter</parameter>
will be passed to <function>comedi_to_physical</function>
or <function>comedi_from_physical</function>.
The <parameter class="function">parsed_calibration</parameter> parameter
points to the
software calibration values for your device, and may be obtained by calling
<link linkend="func-ref-comedi-parse-calibration-file"><function>comedi_parse_calibration_file</function></link>
on a calibration file generated by the comedi_soft_calibrate program.
<function><link
linkend="func-ref-comedi-parse-calibration-file">comedi_parse_calibration_file</link></function>
on a calibration file generated by the
<command>comedi_soft_calibrate</command> 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.
with the <constant>SDF_SOFT_CALIBRATED</constant> subdevice flag.
Whether or not the result of this function actually depends on the <parameter>channel</parameter>
Whether or not the result of this function actually depends on the
<parameter class="function">channel</parameter>
parameter is
hardware dependent. For example, the calibration of a multiplexed analog input will typically
not depend on the channel, only the range. Analog outputs will typically use different calibrations
@ -178,29 +221,36 @@ Description:
Software calibrations are implemented as polynomials (up to third order). Since the inverse
of a polynomial 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.
may not be able to get converters for the <quote>reverse</quote> direction. For example, you may be
able to get a converter for an analog input in the
<constant>COMEDI_TO_PHYSICAL</constant> direction, but not
in the <constant>COMEDI_FROM_PHYSICAL</constant> direction.
Returns:
Zero on success or -1 on failure.
Returns <literal>0</literal> on success, <literal>-1</literal> on failure.
Function: comedi_parse_calibration_file -- load contents of calibration file
Retval: comedi_calibration_t*
Param: const char *file_path
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
<link linkend="func-ref-comedi-apply-parsed-calibration"><function>comedi_apply_parsed_calibration</function></link>
or <link linkend="func-ref-comedi-get-softcal-converter"><function>comedi_get_softcal_converter</function></link>
<command>comedi_calibrate</command> or
<command>comedi_soft_calibrate</command> programs) and returns a pointer
to a <type>comedi_calibration_t</type> which can be passed to the
<function><link
linkend="func-ref-comedi-apply-parsed-calibration">comedi_apply_parsed_calibration</link></function>
or <function><link
linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>
functions. When you are
finished using the comedi_calibration_t, you should
call <link linkend="func-ref-comedi-cleanup-calibration"><function>comedi_cleanup_calibration</function></link>
finished using the <type>comedi_calibration_t</type>, you should
call <function><link
linkend="func-ref-comedi-cleanup-calibration">comedi_cleanup_calibration</link></function>
to free the resources
associated with the comedi_calibration_t.
associated with the <type>comedi_calibration_t</type>.
The <link linkend="func-ref-comedi-get-default-calibration-path"><function>comedi_get_default_calibration_path</function></link>
The <function><link
linkend="func-ref-comedi-get-default-calibration-path">comedi_get_default_calibration_path</link></function>
function may be useful in conjunction with this function.
Returns:
A pointer to parsed calibration information on success, or NULL on failure.
A pointer to parsed calibration information on success, or
<constant>NULL</constant> on failure.