8c31fb88c1
Change comedi_set_read_subdevice() and comedi_set_write_subdevice() to do nothing if the requested subdevice is already set as the current read or write subdevice, respectively. The functions now return success even if the Comedi drivers do not support changes to the read or write subdevice as long as the specified subdevice is the default one.
439 lines
18 KiB
Text
439 lines
18 KiB
Text
Asynchronous commands
|
|
Function: comedi_cancel -- stop streaming input/output in progress
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_cancel</function> can be used to stop a command
|
|
previously started by
|
|
<function><link linkend="func-ref-comedi-command">comedi_command</link></function>
|
|
which is still in progress
|
|
on the subdevice indicated by the parameters <parameter class="function">device</parameter>
|
|
and <parameter class="function">subdevice</parameter>.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_command -- start streaming input/output
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: comedi_cmd * command
|
|
Description:
|
|
The function <function>comedi_command</function> starts a streaming input
|
|
or output. The
|
|
command structure pointed to by <parameter class="function">command</parameter> specifies
|
|
settings for the
|
|
acquisition. The command must be able to pass
|
|
<function><link
|
|
linkend="func-ref-comedi-command-test">comedi_command_test</link></function>
|
|
with a return value of <literal>0</literal>, or
|
|
<function>comedi_command</function> will fail.
|
|
For input subdevices, sample values are read using the
|
|
function <function>read</function> on the device file descriptor.
|
|
For output subdevices,
|
|
sample values are written using the function <function>write</function>.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_command_test -- test streaming input/output configuration
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: comedi_cmd * command
|
|
Description:
|
|
The function <function>comedi_command_test</function> tests the command structure pointed
|
|
to by the parameter <parameter class="function">command</parameter> and returns an
|
|
integer describing the
|
|
testing stages that were successfully passed. In addition, if elements
|
|
of the <type>comedi_cmd</type> 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.
|
|
Returns:
|
|
The meanings of the return value are as follows:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>0</literal> indicates a valid command.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>1</literal> indicates that one of the
|
|
<structfield>…_src</structfield>
|
|
members of the command contained an
|
|
unsupported trigger. The bits corresponding to the unsupported
|
|
triggers are zeroed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>2</literal> indicates that the particular combination
|
|
of <structfield>…_src</structfield> settings is not supported by the driver, or that
|
|
one of the <structfield>…_src</structfield> members has the bit corresponding to
|
|
multiple trigger sources set at the same time.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>3</literal> indicates that one of the
|
|
<structfield>…_arg</structfield> members
|
|
of the command is set outside the range of allowable values.
|
|
For instance, an argument for a
|
|
<constant>TRIG_TIMER</constant> source which
|
|
exceeds the board's maximum speed. The invalid
|
|
<structfield>…_arg</structfield>
|
|
members will be adjusted to valid values.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>4</literal> indicates that one of the
|
|
<structfield>…_arg</structfield> members
|
|
required adjustment. For instance, the argument of a
|
|
<constant>TRIG_TIMER</constant> source may have been rounded to the nearest
|
|
timing period supported by the board.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>5</literal> indicates that some aspect of the
|
|
command's <structfield>chanlist</structfield> 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>
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_contents -- streaming buffer status
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_get_buffer_contents</function> is used on a subdevice
|
|
that has a Comedi command in progress to get the number of unread bytes. For
|
|
a streaming input command, this is the number of bytes that can be read. For
|
|
a streaming output command, subtracting this from the buffer size gives the
|
|
space available to be written.
|
|
Returns:
|
|
On success, <function>comedi_get_buffer_contents</function> returns the
|
|
number of unread bytes in the buffer.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_read_offset -- streaming buffer read offset
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_get_buffer_read_offset</function> is used on
|
|
a subdevice that has a Comedi command in progress to get the current read
|
|
position in the streaming buffer as an offset in bytes from the start of
|
|
the buffer. The position will wrap around to 0 when it reaches the buffer
|
|
size. This offset is only useful for memory mapped buffers.
|
|
|
|
This function replaces <function><link
|
|
linkend="func-ref-comedi-get-buffer-offset">comedi_get_buffer_offset</link></function> and has the same functionality.
|
|
Returns:
|
|
On success, <function>comedi_get_buffer_read_offset</function> returns the current
|
|
read position as an offset in bytes from the start of the buffer.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_write_offset -- streaming buffer write offset
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_get_buffer_write_offset</function> is used on
|
|
a subdevice that has a Comedi command in progress to get the current write
|
|
position in the streaming buffer as an offset in bytes from the start of
|
|
the buffer. The position will wrap around to 0 when it reaches the buffer
|
|
size. This offset is only useful for memory mapped buffers.
|
|
Returns:
|
|
On success, <function>comedi_get_buffer_write_offset</function> returns the
|
|
current write position as an offset in bytes from the start of the buffer.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_read_count -- streaming buffer read count
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int * read_count
|
|
Description:
|
|
The function <function>comedi_get_buffer_read_count</function> is used on
|
|
a subdevice that has a Comedi command in progress to get the number of bytes
|
|
that have been read from the buffer, modulo
|
|
<constant class="limit">UINT_MAX</constant> + <literal>1</literal>. The
|
|
value is stored in
|
|
<code>*<parameter class="function">read_count</parameter></code>.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_write_count -- streaming buffer write count
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int * write_count
|
|
Description:
|
|
The function <function>comedi_get_buffer_write_count</function> is used on
|
|
a subdevice that has a Comedi command in progress to get the number of bytes
|
|
that have been written to the buffer, modulo
|
|
<constant class="limit">UINT_MAX</constant> + <literal>1</literal>. The
|
|
value is stored in
|
|
<code>*<parameter class="function">write_count</parameter></code>.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_buffer_size -- streaming buffer size of subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_get_buffer_size</function> returns the size (in bytes)
|
|
of the streaming buffer for the subdevice specified by
|
|
<parameter class="function">device</parameter> and
|
|
<parameter class="function">subdevice</parameter>.
|
|
Returns:
|
|
On success, <function>comedi_get_buffer_size</function> returns the size of
|
|
the buffer in bytes.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: comedi_cmd * command
|
|
Param: unsigned int chanlist_len
|
|
Param: unsigned int scan_period_ns
|
|
Description:
|
|
The command capabilities of the subdevice indicated by the parameters
|
|
<parameter class="function">device</parameter> and <parameter
|
|
class="function">subdevice</parameter>
|
|
are probed, and the results placed in the
|
|
command structure pointed to by the parameter <parameter
|
|
class="function">command</parameter>.
|
|
The command structure pointed to by <parameter class="function">command</parameter>
|
|
is modified to be a
|
|
valid command that can be used as a parameter to
|
|
<function><link linkend="func-ref-comedi-command">comedi_command</link></function>
|
|
(after the command has additionally been assigned a valid
|
|
<structfield>chanlist</structfield> array).
|
|
The command measures scans consisting of <parameter class="function">chanlist_len</parameter>
|
|
channels
|
|
at a scan rate that corresponds to a period of
|
|
<parameter class="function">scan_period_ns</parameter> nanoseconds.
|
|
The rate is adjusted to a rate that the device
|
|
can handle.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_cmd_src_mask -- streaming input/output capabilities
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: comedi_cmd * command
|
|
Description:
|
|
The command capabilities of the subdevice indicated by the parameters
|
|
<parameter class="function">device</parameter> and <parameter
|
|
class="function">subdevice</parameter>
|
|
are probed, and the results placed in the
|
|
command structure pointed to by <parameter class="function">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:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_max_buffer_size -- maximum streaming buffer size
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_get_max_buffer_size</function> returns the maximum
|
|
allowable size (in bytes) of the streaming buffer for the subdevice
|
|
specified by <parameter class="function">device</parameter>
|
|
and <parameter class="function">subdevice</parameter>.
|
|
Changing the maximum buffer
|
|
size can be accomplished with
|
|
<function><link
|
|
linkend="func-ref-comedi-set-max-buffer-size">comedi_set_max_buffer_size</link></function>
|
|
or with the <command>comedi_config</command> program,
|
|
and requires appropriate privileges.
|
|
Returns:
|
|
On success, the maximum allowable size (in bytes) of the streaming buffer
|
|
is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_read_subdevice -- find streaming input subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Description:
|
|
The function <function>comedi_get_read_subdevice</function> returns the
|
|
index of the subdevice
|
|
whose streaming input buffer is currently accessible through the
|
|
device <parameter class="function">device</parameter>, if there is one.
|
|
Returns:
|
|
On success, <function>comedi_get_read_subdevice</function>returns the index
|
|
of the current <quote>read</quote> subdevice if there is one,
|
|
or <literal>-1</literal> if there is no <quote>read</quote> subdevice.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_get_write_subdevice -- find streaming output subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Description:
|
|
The function <function>comedi_get_write_subdevice</function> returns the
|
|
index of the subdevice
|
|
whose streaming output buffer is currently accessible through the
|
|
device <parameter class="device">device</parameter>, if there is one.
|
|
Returns:
|
|
On success, <function>comedi_get_write_subdevice</function>returns the index
|
|
of the current <quote>write</quote> subdevice if there is one,
|
|
or <literal>-1</literal> if there is no <quote>write</quote> subdevice.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_mark_buffer_read -- streaming buffer control
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int num_bytes
|
|
Description:
|
|
The function <function>comedi_mark_buffer_read</function> is used on a subdevice
|
|
that has a Comedi input command in progress. It should only be used
|
|
if you are using a <function>mmap</function> mapping to read data from Comedi's buffer
|
|
(as opposed to calling <function>read</function> on the device file
|
|
descriptor),
|
|
since Comedi will automatically keep track of how many bytes have been
|
|
transferred via <function>read</function> calls. This function is
|
|
used to indicate that the next <parameter class="function">num_bytes</parameter>
|
|
bytes in the buffer
|
|
are no longer needed and may be discarded.
|
|
Returns:
|
|
On success, <function>comedi_mark_buffer_read</function> returns the
|
|
number of bytes successfully marked as read. The return value may be less than
|
|
the <parameter class="function">num_bytes</parameter>.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_mark_buffer_written -- streaming buffer control
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int num_bytes
|
|
Description:
|
|
The function <function>comedi_mark_buffer_written</function> is used on a subdevice
|
|
that has a Comedi output command in progress. It should only be used
|
|
if you are using a <function>mmap</function> mapping to write data to Comedi's buffer
|
|
(as opposed to calling <function>write</function> on the device
|
|
file descriptor), since Comedi
|
|
will automatically keep track of how many bytes have been
|
|
transferred via <function>write</function> calls. This function is
|
|
used to indicate that the next <parameter class="function">num_bytes</parameter>
|
|
bytes in the buffer
|
|
are valid and may be sent to the device.
|
|
Returns:
|
|
On success, <function>comedi_mark_buffer_written</function> returns the
|
|
number of bytes successfully marked as written. The return value may be less than
|
|
the <parameter class="function">num_bytes</parameter>.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_poll -- force updating of streaming buffer
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Description:
|
|
The function <function>comedi_poll</function> is used on a subdevice that has a
|
|
Comedi command in progress in order to update the streaming buffer.
|
|
If supported by the driver, all available samples are copied to
|
|
the streaming buffer. These samples may be pending in DMA buffers
|
|
or device FIFOs.
|
|
Only a few Comedi drivers support this operation.
|
|
Returns:
|
|
On success, <function>comedi_poll</function> returns the number of additional
|
|
bytes available.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_set_buffer_size -- streaming buffer size of subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int size
|
|
Description:
|
|
The function <function>comedi_set_buffer_size</function> changes the size of the
|
|
streaming buffer for the subdevice specified by
|
|
<parameter class="function">device</parameter> and <parameter
|
|
class="function">subdevice</parameter>.
|
|
The buffer size will be set to <parameter class="function">size</parameter> bytes,
|
|
rounded up to a multiple of the virtual memory page
|
|
size. The virtual memory page size can be determined using
|
|
<code language="C">sysconf(_SC_PAGE_SIZE)</code>.
|
|
|
|
This function does not require special privileges. However,
|
|
it is limited to a (adjustable) maximum buffer size, which can
|
|
be changed by a privileged user calling
|
|
<function><link
|
|
linkend="func-ref-comedi-set-max-buffer-size">comedi_set_max_buffer_size</link></function>,
|
|
or running the program <command>comedi_config</command>.
|
|
Returns:
|
|
On success, <function>comedi_set_buffer_size</function> returns the new
|
|
buffer size in bytes.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_set_max_buffer_size -- streaming maximum buffer size of subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Param: unsigned int max_size
|
|
Description:
|
|
The function <function>comedi_set_max_buffer_size</function> changes the maximum
|
|
allowable size (in bytes) of the streaming buffer for the subdevice
|
|
specified by <parameter class="function">device</parameter> and
|
|
<parameter class="function">subdevice</parameter>. Changing the maximum buffer
|
|
size requires the user to have appropriate privileges.
|
|
Returns:
|
|
On success, <function>comedi_set_max_buffer_size</function> returns the new
|
|
maximum buffer size in bytes.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_set_read_subdevice -- set streaming input subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Status: Works for Linux "in-tree" Comedi since kernel version 3.19.
|
|
Description:
|
|
The function <function>comedi_set_read_subdevice</function> sets
|
|
<parameter class="function">subdevice</parameter> as the current
|
|
<quote>read</quote> subdevice if the subdevice supports streaming
|
|
input commands.
|
|
|
|
No action is performed if <parameter class="function">subdevice</parameter>
|
|
is already the current <quote>read</quote> subdevice.
|
|
|
|
Changes are local to the <emphasis>open file description</emphasis> for this
|
|
<parameter class="function">device</parameter> and have no effect on other
|
|
open file descriptions for the underlying device node.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|
|
|
|
Function: comedi_set_write_subdevice -- set streaming output subdevice
|
|
Retval: int
|
|
Param: comedi_t * device
|
|
Param: unsigned int subdevice
|
|
Status: Works for Linux "in-tree" Comedi since kernel version 3.19.
|
|
Description:
|
|
The function <function>comedi_set_write_subdevice</function> sets
|
|
<parameter class="function">subdevice</parameter> as the current
|
|
<quote>write</quote> subdevice if the subdevice supports streaming
|
|
output commands.
|
|
|
|
No action is performed if <parameter class="function">subdevice</parameter>
|
|
is already the current <quote>write</quote> subdevice.
|
|
|
|
Changes are local to the <emphasis>open file description</emphasis> for this
|
|
<parameter class="function">device</parameter> and have no effect on other
|
|
open file descriptions for the underlying device node.
|
|
Returns:
|
|
On success, <literal>0</literal> is returned.
|
|
On failure, <literal>-1</literal> is returned.
|