From 1c64dcb1b57a37fd5f0968c1b61a1841b0609592 Mon Sep 17 00:00:00 2001 From: Ian Abbott Date: Tue, 8 May 2012 16:51:49 +0100 Subject: [PATCH] doc/funcref: Some DocBook mark-up changes. --- doc/funcref | 420 ++++++++++++++++++++++++++++------------------------ 1 file changed, 224 insertions(+), 196 deletions(-) diff --git a/doc/funcref b/doc/funcref index 661a922..ffe484c 100644 --- a/doc/funcref +++ b/doc/funcref @@ -4,9 +4,10 @@ Retval: int Param: comedi * device Description: Close a device previously opened by - comedi_open. + comedi_open. Returns: - If successful, comedi_close returns 0. On failure, -1 is returned. + If successful, comedi_close returns 0. + On failure, -1 is returned. Function: comedi_data_read -- read single sample from channel Retval: int @@ -18,40 +19,41 @@ 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. + 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 + 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 function comedi_data_read reads one data value from the specified channel and stores the value in - *data. + *data. - WARNING: comedi_data_read() does not do any pausing to + WARNING: comedi_data_read does not do any pausing to allow multiplexed analog inputs to settle before starting 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, + comedi_data_read_delayed, or set the input channel at an earlier time with - comedi_data_read_hint. + comedi_data_read_hint. 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. + comedi_get_maxdata. Conversion of data values to physical units can be performed by the function - comedi_to_physical. + comedi_to_physical. Returns: - On success, comedi_data_read() returns 1 (the number of samples - read). If there is an error, -1 is returned. + On success, comedi_data_read returns 1 (the number of samples + read). If there is an error, -1 is returned. Function: comedi_data_read_n -- read multiple samples from channel Retval: int @@ -64,10 +66,10 @@ Param: lsampl_t * data Param: unsigned int n Description: Similar to - comedi_data_read - except it reads n samples into the array - data. The precise timing of the samples is not - hardware controlled. + comedi_data_read + except it reads n samples into the + array data. + The precise timing of the samples is not hardware controlled. Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time Retval: int @@ -80,7 +82,7 @@ Param: lsampl_t * data Param: unsigned int nanosec Description: Similar to - comedi_data_read + 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 @@ -105,9 +107,9 @@ Param: unsigned int range Param: unsigned int aref Description: Used to prepare an analog input for a subsequent call to - comedi_data_read. + comedi_data_read. It is not necessary to use this - function, but it can be useful for eliminating inaccuaracies + function, but it can be useful for eliminating inaccuracies caused by insufficient settling times when switching the channel or gain on an analog input. This function sets an analog input @@ -115,7 +117,7 @@ Description: perform an actual analog to digital conversion. Alternatively, one can simply use - comedi_data_read_delayed, + comedi_data_read_delayed, which sets up the input, pauses to allow settling, then performs a conversion. @@ -129,66 +131,66 @@ 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 + 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 + 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. + The function comedi_data_write writes the data value specified + by the parameter data to the specified channel. Returns: - On success, comedi_data_write() returns 1 (the number of samples - written). If there is an error, -1 is returned. + On success, 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. + The function comedi_do_insn performs a single instruction. Returns: If successful, returns a non-negative number. For the case - of INSN_READ or INSN_WRITE instructions, + of INSN_READ or INSN_WRITE instructions, comedi_do_insn returns the number of samples read or written, which may be less than the number requested. - If there is an error, -1 is returned. + 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 + The function comedi_do_insnlist performs multiple Comedi instructions as part of one system call. This function can be used to avoid the overhead of multiple system calls. Returns: - The function comedi_do_insnlist() returns the number of + The function comedi_do_insnlist returns the number of successfully completed instructions. Error information for the unsuccessful instruction is not available. If there is - an error before the first instruction can be executed, -1 + an error before the first instruction can be executed, -1 is returned. Function: comedi_fileno -- get file descriptor for open Comedilib device Retval: int Param: comedi_t * device Description: - The function comedi_fileno returns the file descriptor for - the device dev. This descriptor can then be used as the - file descriptor parameter of read(), write(), etc. + The function comedi_fileno returns the file descriptor for + the device device. This descriptor can then be used as the + file descriptor parameter of read, write, etc. This function is intended to mimic the standard C library - function fileno(). + function fileno. The returned file descriptor should not be closed, and will become invalid when - comedi_close - is called on device. + comedi_close + is called on device. Returns: - A file descriptor, or -1 on error. + A file descriptor, or -1 on error. Function: comedi_find_range -- search for range Retval: int @@ -199,15 +201,18 @@ 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 channel - belonging to a subdevice of the comedi device device, - that includes both min and max in - units of unit. + The function comedi_find_range tries to + locate the optimal (smallest) range for the channel + channel + belonging to subdevice subdevice + of the comedi device device, + that includes both min + and max in + units of unit. Returns: If a matching range is found, the index of the matching range is returned. If no matching range is available, the function returns - -1. + -1. Function: comedi_find_subdevice_by_type -- search for subdevice type Retval: int @@ -216,36 +221,39 @@ Param: int type Param: unsigned int start_subdevice Description: The function comedi_find_subdevice_by_type tries to - locate a subdevice belonging to comedi device device, - having type type, starting with the subdevice - start_subdevice. The - comedi_subdevice_type enum + locate a subdevice belonging to comedi device + device, + having type type, starting with + the subdevice start_subdevice. The + comedi_subdevice_type enum specifies the possible subdevice types. Returns: If it finds a subdevice with the requested type, it returns its index. If there is an error, the function - returns -1 and sets the appropriate error. + returns -1 and sets the appropriate error. Function: comedi_from_physical -- convert physical units to sample Retval: lsampl_t Param: double data -Param: const comedi_polynomial_t *conversion_polynomial +Param: const comedi_polynomial_t * conversion_polynomial Description: - Converts data given in physical units into Comedi's + Converts data given in physical units into Comedi's integer sample values - (lsampl_t, between 0 and maxdata). The conversion_polynomial + (lsampl_t, between 0 and maxdata — + see comedi_get_maxdata). + The conversion_polynomial parameter is obtained from either - comedi_get_hardcal_converter or - comedi_get_softcal_converter. + 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 + data is performed. It is up to you to ensure your data is within the limits of the output range you are using. This function is intended to supplant - comedi_from_phys, + comedi_from_phys, and was introduced in order to support software calibrations. Returns: @@ -255,19 +263,20 @@ 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. + The function comedi_get_board_name returns a pointer + to a string containing the name of 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_driver_name -- Comedi driver name Retval: char * Param: comedi_t * device Description: - The function comedi_get_driver_name returns a pointer + 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 + 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 @@ -276,21 +285,22 @@ 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. + 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. + 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 function comedi_get_n_channels returns the number + of channels of the subdevice subdevice + belonging to the comedi device device. + This function returns -1 on error and the Comedilib error value is set. Function: comedi_get_n_ranges -- number of ranges of channel @@ -299,16 +309,20 @@ 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. + The function comedi_get_n_ranges returns the number + of ranges of the channel channel + belonging to the subdevice 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: - Returns the number of subdevices belonging to the Comedi - device referenced by the parameter device, or -1 on error. + The function comedi_get_n_subdevices returns the number + of subdevices belonging to the Comedi + device referenced by the parameter device, + or -1 on error. Function: comedi_get_range -- range information of channel Retval: comedi_range * @@ -317,182 +331,193 @@ 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 + The function comedi_get_range returns a pointer to a + comedi_range structure that contains information on - the range specified by the subdevice, - channel, and range - parameters. - The pointer is valid until the Comedi device device is closed. - If there is an error, NULL is returned. + the range specified by the subdevice, + channel, + and range parameters. + The pointer is valid until the Comedi device + device is closed. + If there is an error, NULL is returned. Function: comedi_get_subdevice_flags -- properties of subdevice Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - This function returns a bitfield describing the capabilities of - the specified subdevice. If there is an error, -1 is returned, + The function comedi_get_subdevice_flags + returns a bitfield describing the capabilities of + the specified subdevice subdevice + of the Comedi device device. + If there is an error, -1 is returned, and the Comedilib error value is set. - - subdevice flags + Subdevice Flag - Value (hexadecimal) + Value (hex) Description - SDF_BUSY - 0x00000001 - The subdevice is busy performing an asynchronous command. A subdevice being "busy" - is slightly different from the "running" state flagged by SDF_RUNNING. A "running" subdevice - is always "busy", but a "busy" subdevice is not necessarily "running". For example, suppose an + SDF_BUSY + 0x00000001 + The subdevice is busy performing an asynchronous command. + A subdevice being busy + is slightly different from the running state flagged by + SDF_RUNNING. A running subdevice + is always busy, but a busy subdevice is + not necessarily running. For example, suppose an analog input command has been completed by the hardware, but there are still samples in - Comedi's buffer waiting to be read out. In this case, the subdevice is not "running", but - is still "busy" until all the samples are read out or comedi_cancel() is called. + Comedi's buffer waiting to be read out. In this case, the subdevice is not + running, but is still busy until all the + samples are read out or comedi_cancel is called. - SDF_BUSY_OWNER - 0x00000002 - The subdevice is "busy", and the command it is running was started by the current process. + SDF_BUSY_OWNER + 0x00000002 + The subdevice is busy, and the command it is running was started by the current process. - SDF_LOCKED - 0x00000004 - The subdevice has been locked by comedi_lock(). + SDF_LOCKED + 0x00000004 + The subdevice has been locked by comedi_lock. - SDF_LOCK_OWNER - 0x00000008 + SDF_LOCK_OWNER + 0x00000008 The subdevice is locked, and was locked by the current process. - SDF_MAXDATA - 0x00000010 + SDF_MAXDATA + 0x00000010 The maximum data value for the subdevice depends on the channel. - SDF_FLAGS - 0x00000020 + SDF_FLAGS + 0x00000020 The subdevice flags depend on the channel (unfinished/broken support in library). - SDF_RANGETYPE - 0x00000040 + SDF_RANGETYPE + 0x00000040 The range type depends on the channel. - SDF_CMD - 0x00001000 + SDF_CMD + 0x00001000 The subdevice supports asynchronous commands. - SDF_SOFT_CALIBRATED - 0x00002000 + SDF_SOFT_CALIBRATED + 0x00002000 The subdevice relies on the host to do calibration in software. - Software calibration coefficients are determined by the comedi_soft_calibrate - utility. See the description of the comedi_get_softcal_converter() function + Software calibration coefficients are determined by the comedi_soft_calibrate + utility. See the description of the + comedi_get_softcal_converter function for more information. - SDF_READABLE - 0x00010000 + SDF_READABLE + 0x00010000 The subdevice can be read (e.g. analog input). - SDF_WRITABLE - 0x00020000 + SDF_WRITABLE + 0x00020000 The subdevice can be written to (e.g. analog output). - SDF_INTERNAL - 0x00040000 + SDF_INTERNAL + 0x00040000 The subdevice does not have externally visible lines. - SDF_GROUND - 0x00100000 - The subdevice supports AREF_GROUND. + SDF_GROUND + 0x00100000 + The subdevice supports analog reference AREF_GROUND. - SDF_COMMON - 0x00200000 - The subdevice supports AREF_COMMON. + SDF_COMMON + 0x00200000 + The subdevice supports analog reference AREF_COMMON. - SDF_DIFF - 0x00400000 - The subdevice supports AREF_DIFF. + SDF_DIFF + 0x00400000 + The subdevice supports analog reference AREF_DIFF. - SDF_OTHER - 0x00800000 - The subdevice supports AREF_OTHER + SDF_OTHER + 0x00800000 + The subdevice supports analog reference AREF_OTHER - SDF_DITHER - 0x01000000 - The subdevice supports dithering (via the CR_ALT_FILTER chanspec flag). + SDF_DITHER + 0x01000000 + The subdevice supports dithering (via the CR_ALT_FILTER chanspec flag). - SDF_DEGLITCH - 0x02000000 - The subdevice supports deglitching (via the CR_ALT_FILTER chanspec flag). + SDF_DEGLITCH + 0x02000000 + The subdevice supports deglitching (via the CR_ALT_FILTER chanspec flag). - SDF_RUNNING - 0x08000000 + SDF_RUNNING + 0x08000000 An asynchronous command is running. You can use this flag to poll for the completion of an output command. - SDF_LSAMPL - 0x10000000 - The subdevice uses the 32 bit lsampl_t type instead of the 16 bit sampl_t for + SDF_LSAMPL + 0x10000000 + The subdevice uses the 32-bit lsampl_t type instead of + the 16-bit sampl_t for asynchronous command data. - SDF_PACKED - 0x20000000 + SDF_PACKED + 0x20000000 The subdevice uses bitfield samples for asynchronous command data, one bit per channel (otherwise it uses - one sampl_t or lsampl_t per channel). Commonly used for digital subdevices. + one sampl_t or lsampl_t per channel). + Commonly used for digital subdevices. -
+ Function: comedi_get_subdevice_type -- type of subdevice Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - The function comedi_get_subdevice_type() returns an + 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 - comedi_subdevice_type enum + device device and has the subdevice index + subdevice. The + comedi_subdevice_type enum specifies the possible values for the subdevice type. Returns: The function returns the subdevice type, or - -1 if there is an error. + -1 if there is an error. 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. + 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 + numbers. For example, 0x00073d is the version code for version 0.7.61. This function is of limited usefulness. A typical @@ -507,35 +532,37 @@ Param: comedi_t * device Param: unsigned int subdevice Param: unsigned int trig_num Description: - This function sends an INSN_INTTRIG instruction to a subdevice, which causes an internal triggering event. + This function sends an INSN_INTTRIG instruction to a subdevice, which causes an internal triggering event. This event can, for example, trigger a subdevice to start an asynchronous command. - The trig_num parameter is reserved for future use, and should be set to 0. + The trig_num parameter is reserved for future use, and should be set to 0. It is likely it will be used in the future to support multiple independent internal triggers. For example, an asynchronous command might be specified for a subdevice - with a start_src of TRIG_INT, and - a start_arg of 5. Then the start event would only be triggered if comedi_internal_trigger() were - called on the subdevice with a trig_num equal to the same value of 5. + with a start_src of TRIG_INT, + and a start_arg of 5. + Then the start event would only be triggered if comedi_internal_trigger + were called on the subdevice with a trig_num + equal to the same value of 5. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_lock -- subdevice reservation Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - The function comedi_lock() reserves a subdevice for use by the + The function comedi_lock reserves a subdevice for use by the current process. While the lock is held, no other process is allowed to read, write, or configure that subdevice, although other processes can read information about the subdevice. The lock is released by - comedi_unlock, + comedi_unlock, or when - comedi_close - is called on device. + comedi_close + is called on device. Returns: - If successful, 0 is returned. If there is an error, - -1 is returned. + If successful, 0 is returned. If there is an error, + -1 is returned. Function: comedi_maxdata_is_chan_specific -- maximum sample depends on channel Retval: int @@ -543,8 +570,8 @@ Param: comedi_t * device Param: unsigned int subdevice Description: If each channel of the specified subdevice may have different maximum - sample values, this function returns 1. Otherwise, this function - returns 0. On error, this function returns -1. + sample values, this function returns 1. Otherwise, this function + returns 0. On error, this function returns -1. Function: comedi_open -- open a Comedi device Retval: comedi_t * @@ -552,9 +579,10 @@ Param: const char * filename Description: Open a Comedi device specified by the file filename. Returns: - If successful, 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. + If successful, comedi_open returns a pointer to + a valid comedi_t + structure. This structure is opaque; the pointer should not + be dereferenced by the application. NULL is returned on failure. Function: comedi_range_is_chan_specific -- range information depends on channel Retval: int @@ -562,28 +590,28 @@ Param: comedi_t * device Param: unsigned int subdevice Description: If each channel of the specified subdevice may have different range - information, this function returns 1. Otherwise, this function - returns 0. On error, this function returns -1. + information, this function returns 1. Otherwise, this function + returns 0. On error, this function returns -1. Function: comedi_to_physical -- convert sample to physical units Retval: double Param: lsampl_t data -Param: const comedi_polynomial_t *conversion_polynomial +Param: const comedi_polynomial_t * conversion_polynomial Description: - Converts data given in Comedi's integer - sample values (lsampl_t, between 0 and - maxdata) into physical units (double). The - conversion_polynomial + Converts data given in Comedi's integer + sample values (lsampl_t, between 0 and + maxdata) into physical units (double). The + conversion_polynomial parameter is obtained from either - comedi_get_hardcal_converter or - comedi_get_softcal_converter. + comedi_get_hardcal_converter or + comedi_get_softcal_converter. No range checking of the - input data is performed. It is up to - you to check for data values of + input data is performed. It is up to + you to check for data values of 0 or maxdata if you want to detect possibly out-of-range readings. This function is intended to supplant - comedi_to_phys, + comedi_to_phys, and was introduced in order to support software calibrations. Returns: Physical value corresponding to the input sample value. @@ -593,9 +621,9 @@ Retval: int Param: comedi_t * device Param: unsigned int subdevice Description: - The function comedi_unlock() releases a subdevice locked + The function comedi_unlock releases a subdevice locked by - comedi_lock. + comedi_lock. Returns: - Zero on success, otherwise -1. + 0 on success, otherwise -1. -- 2.26.2