libpruio  0.2
Input/Output driver for digital/analog lines on Beagleboard hardware
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/features.md
1 Features {#ChaFeatures}
2 ========
3 \tableofcontents
4 
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
8 
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
24 
25 
26 PRUSS {#SecPruss}
27 =====
28 
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
34 PruIo::PruIo().
35 
36 
37 Operation {#SecOperation}
38 =========
39 
40 libpruio controls the AM3359 CPU subsystems
41 
42 - TSC_ADCSS (Touch Screen Controler and Analog to Digital Converter
43  SubSystem)
44 
45 - GPIO (4x General Purpose Input Output subsystem)
46 
47 - PWMSS (3x Pulse Width Modulation SubSystem, containing modules PWM,
48  CAP and QEP)
49 
50 by a sequence of these three steps
51 
52 -# Create a PruIo structure, read initial configuration (constructor
53  PruIo::PruIo() ).
54 
55 -# Upload customize configuration to the subsystem registers and start
56  operation (function PruIo::config() ).
57 
58 -# When done, restore original register configuration and destroy the
59  PruIo structure (destructor PruIo::~PruIo).
60 
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.
64 
65 \note Create just one PruIo structure at a time.
66 
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.
71 
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.
75 
76 
77 Modi {#SecModi}
78 ====
79 
80 libpruio supports three run modi. They differ in the priority of the
81 timing of the ADC subsystem restarts:
82 
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.
88 
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.
94 
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).
98 
99 Choose the run modus by setting parameter *Samp* in the call to
100 function PruIo::config()
101 
102 - `Samp = 1` for IO mode, immediate start.
103 
104 - `Samp > 1` for RB, call function PruIo::rb_start() to start.
105 
106 - `Samp > 1` for MM, each call to function PruIo::mm_start() starts a new measurement.
107 
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
110 PruIo::~PruIo.
111 
112 
113 Pinmuxing {#SecPinmuxing}
114 =========
115 
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.
119 
120 - An output line gets configured by the first call to the setValue
121  member function (ie. GpioUdt::setValue() or PwmMod::setValue() ).
122 
123 - An input line gets configured by a call to the config member function
124  (ie. GpioUdt::config() or CapMod::config() ).
125 
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.
129 
130 
131 GPIO {#SecGpio}
132 ====
133 
134 General Purpose Input Output is available by the GpioUdt member
135 functions (in IO and RB mode, for all header pins).
136 
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
141  Steinkuehler).
142 
143 - Call function GpioUdt::Value() to get the current state (input or output).
144 
145 - Call function GpioUdt::setValue() to set an output state.
146 
147 Furthermore, simultameous input and output can get realized by direct
148 access to the PRU software (experts only).
149 
150 
151 CAP {#SecCap}
152 ===
153 
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.
157 
158 - Call function CapMod::config() to configure the pin as CAP input.
159 
160 - Call function CapMod::Value() to get the current frequency and/or duty cycle.
161 
162 A minimal frequency can get specified to reduce the reaction time in
163 case of no input.
164 
165 
166 PWM {#SecPwm}
167 ===
168 
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.
174 
175 - Call function PwmMod::setValue() to set the frequncy and duty cycle
176  (and configure the pin, if necessary).
177 
178 - Call function CapMod::Value() to get the current frequency and/or
179  duty cycle (those may differ from the required values).
180 
181 Furthermore advanced features of the PWMSS subsystems can be used by
182 direct access to the register configuration and PRU software (experts
183 only).
184 
185 
186 ADC {#SecAdc}
187 ===
188 
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.
195 
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
199 AIN-7.
200 
201 - Call function PruIo::config() to set the run mode, the step mask, the
202  measurement timing and the bit encoding.
203 
204 - Call function AdcUdt::setStep() to customize a step configuration
205  (optional).
206 
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().
210 
211 
212 Bit Encoding {#SubSecBitEncoding}
213 ------------
214 
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).
220 
221 - Adapt parameter *Mds* in the call to function PruIo::config() to
222  customize the bit encoding.
223 
224 
225 Ring Buffer {#SubSecRB}
226 -----------
227 
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.
231 
232 - Read PruIo::DRam `[0]` to get the most recent write position (UInt16
233  index).
234 
235 
236 Triggers {#SubSecTriggers}
237 --------
238 
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.
243 
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.
248 
249 Post-triggers may delay the measurement start or the start of the next
250 trigger for a certain time.
251 
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.
254 
255 Call function
256 
257 - AdcUdt::mm_trg_pin() to create a trigger specification for a
258  digital line,
259 
260 - AdcUdt::mm_trg_ain() to create a trigger specification for an
261  analog line, and
262 
263 - AdcUdt::mm_trg_pre() to create a pre-trigger specification for
264  an analog line.
265 
266 Pass the trigger specification[s] to function PruIo::mm_start()
267 to activate them.
268 
269 
270 Subsystem Control {#SecSubSysCont}
271 =================
272 
273 libpruio controls several subsystems, listed in section \ref
274 SecOperation. Each of these subsystems can either
275 
276 - get configured and used (the default), or
277 
278 - get switched of (ie. to reduce power consumption). or
279 
280 - get ignored (no subsystem access, just evaluate the initial state).
281 
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.
287 
288 By default all subsystems are active (not ignored). All active
289 subsystems are enabled after the constructor call (unless the hardware
290 fails). Check
291 
292 - the subsystems initial clock value to find out if the subsystem was
293  enabled before the constructor call (ie. AdcSet::ClVa or
294  GpioSet::ClVa have values of `2` if enabled),
295 
296 - the subsystems version information to find out if the subsystem is
297  enabled after the constructor call (ie. AdcSet::REVISION or
298  PwmssSet::IDVER have values of `0` (zero) if wakeup failed).
299 
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
303 function PruIo::config() can change a subsystem state.
304 
305 - Set its status bit in parameter *Act* when calling the constructor
306  PruIo::PruIo().
307 
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
311  subsystem (PWMSS-2).
312 
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.
316 
317 
318 Overlays {#SecOverlays}
319 ========
320 
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
328 privileges.
329 
330 Adapt the source code, compile and execute it.
331 
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).
Definition: pruio_gpio.bi:21
Main structure, binding all components together.
Definition: pruio.bi:118
~PruIo()
Destructor to restore configurations and clear memory.
Definition: pruio.bas:295
PruIo(BYVAL_AS_UInt16, BYVAL_AS_UInt8, BYVAL_AS_UInt32, BYVAL_AS_UInt8)
Constructor, initialize subsystems, create default configuration.
Definition: pruio.bas:190
UInt32 IDVER
IP Revision Register (see ARM Reference Guide, chapter 15.1.3.1 ).
Definition: pruio_pwmss.bi:39
Structure for ADC subsystem features, containing all functions and variables to handle the subsystem...
Definition: pruio_adc.bi:95
UInt32 last[...]
The previous data of the channels.
Definition: oszi.bas:59
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).
Definition: pruio_adc.bas:229
UInt32 ClVa
Clock value (defaults to 2 = enabled, set to 0 = disabled).
Definition: pruio_adc.bi:53
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).
Definition: pruio.bas:450
VAR x
The header pin name.
Definition: dts_custom.bas:82
UInt32 REVISION
Register at offset 00h (see ARM Reference Guide, chapter 12.5.1.1 ).
Definition: pruio_adc.bi:58