libpruio  0.0
AM33xx-PRU driver for digital input / output and analog input
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/_Features.md
Go to the documentation of this file.
1 Features {#ChaFeatures}
2 ========
3 \tableofcontents
4 
5 libpruio features in short
6 
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)
26 
27 Functional Description {#SecFunction}
28 ======================
29 
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.
33 
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.
37 
38 Operation gets done in three steps
39 
40 -# wake up and prepare ADC and GPIO devices, fetch original configuration
41 -# configure devices
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
47 
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.
51 
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
57 measurement.
58 
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).
62 
63 
64 Constructor {#SubConstructor}
65 -----------
66 
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).
70 
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.
75 
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.
81 
82 Later, these default settings can get extended by additional steps or
83 the default steps can get overriden by customized parameters.
84 
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.
88 
89 
90 GPIO Pin Configuration {#SubCustomizePin}
91 ----------------------
92 
93 The function \ref PruIo::gpio_set() is used to customize the
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).
100 
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.
109 
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().
115 
116 
117 GPIO Pin Description {#SubDescripbePin}
118 --------------------
119 
120 The function \ref PruIo::gpio_get_config() creates a human readable
121 desription of a current CPU ball setting. Detailed information are
122 generated for balls in mode 7 (GPIO). Otherwise only the mode number
123 gets shown.
124 
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.
128 "b097").
129 
130 
131 ADC Step Configuration {#SubCustomizeStep}
132 ----------------------
133 
134 The function \ref PruIo::adc_step() is used to customize the
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
138 PruIo::config().
139 
140 
141 ADC Settings {#SubCustomizeAdc}
142 ------------
143 
144 Furthermore (for advanced users) some registers of the ADC device can
145 get influenced by changing the member variables \ref PruIo::AdcReg24 to
146 \ref PruIo::AdcReg40 (ie. IRQ and DMA settings). These get uploaded to
147 the ADC device by each call to function \ref PruIo::config().
148 
149 
150 Config {#SubConfig}
151 ------
152 
153 The function \ref PruIo::config() uploads the local driver
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.
157 
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
160 mode.
161 
162 
163 Digital IO {#SubDIO}
164 ----------
165 
166 Digital input and output is available in IO mode. Set the state of an
167 output pin by a call to function \ref PruIo::gpio_out() or get the
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.
172 
173 \note Digital IO is only available in IO mode. It doesn't work in MM mode.
174 
175 
176 Analog Input {#SubAI}
177 ------------
178 
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().
185 
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
191 get skipped).
192 
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.
196 
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.)
203 
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.
207 
208 
209 Start (MM) {#SubStart}
210 ----------
211 
212 The function \ref PruIo::mm_start() is used to start a measurement in
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
219 given order.
220 
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
227 (see below).
228 
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.
235 
236 
237 Digital Trigger (MM) {#SubTrigPin}
238 --------------------
239 
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.
243 
244 Use function \ref PruIo::mm_trg_pin() to create a digital trigger
245 specification and pass it in the call to function \ref
246 PruIo::mm_start().
247 
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.
252 
253 A delay time can get added after the trigger event and before the
254 measurement (or the next trigger) starts.
255 
256 
257 Analog Trigger (MM) {#SubTrigAin}
258 -------------------
259 
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.
265 
266 Use function \ref PruIo::mm_trg_ain() to create an analog trigger
267 specification and pass it in the call to function \ref
268 PruIo::mm_start().
269 
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.
275 
276 A delay time can get added after the trigger event and before the
277 measurement (or the next trigger) starts.
278 
279 
280 Pre-Trigger (MM) {#SubTrigPre}
281 ----------------
282 
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.
291 
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
294 steps.
295 
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
299 get ignored).
300 
301 
302 Destructor {#SubDestructor}
303 ----------
304 
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.
309 
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).
313 
314 
315 PRU subsystem {#SubPru01}
316 -------------
317 
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
323 details.