Updated and added some links to reference for asynchronous command
functions.
This commit is contained in:
Frank Mori Hess
parent
0c69850ffc
commit
2d4cc8f6d0
1 changed files with 139 additions and 75 deletions
|
|
@ -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 *<parameter>command</parameter> specifies
|
||||
settings for the
|
||||
acquisition. The command must be able to pass
|
||||
<link linkend="func-ref-comedi-command-test"><function>comedi_command_test</function></link>
|
||||
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 <parameter>command</parameter> 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 *<parameter>command</parameter> 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.
|
||||
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.
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>0 indicates a valid command.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
1 indicates that one of the *_src
|
||||
members of the command contained an
|
||||
unsupported trigger. The bits corresponding to the unsupported
|
||||
triggers are zeroed.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
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
|
||||
<parameter>device</parameter> and
|
||||
<parameter>subdevice</parameter>. 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
|
||||
<parameter>device</parameter> and <parameter>subdevice</parameter>
|
||||
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 *<parameter>command</parameter> is modified to be a
|
||||
valid command that can be used as a parameter to
|
||||
<link linkend="func-ref-comedi-command"><function>comedi_command</function></link>
|
||||
(after the command has additionally been assigned a valid chanlist array).
|
||||
The command measures scans consisting of <parameter>chanlist_len</parameter>
|
||||
channels
|
||||
at a scan rate that corresponds to a period of
|
||||
<parameter>scan_period_ns</parameter> 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.
|
||||
<parameter>device</parameter> and <parameter>subdevice</parameter>
|
||||
are probed, and the results placed in the
|
||||
command structure *<parameter>command</parameter>. 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 <parameter>device</parameter> and <parameter>subdevice</parameter>.
|
||||
Changing the maximum buffer
|
||||
size can be accomplished with
|
||||
<link linkend="func-ref-comedi-set-max-buffer-size"><function>comedi_set_max_buffer_size</function></link>
|
||||
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 <parameter>dev</parameter>. 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 <parameter>dev</parameter>. 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 <parameter>num_bytes</parameter>
|
||||
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 <function>comedi_mark_buffer_read</function> returns the
|
||||
number of bytes successfully marked as read,
|
||||
or -1 on error. The return value may be less than
|
||||
<parameter>num_bytes</parameter> if you attempt to mark more
|
||||
bytes read than are currently available for reading, or
|
||||
if <parameter>num_bytes</parameter> 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 <parameter>num_bytes</parameter>
|
||||
bytes in the buffer
|
||||
are valid and may be sent to the device.
|
||||
If there is an error, -1 is returned.
|
||||
Returns:
|
||||
The function <function>comedi_mark_buffer_written</function> returns
|
||||
number of bytes successfully marked as written,
|
||||
or -1 on error. The return value may be less than
|
||||
<parameter>num_bytes</parameter> if you attempt to mark more
|
||||
bytes written than the amount of free space currently available
|
||||
in the output buffer, or
|
||||
if <parameter>num_bytes</parameter> 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
|
||||
<parameter>device</parameter> and <parameter>subdevice</parameter>.
|
||||
The buffer size will be set to <parameter>size</parameter> 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
|
||||
<link linkend="func-ref-comedi-set-max-buffer-size"><function>comedi_set_max_buffer_size</function></link>,
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue