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 streaming input or output.  The
  21  command structure pointed to by the parameter command specifies the
  22  acquisition.  The command must be able to pass comedi_command_test()
  23  with a return value of 0, or comedi_command() will fail.
  24  For input subdevices, sample values are read using the
  25  function read().  For output subdevices, sample values are written
  26  using the function write().
  27
  28  If successful, 0 is returned, otherwise -1.
  29
  30 Function: comedi_command_test -- test streaming input/output configuration
  31 Retval: int
  32 Param: comedi_t * device
  33 Param: comedi_cmd * command
  34 Description:
  35  The function comedi_command_test() tests the command structure pointed
  36  to by the parameter command and returns an integer describing the
  37  testing stages that were successfully passed.  In addition, if elements
  38  of the command structure are invalid, they may be modified.  Source
  39  elements are modified to remove invalid source triggers.  Argument
  40  elements are adjusted or rounded to the nearest valid value.
  41
  42  The meanings of the return value are as follows.
  43
  44  0 indicates a valid command.
  45
  46  1 indicates that one of the *_src
  47  members of the command contained an
  48  unsupported trigger.  The bits corresponding to the unsupported
  49  triggers are zeroed.
  50
  51  2 indicates that the particular combination
  52  of *_src settings is not supported by the driver, or that
  53  one of the *_src members has the bit corresponding to
  54  multiple trigger sources set at the same time.
  55
  56  3 indicates that one of the *_arg members
  57  of the command is set outside the range of allowable values.
  58  For instance, an argument for a TRIG_TIMER source which
  59  exceeds the board's maximum speed.  The invalid *_arg
  60  members will be adjusted to valid values.
  61
  62  4 indicates that one of the *_arg members
  63  required adjustment.  For instance, the argument of a
  64  TRIG_TIMER source may have been rounded to the nearest
  65  timing period supported by the board.
  66
  67  5 indicates that some aspect of the
  68  command's chanlist is unsupported by the board.  For example,
  69  some board's require that all channels in the chanlist
  70  use the same range.
  71
  72 Function: comedi_get_buffer_contents -- streaming buffer status
  73 Retval: int
  74 Param: comedi_t * device
  75 Param: unsigned int subdevice
  76 Description:
  77  The function comedi_get_buffer_contents() is used on a subdevice
  78  that has a Comedi command in progress.  The number of bytes that
  79  are available in the streaming buffer is returned.  If there is
  80  an error, -1 is returned.
  81
  82 Function: comedi_get_buffer_offset -- streaming buffer status
  83 Retval: int
  84 Param: comedi_t * device
  85 Param: unsigned int subdevice
  86 Description:
  87  The function comedi_get_buffer_offset() is used on a subdevice
  88  that has a Comedi command in progress.  This function returns
  89  the offset in bytes of the read pointer in the streaming buffer.
  90  This offset is only useful for memory mapped buffers.
  91  If there is an error, -1 is returned.
  92
  93 Function: comedi_get_buffer_size -- streaming buffer size of subdevice
  94 Retval: int
  95 Param: comedi_t * device
  96 Param: unsigned int subdevice
  97 Description:
  98  The function comedi_get_buffer_size() returns the size (in bytes)
  99  of the streaming buffer for the subdevice specified by device and
 100  subdevice.  On error, -1 is returned.
 101
 102 Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities
 103 Retval: int
 104 Param: comedi_t * device
 105 Param: unsigned int subdevice
 106 Param: comedi_cmd * command
 107 Param: unsigned int chanlist_len
 108 Param: unsigned int scan_period_ns
 109 Description:
 110  The command capabilities of the subdevice indicated by the parameters
 111  device and subdevice are probed, and the results placed in the
 112  command structure pointed to by the parameter command.  The command
 113  structure pointed to by the parameter command is modified to be a
 114  valid command that can be used as a parameter to comedi_command()
 115  (after the command has been assigned a valid chanlist array).
 116  The command measures scans consisting of chanlist_len channels
 117  at a scan rate that corresponds to the
 118  period scan_period_ns.  The rate is adjusted to a rate that the device
 119  can handle.  If successful, 0 is returned, otherwise -1.
 120
 121 Function: comedi_get_cmd_src_mask -- streaming input/output capabilities
 122 Retval: int
 123 Param: comedi_t * device
 124 Param: unsigned int subdevice
 125 Param: comedi_cmd * command
 126 Description:
 127  The command capabilities of the subdevice indicated by the parameters
 128  device and subdevice are probed, and the results placed in the
 129  command structure pointed to by the parameter command.  The trigger
 130  source elements of the command structure are set to the logical OR
 131  value of possible trigger sources.  Other elements in the structure
 132  are undefined.  If successful, 0 is returned, otherwise -1.
 133
 134 Function: comedi_get_max_buffer_size -- maximum streaming buffer size
 135 Retval: int
 136 Param: comedi_t * device
 137 Param: unsigned int subdevice
 138 Description:
 139  The function comedi_get_max_buffer_size() returns the maximum
 140  allowable size (in bytes) of the streaming buffer for the subdevice
 141  specified by device and subdevice.  Changing the maximum buffer
 142  size requires appropriate privileges.  On error, -1 is returned.
 143
 144 Function: comedi_get_read_subdevice -- find streaming input subdevice
 145 Retval: int
 146 Param: comedi_t * device
 147 Description:
 148  The function comedi_get_read_subdevice() returns the subdevice
 149  that allows streaming input for device dev.  If no subdevice
 150  supports streaming input, -1 is returned and the Comedilib error
 151  number is set to XXX "subdevice not found".
 152
 153 Function: comedi_get_write_subdevice -- find streaming output subdevice
 154 Retval: int
 155 Param: comedi_t * device
 156 Description:
 157  The function comedi_get_write_subdevice() returns the subdevice
 158  that allows streaming output for device dev.  If no subdevice
 159  supports streaming output, -1 is returned and the Comedilib error
 160  number is set to XXX "subdevice not found".
 161
 162 Function: comedi_mark_buffer_read -- streaming buffer control
 163 Retval: int
 164 Param: comedi_t * device
 165 Param: unsigned int subdevice
 166 Param: unsigned int num_bytes
 167 Description:
 168  The function comedi_mark_buffer_read() is used on a subdevice
 169  that has a Comedi input command in progress.  It should only be used
 170  if you are using a mmap() (as opposed
 171  to calling read() on the device file) to read data from Comedi's buffer,
 172  since Comedi will automatically keep track of how many bytes have been
 173  transferred via read() calls.  This function is
 174  used to indicate that the next num_bytes bytes in the buffer
 175  are no longer needed and may be discarded.
 176 Returns:
 177  A return value ret greater than 0 indicates that the read offset in
 178  the streaming buffer, as returned by comedi_get_buffer_offset, has been
 179  incremented by ret bytes.  If there is an error, -1 is returned.
 180
 181 Function: comedi_mark_buffer_written -- streaming buffer control
 182 Retval: int
 183 Param: comedi_t * device
 184 Param: unsigned int subdevice
 185 Param: unsigned int num_bytes
 186 Description:
 187  The function comedi_mark_buffer_written() is used on a subdevice
 188  that has a Comedi output command in progress.  It should only be used
 189  if you are using a mmap() (as opposed to calling write() on the device
 190  file) to write data to Comedi's buffer, since Comedi
 191  will automatically keep track of how many bytes have been
 192  transferred via write() calls.  This function is
 193  used to indicate that the next num_bytes bytes in the buffer
 194  are valid and may be sent to the device.
 195  If there is an error, -1 is returned.
 196
 197 Function: comedi_poll -- force updating of streaming buffer
 198 Retval: int
 199 Param: comedi_t * device
 200 Param: unsigned int subdevice
 201 Description:
 202  The function comedi_poll() is used on a subdevice that has a
 203  Comedi command in progress in order to update the streaming buffer.
 204  If supported by the driver, all available samples are copied to
 205  the streaming buffer.  These samples may be pending in DMA buffers
 206  or device FIFOs.  If successful, the number of additional bytes
 207  available is returned.  If there is an error, -1 is returned.
 208
 209 Function: comedi_set_buffer_size -- streaming buffer size of subdevice
 210 Retval: int
 211 Param: comedi_t * device
 212 Param: unsigned int subdevice
 213 Param: unsigned int size
 214 Description:
 215  The function comedi_set_buffer_size() changes the size of the
 216  streaming buffer for the subdevice specified by device and subdevice.
 217  The parameter size must be a multiple of the virtual memory page
 218  size.
 219
 220  The virtual memory page size can be determined using
 221  sysconf(_SC_PAGE_SIZE).
 222
 223 Function: comedi_set_max_buffer_size -- streaming buffer size of subdevice
 224 Retval: int
 225 Param: comedi_t * device
 226 Param: unsigned int subdevice
 227 Param: unsigned int max_size
 228 Description:
 229  The function comedi_set_max_buffer_size() changes the maximum
 230  allowable size (in bytes) of the streaming buffer for the subdevice
 231  specified by device and subdevice.  Changing the maximum buffer
 232  size requires appropriate privileges.  If successful, the old buffer
 233  size is returned.  On error, -1 is returned.