doc/command_funcref.txt

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