doc/command_funcref.txt

   1 Asynchronous commands
   2 Function: comedi_cancel -- stop streaming input/output in progress
   3 Retval: int
   4 Param: comedi_t * device
   5 Param: unsigned int subdevice
   6 Description:
   7  The function <function>comedi_cancel</function> can be used to stop a command
   8  previously started by
   9  <function><link linkend="func-ref-comedi-command">comedi_command</link></function>
  10  which is still in progress
  11  on the subdevice indicated by the parameters <parameter class="function">device</parameter>
  12  and <parameter class="function">subdevice</parameter>.
  13 Returns:
  14  If successful, <literal>0</literal> is returned, otherwise
  15  <literal>-1</literal>.
  16
  17 Function: comedi_command -- start streaming input/output
  18 Retval: int
  19 Param: comedi_t * device
  20 Param: comedi_cmd * command
  21 Description:
  22  The function <function>comedi_command</function> starts a streaming input
  23  or output.  The
  24  command structure pointed to by <parameter class="function">command</parameter> specifies
  25  settings for the
  26  acquisition.  The command must be able to pass
  27  <function><link
  28  linkend="func-ref-comedi-command-test">comedi_command_test</link></function>
  29  with a return value of <literal>0</literal>, or
  30  <function>comedi_command</function> will fail.
  31  For input subdevices, sample values are read using the
  32  function <function>read</function> on the device file.  For output subdevices,
  33  sample values are written using the function <function>write</function>.
  34 Returns:
  35  If successful, <literal>0</literal> is returned, otherwise
  36  <literal>-1</literal>.
  37
  38 Function: comedi_command_test -- test streaming input/output configuration
  39 Retval: int
  40 Param: comedi_t * device
  41 Param: comedi_cmd * command
  42 Description:
  43  The function <function>comedi_command_test</function> tests the command structure pointed
  44  to by the parameter <parameter class="function">command</parameter> and returns an
  45  integer describing the
  46  testing stages that were successfully passed.  In addition, if elements
  47  of the <type>comedi_cmd</type> structure are invalid, they may be modified.  Source
  48  elements are modified to remove invalid source triggers.  Argument
  49  elements are adjusted or rounded to the nearest valid value.
  50
  51  The meanings of the return value are as follows:
  52
  53  <itemizedlist>
  54         <listitem>
  55                 <para><literal>0</literal> indicates a valid command.</para>
  56         </listitem>
  57         <listitem>
  58                 <para>
  59                         <literal>1</literal> indicates that one of the
  60                         <structfield>&hellip;_src</structfield>
  61                         members of the command contained an
  62                         unsupported trigger.  The bits corresponding to the unsupported
  63                         triggers are zeroed.
  64                 </para>
  65         </listitem>
  66         <listitem>
  67                 <para>
  68                         <literal>2</literal> indicates that the particular combination
  69                         of <structfield>&hellip;_src</structfield> settings is not supported by the driver, or that
  70                         one of the <structfield>&hellip;_src</structfield> members has the bit corresponding to
  71                         multiple trigger sources set at the same time.
  72                 </para>
  73         </listitem>
  74         <listitem>
  75                 <para>
  76                         <literal>3</literal> indicates that one of the
  77                         <structfield>&hellip;_arg</structfield> members
  78                         of the command is set outside the range of allowable values.
  79                         For instance, an argument for a
  80                         <constant>TRIG_TIMER</constant> source which
  81                         exceeds the board's maximum speed.  The invalid
  82                         <structfield>&hellip;_arg</structfield>
  83                         members will be adjusted to valid values.
  84                 </para>
  85         </listitem>
  86         <listitem>
  87                 <para>
  88                         <literal>4</literal> indicates that one of the
  89                         <structfield>&hellip;_arg</structfield> members
  90                         required adjustment.  For instance, the argument of a
  91                         <constant>TRIG_TIMER</constant> source may have been rounded to the nearest
  92                         timing period supported by the board.
  93                 </para>
  94         </listitem>
  95         <listitem>
  96                 <para>
  97                         <literal>5</literal> indicates that some aspect of the
  98                         command's <structfield>chanlist</structfield> is unsupported by the board.  For example,
  99                         some analog input boards require that all channels in the chanlist
 100                         use the same input range.
 101                 </para>
 102         </listitem>
 103         </itemizedlist>
 104
 105 Function: comedi_get_buffer_contents -- streaming buffer status
 106 Retval: int
 107 Param: comedi_t * device
 108 Param: unsigned int subdevice
 109 Description:
 110  The function <function>comedi_get_buffer_contents</function> is used on a subdevice
 111  that has a Comedi command in progress.  The number of bytes that
 112  are available in the streaming buffer is returned.  If there is
 113  an error, <literal>-1</literal> is returned.
 114
 115 Function: comedi_get_buffer_offset -- streaming buffer status
 116 Retval: int
 117 Param: comedi_t * device
 118 Param: unsigned int subdevice
 119 Description:
 120  The function <function>comedi_get_buffer_offset</function> is used on a subdevice
 121  that has a Comedi command in progress.  This function returns
 122  the offset in bytes of the read pointer in the streaming buffer.
 123  This offset is only useful for memory mapped buffers.
 124  If there is an error, <literal>-1</literal> is returned.
 125
 126 Function: comedi_get_buffer_size -- streaming buffer size of subdevice
 127 Retval: int
 128 Param: comedi_t * device
 129 Param: unsigned int subdevice
 130 Description:
 131  The function <function>comedi_get_buffer_size</function> returns the size (in bytes)
 132  of the streaming buffer for the subdevice specified by
 133  <parameter class="function">device</parameter> and
 134  <parameter class="function">subdevice</parameter>.
 135  On error, <literal>-1</literal> is returned.
 136
 137 Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities
 138 Retval: int
 139 Param: comedi_t * device
 140 Param: unsigned int subdevice
 141 Param: comedi_cmd * command
 142 Param: unsigned int chanlist_len
 143 Param: unsigned int scan_period_ns
 144 Description:
 145  The command capabilities of the subdevice indicated by the parameters
 146  <parameter class="function">device</parameter> and <parameter
 147  class="function">subdevice</parameter>
 148  are probed, and the results placed in the
 149  command structure pointed to by the parameter <parameter
 150  class="function">command</parameter>.
 151  The command structure pointed to by <parameter class="function">command</parameter>
 152  is modified to be a
 153  valid command that can be used as a parameter to
 154  <function><link linkend="func-ref-comedi-command">comedi_command</link></function>
 155  (after the command has additionally been assigned a valid
 156  <structfield>chanlist</structfield> array).
 157  The command measures scans consisting of <parameter class="function">chanlist_len</parameter>
 158  channels
 159  at a scan rate that corresponds to a period of
 160  <parameter class="function">scan_period_ns</parameter> nanoseconds.
 161  The rate is adjusted to a rate that the device
 162  can handle.
 163 Returns:
 164  If successful, <literal>0</literal> is returned, otherwise
 165  <literal>-1</literal>.
 166
 167 Function: comedi_get_cmd_src_mask -- streaming input/output capabilities
 168 Retval: int
 169 Param: comedi_t * device
 170 Param: unsigned int subdevice
 171 Param: comedi_cmd * command
 172 Description:
 173  The command capabilities of the subdevice indicated by the parameters
 174  <parameter class="function">device</parameter> and <parameter
 175  class="function">subdevice</parameter>
 176  are probed, and the results placed in the
 177  command structure pointed to by <parameter class="function">command</parameter>.  The trigger
 178  source elements of the command structure are set to be the bitwise-or
 179  of the subdevice's supported trigger sources.  Other elements in the structure
 180  are undefined.
 181 Returns:
 182  If successful, <literal>0</literal> is returned, otherwise
 183  <literal>-1</literal>.
 184
 185 Function: comedi_get_max_buffer_size -- maximum streaming buffer size
 186 Retval: int
 187 Param: comedi_t * device
 188 Param: unsigned int subdevice
 189 Description:
 190  The function <function>comedi_get_max_buffer_size</function> returns the maximum
 191  allowable size (in bytes) of the streaming buffer for the subdevice
 192  specified by <parameter class="function">device</parameter>
 193  and <parameter class="function">subdevice</parameter>.
 194  Changing the maximum buffer
 195  size can be accomplished with
 196  <function><link
 197  linkend="func-ref-comedi-set-max-buffer-size">comedi_set_max_buffer_size</link></function>
 198  or with the <command>comedi_config</command> program,
 199  and requires appropriate privileges.  On error, <literal>-1</literal> is returned.
 200
 201 Function: comedi_get_read_subdevice -- find streaming input subdevice
 202 Retval: int
 203 Param: comedi_t * device
 204 Description:
 205  The function <function>comedi_get_read_subdevice</function> returns the
 206  index of the subdevice
 207  whose streaming input buffer is accessible through the
 208  device <parameter class="function">device</parameter>.  If
 209  there is no such subdevice, <literal>-1</literal> is returned.
 210
 211 Function: comedi_get_write_subdevice -- find streaming output subdevice
 212 Retval: int
 213 Param: comedi_t * device
 214 Description:
 215  The function <function>comedi_get_write_subdevice</function> returns the
 216  index of the subdevice
 217  whose streaming output buffer is accessible through the
 218  device <parameter class="device">device</parameter>.  If there is no such subdevice,
 219  <literal>-1</literal> is returned.
 220
 221 Function: comedi_mark_buffer_read -- streaming buffer control
 222 Retval: int
 223 Param: comedi_t * device
 224 Param: unsigned int subdevice
 225 Param: unsigned int num_bytes
 226 Description:
 227  The function <function>comedi_mark_buffer_read</function> is used on a subdevice
 228  that has a Comedi input command in progress.  It should only be used
 229  if you are using a <function>mmap</function> mapping to read data from Comedi's buffer
 230  (as opposed to calling <function>read</function> on the device file),
 231  since Comedi will automatically keep track of how many bytes have been
 232  transferred via <function>read</function> calls.  This function is
 233  used to indicate that the next <parameter class="function">num_bytes</parameter>
 234  bytes in the buffer
 235  are no longer needed and may be discarded.
 236 Returns:
 237  The function <function>comedi_mark_buffer_read</function> returns the
 238  number of bytes successfully marked as read,
 239  or <literal>-1</literal> on error.  The return value may be less than
 240  <parameter class="function">num_bytes</parameter> if you attempt to mark more
 241  bytes read than are currently available for reading, or
 242  if <parameter class="function">num_bytes</parameter> must be rounded down
 243  to be an exact multiple of the subdevice's
 244  sample size (either <code language="C">sizeof(sampl_t)</code> or
 245  <code language="C">sizeof(lsampl_t)</code>).
 246
 247 Function: comedi_mark_buffer_written -- streaming buffer control
 248 Retval: int
 249 Param: comedi_t * device
 250 Param: unsigned int subdevice
 251 Param: unsigned int num_bytes
 252 Description:
 253  The function <function>comedi_mark_buffer_written</function> is used on a subdevice
 254  that has a Comedi output command in progress.  It should only be used
 255  if you are using a <function>mmap</function> mapping to write data to Comedi's buffer
 256  (as opposed to calling <function>write</function> on the device
 257  file), since Comedi
 258  will automatically keep track of how many bytes have been
 259  transferred via <function>write</function> calls.  This function is
 260  used to indicate that the next <parameter class="function">num_bytes</parameter>
 261  bytes in the buffer
 262  are valid and may be sent to the device.
 263 Returns:
 264  The function <function>comedi_mark_buffer_written</function> returns
 265  number of bytes successfully marked as written,
 266  or <literal>-1</literal> on error.  The return value may be less than
 267  <parameter class="function">num_bytes</parameter> if you attempt to mark more
 268  bytes written than the amount of free space currently available
 269  in the output buffer, or
 270  if <parameter class="function">num_bytes</parameter> must be
 271  rounded down to be an exact multiple of the subdevice's
 272  sample size (either <code language="C">sizeof(sampl_t)</code>
 273  or <code language="C">sizeof(lsampl_t)</code>).
 274
 275 Function: comedi_poll -- force updating of streaming buffer
 276 Retval: int
 277 Param: comedi_t * device
 278 Param: unsigned int subdevice
 279 Description:
 280  The function <function>comedi_poll</function> is used on a subdevice that has a
 281  Comedi command in progress in order to update the streaming buffer.
 282  If supported by the driver, all available samples are copied to
 283  the streaming buffer.  These samples may be pending in DMA buffers
 284  or device FIFOs.  If successful, the number of additional bytes
 285  available is returned.  If there is an error, <literal>-1</literal> is returned.
 286
 287 Function: comedi_set_buffer_size -- streaming buffer size of subdevice
 288 Retval: int
 289 Param: comedi_t * device
 290 Param: unsigned int subdevice
 291 Param: unsigned int size
 292 Description:
 293  The function <function>comedi_set_buffer_size</function> changes the size of the
 294  streaming buffer for the subdevice specified by
 295  <parameter class="function">device</parameter> and <parameter
 296  class="function">subdevice</parameter>.
 297  The buffer size will be set to <parameter class="function">size</parameter> bytes,
 298  rounded up to a multiple of the virtual memory page
 299  size.  The virtual memory page size can be determined using
 300  <code language="C">sysconf(_SC_PAGE_SIZE)</code>.
 301
 302  This function does not require special privileges.  However,
 303  it is limited to a (adjustable) maximum buffer size, which can
 304  be changed by a privileged user calling
 305  <function><link
 306  linkend="func-ref-comedi-set-max-buffer-size">comedi_set_max_buffer_size</link></function>,
 307  or running the program <command>comedi_config</command>.
 308 Returns:
 309  The new buffer size in bytes is returned on success.  On error,
 310  <literal>-1</literal> is returned.
 311
 312 Function: comedi_set_max_buffer_size -- streaming maximum buffer size of subdevice
 313 Retval: int
 314 Param: comedi_t * device
 315 Param: unsigned int subdevice
 316 Param: unsigned int max_size
 317 Description:
 318  The function <function>comedi_set_max_buffer_size</function> changes the maximum
 319  allowable size (in bytes) of the streaming buffer for the subdevice
 320  specified by <parameter class="function">device</parameter> and
 321  <parameter class="function">subdevice</parameter>.  Changing the maximum buffer
 322  size requires the user to have appropriate privileges.
 323 Returns:
 324  The new maximum buffer size is returned on success.  On error, <literal>-1</literal> is returned.