doc/funcref

   1 Core Functions
   2 Function: comedi_close -- close a Comedi device
   3 Retval: int
   4 Param: comedi * device
   5 Description:
   6  Close a device previously opened by
   7  <function><link linkend="func-ref-comedi-open">comedi_open</link></function>.
   8 Returns:
   9  If successful, <function>comedi_close</function> returns <literal>0</literal>.
  10  On failure, <literal>-1</literal> is returned.
  11
  12 Function: comedi_data_read -- read single sample from channel
  13 Retval: int
  14 Param: comedi_t * device
  15 Param: unsigned int subdevice
  16 Param: unsigned int channel
  17 Param: unsigned int range
  18 Param: unsigned int aref
  19 Param: lsampl_t * data
  20 Description:
  21  Reads a single sample on the channel specified by the Comedi
  22  device <parameter class="function">device</parameter>, the subdevice
  23  <parameter class="function">subdevice</parameter>, and the channel
  24  <parameter class="function">channel</parameter>.
  25  For the A/D conversion (if appropriate),
  26  the device is configured to use range specification
  27  <parameter class="function">range</parameter> and (if appropriate) analog
  28  reference type <parameter class="function">aref</parameter>.
  29  Analog reference types that are not supported
  30  by the device are silently ignored.
  31
  32  The function <function>comedi_data_read</function> reads one data value from
  33  the specified channel and stores the value in
  34  <code>*<parameter class="function">data</parameter></code>.
  35
  36  WARNING: <function>comedi_data_read</function> does not do any pausing to
  37  allow multiplexed analog inputs to settle before
  38  starting an analog to digital conversion.  If you are
  39  switching between different channels and need to allow
  40  your analog input to settle for an accurate reading,
  41  use
  42  <function><link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link></function>,
  43  or set the
  44  input channel at an earlier time with
  45  <function><link linkend="func-ref-comedi-data-read-hint">comedi_data_read_hint</link></function>.
  46
  47  Data values returned by this function are unsigned integers
  48  less than or equal to the maximum sample value of the channel,
  49  which can be determined using the function
  50  <function><link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link></function>.
  51  Conversion of data values to physical units can be performed
  52  by the functions <function><link linkend="func-ref-comedi-to-phys">comedi_to_phys</link></function> (linear conversion) or <function><link linkend="func-ref-comedi-to-physical">comedi_to_physical</link></function> (non-linear polynomial conversion).
  53 Returns:
  54  On success, <function>comedi_data_read</function> returns <literal>1</literal> (the number of samples
  55  read).  If there is an error, <literal>-1</literal> is returned.
  56
  57 Function: comedi_data_read_n -- read multiple samples from channel
  58 Retval: int
  59 Param: comedi_t * device
  60 Param: unsigned int subdevice
  61 Param: unsigned int channel
  62 Param: unsigned int range
  63 Param: unsigned int aref
  64 Param: lsampl_t * data
  65 Param: unsigned int n
  66 Description:
  67  Similar to
  68  <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>
  69  except it reads <parameter class="function">n</parameter> samples into the
  70  array <parameter class="function">data</parameter>.
  71  The precise timing of the samples is not hardware controlled.
  72
  73 Function: comedi_data_read_delayed -- read single sample from channel after delaying for specified settling time
  74 Retval: int
  75 Param: comedi_t * device
  76 Param: unsigned int subdevice
  77 Param: unsigned int channel
  78 Param: unsigned int range
  79 Param: unsigned int aref
  80 Param: lsampl_t * data
  81 Param: unsigned int nanosec
  82 Description:
  83  Similar to
  84  <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>
  85  except it will wait for the
  86  specified number of nanoseconds between setting the input
  87  channel and taking a sample.  For analog inputs, most
  88  boards have a single
  89  analog to digital converter which is multiplexed to be
  90  able to read multiple channels.  If the input is not allowed
  91  to settle after the multiplexer switches channels, the
  92  reading will be inaccurate.  This function is useful
  93  for allowing a multiplexed analog input to settle
  94  when switching channels.
  95
  96  Although the settling time is specified in nanoseconds, the
  97  actual settling time will be rounded up to the nearest
  98  microsecond.
  99
 100 Function: comedi_data_read_hint -- tell driver which channel/range/aref you are going to read from next
 101 Retval: int
 102 Param: comedi_t * device
 103 Param: unsigned int subdevice
 104 Param: unsigned int channel
 105 Param: unsigned int range
 106 Param: unsigned int aref
 107 Description:
 108  Used to prepare an analog input for a subsequent call to
 109  <function><link linkend="func-ref-comedi-data-read">comedi_data_read</link></function>.
 110  It is not necessary to use this
 111  function, but it can be useful for eliminating inaccuracies
 112  caused by insufficient settling times when switching the
 113  channel
 114  or gain on an analog input.  This function sets an analog input
 115  to the channel, range, and aref specified but does not
 116  perform an actual analog to digital conversion.
 117
 118  Alternatively, one can simply use
 119  <function><link linkend="func-ref-comedi-data-read-delayed">comedi_data_read_delayed</link></function>,
 120  which sets up the
 121  input, pauses to allow settling, then performs a conversion.
 122
 123 Function: comedi_data_write -- write single sample to channel
 124 Retval: int
 125 Param: comedi_t * device
 126 Param: unsigned int subdevice
 127 Param: unsigned int channel
 128 Param: unsigned int range
 129 Param: unsigned int aref
 130 Param: lsampl_t data
 131 Description:
 132  Writes a single sample on the channel that is specified by the
 133  Comedi device <parameter class="function">device</parameter>, the subdevice
 134  <parameter class="function">subdevice</parameter>, and the channel
 135  <parameter class="function">channel</parameter>.  If appropriate, the device is
 136  configured to use range
 137  specification <parameter class="function">range</parameter> and analog
 138  reference type <parameter class="function">aref</parameter>.  Analog
 139  reference types that are not supported by the device are
 140  silently ignored.
 141
 142  The function <function>comedi_data_write</function> writes the data value specified
 143  by the parameter <parameter class="function">data</parameter> to the specified channel.
 144 Returns:
 145  On success, <function>comedi_data_write</function> returns <literal>1</literal> (the number of samples
 146  written).  If there is an error, <literal>-1</literal> is returned.
 147
 148 Function: comedi_do_insn -- perform instruction
 149 Retval: int
 150 Param: comedi_t * device
 151 Param: comedi_insn * instruction
 152 Description:
 153  The function <function>comedi_do_insn</function> performs a single instruction.
 154 Returns:
 155  If successful, returns a non-negative number.  For the case
 156  of <constant>INSN_READ</constant> or <constant>INSN_WRITE</constant> instructions,
 157  <function>comedi_do_insn</function> returns the number of samples
 158  read or written, which may be less than the number requested.
 159  If there is an error, <literal>-1</literal> is returned.
 160
 161 Function: comedi_do_insnlist -- perform multiple instructions
 162 Retval: int
 163 Param: comedi_t * device
 164 Param: comedi_insnlist * list
 165 Description:
 166  The function <function>comedi_do_insnlist</function> performs multiple Comedi
 167  instructions as part of one system call. This function
 168  can be used to avoid the overhead of multiple
 169  system calls.
 170 Returns:
 171  The function <function>comedi_do_insnlist</function> returns the number of
 172  successfully completed instructions.  Error information for
 173  the unsuccessful instruction is not available.  If there is
 174  an error before the first instruction can be executed, <literal>-1</literal>
 175  is returned.
 176
 177 Function: comedi_fileno -- get file descriptor for open Comedilib device
 178 Retval: int
 179 Param: comedi_t * device
 180 Description:
 181  The function <function>comedi_fileno</function> returns the file descriptor for
 182  the device <parameter class="function">device</parameter>.  This descriptor can then be used as the
 183  file descriptor parameter of <function>read</function>, <function>write</function>, etc.
 184  This function is intended to mimic the standard C library
 185  function <function>fileno</function>.
 186
 187  The returned file descriptor should not be closed, and will
 188  become invalid when
 189  <function><link linkend="func-ref-comedi-close">comedi_close</link></function>
 190  is called on <parameter class="function">device</parameter>.
 191 Returns:
 192  A file descriptor, or <literal>-1</literal> on error.
 193
 194 Function: comedi_find_range -- search for range
 195 Retval: int
 196 Param: comedi_t * device
 197 Param: unsigned int subdevice
 198 Param: unsigned int channel
 199 Param: unsigned int unit
 200 Param: double min
 201 Param: double max
 202 Description:
 203  The function <function>comedi_find_range</function> tries to
 204  locate the optimal (smallest) range for the channel
 205  <parameter class="function">channel</parameter>
 206  belonging to subdevice <parameter class="function">subdevice</parameter>
 207  of the comedi device <parameter class="function">device</parameter>,
 208  that includes both <parameter class="function">min</parameter>
 209  and <parameter class="function">max</parameter> in
 210  units of <parameter class="function">unit</parameter>.
 211 Returns:
 212  If a matching range is found, the index of the matching range is
 213  returned.  If no matching range is available, the function returns
 214  <literal>-1</literal>.
 215
 216 Function: comedi_find_subdevice_by_type -- search for subdevice type
 217 Retval: int
 218 Param: comedi_t * device
 219 Param: int type
 220 Param: unsigned int start_subdevice
 221 Description:
 222  The function <function>comedi_find_subdevice_by_type</function> tries to
 223  locate a subdevice belonging to comedi device
 224  <parameter class="function">device</parameter>,
 225  having type <parameter class="function">type</parameter>, starting with
 226  the subdevice <parameter class="function">start_subdevice</parameter>. The
 227  <type><link linkend="ref-enum-comedi-subdevice-type">comedi_subdevice_type</link></type> enum
 228  specifies the possible subdevice types.
 229
 230 Returns:
 231  If it finds a subdevice with the requested
 232  type, it returns its index.  If there is an error, the function
 233  returns <literal>-1</literal> and sets the appropriate error.
 234
 235 Function: comedi_from_phys -- convert physical units to sample
 236 Retval: lsampl_t
 237 Param: double data
 238 Param: comedi_range * range
 239 Param: lsampl_t maxdata
 240 Description:
 241  Converts parameter <parameter class="function">data</parameter> given in
 242  physical units (<type>double</type>) into sample values
 243  (<type>lsampl_t</type>, between <literal>0</literal> and maxdata).
 244  The parameter <parameter class="function">range</parameter>
 245  represents the conversion information to use, and the parameter
 246  <parameter class="function">maxdata</parameter> represents the maximum possible data value for the
 247  channel that the data will be written to. The mapping between
 248  physical units and raw data is linear and
 249  assumes that the converter has ideal characteristics.
 250
 251  Conversion is not affected by out-of-range behavior.  Out-of-range
 252  data parameters are silently truncated to the range <literal>0</literal>
 253  to <parameter class="function">maxdata</parameter>.
 254
 255 Function: comedi_from_physical -- convert physical units to sample using calibration data
 256 Retval: lsampl_t
 257 Param: double data
 258 Param: const comedi_polynomial_t * conversion_polynomial
 259 Description:
 260  Converts <parameter class="function">data</parameter> given in physical units into Comedi's
 261  integer sample values
 262  (<type>lsampl_t</type>, between <literal>0</literal> and maxdata &mdash;
 263  see <function><link linkend="func-ref-comedi-get-maxdata">comedi_get_maxdata</link></function>).
 264  The <parameter class="function">conversion_polynomial</parameter>
 265  parameter is obtained from either
 266  <function><link linkend="func-ref-comedi-get-hardcal-converter">comedi_get_hardcal_converter</link></function> or
 267  <function><link linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>. The allows non linear and board specific
 268  correction.
 269  The result will be rounded
 270  using the C library's current rounding direction.
 271  No range checking of the input
 272  <parameter class="function">data</parameter> is performed.  It is up to you to ensure
 273  your data is within the limits of the output range you are using.
 274 Returns:
 275  Comedi sample value corresponding to input physical value.
 276
 277 Function: comedi_get_board_name -- Comedi device name
 278 Retval: const char *
 279 Param: comedi_t * device
 280 Description:
 281  The function <function>comedi_get_board_name</function> returns a pointer
 282  to a string containing the name of the comedi device represented by
 283  <parameter class="function">device</parameter>.  This pointer is
 284  valid until the device is closed.  This
 285  function returns <constant>NULL</constant> if there is an error.
 286
 287 Function: comedi_get_driver_name -- Comedi driver name
 288 Retval: char *
 289 Param: comedi_t * device
 290 Description:
 291  The function <function>comedi_get_driver_name</function> returns a pointer
 292  to a string containing the name of the driver being used by comedi
 293  for the comedi device represented by <parameter class="function">device</parameter>.  This pointer is
 294  valid until the device is closed.  This function returns <constant>NULL</constant>
 295  if there is an error.
 296
 297 Function: comedi_get_maxdata -- maximum sample of channel
 298 Retval: lsampl_t
 299 Param: comedi_t * device
 300 Param: unsigned int subdevice
 301 Param: unsigned int channel
 302 Description:
 303  The function <function>comedi_get_maxdata</function> returns the maximum
 304  valid data value for channel <parameter class="function">channel</parameter>
 305  of subdevice <parameter clas="function">subdevice</parameter> belonging to
 306  the comedi device <parameter class="function">device</parameter>.
 307 Returns:
 308  The maximum valid sample value, or <literal>0</literal> on error.
 309
 310 Function: comedi_get_n_channels -- number of subdevice channels
 311 Retval: int
 312 Param: comedi_t * device
 313 Param: unsigned int subdevice
 314 Description:
 315  The function <function>comedi_get_n_channels</function> returns the number
 316  of channels of the subdevice <parameter class="function">subdevice</parameter>
 317  belonging to the comedi device <parameter class="function">device</parameter>.
 318  This function returns <literal>-1</literal> on error and
 319  the Comedilib error value is set.
 320
 321 Function: comedi_get_n_ranges -- number of ranges of channel
 322 Retval: int
 323 Param: comedi_t * device
 324 Param: unsigned int subdevice
 325 Param: unsigned int channel
 326 Description:
 327  The function <function>comedi_get_n_ranges</function> returns the number
 328  of ranges of the channel <parameter class="function">channel</parameter>
 329  belonging to the subdevice <parameter class="function">subdevice</parameter>
 330  of the comedi device <parameter class="function">device</parameter>.
 331  This function returns <literal>-1</literal> on error.
 332
 333 Function: comedi_get_n_subdevices -- number of subdevices
 334 Retval: int
 335 Param: comedi_t * device
 336 Description:
 337  The function <function>comedi_get_n_subdevices</function> returns the number
 338  of subdevices belonging to the Comedi
 339  device referenced by the parameter <parameter class="function">device</parameter>,
 340  or <literal>-1</literal> on error.
 341
 342 Function: comedi_get_range -- range information of channel
 343 Retval: comedi_range *
 344 Param: comedi_t * device
 345 Param: unsigned int subdevice
 346 Param: unsigned int channel
 347 Param: unsigned int range
 348 Description:
 349  The function <function>comedi_get_range</function> returns a pointer to a
 350  <type><link linkend="ref-type-comedi-range">comedi_range</link></type>
 351  structure that contains information on
 352  the range specified by the <parameter class="function">subdevice</parameter>,
 353  <parameter class="function">channel</parameter>,
 354  and <parameter class="function">range</parameter> parameters.
 355  The pointer is valid until the Comedi device
 356  <parameter class="function">device</parameter> is closed.
 357  If there is an error, <constant>NULL</constant> is returned.
 358
 359 Function: comedi_get_subdevice_flags -- properties of subdevice
 360 Retval: int
 361 Param: comedi_t * device
 362 Param: unsigned int subdevice
 363 Description:
 364  The function <function>comedi_get_subdevice_flags</function>
 365  returns a bitfield describing the capabilities of
 366  the specified subdevice <parameter class="function">subdevice</parameter>
 367  of the Comedi device <parameter class="function">device</parameter>.
 368  If there is an error, <literal>-1</literal> is returned,
 369  and the Comedilib error value is set.
 370
 371  <informaltable colsep="1" rowsep="1" orient="port" pgwide="1">
 372  <tgroup cols="3" align="left" >
 373  <thead>
 374  <row>
 375  <entry>Subdevice Flag</entry>
 376  <entry>Value (hex)</entry>
 377  <entry>Description</entry>
 378  </row>
 379  </thead>
 380  <tbody>
 381  <row>
 382  <entry><constant>SDF_BUSY</constant></entry>
 383  <entry><literal>0x00000001</literal></entry>
 384  <entry>The subdevice is busy performing an asynchronous command.
 385  A subdevice being <quote>busy</quote>
 386  is slightly different from the <quote>running</quote> state flagged by
 387  <constant>SDF_RUNNING</constant>.  A <quote>running</quote> subdevice
 388  is always <quote>busy</quote>, but a <quote>busy</quote> subdevice is
 389  not necessarily <quote>running</quote>.  For example, suppose an
 390  analog input command has been completed by the hardware, but there are still samples in
 391  Comedi's buffer waiting to be read out.  In this case, the subdevice is not
 392  <quote>running</quote>, but is still <quote>busy</quote> until all the
 393  samples are read out or <function><link linkend="func-ref-comedi-cancel">comedi_cancel</link></function> is called.</entry>
 394  </row>
 395  <row>
 396  <entry><constant>SDF_BUSY_OWNER</constant></entry>
 397  <entry><literal>0x00000002</literal></entry>
 398  <entry>The subdevice is <quote>busy</quote>, and the command it is running was started by the current process.</entry>
 399  </row>
 400  <row>
 401  <entry><constant>SDF_LOCKED</constant></entry>
 402  <entry><literal>0x00000004</literal></entry>
 403  <entry>The subdevice has been locked by <function><link linkend="func-ref-comedi-lock">comedi_lock</link></function>.</entry>
 404  </row>
 405  <row>
 406  <entry><constant>SDF_LOCK_OWNER</constant></entry>
 407  <entry><literal>0x00000008</literal></entry>
 408  <entry>The subdevice is locked, and was locked by the current process.</entry>
 409  </row>
 410  <row>
 411  <entry><constant>SDF_MAXDATA</constant></entry>
 412  <entry><literal>0x00000010</literal></entry>
 413  <entry>The maximum data value for the subdevice depends on the channel.</entry>
 414  </row>
 415  <row>
 416  <entry><constant>SDF_FLAGS</constant></entry>
 417  <entry><literal>0x00000020</literal></entry>
 418  <entry>The subdevice flags depend on the channel (unfinished/broken support in library).</entry>
 419  </row>
 420  <row>
 421  <entry><constant>SDF_RANGETYPE</constant></entry>
 422  <entry><literal>0x00000040</literal></entry>
 423  <entry>The range type depends on the channel.</entry>
 424  </row>
 425  <row>
 426  <entry><constant>SDF_CMD</constant></entry>
 427  <entry><literal>0x00001000</literal></entry>
 428  <entry>The subdevice supports asynchronous commands.</entry>
 429  </row>
 430  <row>
 431  <entry><constant>SDF_SOFT_CALIBRATED</constant></entry>
 432  <entry><literal>0x00002000</literal></entry>
 433  <entry>The subdevice relies on the host to do calibration in software.
 434  Software calibration coefficients are determined by the <command>comedi_soft_calibrate</command>
 435  utility.  See the description of the
 436  <function><link linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function> function
 437  for more information.
 438  </entry>
 439  </row>
 440  <row>
 441  <entry><constant>SDF_READABLE</constant></entry>
 442  <entry><literal>0x00010000</literal></entry>
 443  <entry>The subdevice can be read (e.g. analog input).</entry>
 444  </row>
 445  <row>
 446  <entry><constant>SDF_WRITABLE</constant></entry>
 447  <entry><literal>0x00020000</literal></entry>
 448  <entry>The subdevice can be written to (e.g. analog output).</entry>
 449  </row>
 450  <row>
 451  <entry><constant>SDF_INTERNAL</constant></entry>
 452  <entry><literal>0x00040000</literal></entry>
 453  <entry>The subdevice does not have externally visible lines.</entry>
 454  </row>
 455  <row>
 456  <entry><constant>SDF_GROUND</constant></entry>
 457  <entry><literal>0x00100000</literal></entry>
 458  <entry>The subdevice supports analog reference <constant>AREF_GROUND</constant>.</entry>
 459  </row>
 460  <row>
 461  <entry><constant>SDF_COMMON</constant></entry>
 462  <entry><literal>0x00200000</literal></entry>
 463  <entry>The subdevice supports analog reference <constant>AREF_COMMON</constant>.</entry>
 464  </row>
 465  <row>
 466  <entry><constant>SDF_DIFF</constant></entry>
 467  <entry><literal>0x00400000</literal></entry>
 468  <entry>The subdevice supports analog reference <constant>AREF_DIFF</constant>.</entry>
 469  </row>
 470  <row>
 471  <entry><constant>SDF_OTHER</constant></entry>
 472  <entry><literal>0x00800000</literal></entry>
 473  <entry>The subdevice supports analog reference <constant>AREF_OTHER</constant></entry>
 474  </row>
 475  <row>
 476  <entry><constant>SDF_DITHER</constant></entry>
 477  <entry><literal>0x01000000</literal></entry>
 478  <entry>The subdevice supports dithering (via the <constant>CR_ALT_FILTER</constant> chanspec flag).</entry>
 479  </row>
 480  <row>
 481  <entry><constant>SDF_DEGLITCH</constant></entry>
 482  <entry><literal>0x02000000</literal></entry>
 483  <entry>The subdevice supports deglitching (via the <constant>CR_ALT_FILTER</constant> chanspec flag).</entry>
 484  </row>
 485  <row>
 486  <entry><constant>SDF_RUNNING</constant></entry>
 487  <entry><literal>0x08000000</literal></entry>
 488  <entry>An asynchronous command is running.  You can use this flag to poll for the completion of an
 489  output command.</entry>
 490  </row>
 491  <row>
 492  <entry><constant>SDF_LSAMPL</constant></entry>
 493  <entry><literal>0x10000000</literal></entry>
 494  <entry>The subdevice uses the 32-bit <type>lsampl_t</type> type instead of
 495  the 16-bit <type>sampl_t</type> for
 496  asynchronous command data.</entry>
 497  </row>
 498  <row>
 499  <entry><constant>SDF_PACKED</constant></entry>
 500  <entry><literal>0x20000000</literal></entry>
 501  <entry>The subdevice uses bitfield samples for asynchronous command data,
 502  one bit per channel (otherwise it uses
 503  one <type>sampl_t</type> or <type>lsampl_t</type> per channel).
 504  Commonly used for digital subdevices.</entry>
 505  </row>
 506  </tbody>
 507  </tgroup>
 508  </informaltable>
 509
 510 Function: comedi_get_subdevice_type -- type of subdevice
 511 Retval: int
 512 Param: comedi_t * device
 513 Param: unsigned int subdevice
 514 Description:
 515  The function <function>comedi_get_subdevice_type</function> returns an
 516  integer describing the type of subdevice that belongs to the comedi
 517  device <parameter class="function">device</parameter> and has the subdevice index
 518  <parameter class="function">subdevice</parameter>.  The
 519  <type><link linkend="ref-enum-comedi-subdevice-type">comedi_subdevice_type</link></type> enum
 520  specifies the possible values for the subdevice type.
 521 Returns:
 522  The function returns the subdevice type, or
 523  <literal>-1</literal> if there is an error.
 524
 525 Function: comedi_get_version_code -- Comedi version code
 526 Retval: int
 527 Param: comedi_t * device
 528 Description:
 529  Returns the Comedi kernel module version code.  A valid Comedi
 530  device referenced by the parameter <parameter class="function">device</parameter>
 531  is necessary to
 532  communicate with the kernel module.  On error, <literal>-1</literal> is returned.
 533
 534  The version code is encoded as a bitfield of three 8-bit
 535  numbers.  For example, <literal>0x00073d</literal> is the version code for
 536  version 0.7.61.
 537
 538  This function is of limited usefulness.  A typical
 539  mis-application of this function is to use it to determine
 540  if a certain feature is supported.  If the application needs
 541  to know of the existence of a particular feature, an existence
 542  test function should be written and put in the Comedilib source.
 543
 544 Function: comedi_internal_trigger -- generate soft trigger
 545 Retval: int
 546 Param: comedi_t * device
 547 Param: unsigned int subdevice
 548 Param: unsigned int trig_num
 549 Description:
 550  This function sends an <constant>INSN_INTTRIG</constant> instruction to a subdevice, which causes an internal triggering event.
 551  This event can, for example, trigger a subdevice to start an asynchronous command.
 552
 553  The <parameter class="function">trig_num</parameter> parameter is reserved for future use, and should be set to 0.
 554  It is likely it will be used in the future to support multiple independent internal triggers.
 555  For example, an asynchronous command might be specified for a subdevice
 556  with a <structfield>start_src</structfield> of <constant>TRIG_INT</constant>,
 557  and a <structfield>start_arg</structfield> of <literal>5</literal>.
 558  Then the start event would only be triggered if <function>comedi_internal_trigger</function>
 559  were called on the subdevice with a <parameter class="function">trig_num</parameter>
 560  equal to the same value of <literal>5</literal>.
 561 Returns:
 562  <literal>0</literal> on success, <literal>-1</literal> on error.
 563
 564 Function: comedi_lock -- subdevice reservation
 565 Retval: int
 566 Param: comedi_t * device
 567 Param: unsigned int subdevice
 568 Description:
 569  The function <function>comedi_lock</function> reserves a subdevice for use by the
 570  current process.  While the lock is held, no other process is
 571  allowed to read, write, or configure that subdevice, although
 572  other processes can read information about the subdevice.  The
 573  lock is released by
 574  <function><link linkend="func-ref-comedi-unlock">comedi_unlock</link></function>,
 575  or when
 576  <function><link linkend="func-ref-comedi-close">comedi_close</link></function>
 577  is called on <parameter class="function">device</parameter>.
 578 Returns:
 579  If successful, <literal>0</literal> is returned.  If there is an error,
 580  <literal>-1</literal> is returned.
 581
 582 Function: comedi_maxdata_is_chan_specific -- maximum sample depends on channel
 583 Retval: int
 584 Param: comedi_t * device
 585 Param: unsigned int subdevice
 586 Description:
 587  If each channel of the specified subdevice may have different maximum
 588  sample values, this function returns <literal>1</literal>.  Otherwise, this function
 589  returns <literal>0</literal>.  On error, this function returns <literal>-1</literal>.
 590
 591 Function: comedi_open -- open a Comedi device
 592 Retval: comedi_t *
 593 Param: const char * filename
 594 Description:
 595  Open a Comedi device specified by the file filename.
 596 Returns:
 597  If successful, <function>comedi_open</function> returns a pointer to
 598  a valid <type>comedi_t</type>
 599  structure.  This structure is opaque; the pointer should not
 600  be dereferenced by the application.  <constant>NULL</constant> is returned on failure.
 601
 602 Function: comedi_range_is_chan_specific -- range information depends on channel
 603 Retval: int
 604 Param: comedi_t * device
 605 Param: unsigned int subdevice
 606 Description:
 607  If each channel of the specified subdevice may have different range
 608  information, this function returns <literal>1</literal>.  Otherwise, this function
 609  returns <literal>0</literal>.  On error, this function returns <literal>-1</literal>.
 610
 611 Function: comedi_set_global_oor_behavior -- out-of-range behavior
 612 Retval: enum comedi_oor_behavior
 613 Param: enum comedi_oor_behavior behavior
 614 Description:
 615  This function changes the Comedilib out-of-range behavior.
 616  This currently affects the behavior of
 617  <function><link linkend="func-ref-comedi-to-phys">comedi_to_phys</link></function>
 618  when converting endpoint sample values, that is, sample values
 619  equal to <literal>0</literal> or <parameter
 620  class="function">maxdata</parameter>.  If the out-of-range behavior is set to
 621  <constant>COMEDI_OOR_NAN</constant>, endpoint values are converted to
 622  <constant>NAN</constant>.  If the
 623  out-of-range behavior is set to <constant>COMEDI_OOR_NUMBER</constant>, the endpoint
 624  values are converted similarly to other values.
 625 Returns:
 626  The previous out-of-range behavior is returned.
 627
 628 Function: comedi_to_phys -- convert sample to physical units
 629 Retval: double
 630 Param: lsampl_t data
 631 Param: comedi_range * range
 632 Param: lsampl_t maxdata
 633 Description:
 634  Converts parameter <parameter class="function">data</parameter> given in sample values
 635  (<type>lsampl_t</type>, between <literal>0</literal> and
 636  <parameter class="function">maxdata</parameter>) into physical units
 637  (<type>double</type>). The parameter <parameter
 638  class="function">range</parameter>
 639  represents the conversion information to use, and the parameter
 640  <parameter class="function">maxdata</parameter> represents the maximum possible data value for the
 641  channel that the data was read. The mapping between physical units
 642  is linear and assumes ideal converter characteristics.
 643
 644  Conversion of endpoint sample values, that is, sample values
 645  equal to <literal>0</literal> or <parameter class="function">maxdata</parameter>,
 646  is affected by the Comedilib out-of-range
 647  behavior (see function <function><link
 648  linkend="func-ref-comedi-set-global-oor-behavior"
 649  >comedi_set_global_oor_behavior></link></function>).
 650  If the out-of-range behavior is set to
 651  <constant>COMEDI_OOR_NAN</constant>,
 652  endpoint values are converted to <constant>NAN</constant>.  If the out-of-range
 653  behavior is set to <constant>COMEDI_OOR_NUMBER</constant>, the endpoint values are
 654  converted similarly to other values.
 655
 656  If there is an error, <constant>NAN</constant> is returned.
 657
 658 Function: comedi_to_physical -- convert sample to physical units using polynomials
 659 Retval: double
 660 Param: lsampl_t data
 661 Param: const comedi_polynomial_t * conversion_polynomial
 662 Description:
 663  Converts <parameter class="function">data</parameter> given in Comedi's integer
 664  sample values (<type>lsampl_t</type>, between <literal>0</literal> and
 665  maxdata) into physical units (<type>double</type>).  The
 666  <parameter class="functioN">conversion_polynomial</parameter>
 667  parameter is obtained from either
 668  <function><link linkend="func-ref-comedi-get-hardcal-converter">comedi_get_hardcal_converter</link></function> or
 669  <function><link linkend="func-ref-comedi-get-softcal-converter">comedi_get_softcal_converter</link></function>.
 670  No range checking of the
 671  input <parameter class="function">data</parameter> is performed.  It is up to
 672  you to check for <parameter class="function">data</parameter> values of
 673  0 or maxdata if you want to detect possibly out-of-range readings.
 674 Returns:
 675  Physical value corresponding to the input sample value.
 676
 677 Function: comedi_unlock -- subdevice reservation
 678 Retval: int
 679 Param: comedi_t * device
 680 Param: unsigned int subdevice
 681 Description:
 682  The function <function>comedi_unlock</function> releases a subdevice locked
 683  by
 684  <function><link linkend="func-ref-comedi-lock">comedi_lock</link></function>.
 685 Returns:
 686  <literal>0</literal> on success, otherwise <literal>-1</literal>.
 687