From: Ian Abbott Date: Tue, 8 May 2012 17:08:56 +0000 (+0100) Subject: doc/calibration_funcref.txt: Some DocBook mark-up changes. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=c1cd8025465ae3fa3beb9ec146f3184b14d7db3b;p=comedilib.git doc/calibration_funcref.txt: Some DocBook mark-up changes. --- diff --git a/doc/calibration_funcref.txt b/doc/calibration_funcref.txt index 9bb05ad..329a391 100644 --- a/doc/calibration_funcref.txt +++ b/doc/calibration_funcref.txt @@ -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 comedi_apply_calibration sets the + hardware calibration for the subdevice specified by + device and + subdevice + so that it is in proper calibration when using the channel specified by + channel, + range index specified by range and + analog reference specified by 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 + 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 + 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. + 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 + 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 + The file_path parameter can be used to specify the file which contains the calibration information. - If file_path is NULL, then comedilib + 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). + 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_file + comedi_parse_calibration_file, + comedi_apply_parsed_calibration, + and comedi_cleanup_calibration_file provide the same functionality at a slightly lower level. Returns: - Zero on success, a negative number on failure. + Returns 0 on success, -1 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 - comedi_apply_calibration, + 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 + efficient than comedi_apply_calibration since the calibration file does not need to be reparsed with - every call. The calibration is + every call. The value of parameter calibration is obtained by a call to - comedi_parse_calibration_file. + comedi_parse_calibration_file. Returns: - Zero on success, a negative number on failure. + Returns 0 on success, -1 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 - comedi_parse_calibration_file. - *calibration + comedi_calibration_t obtained from + comedi_parse_calibration_file. + The comedi_calibration_t pointed to by + 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 +Retval: char * +Param: comedi_t * device 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 + This function returns a pointer to a string containing a default calibration file + path appropriate for the Comedi device specified by + device. Memory for the + string is allocated by the function, and should be freed with the C library + function free 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. + 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: 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 *converter so it can be + The function comedi_get_hardcal_converter initializes + the comedi_polynomial_t pointed to by + converter so it can be passed to either - comedi_to_physical, - or comedi_from_physical. + 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(). + 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 + This function initializes the comedi_polynomial_t pointed to by + 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() + 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. + with the SDF_SOFT_CALIBRATED subdevice flag. - The result of this function will only depend on the channel + 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 - returns true for the specified subdevice. + comedi_range_is_chan_specific + or comedi_maxdata_is_chan_specific + returns true for the specified subdevice. Returns: - Zero on success or -1 on failure. + Returns 0 on success, -1 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 *converter so it can be + The function comedi_get_softcal_converter initializes + the comedi_polynomial_t pointed to by + converter so it can be passed to either - comedi_to_physical - or comedi_from_physical. - The *converter - struct 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 + comedi_to_physical + or comedi_from_physical. + The comedi_polynomial_t pointed to by + converter + can then be used to + convert data for 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 + points to 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. + 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. + with the SDF_SOFT_CALIBRATED subdevice flag. - Whether or not the result of this function actually depends on the channel + Whether or not the result of this function actually depends on the + channel 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 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. + Returns 0 on success, -1 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 - comedi_apply_parsed_calibration - or comedi_get_softcal_converter + 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 + finished using the comedi_calibration_t, you should + call comedi_cleanup_calibration to free the resources - associated with the comedi_calibration_t. + associated with the comedi_calibration_t. - The comedi_get_default_calibration_path + 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. + A pointer to parsed calibration information on success, or + NULL on failure.