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