From: Ian Abbott Date: Wed, 9 May 2012 13:45:18 +0000 (+0100) Subject: doc/extensions_funcref.txt: Some DocBook mark-up changes. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=382f445b4a091aa964c19690587bdc3dbd6f8e3a;p=comedilib.git doc/extensions_funcref.txt: Some DocBook mark-up changes. --- diff --git a/doc/extensions_funcref.txt b/doc/extensions_funcref.txt index 0abb201..4bf079a 100644 --- a/doc/extensions_funcref.txt +++ b/doc/extensions_funcref.txt @@ -7,44 +7,49 @@ Param: unsigned int source Status: alpha Description: This function arms a subdevice. It may, for example, arm a counter - to begin counting. The source parameter specifies + to begin counting. The source + parameter specifies what source should trigger the subdevice to begin. The possible sources are driver-dependant. This function is only useable - on subdevices that provide support for the INSN_CONFIG_ARM configuration + on subdevices that provide support for the + INSN_CONFIG_ARM configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_get_clock_source -- get master clock for a subdevice Retval: int Param: comedi_t * device Param: unsigned int subdevice Param: unsigned int channel -Param: unsigned int *clock -Param: unsigned int *period_ns +Param: unsigned int * clock +Param: unsigned int * period_ns Status: alpha Description: This function queries the master clock for a subdevice, as set by - comedi_set_clock_source(). + comedi_set_clock_source. The currently configured master clock - will be written to *clock. + will be written to + *clock. The possible values and their corresponding clocks are driver-dependant. - The frequency of the clock in nanoseconds (or zero if it is unknown) + The period of the clock in nanoseconds (or zero if it is unknown) will be written to - *period_ns. + *period_ns. If the subdevice does not support configuring its master clocks - on a per-channel basis, then the channel + on a per-channel basis, then the channel parameter will be ignored. - It is safe to pass NULL pointers as the clock or - period_ns + It is safe to pass NULL pointers as the + clock or + period_ns parameters. This function is only useable - on subdevices that provide support for the INSN_CONFIG_GET_CLOCK_SOURCE + on subdevices that provide support for the + INSN_CONFIG_GET_CLOCK_SOURCE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_get_gate_source -- get gate for a subdevice Retval: int @@ -52,24 +57,25 @@ Param: comedi_t * device Param: unsigned int subdevice Param: unsigned int channel Param: unsigned int gate_index -Param: unsigned int *gate_source +Param: unsigned int * gate_source Status: alpha Description: - This function queries the gate for a subdevice, as - set by - comedi_set_gate_source(). + This function queries the gate for a subdevice, as set by + comedi_set_gate_source. The currently configured gate source - will be written to *gate_source. + will be written to + *gate_source. The possible values and their corresponding gates are driver-dependant. If the subdevice does not support configuring its gates on a per-channel basis, then the - channel parameter will be ignored. + channel parameter will be ignored. This function is only useable - on subdevices that provide support for the INSN_CONFIG_GET_GATE_SOURCE + on subdevices that provide support for the + INSN_CONFIG_GET_GATE_SOURCE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_get_hardware_buffer_size -- get size of subdevice's hardware buffer Retval: int @@ -77,40 +83,44 @@ Param: comedi_t *device Param: unsigned int subdevice Param: enum comedi_io_direction direction Description: - This functions returns the number of bytes the subdevice can hold in it's hardware buffer. - The term "hardware buffer" refers to any fifos, etc. on the acquisition board itself which - are used during streaming commands. This does not include the buffer maintained by - the comedi kernel module in host memory, whose size may be queried by - comedi_get_buffer_size. - The direction parameter of type - enum comedi_io_direction - should be set to COMEDI_INPUT to query the input buffer size (e.g., the buffer of an analog - input subdevice), or COMEDI_OUTPUT to query the output buffer size (e.g., the buffer of - an analog output). + This function returns the number of bytes the subdevice can hold in it's hardware buffer. + The term hardware buffer refers to any FIFOs, etc. on the acquisition board itself which + are used during streaming commands. This does not include the buffer maintained by + the comedi kernel module in host memory, whose size may be queried by + comedi_get_buffer_size. + The direction parameter of type + enum + comedi_io_direction + should be set to COMEDI_INPUT to query the input buffer size (e.g., the buffer of an analog + input subdevice), or COMEDI_OUTPUT to query the output buffer size (e.g., the buffer of + an analog output). Returns: - Number of bytes, or -1 on error. + Hardware buffer size in bytes, or -1 on error. Function: comedi_get_routing -- get routing for an output Retval: int Param: comedi_t * device Param: unsigned int subdevice Param: unsigned int channel -Param: unsigned int *routing +Param: unsigned int * routing Status: alpha Description: This function queries the routing for an output, as set by - comedi_set_routing(). + comedi_set_routing. The currently configured routing - will be written to *routing. + will be written to + *routing. The possible values and their corresponding routings are driver-dependant. This function is only useable - on subdevices that provide support for the INSN_CONFIG_GET_ROUTING + on subdevices that provide support for the + INSN_CONFIG_GET_ROUTING configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_reset -- reset a subdevice Retval: int @@ -119,10 +129,11 @@ Param: unsigned int subdevice Status: alpha Description: This function resets a subdevice. It is only useable - on subdevices that provide support for the INSN_CONFIG_RESET configuration + on subdevices that provide support for the + INSN_CONFIG_RESET configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_clock_source -- set master clock for a subdevice Retval: int @@ -133,29 +144,31 @@ Param: unsigned int clock Param: unsigned int period_ns Status: alpha Description: - This function selects a master clock for a subdevice. The clock + This function selects a master clock for a subdevice. The clock parameter selects the master clock, and is driver-dependant. If the subdevice does not support configuring its master clocks on a - per-channel basis, then the channel parameter + per-channel basis, then the channel parameter will be ignored. - The period_ns + The period_ns parameter specifies the clock's period in nanoseconds. It may left unspecified by using a value of zero. Drivers will ignore the clock period if they already - know what the clock period should be for the specified clock (i.e. for an + know what the clock period should be for the specified clock (e.g. for an on-board 20MHz oscillator). Certain boards which use a phase-locked loop to - synchronize to external clock sources must be told the frequency of the external + synchronize to external clock sources must be told the period of the external clock. Specifying a clock period for an external clock may also allow - the driver to support TRIG_TIMER sources in commands while + the driver to support TRIG_TIMER sources in commands while using the external clock. - The clock may be queried with the comedi_get_clock_source() + The clock may be queried with the + comedi_get_clock_source function. This function is only useable - on subdevices that provide support for the INSN_CONFIG_SET_CLOCK_SOURCE - configuration instruction. + on subdevices that provide support for the + INSN_CONFIG_SET_CLOCK_SOURCE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_counter_mode -- change mode of a counter subdevice Retval: int @@ -166,17 +179,17 @@ Param: unsigned int mode Status: alpha Description: This function configures a counter subdevice. The meaning of the - mode parameter is driver-dependent. + mode parameter is driver-dependent. If the subdevice does not support configuring its mode on a per-channel basis, then the - channel + channel parameter will be ignored. It is only useable - on subdevices that provide support for the INSN_CONFIG_SET_COUNTER_MODE - configuration instruction. + on subdevices that provide support for the + INSN_CONFIG_SET_COUNTER_MODE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_filter -- select a filter for a subdevice Retval: int @@ -192,14 +205,14 @@ Description: noise from causing unwanted transitions on the digital inputs. This function can tell the hardware which deglitching filter to use, or to use none at all. - The filter + The filter parameter selects which of the subdevice's filters to use, and is driver-dependant. This function is only useable - on subdevices that provide support for the INSN_CONFIG_FILTER - configuration instruction. + on subdevices that provide support for the + INSN_CONFIG_FILTER configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_gate_source -- select gate source for a subdevice Retval: int @@ -210,23 +223,26 @@ Param: unsigned int gate_index Param: unsigned int gate_source Status: alpha Description: - This function selects a gate source for a subdevice. The gate_index + This function selects a gate source for a subdevice. The + gate_index parameter selects which gate is being configured, should the subdevice have multiple gates. It takes a value from 0 to N-1 for a subdevice with N different gates. - The gate_source parameter selects which signal you wish to + The gate_source parameter selects which signal you wish to use as the gate, and is also driver-dependent. If the subdevice does not support configuring its gates on a per-channel basis, then the - channel parameter will be ignored. + channel parameter will be ignored. - You may query the gate source with the comedi_get_gate_source() + You may query the gate source with the + comedi_get_gate_source function. This function is only useable - on subdevices that provide support for the INSN_CONFIG_SET_GATE_SOURCE + on subdevices that provide support for the + INSN_CONFIG_SET_GATE_SOURCE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_other_source -- select source signal for something other than a gate or clock Retval: int @@ -238,27 +254,33 @@ Param: unsigned int source Status: alpha Description: This function allows selection of a source signal for something on a subdevice - other than a gate (which uses comedi_set_gate_source()) or a clock (which uses - comedi_set_clock_source()). The other parameter selects - which "other" we are configuring, and is driver-dependent. The - source selects the source we which to use for the - "other". If the subdevice does not - support configuring its "other" sources on a per-channel basis, then the - channel + other than a gate (which uses + comedi_set_gate_source) + or a clock (which uses + comedi_set_clock_source). + The other parameter selects + which other we are configuring, and is driver-dependent. The + source parameter selects the source + we which to use for the other. If the subdevice does not + support configuring its other sources on a per-channel basis, + then the channel parameter will be ignored. As an example, this function is used to select which PFI digital input channels should be used as the A/B/Z signals when running a counter on an NI M-Series board as - a quadrature encoder. The other parameter selects either the A, B, - or Z signal, and the source parameter is used to specify + a quadrature encoder. The other parameter selects either the A, B, + or Z signal, and the source parameter is used to specify which PFI digital input channel the external A, B, or Z signal is physically connected to. This function is only useable - on subdevices that provide support for the INSN_CONFIG_SET_OTHER_SOURCE + on subdevices that provide support for the + INSN_CONFIG_SET_OTHER_SOURCE configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error. Function: comedi_set_routing -- select a routing for an output Retval: int @@ -270,14 +292,16 @@ Status: alpha Description: This function configures a mutiplexed output channel which can output a variety of different signals (such as NI's RTSI and PFI lines). - The routing + The routing parameter selects which signal should be routed to appear on the selected output channel, and is driver-dependant. The routing may be queried with the - comedi_get_routing() function. + comedi_get_routing + function. This function is only useable - on subdevices that provide support for the INSN_CONFIG_SET_ROUTING + on subdevices that provide support for the + INSN_CONFIG_SET_ROUTING configuration instruction. Returns: - 0 on success, -1 on error. + 0 on success, -1 on error.