1 Features {#ChaFeatures}
5 libpruio features in
short
7 - wakeup devices (GPIO and ADC)
8 - read original devices configuration (
if any)
9 - customize GPIO configuration
10 - customizing from user-point-of-view (header pins instead of CPU ball numbers)
11 - create a text description
for a GPIO configuration
12 - lock or unlock GPIOs
13 - customize ADC configuration and channel settings
14 - run in IO mode (IO) or measurement mode (MM)
15 - get GPIO input state (IO)
16 - set GPIO output state (IO)
17 - fetch ADC samples continuously (IO)
18 - fetch a given number of samples for a given set of channels (MM)
19 - start measurement by one or up to four trigger events (MM)
20 - absolute or delta triggers (MM)
21 - post-triggers start sampling after a certain time (MM)
22 - pre-trigger starts sampling before the trigger event happened (MM)
23 - transform ADC samples to 13, 14, 15 or 16 bit values
24 - restore previous settings when done (if any)
25 - run either on PRU-0 or PRU-1 (default)
27 Functional Description {#SecFunction}
28 ======================
30 This driver uses a PRU subsystem to operate the ARM devives Control
31 Module, GPIO[0-3] and TSC_ADC_SS. The software can either run on PRU-0
32 or on PRU-1 (the later is the
default) and is highly configurable.
34 To run
this library the PRU subsystems must be enabled and read / write
35 privilegues are necessary to the PRU system interrupt `/dev/uio5`,
36 see \ref ChaPreparation
for details.
38 Operation gets done in three steps
40 -# wake up and prepare ADC and GPIO devices, fetch original configuration
42 - customize GPIO settings (optional)
43 - customize ADC channel settings (or use defaults)
44 - upload settings to PRU and start (in IO mode) or wait
for start command (in MM mode)
45 - start measurement (MM)
46 -# when done, restore original configuration (
if any) and destroy driver UDT
48 After configuration the driver software runs on the PRU subsystem in an
49 endless loop. Interrupt
this loop by either uploading a
new
50 configuration or destroying the driver structure.
52 The driver either runs in input / output mode (IO) or measurement mode
53 (MM). In IO mode the software on the host (ARM) controls the data flow
54 and the driver continuously transfers values to and from the devices.
55 In MM mode the software on the host starts the execution and then waits
56 until the driver software on the PRU finished the specified
59 All parameters for the ADC device are stored local in the
PruIo
60 structure and get uploaded by a call the function \ref
PruIo::config().
61 GPIO settings can get changed at runtime (in IO mode).
64 Constructor {#SubConstructor}
67 The constructor \ref
PruIo::PruIo() creates a new driver structure and
68 prepares the devices. It wakes up the GPIO and ADC devices (if powered
69 off) or reads the original configuration (if already running).
71 The digital input lines (GPIO) are used unchanged. All lines connected
72 to one of the Beaglebone headers P8 or P9 get checked. Each connector
73 (pin) that is configured in mode 7 (GPIO) gets unlocked. Pins in other
74 modes and pins not connected to a header get locked.
76 A set of ADC step configurations get created with default values. Step
77 1 to 8 are set to sample inputs AIN0 to AIN7 with an avaraging of 4
78 samples and an open delay of 200 cycles, resulting in a sampling rate
79 of 10 kilo samples per second. Pass parameters to customize avaranging,
80 open delay and sample delay for the steps in the default configuration.
82 Later, these default settings can get extended by additional steps or
83 the default steps can get overriden by customized parameters.
85 \note Never create more than one instance of the
PruIo at a time. They
86 may interfere on memory or interrupt settings. Destroy the first
87 instance before creating a new one.
90 GPIO Pin Configuration {#SubCustomizePin}
91 ----------------------
94 configuration of CPU connectors (balls). The Control Module in the ARM
95 processor is used to connect a CPU ball to an internal CPU device. To
96 use a ball as GPIO, it must be set in mode 7. In this mode it can
97 either be an input or an output. Input balls can optionally get
98 connected to a pullup or pulldown resistor. Output balls get set to an
99 initial high or low state (and have no resistor connected by default).
101 The libpruio user need not care about CPU balls. The extension
102 pruio_pins.bi contains macros to perform configurations from the user
103 point of view. These macros hide the CPU ball number behind an easy to
104 understand name in case of all balls connected to a Beaglebone header
105 (P8 or P9). In contrast to the CPU balls these connectors are called
106 pin in this document. Ie. use '
P8_07' to refer to the CPU ball
107 connected to pin 7 on header P8. The file pruio_pins.bi also contains
108 arrays to easy address groups of pins.
110 libpruio contains a locking mechanism to protect unintentional pin
111 changes. All balls are locked by default, except the pins (balls
112 connected to a Beaglebone header P8 or P9) that are configured in mode
113 7 at startup (these get unlocked by the constructor). The user is free
114 to customize the locking by calls to function \ref
PruIo::gpio_set().
117 GPIO Pin Description {#SubDescripbePin}
121 desription of a current CPU ball setting. Detailed information are
122 generated for balls in mode 7 (GPIO). Otherwise only the mode number
125 This function can be used on all CPU balls. Pins on the headers are
126 named after their position (ie. like "H8_46") and internaly connected
127 CPU balls are named by their Control Module reference number (ie.
131 ADC Step Configuration {#SubCustomizeStep}
132 ----------------------
135 configuration for a single channel. Changes get stored in to the local
136 settings in the driver structure and take into acount after uploading
137 the driver configuration by the next call to function \ref
141 ADC Settings {#SubCustomizeAdc}
144 Furthermore (
for advanced users) some registers of the ADC device can
145 get influenced by changing the member variables \ref
PruIo::AdcReg24 to
147 the ADC device by each call to function \ref
PruIo::config().
154 configuration (from the host = ARM) and the instructions to the PRU
155 device. And it starts executing the program, which configures the
156 devices Arm Control Module, GPIOs and ADC.
158 Depending on the requirend number of samples it either immediately
159 starts in IO mode or waits for a call to \ref
PruIo::mm_start() in MM
166 Digital input and output is available in IO mode. Set the state of an
168 state of an input or output pin by a call to function \ref
169 PruIo::gpio_get(). You can get the state of all pins, but setting
170 the state is only allowed for unlocked pins in output mode. Use
171 function \ref
PruIo::gpio_set() to change pin mode and locking.
173 \note Digital IO is only available in IO mode. It doesn't work in MM mode.
176 Analog Input {#SubAI}
179 Analog input is available in IO mode and in MM mode. In MM mode the
180 driver fetches a pre-defined set of samples in real time (and does
181 nothing
else). In IO mode the driver updates the ADC samples
182 continuously and the software on the host (ARM) controls when to fetch
183 a value. Switch between both modes by setting the parameter Samp in a
184 call to function \ref
PruIo::config().
186 Refer to the samples of the ADC device by the member array \ref
187 PruIo::Value. Its context depends on the execution mode. In IO mode the
188 array contains one value for each step. Non-active steps are set to 0
189 (= zero). Active steps contain the
last sampled value. In MM mode the
190 array contains only valid samples (all zero values of non-active steps
193 The sampled values can get scaled in 12 to 16 bit resolution (ie. to
194 directly compare the values with results from a 16 bit audio device).
195 See parameter Mds for function \ref
PruIo::config() for details.
197 In IO mode the sampling rate depends on the configuration of the ADC
198 device and the steps. The parameter ClkDiv and the avaraging, the open
199 and the sample delay values specify the time the ADC device needs to
200 execute a run through all active steps. When such a run is finished the
201 driver starts the ADC device again. (The timing of the re-start may
202 vary a few micro seconds.)
204 In MM mode the sampling rate gets defined by the parameter Tmr in the
205 call to function \ref
PruIo::config(). In this mode the driver uses an
206 internal CPU timer to garanty maximum timing precision.
209 Start (MM) {#SubStart}
213 measurement mode (MM). By default (no parameters) the measurement
214 starts immediately. Otherwise the measurement starts after all
215 specified trigger events happend. Up to four trigger events can get
216 specified by parameters. In case of more than one trigger event, the
217 first trigger starts the second, the second starts the third and so on.
218 Measurement doesn't start before all trigger events happened in the
221 Trigger events can either be specified as an event on a digital or
222 analog line. In case of a digital event the trigger waits until the
223 specified input or output GPIO gets in the given state. In case of an
224 analog trigger a specified ADC step gets executed and the resulting
225 sample gets compared with the trigger setting. Delay times can be added
226 after, but for an analog trigger also before the trigger event happens
229 This function is designed for synchronuous calls. It waits until all
230 trigger events occured and the measurement is finished. Enclose it in a
231 thread when you need asynchronous execution. But never execute more
232 than one call at a time. When running in a thread the current state can
233 get checked in the member variable \ref
PruIo::DRam[0]. See \ref
234 ChaMessages for details.
237 Digital Trigger (MM) {#SubTrigPin}
240 An digital trigger is used to start a measurement in MM. It compares
241 the state of the given CPU ball against the specified trigger value.
242 Input or output balls can be used as trigger.
245 specification and pass it in the call to function \ref
248 During the waiting phase only the GPIO state gets checked and the ADC
249 device is in idle mode. After the trigger event happened, the ADC gets
250 started, all configured steps get active and sampling rate slows down
251 to the specified value.
253 A delay time can get added after the trigger event and before the
254 measurement (or the next trigger) starts.
257 Analog Trigger (MM) {#SubTrigAin}
260 An analog trigger is used to start a measurement in MM. It compares the
261 current sample of the given ADC step against the specified trigger
262 value. The trigger
event happens
if the current sample is either
263 greater or less than the specified trigger value. The trigger value can
264 either be an absolute value or it can
get specified as relative change.
267 specification and pass it in the call to function \ref
270 During the waiting phase only the trigger step is active and the ADC
271 device runs at maximum sampling rate with the previously configured ADC
272 settings (all other steps are disabled). After the trigger event
273 happened, all configured steps get active and sampling rate slows
274 down to the specified value.
276 A delay time can get added after the trigger event and before the
277 measurement (or the next trigger) starts.
280 Pre-Trigger (MM) {#SubTrigPre}
283 An pre-trigger is used to start a measurement in MM. In contrast to the
284 previous triggers a pre-trigger starts measurement before the trigger
285 event happens. This means the measurement gets started immediately,
286 doing all active steps. The samples
get stored in a ring buffer,
287 overriding old values when the buffer is
full. When the trigger
event
288 happens, measurement continues but the samples
get stored in the normal
289 buffer (outside the ring buffer). After the measurement the samples in
290 the ring buffer
get sorted in the right order.
292 Currently a pre-trigger only can use an analog input line (but no
293 digital). It
's possible to either trigger on one or all active analog
296 Use function \ref PruIo::mm_trg_pre() to create a specification for a
297 pre-trigger and pass it in the call to function \ref PruIo::mm_start().
298 A pre-trigger is allways the last trigger specification (further specs
302 Destructor {#SubDestructor}
305 The destructor resets the devices Control Module, GPIOs and ADC to the
306 original state. It powers off the devices or restores the original
307 configurations (if they were running on start-up). Then it frees the
308 memory used by the driver structure.
310 It's possible to
override the original configurations (only useful
for
311 advanced users and undocumented, check source code and \ArmRef{9, 12
312 and 25}
for details).
315 PRU subsystem {#SubPru01}
318 The driver is designed to run either on PRU-0 or PRU-1 subsystem, so
319 you can use the other PRU system
for additional purposes. By
default it
320 runs on PRU-1 (see \ref
PruIo::PruIo to customize) and uses its DRam
321 memory area. In
case of a pre-trigger (in MM mode) the DRam from the
322 other PRU may be used to sort the samples, see \ref ChaMemory
for