File: experimentalfunctionality.html

package info (click to toggle)
comedilib 0.11.0%2B5-1
links: PTS, VCS
area: main
in suites: bookworm, bullseye
size: 8,540 kB
sloc: xml: 19,779; ansic: 14,719; sh: 5,672; cpp: 2,211; ruby: 1,658; perl: 700; makefile: 594; yacc: 439; lex: 86; python: 17
file content (706 lines) | stat: -rw-r--r-- 42,152 bytes
parent folder | download | duplicates (3)
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>4.7.  Experimental functionality</title><link rel="stylesheet" type="text/css" href="comedilib.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Comedi"><link rel="up" href="acquisitionfunctions.html" title="4.  Acquisition and configuration functions"><link rel="prev" href="slowlyvarying.html" title="4.6.  Slowly-varying inputs"><link rel="next" href="comedireference.html" title="5.  Comedi reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.7. 
Experimental functionality
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="slowlyvarying.html">Prev</a> </td><th width="60%" align="center">4. 
Acquisition and configuration functions
</th><td width="20%" align="right"> <a accesskey="n" href="comedireference.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="experimentalfunctionality"></a>4.7. 
Experimental functionality
</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="experimentalfunctionality.html#digitalinputcombining">4.7.1. 
Digital input combining machines
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#analogconversion">4.7.2. 
Analog filtering configuration
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#waveformgeneration">4.7.3. 
Analog Output Waveform Generation
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#extendedtriggering">4.7.4. 
Extended Triggering
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#analogtriggering">4.7.5. 
Analog Triggering
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#bitfieldmatching">4.7.6. 
Bitfield Pattern Matching Extended Trigger
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#countertimer">4.7.7. 
Counter configuration
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#auxcounter">4.7.8. 
One source plus auxiliary counter configuration
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#GPCT">4.7.9. 
National Instruments General Purpose Counters/Timers (GPCT)
</a></span></dt><dt><span class="section"><a href="experimentalfunctionality.html#RTSI">4.7.10. 
National Instruments RTSI trigger bus
</a></span></dt></dl></div><p>
The following subsections document functionality that has not yet
matured. Most of this functionality has even not been implemented yet
in any single device driver. This information is included here, in
order to stimulate discussion about their API, and to encourage
pioneering implementations.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="digitalinputcombining"></a>4.7.1. 
Digital input combining machines
</h4></div></div></div><p>
(<span class="strong"><strong>Status: experimental (i.e., no driver implements
this yet)</strong></span>)
</p><p>
When one or several digital inputs are used to modify an output
value, either an accumulator or a single digital line or bit,
a bitfield structure is typically used in the <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> interface.
The digital inputs have two properties, <span class="quote">“<span class="quote">sensitive</span>”</span> inputs
and <span class="quote">“<span class="quote">modifier</span>”</span> inputs.  Edge transitions on sensitive
inputs cause changes in the output signal, whereas modifier inputs
change the effect of edge transitions on sensitive inputs.  Note that
inputs can be both modifier inputs and sensitive inputs.
</p><p>
For simplification purposes, it is assumed that multiple digital
inputs do not change simultaneously.
</p><p>
The combined state of the modifier inputs determine a modifier
state.  For each combination of modifier state and sensitive
input, there is a set of bits that determine the effect on the
output value due to positive or negative transitions of the
sensitive input.  For each transition direction, there are two
bits defined as follows:

</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term">00</span></dt><dd>transition is ignored.</dd><dt><span class="term">01</span></dt><dd>accumulator is incremented, or output is set.</dd><dt><span class="term">10</span></dt><dd>accumulator is decremented, or output is cleared.</dd><dt><span class="term">11</span></dt><dd>reserved.</dd></dl></div><p>

For example, a simple digital follower is specified by the bit
pattern 01 10, because it sets the output on positive transitions
of the input, and clears the output on negative transitions.  A
digital inverter is similarily 10 01.  These systems have only
one sensitive input.
</p><p>
As another example, a simple up counter, which increments on
positive transitions of one input, is specified by 01 00.  This
system has only one sensitive input.
</p><p>
When multiple digital inputs are used, the inputs are divided
into two types, inputs which cause changes in the accumulator, and
those that only modify the meaning of transitions on other inputs.
Modifier inputs do not require bitfields, but there needs to be
a bitfield of length 4*(2^(N-1)) for each edge sensitive input,
where N is the total number of inputs.  Since N is usually 2 or
3, with only one edge sensitive input, the scaling issues are
not significant.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="analogconversion"></a>4.7.2. 
Analog filtering configuration
</h4></div></div></div><p>
<span class="strong"><strong>(Status: design (i.e., no driver implements
this yet).)</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em>
field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is ignored.
</p><p>
Some devices have the capability to add white noise (dithering) to
analog input measurement.  This additional noise can then be averaged
out, to get a more accurate measurement of the input signal.  It
should not be assumed that channels can be separately configured.
A simple design can use 1 bit to turn this feature on/off.
</p><p>
Some devices have the capability of changing the glitch characteristics
of analog output subsytems.  The default (off) case should be where
the average settling time is lowest.  A simple design can use 1 bit
to turn this feature on/off.
</p><p>
Some devices have a configurable analog filters as part of the analog
input stage.  A simple design can use 1 bit to enable/disable the
filter.  Default is disabled, i.e., the filter being bypassed, or if
the choice is between two filters, the filter with the largest
bandwidth.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="waveformgeneration"></a>4.7.3. 
Analog Output Waveform Generation
</h4></div></div></div><p>
<span class="strong"><strong>(Status: design (i.e., no driver implements
this yet).)</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is ignored.
</p><p>
Some devices have the ability to cyclicly loop through samples kept in
an on-board analog output FIFO.  This config should allow the user to
enable/disable this mode.
</p><p>
This config should allow the user to configure the number of samples
to loop through.  It may be necessary to configure the channels used.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="extendedtriggering"></a>4.7.4. 
Extended Triggering
</h4></div></div></div><p>
<span class="strong"><strong>(Status: alpha.)</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is ignored.
</p><p>
This section covers common information for all extended
triggering configuration, and doesn't describe a particular
type of extended trigger.
</p><p>
Extended triggering is used to configure triggering engines that
do not fit into commands.  In a typical programming sequence, the
application will use
<a class="link" href="instructionsconfiguration.html" title="4.3.  Instructions for configuration">configuration instructions</a>
to configure an extended trigger, and a
<a class="link" href="commandsstreaming.html" title="4.5.  Commands for streaming acquisition">command</a>,
specifying
<code class="constant"><a class="link" href="commandsstreaming.html#trig-other">TRIG_OTHER</a></code>
as one of the trigger sources.
</p><p>
Extended trigger configuration should be designed in such a way
that the user can probe for valid parameters, similar to how
command testing works.  An extended trigger configuration instruction
should not configure the hardware directly, rather, the configuration
should be saved until the subsequent command is issued.  This
allows more flexibility for future interface changes.
</p><p>
It has not been decided whether the configuration stage should return a
token that is then used as the trigger argument in the command.
Using tokens is one method to satisfy the problem that extended
trigger configurations may have subtle compatiblity issues with
other trigger sources/arguments that can only be determined at
command test time.  Passing all stages of a command test should
only be allowed with a properly configured extended trigger.
</p><p>
Extended triggers must use
<em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em>[1] as flags.  The
upper 16 bits are reserved and used only for flags that are common to
all extended triggers.  The lower 16 bits may be defined by the
particular type of extended trigger.
</p><p>
Various types of extended triggers must use
<em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em>[1] to know which
event the extended trigger will be assigned to in the command
structure.  The possible values are an OR'd mask of the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="constant">COMEDI_EV_START</code>
    </p></li><li class="listitem"><p>
<code class="constant">COMEDI_EV_SCAN_BEGIN</code>
    </p></li><li class="listitem"><p>
<code class="constant">COMEDI_EV_CONVERT</code>
    </p></li><li class="listitem"><p>
<code class="constant">COMEDI_EV_SCAN_END</code>
    </p></li><li class="listitem"><p>
<code class="constant">COMEDI_EV_STOP</code>
    </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="analogtriggering"></a>4.7.5. 
Analog Triggering
</h4></div></div></div><p>
<span class="strong"><strong>
(Status: alpha. The <code class="filename">ni_mio_common.c</code> driver
implements this feature.)
</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is ignored.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used as follows:
</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term">data[1]</span></dt><dd>trigger and combining machine configuration.</dd><dt><span class="term">data[2]</span></dt><dd>analog triggering signal chanspec.</dd><dt><span class="term">data[3]</span></dt><dd>primary analog level.</dd><dt><span class="term">data[4]</span></dt><dd>secondary analog level.</dd></dl></div><p>
</p><p>
Analog triggering is described by a digital combining machine that
has two sensitive digital inputs.  The sensitive digital inputs are
generated by configurable analog comparators.  The analog comparators
generate a digital 1 when the analog triggering signal is greater
than the comparator level.  The digital inputs are not modifier
inputs.  Note, however, there is an effective modifier due to the
restriction that the primary analog comparator level must be less
than the secondary analog comparator level.
</p><p>
If only one analog comparator signal is used, the combining machine
for the secondary input should be set to ignored, and the secondary
analog level should be set to <code class="literal">0</code>.
</p><p>
The interpretation of the chanspec and voltage levels is device
dependent, but should correspond to similar values of the analog
input subdevice, if possible.
</p><p>
Notes:  Reading range information is not addressed.  This makes it
difficult to convert comparator voltages to data values.
</p><p>
Possible extensions: A parameter that specifies the necessary time
that the set condition has to be true before the trigger is generated.
A parameter that specifies the necessary time that the reset condition
has to be true before the state machine is reset.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="bitfieldmatching"></a>4.7.6. 
Bitfield Pattern Matching Extended Trigger
</h4></div></div></div><p>
<span class="strong"><strong>
(Status: design. No driver implements this feature yet.)
</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is ignored.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used as follows:
</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term">data[1]</span></dt><dd>trigger flags.</dd><dt><span class="term">data[2]</span></dt><dd>mask.</dd><dt><span class="term">data[3]</span></dt><dd>pattern.</dd></dl></div><p>
The pattern matching trigger issues a trigger when all of a specifed
set of input lines match a specified pattern.  If the device allows,
the input lines should correspond to the input lines of a digital input
subdevice, however, this will necessarily be device dependent.  Each
possible digital line that can be matched is assigned a bit in the
mask and pattern.  A bit set in the mask indicates that the
input line must match the corresponding bit in the pattern.
A bit cleared in the mask indicates that the input line is ignored.
</p><p>
Notes: This only allows 32 bits in the pattern/mask, which may be
too few.  Devices may support selecting different sets of lines from
which to match a pattern.
</p><p>
Discovery: The number of bits can be discovered by setting the mask
to all 1's.  The driver must modify this value and return
<code class="constant">-EAGAIN</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="countertimer"></a>4.7.7. 
Counter configuration
</h4></div></div></div><p>
<span class="strong"><strong>
(Status: design. No driver implements this feature yet.)
</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used to specify which counter to use. (I.e., the
counter is a <a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> channel.)
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used as follows:
</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term">data[1]</span></dt><dd>trigger configuration.</dd><dt><span class="term">data[2]</span></dt><dd>primary input chanspec.</dd><dt><span class="term">data[3]</span></dt><dd>primary combining machine configuration.</dd><dt><span class="term">data[4]</span></dt><dd>secondary input chanspec.</dd><dt><span class="term">data[5]</span></dt><dd>secondary combining machine configuration.</dd><dt><span class="term">data[6]</span></dt><dd>latch configuration.</dd></dl></div><p>
Note that this configuration is only useful if the counting has to be
done in <span class="emphasis"><em>software</em></span>. Many cards offer configurable
counters in hardware; e.g., general purpose timer cards can be
configured to act as pulse generators, frequency counters, timers,
encoders, etc.
</p><p>
Counters can be operated either in synchronous mode (using
<code class="constant"><a class="link" href="datatypesstructures.html#insn-read">INSN_READ</a></code>)
or asynchronous mode (using
<a class="link" href="commandsstreaming.html" title="4.5.  Commands for streaming acquisition">commands</a>), similar to analog
input subdevices.
The input signal for both modes is the accumulator.
Commands on counter subdevices are almost always specified using
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-src">scan_begin_src</a></code></em>
= <code class="constant"><a class="link" href="commandsstreaming.html#trigother-event">TRIG_OTHER</a></code>,
with the counter configuration also serving as the extended configuration for
the <span class="quote">“<span class="quote">scan begin</span>”</span> source.
</p><p>
Counters are made up of an accumulator and a combining machine that
determines when the accumulator should be incremented or decremented
based on the values of the input signals.  The combining machine
optionally determines when the accumulator should be latched and
put into a buffer.  This feature is used in asynchronous mode.
</p><p>
Note: How to access multiple pieces of data acquired at each event?
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="auxcounter"></a>4.7.8. 
One source plus auxiliary counter configuration
</h4></div></div></div><p>
<span class="strong"><strong>
(Status: design. No driver implements this feature yet.)
</strong></span>
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-insn">insn</a></code></em> field of the
<a class="link" href="instructions.html#insn-data-structure">instruction data structure</a>
has not been assigned yet.
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-chanspec">chanspec</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used to …
</p><p>
The <em class="structfield"><code><a class="link" href="instructions.html#insn-data-structure-data">data</a></code></em> field
of the <a class="link" href="instructions.html#insn-data-structure">instruction data
structure</a> is used as follows:
</p><p>
</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term">data[1]</span></dt><dd>
is flags, including the flags for the command triggering
configuration.  If a command is not subsequently issued on the
subdevice, the command triggering portion of the flags are ignored.
  </dd><dt><span class="term">data[2]</span></dt><dd>
determines the mode of operation.  The mode of operation
is actually a bitfield that encodes what to do for various
transitions of the source signals.
  </dd><dt><span class="term">data[3], </span><span class="term">data[4]</span></dt><dd>
determine the primary source for the counter, similar to the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-src">…_src</a></code></em> and the
<em class="structfield"><code><a class="link" href="commandsstreaming.html#command-data-struct-scan-begin-arg">…_arg</a></code></em> fields
used in the
<a class="link" href="commandsstreaming.html#command-data-struct">command data structure</a>.
  </dd></dl></div><p>
</p><p>
Notes: How to specify which events cause a latch and push, and what
should get latched?
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="GPCT"></a>4.7.9. 
National Instruments General Purpose Counters/Timers (GPCT)
</h4></div></div></div>

Counters/timers and pulse generators are fairly different in terms of
functionality, but they correspond to similar devices seen either as input
or output. When generalising, these devices are both referred to as
"counters". The NI boards provide a couple of such counters, under the name of
GPCT.
A counter is made of the following basic elements:
<div class="variablelist"><dl class="variablelist compact"><dt><span class="term">Input source</span></dt><dd>the signal measured or the clock of the pulse generation.</dd><dt><span class="term">Gate</span></dt><dd>controls when the counting (or sampling) occurs.</dd><dt><span class="term">Register</span></dt><dd>holds the current count.</dd><dt><span class="term">Out</span></dt><dd>for the output counters (pulse generators), the output signal.</dd></dl></div><p>
There are many different ways to count, time or generate pulses. All the modes
rely on the counter and some particular configuration. For example, in a typical
buffered counting mode, the source is the (digital) signal that is measured, the
counter is increased at every rising edge of the signal, the gate is the
(digital) signal indicating when to save the counter to memory. It is preferable
you get first familiarized with these various modes by reading your NI board
documentation before reading the following description on the mapping to the
comedi interface.
</p><p>
Each counter of the board is represented in comedi as a subdevice of type
<code class="constant">COMEDI_SUBD_COUNTER</code>. Each subdevice has a device file
associated (eg, <code class="filename">/dev/comedi0_subd11</code>) in order to read or
write buffered data from or to the counter.
Note that the comedi subdevice has three "channels". In most case, only channel
0 is to be used. Reading or writing on channel 0 corresponds to reading/writing
the counter value. The GPCT also has two registers named A and B, they can be
accessed respectively via channels 1 and 2.
</p><p>
To configure the behaviour of the counter with comedi, the
function <code class="function">comedi_set_counter_mode</code> is used.
The possible mode values are to be found in the <span class="type">ni_gpct_mode_bits</span>
enum constants. For instance, by default the counter is cumulative, even in
buffered counting. To reinitialise it after each sampling (ie, after an edge on
the gate signal), one can add the <code class="constant">NI_GPCT_LOADING_ON_GATE_BIT</code>
to the mode. In that case, the counter will be reset to the value of the A
register after each sampling.
</p><p>
To configure the signal to be used as the "source", one uses the <code class="function">
comedi_set_clock_source</code> with one constant from the
<span class="type">ni_gpct_clock_source_bits</span> enum. When the period of the signal is
fixed and known, it should be specified as the last parameter of the method, otherwise
<code class="literal">0</code> should be passed. Note that in comedi this is called "clock"
because in timer and pulse generator, this signal is used as the clock.
</p><p>
To configure the signal to be used as the "gate", one uses the <code class="function">
comedi_set_gate_source</code> with one constant from the <span class="type">
ni_gpct_gate_select</span> enum. When the gate signal is not be used,
<code class="constant">NI_GPCT_DISABLED_GATE_SELECT</code> should be specified. Some
NI boards have two gates, but the behaviour associated with the second gate is
usually unknown so it is recommended to disable it. Note that this is called
"gate" because in some modes, this signal is used to block/unblock the counter.
</p><p>
The function <code class="function">comedi_reset</code> will stop and reset a counter.
After being configured, to start a counter, it should be "armed", which can be
done either with the <code class="function">comedi_arm</code> function (for simple counting
mode), or with the <em class="structfield"><code>start_src</code></em> member of the command
(for buffered counting).
</p><p>
One side thing to mention is the signal routing of the NI card, which is done
via the PFIs (Programmable Function Inputs).
NI's naming is confusing because they use the same name for the
terminal (ie, physical input/output pins) and for the signal
(ie, the logical information that controls/indicates a specific event).

The routing allows to configure which signal goes to a PFI terminal.
This is done via <code class="function">comedi_set_routing</code>, with subdevice being
the special DIO comedi subdevice (eg, 7 on M-series), the PFI terminal
number as channel, the signal that should be routed to it encoded as source with
one of the constants from the <span class="type">ni_pfi_routing</span> enum.
The direction of the pin must also be correctly configured (ie, whether it is
used as input or output). This is done via <code class="function">comedi_dio_config</code>
with the same subdevice and channel, and either <code class="constant">COMEDI_INPUT</code>
or <code class="constant">COMEDI_OUTPUT</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="RTSI"></a>4.7.10. 
National Instruments RTSI trigger bus
</h4></div></div></div><p>
A number of NI boards support the RTSI (Real Time System Integration) bus.
It's primary use is to synchronize multiple DAQ cards.
On PXI boards, the RTSI lines correspond to the PXI trigger lines 0 to 7.  PCI
boards use cables to connect to their RTSI ports.
The RTSI bus consists of 8 digital signal lines numbered 0 to 7 that are bi-directional.
Each of these signal lines
can be configured as an input or output, and the signal appearing on the output
of each line can be configured to one of several internal board timing signals
(although on older boards RTSI line 7 can only be used for the clock signal).
The <code class="systemitem">ni_pcimio</code>, <code class="systemitem">ni_atmio</code>, and
<code class="systemitem">ni_mio_cs</code> drivers expose the RTSI bus
as a digital I/O subdevice (subdevice number 10).
</p><p>
The functions <code class="function">comedi_dio_config</code> and
<code class="function">comedi_dio_get_config</code> can be used on
the RTSI subdevice to
set/query the direction (input or output) of each of the RTSI lines individually.
</p><p>
The subdevice also supports the
<code class="constant">INSN_CONFIG_SET_CLOCK_SRC</code> and
<code class="constant">INSN_CONFIG_GET_CLOCK_SRC</code> configuration
instructions, which can be
used to configure/query what source the board uses to synchronize its
master clock to.  The various possibilities are defined in the <code class="filename">comedi.h</code>
header file:
</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Clock Source</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><code class="constant">NI_MIO_INTERNAL_CLOCK</code></td><td align="left">
Use the board's internal oscillator.
</td></tr><tr><td align="left"><code class="constant">NI_MIO_RTSI_CLOCK</code></td><td align="left">
Use the RTSI line 7 as the master clock.  This source is
only supported on pre-m-series boards.  The newer m-series boards
use <code class="function">NI_MIO_PLL_RTSI_CLOCK</code> instead.
</td></tr><tr><td align="left"><code class="constant">NI_MIO_PLL_PXI_STAR_TRIGGER_CLOCK</code></td><td align="left">
Only available for newer m-series PXI boards.  Synchronizes the board's
phased-locked loop (which runs at 80MHz) to the PXI star trigger
line.
</td></tr><tr><td align="left"><code class="constant">NI_MIO_PLL_PXI10_CLOCK</code></td><td align="left">
Only available for newer m-series PXI boards.
Synchronizes the board's
phased-locked loop (which runs at 80MHz) to the 10 MHz PXI backplane
clock.
</td></tr><tr><td align="left">
<code class="function">NI_MIO_PLL_RTSI_CLOCK</code>(<em class="parameter"><code>n</code></em>)
</td><td align="left">
Only available for newer m-series boards.
The function returns a clock source which will cause the board's
phased-locked loop (which runs at 80MHz) to syncronize to the RTSI
line specified in the function argument.
</td></tr></tbody></table></div><p>
For all clock sources except <code class="constant">NI_MIO_INTERNAL_CLOCK</code>
and <code class="constant">NI_MIO_PLL_PXI10_CLOCK</code>,
you should pass the period of the clock your are feeding to the board when
using <code class="constant">INSN_CONFIG_SET_CLOCK_SRC</code>.
</p><p>
Finally, the configuration instructions
<code class="constant">INSN_CONFIG_SET_ROUTING</code> and
<code class="constant">INSN_CONFIG_GET_ROUTING</code>
can be used to select/query which internal signal
will appear on a given RTSI output line.  The header file <code class="filename">comedi.h</code> defines
the following signal sources which can be routed to an RTSI line:
</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Signal Source</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_ADR_START1</code></td><td align="left">
ADR_START1, an analog input start signal.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_ADR_START2</code></td><td align="left">
ADR_START2, an analog input stop signal.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_SCLKG</code></td><td align="left">
SCLKG, a sample clock signal.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_DACUPDN</code></td><td align="left">
DACUPDN, a dac update signal.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_DA_START1</code></td><td align="left">
DA_START1, an analog output start signal.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_G_SRC0</code></td><td align="left">
G_SRC0, the source signal to general purpose counter 0.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_G_GATE0</code></td><td align="left">
G_GATE0, the gate signal to general purpose counter 0.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_RGOUT0</code></td><td align="left">
RGOUT0, the output signal of general purpose counter 0.  See the NI's
DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left">
<code class="function">NI_RTSI_OUTPUT_RTSI_BRD</code>(<em class="parameter"><code>n</code></em>)
</td><td align="left">
RTSI_BRD0 though RTSI_BRD3 are four internal signals which can
have various other signals routed to them in turn.  Currently, comedi
provides no way to configure the signals routed to the RTSI_BRD lines.
See the NI's DAQ-STC Technical Reference Manual for more information.
</td></tr><tr><td align="left"><code class="constant">NI_RTSI_OUTPUT_RTSI_OSC</code></td><td align="left">
The RTSI clock signal.  On pre-m-series boards, this signal is always
routed to RTSI line 7, and cannot be routed to lines 0 through 6.  On
m-series boards, any RTSI line can be configured to output the clock
signal.
</td></tr></tbody></table></div><p>
The RTSI bus pins may be used as trigger inputs for many of the
<a class="ulink" href="http://www.comedi.org" target="_top"><acronym class="acronym">Comedi</acronym></a> trigger functions. To use the RTSI bus pins, set the source to be
<code class="constant">TRIG_EXT</code> and the source argument using the return values
from the <code class="function">NI_EXT_RTSI</code>(<em class="parameter"><code>n</code></em>) function (or similarly the
<code class="function">NI_EXT_PFI</code>(<em class="parameter"><code>n</code></em>) function if you want
to trigger from a PFI line).  The <code class="constant">CR_EDGE</code> and
<code class="constant">CR_INVERT</code> flags may
also be set on the trigger source argument to specify edge and
falling edge/low level triggering.

</p><p>
An example to set up a device as a master is given below.
</p><pre class="programlisting">
void comediEnableMaster(comedi_t *dev){
        comedi_insn   configCmd;
        lsampl_t      configData[2];
        int           ret;
        unsigned int  d = 0;
        static const unsigned rtsi_subdev = 10;
        static const unsigned rtsi_clock_line = 7;

        /* Route RTSI clock to line 7 (not needed on pre-m-series boards since their
           clock is always on line 7). */
        memset(&amp;configCmd, 0, sizeof(configCmd));
        memset(&amp;configData, 0, sizeof(configData));
        configCmd.insn = INSN_CONFIG;
        configCmd.subdev = rtsi_subdev;
        configCmd.chanspec = rtsi_clock_line;
        configCmd.n = 2;
        configCmd.data = configData;
        configCmd.data[0] = INSN_CONFIG_SET_ROUTING;
        configCmd.data[1] = NI_RTSI_OUTPUT_RTSI_OSC;
        ret = comedi_do_insn(dev, &amp;configCmd);
        if(ret &lt; 0){
                comedi_perror("comedi_do_insn: INSN_CONFIG");
                exit(1);
        }
        // Set clock RTSI line as output
        ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_OUTPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }

        /* Set routing of the 3 main AI RTSI signals and their direction to output.
           We're reusing the already initialized configCmd instruction here since
           it's mostly the same. */
        configCmd.chanspec = 0;
        configCmd.data[1] =  NI_RTSI_OUTPUT_ADR_START1;
        ret = comedi_do_insn(dev, &amp;configCmd);
        if(ret &lt; 0){
                comedi_perror("comedi_do_insn: INSN_CONFIG");
                exit(1);
        }
        ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_OUTPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }

        configCmd.chanspec = 1;
        configCmd.data[1] =  NI_RTSI_OUTPUT_ADR_START2;
        ret = comedi_do_insn(dev, &amp;configCmd);
        if(ret &lt; 0){
                comedi_perror("comedi_do_insn: INSN_CONFIG");
                exit(1);
        }
        ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_OUTPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }

        configCmd.chanspec = 2;
        configCmd.data[1] =  NI_RTSI_OUTPUT_SCLKG;
        ret = comedi_do_insn(dev, &amp;configCmd);
        if(ret &lt; 0){
                comedi_perror("comedi_do_insn: INSN_CONFIG");
                exit(1);
        }
        ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_OUTPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }
}
</pre><p>
An example to slave a m-series device from this master follows.  A pre-m-series
device would need to use <code class="constant">NI_MIO_RTSI_CLOCK</code> for
the clock source instead.  In
your code, you may also wish to configure the master device to use the
external clock source instead of using its internal clock directly (for
best syncronization).
</p><pre class="programlisting">
void comediEnableSlave(comedi_t *dev){
        comedi_insn   configCmd;
        lsampl_t      configData[3];
        int           ret;
        unsigned int  d = 0;;
        static const unsigned rtsi_subdev = 10;
        static const unsigned rtsi_clock_line = 7;

        memset(&amp;configCmd, 0, sizeof(configCmd));
        memset(&amp;configData, 0, sizeof(configData));
        configCmd.insn = INSN_CONFIG;
        configCmd.subdev = rtsi_subdev;
        configCmd.chanspec = 0;
        configCmd.n = 3;
        configCmd.data = configData;
        configCmd.data[0] = INSN_CONFIG_SET_CLOCK_SRC;
        configCmd.data[1] = NI_MIO_PLL_RTSI_CLOCK(rtsi_clock_line);
        configCmd.data[2] = 100;        /* need to give it correct external clock period */
        ret = comedi_do_insn(dev, &amp;configCmd);
        if(ret &lt; 0){
                comedi_perror("comedi_do_insn: INSN_CONFIG");
                exit(1);
        }
        /* configure RTSI clock line as input */
        ret = comedi_dio_config(dev, rtsi_subdev, rtsi_clock_line, INSN_CONFIG_DIO_INPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }
        /* Configure RTSI lines we are using for AI signals as inputs. */
        ret = comedi_dio_config(dev, rtsi_subdev, 0, INSN_CONFIG_DIO_INPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }
        ret = comedi_dio_config(dev, rtsi_subdev, 1, INSN_CONFIG_DIO_INPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }
        ret = comedi_dio_config(dev, rtsi_subdev, 2, INSN_CONFIG_DIO_INPUT);
        if(ret &lt; 0){
                comedi_perror("comedi_dio_config");
                exit(1);
        }
}

int comediSlaveStart(comedi_t *dev){
        comedi_cmd     cmd;
        unsigned int   nChannels = 8;
        double         sampleRate = 50000;
        unsigned int   chanList[8];
        int            i;

        // Setup chan list
        for(i = 0; i &lt; nChannels; i++){
                chanList[i] = CR_PACK(i, 0, AREF_GROUND);
        }
        // Set up command
        memset(&amp;cmd, 0, sizeof(cmd));
        ret = comedi_get_cmd_generic_timed(dev, subdevice, &amp;cmd,
                (int)(1e9/(nChannels * sampleRate)));
        if(ret&lt;0){
                printf("comedi_get_cmd_generic_timed failed\n");
                return ret;
        }
        cmd.chanlist        = chanList;
        cmd.chanlist_len    = nChannels;
        cmd.scan_end_arg    = nChannels;
        cmd.start_src        = TRIG_EXT;
        cmd.start_arg        = CR_EDGE | NI_EXT_RTSI(0);
        cmd.convert_src    = TRIG_EXT;
        cmd.convert_arg    = CR_INVERT | CR_EDGE | NI_EXT_RTSI(2);
        cmd.stop_src        = TRIG_NONE;

        ret = comedi_command(dev0, &amp;cmd0);
        if(ret&lt;0){
                printf("comedi_command failed\n");
                return ret;
        }
        return 0;
}
</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="slowlyvarying.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="acquisitionfunctions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="comedireference.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.6. 
Slowly-varying inputs
 </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. 
		<acronym class="acronym">Comedi</acronym> reference
	</td></tr></table></div></body></html>