From: Frank Mori Hess Date: Tue, 12 Feb 2008 17:01:43 +0000 (+0000) Subject: Updated and added some links to reference for asynchronous command X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=2d4cc8f6d0cbc3749af08beaa0044e087d26b48e;p=comedilib.git Updated and added some links to reference for asynchronous command functions. --- diff --git a/doc/command_funcref.txt b/doc/command_funcref.txt index d5755d5..f360b26 100644 --- a/doc/command_funcref.txt +++ b/doc/command_funcref.txt @@ -17,14 +17,17 @@ 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() + The function comedi_command() starts a streaming input + or output. The + command structure *command specifies + settings for 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 + function read() on the device file. For output subdevices, sample values are written using the function write(). - +Returns: If successful, 0 is returned, otherwise -1. Function: comedi_command_test -- test streaming input/output configuration @@ -33,41 +36,61 @@ 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 + to by the parameter command and returns an + integer describing the testing stages that were successfully passed. In addition, if elements - of the command structure are invalid, they may be modified. Source + 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. + The meanings of the return value are as follows: - 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. + + + 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 analog input boards require that all channels in the chanlist + use the same input range. + + + Function: comedi_get_buffer_contents -- streaming buffer status Retval: int @@ -96,8 +119,9 @@ 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. + 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 @@ -108,15 +132,21 @@ 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 + 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 successful, 0 is returned, otherwise -1. + structure *command is modified to be a + valid command that can be used as a parameter to + comedi_command + (after the command has additionally been assigned a valid chanlist array). + The command measures scans consisting of chanlist_len + channels + at a scan rate that corresponds to a period of + scan_period_ns nanoseconds. + The rate is adjusted to a rate that the device + can handle. +Returns: + If successful, 0 is returned, otherwise -1. Function: comedi_get_cmd_src_mask -- streaming input/output capabilities Retval: int @@ -125,11 +155,14 @@ 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 successful, 0 is returned, otherwise -1. + device and subdevice + are probed, and the results placed in the + command structure *command. The trigger + source elements of the command structure are set to be the bitwise-or + of the subdevice's supported trigger sources. Other elements in the structure + are undefined. +Returns: + If successful, 0 is returned, otherwise -1. Function: comedi_get_max_buffer_size -- maximum streaming buffer size Retval: int @@ -138,26 +171,30 @@ 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. + specified by device and subdevice. + Changing the maximum buffer + size can be accomplished with + comedi_set_max_buffer_size + or with the comedi_config program, + and 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". + whose streaming input buffer is accessible through the + device dev. If + there is no such subdevice, -1 is returned. 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". + whose streaming output buffer is accessible through the + device dev. If there is no such subdevice, + -1 is returned. Function: comedi_mark_buffer_read -- streaming buffer control Retval: int @@ -167,16 +204,22 @@ 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, + if you are using a mmap() to read data from Comedi's buffer + (as opposed to calling read() on the device file), 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 + 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. + The function comedi_mark_buffer_read returns the + number of bytes successfully marked as read, + or -1 on error. The return value may be less than + num_bytes if you attempt to mark more + bytes read than are currently available for reading, or + if num_bytes must be rounded down + to be an exact multiple of the subdevice's + sample size (either sizeof(sampl_t) or sizeof(lsampl_t)). Function: comedi_mark_buffer_written -- streaming buffer control Retval: int @@ -186,13 +229,24 @@ 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 + if you are using a mmap() to write data to Comedi's buffer + (as opposed to calling write() on the device + file), 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 + 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. +Returns: + The function comedi_mark_buffer_written returns + number of bytes successfully marked as written, + or -1 on error. The return value may be less than + num_bytes if you attempt to mark more + bytes written than the amount of free space currently available + in the output buffer, or + if num_bytes must be + rounded down to be an exact multiple of the subdevice's + sample size (either sizeof(sampl_t) or sizeof(lsampl_t)). Function: comedi_poll -- force updating of streaming buffer Retval: int @@ -213,13 +267,22 @@ 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 + streaming buffer for the subdevice specified by + device and subdevice. + The buffer size will be set to size bytes, + rounded up to a multiple of the virtual memory page + size. The virtual memory page size can be determined using sysconf(_SC_PAGE_SIZE). + This function does not require special privileges. However, + it is limited to a (adjustable) maximum buffer size, which can + be changed by a priveliged user calling + comedi_set_max_buffer_size, + or running the program comedi_config. +Returns: + The new buffer size in bytes is returned on success. On error, + -1 is returned. + Function: comedi_set_max_buffer_size -- streaming buffer size of subdevice Retval: int Param: comedi_t * device @@ -229,5 +292,6 @@ 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 successful, the old buffer - size is returned. On error, -1 is returned. + size requires the user to have appropriate privileges. +Returns: + The old buffer size is returned on success. On error, -1 is returned.