doc/extensions_funcref.txt

   1 Extensions
   2 Function: comedi_arm -- arm a subdevice
   3 Retval: int
   4 Param: comedi_t * device
   5 Param: unsigned int subdevice
   6 Param: unsigned int source
   7 Status: alpha
   8 Description:
   9  This function arms a subdevice.  It may, for example, arm a counter
  10  to begin counting.  The <parameter class="function">source</parameter>
  11  parameter specifies
  12  what source should trigger the subdevice to begin.  The possible
  13  sources are driver-dependant.  This function is only useable
  14  on subdevices that provide support for the
  15  <constant>INSN_CONFIG_ARM</constant> configuration
  16  instruction.
  17 Returns:
  18  <literal>0</literal> on success, <literal>-1</literal> on error.
  19
  20 Function: comedi_get_clock_source -- get master clock for a subdevice
  21 Retval: int
  22 Param: comedi_t * device
  23 Param: unsigned int subdevice
  24 Param: unsigned int channel
  25 Param: unsigned int * clock
  26 Param: unsigned int * period_ns
  27 Status: alpha
  28 Description:
  29  This function queries the master clock for a subdevice, as
  30  set by
  31  <function><link linkend="func-ref-comedi-set-clock-source">comedi_set_clock_source</link></function>.
  32  The currently configured master clock
  33  will be written to
  34  <code language="C">*<parameter class="function">clock</parameter></code>.
  35  The possible values and their corresponding clocks are
  36  driver-dependant.
  37  The period of the clock in nanoseconds (or zero if it is unknown)
  38  will be written to
  39  <code language="C">*<parameter class="function">period_ns</parameter></code>.
  40  If the subdevice does not support configuring its master clocks
  41  on a per-channel basis, then the <parameter class="function">channel</parameter>
  42  parameter will be ignored.
  43
  44  It is safe to pass <constant>NULL</constant> pointers as the
  45  <parameter class="function">clock</parameter> or
  46  <parameter class="function">period_ns</parameter>
  47  parameters.  This function is only useable
  48  on subdevices that provide support for the
  49  <constant>INSN_CONFIG_GET_CLOCK_SOURCE</constant>
  50  configuration instruction.
  51 Returns:
  52  <literal>0</literal> on success, <literal>-1</literal> on error.
  53
  54 Function: comedi_get_gate_source -- get gate for a subdevice
  55 Retval: int
  56 Param: comedi_t * device
  57 Param: unsigned int subdevice
  58 Param: unsigned int channel
  59 Param: unsigned int gate_index
  60 Param: unsigned int * gate_source
  61 Status: alpha
  62 Description:
  63  This function queries the gate for a subdevice, as set by
  64  <function><link linkend="func-ref-comedi-set-gate-source">comedi_set_gate_source</link></function>.
  65  The currently configured gate source
  66  will be written to
  67  <code language="C">*<parameter class="function">gate_source</parameter></code>.
  68  The possible values and their corresponding gates are
  69  driver-dependant.  If the subdevice does not
  70  support configuring its gates on a per-channel basis, then the
  71  <parameter class="function">channel</parameter> parameter will be ignored.
  72
  73  This function is only useable
  74  on subdevices that provide support for the
  75  <constant>INSN_CONFIG_GET_GATE_SOURCE</constant>
  76  configuration instruction.
  77 Returns:
  78  <literal>0</literal> on success, <literal>-1</literal> on error.
  79
  80 Function: comedi_get_hardware_buffer_size -- get size of subdevice's hardware buffer
  81 Retval: int
  82 Param: comedi_t *device
  83 Param: unsigned int subdevice
  84 Param: <link linkend="ref-enum-comedi-io-direction">enum comedi_io_direction</link> direction
  85 Description:
  86  This function returns the number of bytes the subdevice can hold in it's hardware buffer.
  87  The term <quote>hardware buffer</quote> refers to any FIFOs, etc. on the acquisition board itself which
  88  are used during streaming commands.  This does not include the buffer maintained by
  89  the comedi kernel module in host memory, whose size may be queried by
  90  <function><link
  91  linkend="func-ref-comedi-get-buffer-size">comedi_get_buffer_size</link></function>.
  92  The <parameter class="function">direction</parameter> parameter of type
  93  <type><link linkend="ref-enum-comedi-io-direction">enum
  94  comedi_io_direction</link></type>
  95  should be set to <constant>COMEDI_INPUT</constant> to query the input buffer size (e.g., the buffer of an analog
  96  input subdevice), or <constant>COMEDI_OUTPUT</constant> to query the output buffer size (e.g., the buffer of
  97  an analog output).
  98 Returns:
  99  Hardware buffer size in bytes, or <literal>-1</literal> on error.
 100
 101 Function: comedi_get_routing -- get routing for an output
 102 Retval: int
 103 Param: comedi_t * device
 104 Param: unsigned int subdevice
 105 Param: unsigned int channel
 106 Param: unsigned int * routing
 107 Status: alpha
 108 Description:
 109  This function queries the routing for an output, as
 110  set by
 111  <function><link linkend="func-ref-comedi-set-routing">comedi_set_routing</link></function>.
 112  The currently configured routing
 113  will be written to
 114  <code language="C">*<parameter class="function">routing</parameter></code>.
 115  The possible values and their corresponding routings are
 116  driver-dependant.
 117
 118  This function is only useable
 119  on subdevices that provide support for the
 120  <constant>INSN_CONFIG_GET_ROUTING</constant>
 121  configuration instruction.
 122 Returns:
 123  <literal>0</literal> on success, <literal>-1</literal> on error.
 124
 125 Function: comedi_reset -- reset a subdevice
 126 Retval: int
 127 Param: comedi_t * device
 128 Param: unsigned int subdevice
 129 Status: alpha
 130 Description:
 131  This function resets a subdevice.  It is only useable
 132  on subdevices that provide support for the
 133  <constant>INSN_CONFIG_RESET</constant> configuration
 134  instruction.
 135 Returns:
 136  <literal>0</literal> on success, <literal>-1</literal> on error.
 137
 138 Function: comedi_set_clock_source -- set master clock for a subdevice
 139 Retval: int
 140 Param: comedi_t * device
 141 Param: unsigned int subdevice
 142 Param: unsigned int channel
 143 Param: unsigned int clock
 144 Param: unsigned int period_ns
 145 Status: alpha
 146 Description:
 147  This function selects a master clock for a subdevice.  The <parameter
 148  class="function">clock</parameter>
 149  parameter selects the master clock, and is driver-dependant.
 150  If the subdevice does not support configuring its master clocks on a
 151  per-channel basis, then the <parameter class="function">channel</parameter> parameter
 152  will be ignored.
 153  The <parameter class="function">period_ns</parameter>
 154  parameter specifies the clock's period in nanoseconds.  It may left unspecified by using
 155  a value of zero.  Drivers will ignore the clock period if they already
 156  know what the clock period should be for the specified clock (e.g. for an
 157  on-board 20MHz oscillator).  Certain boards which use a phase-locked loop to
 158  synchronize to external clock sources must be told the period of the external
 159  clock. Specifying a clock period for an external clock may also allow
 160  the driver to support <constant>TRIG_TIMER</constant> sources in commands while
 161  using the external clock.
 162
 163  The clock may be queried with the
 164  <function><link linkend="func-ref-comedi-get-clock-source">comedi_get_clock_source</link></function>
 165  function.
 166
 167  This function is only useable
 168  on subdevices that provide support for the
 169  <constant>INSN_CONFIG_SET_CLOCK_SOURCE</constant> configuration instruction.
 170 Returns:
 171  <literal>0</literal> on success, <literal>-1</literal> on error.
 172
 173 Function: comedi_set_counter_mode -- change mode of a counter subdevice
 174 Retval: int
 175 Param: comedi_t * device
 176 Param: unsigned int subdevice
 177 Param: unsigned int channel
 178 Param: unsigned int mode
 179 Status: alpha
 180 Description:
 181  This function configures a counter subdevice.  The meaning of the
 182  <parameter class="function">mode</parameter> parameter is driver-dependent.
 183  If the subdevice does not
 184  support configuring its mode on a per-channel basis, then the
 185  <parameter class="function">channel</parameter>
 186  parameter will be ignored.
 187
 188  It is only useable
 189  on subdevices that provide support for the
 190  <constant>INSN_CONFIG_SET_COUNTER_MODE</constant> configuration instruction.
 191 Returns:
 192  <literal>0</literal> on success, <literal>-1</literal> on error.
 193
 194 Function: comedi_set_filter -- select a filter for a subdevice
 195 Retval: int
 196 Param: comedi_t * device
 197 Param: unsigned int subdevice
 198 Param: unsigned int channel
 199 Param: unsigned int filter
 200 Status: alpha
 201 Description:
 202  This function selects a filter for a subdevice.  For instance, a digital
 203  input subdevice may provide deglitching filters with varying cutoff frequencies.
 204  The filters are used to prevent high-frequency
 205  noise from causing unwanted transitions on the digital inputs.  This function can
 206  tell the hardware which deglitching filter to use, or to use none at all.
 207
 208  The <parameter class="function">filter</parameter>
 209  parameter selects which of the subdevice's filters to use, and is driver-dependant.
 210
 211  This function is only useable
 212  on subdevices that provide support for the
 213  <constant>INSN_CONFIG_FILTER</constant> configuration instruction.
 214 Returns:
 215  <literal>0</literal> on success, <literal>-1</literal> on error.
 216
 217 Function: comedi_set_gate_source -- select gate source for a subdevice
 218 Retval: int
 219 Param: comedi_t * device
 220 Param: unsigned int subdevice
 221 Param: unsigned int channel
 222 Param: unsigned int gate_index
 223 Param: unsigned int gate_source
 224 Status: alpha
 225 Description:
 226  This function selects a gate source for a subdevice.  The
 227  <parameter class="function">gate_index</parameter>
 228  parameter selects which gate is being configured, should the subdevice have
 229  multiple gates.  It takes a value
 230  from 0 to N-1 for a subdevice with N different gates.
 231  The <parameter class="function">gate_source</parameter> parameter selects which signal you wish to
 232  use as
 233  the gate, and is also driver-dependent.  If the subdevice does not
 234  support configuring its gates on a per-channel basis, then the
 235  <parameter class="function">channel</parameter> parameter will be ignored.
 236
 237  You may query the gate source with the
 238  <function><link linkend="func-ref-comedi-get-gate-source">comedi_get_gate_source</link></function>
 239  function.
 240  This function is only useable
 241  on subdevices that provide support for the
 242  <constant>INSN_CONFIG_SET_GATE_SOURCE</constant>
 243  configuration instruction.
 244 Returns:
 245  <literal>0</literal> on success, <literal>-1</literal> on error.
 246
 247 Function: comedi_set_other_source -- select source signal for something other than a gate or clock
 248 Retval: int
 249 Param: comedi_t * device
 250 Param: unsigned int subdevice
 251 Param: unsigned int channel
 252 Param: unsigned int other
 253 Param: unsigned int source
 254 Status: alpha
 255 Description:
 256  This function allows selection of a source signal for something on a subdevice
 257  other than a gate (which uses
 258  <function><link
 259  linkend="func-ref-comedi-set-gate-source">comedi_set_gate_source</link></function>)
 260  or a clock (which uses
 261  <function><link
 262  linkend="func-ref-comedi-set-clock-source">comedi_set_clock_source</link></function>).
 263  The <parameter class="function">other</parameter> parameter selects
 264  which <quote>other</quote> we are configuring, and is driver-dependent.  The
 265  <parameter class="function">source</parameter> parameter selects the source
 266  we which to use for the <quote>other</quote>.  If the subdevice does not
 267  support configuring its <quote>other</quote> sources on a per-channel basis,
 268  then the <parameter class="function">channel</parameter>
 269  parameter will be ignored.
 270
 271  As an example, this function is used to select which PFI digital input channels
 272  should be used as the A/B/Z signals when running a counter on an NI M-Series board as
 273  a quadrature encoder.  The <parameter class="function">other</parameter> parameter selects either the A, B,
 274  or Z signal, and the <parameter class="function">source</parameter> parameter is used to specify
 275  which PFI digital input channel the external A, B, or Z signal is
 276  physically connected to.
 277
 278  This function is only useable
 279  on subdevices that provide support for the
 280  <constant>INSN_CONFIG_SET_OTHER_SOURCE</constant>
 281  configuration instruction.
 282 Returns:
 283  <literal>0</literal> on success, <literal>-1</literal> on error.
 284
 285 Function: comedi_set_routing -- select a routing for an output
 286 Retval: int
 287 Param: comedi_t * device
 288 Param: unsigned int subdevice
 289 Param: unsigned int channel
 290 Param: unsigned int routing
 291 Status: alpha
 292 Description:
 293  This function configures a mutiplexed output channel which can
 294  output a variety of different signals (such as NI's RTSI and PFI lines).
 295  The <parameter class="function">routing</parameter>
 296  parameter selects which signal should be routed to appear on the
 297  selected output channel, and is driver-dependant.
 298
 299  The routing may be queried with the
 300  <function><link linkend="func-ref-comedi-get-routing">comedi_get_routing</link></function>
 301  function.
 302  This function is only useable
 303  on subdevices that provide support for the
 304  <constant>INSN_CONFIG_SET_ROUTING</constant>
 305  configuration instruction.
 306 Returns:
 307  <literal>0</literal> on success, <literal>-1</literal> on error.