1 Features {#ChaFeatures}
5 libpruio is designed to enable fast (faster than sysfs), flexible
6 (customizablee) and easy (single source) access to the AM33xx CPU
7 subsystems. Its features in
short
9 - run on PRU-0 or PRU-1 (default)
10 - control subsystems at runtime (disable or enable and configure)
11 - run in different run modi (IO, RB and MM)
12 - configure a header pin
13 - get digital input (GPIO)
14 - set digital output (GPIO)
15 - analyse digital input train (CAP frequency and duty cycle)
16 - set digital output train (PWM frequency and duty cycle)
17 - get analog input (ADC)
18 - apply samples bit encoding (12 to 16 bit)
19 - configure ADC settings (input channel, timing, averaging)
20 - perform high-speed measurements (up to 160 kSamples/s)
21 - start measurement by trigger events (up to 4)
22 - trigger on analog or digital lines
23 - perform a pre-trigger that starts measurement before the event happens
29 libpruio contains software running on the host system (ARM) and
30 software running on a Programable Realtime Unit SubSystem (PRUSS). The
31 AM33xx CPU on Beaglebone hardware contains two PRU subsystems. libpruio
32 can use either PRU-0 or PRU-1 (the later is the default). To use PRU-0,
33 just clear bit 0 in parameter *Act* when calling the constructor
37 Operation {#SecOperation}
40 libpruio controls the AM3359 CPU subsystems
42 - TSC_ADCSS (Touch Screen Controler and Analog to Digital Converter
45 - GPIO (4
x General Purpose Input Output subsystem)
47 - PWMSS (3
x Pulse Width Modulation SubSystem, containing modules PWM,
50 by a sequence of these three steps
52 -# Create a
PruIo structure, read initial configuration (constructor
55 -# Upload customize configuration to the subsystem registers and start
58 -# When done, restore original
register configuration and destroy the
61 Customize the configuration of analog and digital lines and the
62 subsystem registers before step 2. And operate the configured
63 subsystems and lines after step 2.
65 \note Create just one
PruIo structure at a time.
67 libpruio offers a set of API functions to
do simple IO task at a
68 reasonable speed. They may be inefficient in
case of advanced
69 requirements. Therefor libpruio allows direct access to all
register
70 configurations of the subsystems. The later is
for experts only.
72 \note It
's save to control the Beaglebone hardware by the libpruio API
73 functions. In contrast accessing the register sets directly is
74 for experts only and may cause non-revisible hardware damages.
80 libpruio supports three run modi. They differ in the priority of the
81 timing of the ADC subsystem restarts:
83 -# IO mode (inaccurate ADC timing): the PRU is running in an endless
84 loop and handles input and output lines of all subsystems at the
85 same priority. Depending on the number of enabled subsystems and the
86 step configuration, there may be some delay of up to 50 ns before
87 the ADC subsystems starts again to fetches the next set of samples.
89 -# RB mode (accurate ADC timing): the PRU is running in an endless
90 loop and handles restarts of the ADC subsystem at prefered priority.
91 Digital input and output gets only handled when the PRU is waiting
92 for the next ADC restart. This may cause some delay of up to 50 ns
93 before a digital output gets set or a digital value gets in.
95 -# MM mode (accurate timing): the PRU waits for a start command and
96 performs a single measurement. It handles analog samples only (no
97 digital IO available).
99 Choose the run modus by setting parameter *Samp* in the call to
100 function PruIo::config()
102 - `Samp = 1` for IO mode, immediate start.
104 - `Samp > 1` for RB, call function PruIo::rb_start() to start.
106 - `Samp > 1` for MM, each call to function PruIo::mm_start() starts a new measurement.
108 To stop an endless mode (IO or RB) call function PruIo::config() again.
109 Or destroy the libpruio structure when done by calling the destructor
113 Pinmuxing {#SecPinmuxing}
116 A digital line of the AM33xx CPU needs to be configured before use
117 (see section \ref SecPinConfig for details). libpruio checks the pin
118 configuration at run-time, and tries to adapt it if necessary.
120 - An output line gets configured by the first call to the setValue
121 member function (ie. GpioUdt::setValue() or PwmMod::setValue() ).
123 - An input line gets configured by a call to the config member function
124 (ie. GpioUdt::config() or CapMod::config() ).
126 Pinmuxing at run-time requires administrator privileges. To run your
127 libpruio application with user privileges, make sure that digital lines
128 are in the required state (configuration) before executing the code.
134 General Purpose Input Output is available by the GpioUdt member
135 functions (in IO and RB mode, for all header pins).
137 - Call GpioUdt::config() to set the CPU ball in the required state
138 (internal resistor pullup/pulldown/nopull, receiver active) when
139 running under administrator privileges. Otherwise use a device tree
140 overlays or an external tool like pinconfig-pin (Charles
143 - Call function GpioUdt::Value() to get the current state (input or output).
145 - Call function GpioUdt::setValue() to set an output state.
147 Furthermore, simultameous input and output can get realized by direct
148 access to the PRU software (experts only).
154 Capture and Analyse a digital Pulse train is available by the CapMod
155 member functions (in IO and RB mode, two header pins). The frequency
156 and duty cycle of an Beaglebone header input pin can get measured.
158 - Call function CapMod::config() to configure the pin as CAP input.
160 - Call function CapMod::Value() to get the current frequency and/or duty cycle.
162 A minimal frequency can get specified to reduce the reaction time in
169 Generating a Pulse Width Modulated output is available by the PwmMod
170 member functions (in IO and RB mode). Therefor libpruio uses the PWMSS
171 subsystems, either the PWM module (two `17` bit outputs A and B at the
172 same frequency) or the CAP module in auxialiary PWM output mode (single
173 `32` bit output). Both modules are supported in a transparent API.
175 - Call function PwmMod::setValue() to set the frequncy and duty cycle
176 (and configure the pin, if necessary).
178 - Call function CapMod::Value() to get the current frequency and/or
179 duty cycle (those may differ from the required values).
181 Furthermore advanced features of the PWMSS subsystems can be used by
182 direct access to the register configuration and PRU software (experts
189 In all modes (IO, RB and MM) Analog Digital Converted input can get
190 sampled by the AdcUdt member functions, controling the Touch Screen
191 Controler and Analog to Digital Converter Subsystem (TSC_ADC_SS). It
192 samples analog data on eight input lines (AIN-0 to AIN-7). While line
193 AIN-7 is connected by a voltage divider on board to the 3V3 power
194 supply, the other lines (AIN-0 to AIN-6) are free available.
196 The ADC subsystem can use up to `16` step configurations (and an
197 additional charge step) to perform a measurement. libpruio
198 pre-configures steps `1` to `8` by default to sample lines AIN-0 to
201 - Call function PruIo::config() to set the run mode, the step mask, the
202 measurement timing and the bit encoding.
204 - Call function AdcUdt::setStep() to customize a step configuration
207 - Read array AdcUdt::Value to get the sampled values. The context
208 depends on the run mode of libpruio, specified by the parameter
209 *Samp* in the most recent call to function PruIo::config().
212 Bit Encoding {#SubSecBitEncoding}
215 The Beaglebone ADC subsystem samples 12 bit values in the range of `0` to
216 `4095`. Most other devices (ie. like sound cards) use `16` bit encoding
217 (in the range of `0` to `65535`) and the values cannot get compared
218 directly. Therefor libpruio can left shift the samples internaly. By
219 default the output is 16 bit encoded (range 0 to 65520).
221 - Adapt parameter *Mds* in the call to function PruIo::config() to
222 customize the bit encoding.
225 Ring Buffer {#SubSecRB}
228 In Ring Buffer mode the samples from the ADC subsystem continously get
229 stored in the external memory. The calling software has to make sure
230 that only valid values get read.
232 - Read PruIo::DRam `[0]` to get the most recent write position (UInt16
236 Triggers {#SubSecTriggers}
239 In Measurement Mode (MM mode) the start of a measurement can either be
240 immediately, or the start can get triggered by up to four events. When
241 the first event happens, the second trigger gets started, and so on.
242 The last specified trigger starts the measurement.
244 A trigger event may be a digital line reaching a certain state or an
245 analog line reaching a certain voltage. The voltage can get specified
246 as an absolute voltage or as a difference related to the measured
247 voltage at trigger start.
249 Post-triggers may delay the measurement start or the start of the next
250 trigger for a certain time.
252 A pre-trigger can be used to start the measurement before the event
253 happens. Only one pre-trigger is allowed, it's always the
last trigger.
260 -
AdcUdt::mm_trg_ain() to create a trigger specification for an
263 -
AdcUdt::mm_trg_pre() to create a pre-trigger specification for
266 Pass the trigger specification[s] to function
PruIo::mm_start()
270 Subsystem Control {#SecSubSysCont}
273 libpruio controls several subsystems, listed in section \ref
274 SecOperation. Each of these subsystems can either
276 -
get configured and used (the
default), or
278 -
get switched of (ie. to reduce power consumption). or
280 -
get ignored (no subsystem access, just evaluate the initial state).
282 To ignore a subsystem, clear its status bit in parameter *Act* when
283 calling the constructor
PruIo::PruIo(). Each subsystem gets controlled
284 by its own status bit. When a system is set to be ignored, libpruio
285 cannot access it. There
's no configuration data and there's no reset to
286 the initial state
for the subsystem by the destructor
PruIo::~PruIo.
288 By
default all subsystems are active (not ignored). All active
289 subsystems are enabled after the constructor call (unless the hardware
292 - the subsystems initial clock value to find out
if the subsystem was
293 enabled before the constructor call (ie.
AdcSet::ClVa or
296 - the subsystems version information to find out
if the subsystem is
300 libpruio stores a complete set of configuration data
for active
301 subsystems and restores their state by the destructor when finished.
302 Active subsystems can
get enabled or disabled at run-time. Each call to
305 - Set its status bit in parameter *Act* when calling the constructor
308 - To disable a subsystem, set the clock value to `0` (zero), before
309 calling function
PruIo::config(). Ie. set
310 `
PruIo->PwmSS->Conf(2)->ClVa = 0` to switch off the third PWMSS
313 - To enable a subsystem, set the clock value to `2`, before calling
314 function
PruIo::config(). Ie. set `
PruIo->Adc->Conf->ClVa = 2`
315 to enable the ADC subsystem.
318 Overlays {#SecOverlays}
321 The libpruio
package contains tools to create, compile and install
322 device tree overlays in folder src/config. Either an overlay with fixed
323 pin configuration. This overlay type configures the pins before the
324 libpruio code gets executed. The code can run with user privileges. Or
325 an universal overlay, that provide run-time pinmuxing capability. That
326 means the pin mode and resistor / receiver configuration can get
327 changed when the libpruio code is running. The later needs admin
330 Adapt the source code, compile and execute it.
332 - Use dts_custom.bas for overlays with fixed pinmuxing, or
333 - use dts_universal.bas for overlays providing run-time pinmuxing capability.
UInt32 ClVa
Clock value (defaults to 2 = enabled, set to 0 = disabled).
Main structure, binding all components together.
~PruIo()
Destructor to restore configurations and clear memory.
PruIo(BYVAL_AS_UInt16, BYVAL_AS_UInt8, BYVAL_AS_UInt32, BYVAL_AS_UInt8)
Constructor, initialize subsystems, create default configuration.
UInt32 IDVER
IP Revision Register (see ARM Reference Guide, chapter 15.1.3.1 ).
Structure for ADC subsystem features, containing all functions and variables to handle the subsystem...
UInt32 last[...]
The previous data of the channels.
FUNCTION_CDECL_AS_UInt32 mm_trg_pin(BYVAL_AS_UInt8, BYVAL_AS_UInt8, BYVAL_AS_UInt16)
Create a trigger configuration for a digital trigger (GPIO).
UInt32 ClVa
Clock value (defaults to 2 = enabled, set to 0 = disabled).
FUNCTION_CDECL_AS_ZSTRING_PTR config(BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt16)
Load configuration from host (ARM) to driver (PRU).
VAR x
The header pin name.
UInt32 REVISION
Register at offset 00h (see ARM Reference Guide, chapter 12.5.1.1 ).