libpruio  0.2
Input/Output driver for digital/analog lines on Beagleboard hardware
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/messages.md
1 Messages {#ChaMessages}
2 ======
3 \tableofcontents
4 
5 libpruio contains two types of software
6 
7 - software running on the host (ARM), reporting human readable messages, and
8 - software running on the PRUSS, reporting its state in form of a number code.
9 
10 The number codes for the states of the PRUSS software get written to
11 PruIo::DRam `[0]` and the codes are defined in file pruio.hp. Ie.
12 code PRUIO_MSG_INIT_OK signals that the init instruction executed
13 successfuly. In normal operations the user need not care about this
14 feature, except when using RB mode.
15 
16 Instead the user communicates with the functions of the API from the
17 host software. Most of this functions are designed to return 0 (zero)
18 on success or an error text (`ZSTRING PTR` in FB, `*gchar` in C) in
19 case of an error. Additionaly the member variable PruIo::Errr gets
20 set to the same message text. You can use either of them to handle the
21 error message. The texts are always internal strings owned by libpruio
22 and must not be freed.
23 
24 Just a few functions do not follow this principle
25 
26 - All constructors, since they don't return anything (they're SUBs).
27 
28 - The function GpioUdt::Value(), since it returns the GPIO state
29  and -1 in case of an error.
30 
31 - The trigger specification functions AdcUdt::mm_trg_pin(),
32  AdcUdt::mm_trg_ain() and AdcUdt::mm_trg_pre(), since they
33  return the specification and 0 (zero) in case of an error.
34 
35 For those functions the error message (if any) is only available in
36 variable PruIo::Errr.
37 
38 In all cases, libpruio just sets the pointer PruIo::Errr. The
39 calling code may or may not handle the error message. When the code
40 tires to continue, it should reset the pointer to 0 (zero) to avoid
41 blocking further function calls due to former errors.
42 
43 There's a last exception: The main destructor PruIo::~PruIo cannot use
44 the variable PruIo::Errr, since it isn't available after the
45 destructor has finished. Instead, the destructor writes error messages
46 (if any) directly to stderr.
47 
48 Here's an overview of all possible error messages from the public UDT
49 member functions and some hints on how to fix the related code:
50 
51 
52 PruIo {#SecErrPruIo}
53 =====
54 
55 Constructor {#SubSecPruIoCTor}
56 -----------
57 
58 \Item{"cannot open /dev/uio5"} The constructor failed to open the
59 interrupt file /dev/uio5 for read and write access. -> Make sure that
60 the kernel driver uio_pruss is loaded (ie. by an appropriate device
61 tree overlay) and the user has write privileges. Find details in
62 section \ref SecPreconditions.
63 
64 \Item{"failed opening prussdrv library"} The constructor failed to
65 initialize the library libprussdrv. -> Make sure that the library is
66 working properly. (Follow the documentation and test some examples.)
67 
68 \Item{"failed loading Pru_Init instructions"} The constructor failed to
69 load the init instructions to the PRU. -> Make sure that the library
70 libprussdrv is working properly. (Follow the documentation and test
71 some examples.)
72 
73 \Item{"failed executing Pru_Init instructions"} The constructor failed
74 to execute the init instructions on the PRU. -> There's some internal
75 error in the PRU instructions due to customization. Re-install or
76 re-compile the libpruio library.
77 
78 \Item{"out of memory"} The constructor failed to allocate memory for
79 the configurations (Init and Conf). -> Make sure that you have at least
80 5 kB free.
81 
82 
83 Destructor {#SubSecPruIoDTor}
84 ----------
85 
86 \note The variable PruIo::Errr isn't valid when the destructor
87  finished. That's why the following messages get streamed directly
88  to stderr.
89 
90 \Item{"failed loading Pru_Exit instructions"} The destructor failed to
91 load the instructions to restore the subsystems initial state to the
92 PRU. -> Make sure that the library libprussdrv is working properly.
93 (Follow the documentation and test some examples.)
94 
95 \Item{"failed executing Pru_Exit instructions"} The destructor failed
96 to execute instructions to restore the subsystems initial state on the
97 PRU. -> There's some internal error in the PRU instructions due to
98 customization. Re-install or re-compile the libpruio library.
99 
100 \Item{"destructor warning: subsystems are NOT restored"} This is not an
101 error but just a warning. The destructor didn't restore the subsystems
102 initial state, since there were no data. Either the constructor
103 couldn't prepare this data due to an error, or the user deleted the
104 data to prevent restoring.
105 
106 \Item{"destructor warning: constructor failed"} This is not an error
107 but just a warning. The destructor didn't do anything (and didn't
108 restore the subsystems initial state), since the constructor failed in
109 an early state.
110 
111 
112 config {#SubSecPruIoConfig}
113 ------
114 
115 \Item{"ADC not enabled"} Sampling analog lines is required, but the ADC
116 subsystem isn't enabled. -> Either check parameters *Samp* and *Mask*
117 in the previous call to function PruIo::config(). Or check the value of
118 `PruIo->Adc->Conf->ClVa` (and enable ADC subsystem).
119 
120 \Item{"no step active"} The RB or MM mode is active (parameter *Samp* >
121 1), but the parameter *Mask* didn't specify any active channel. ->
122 Check those parameters in the previous call to function
123 PruIo::config().
124 
125 \Item{"out of memory"} The external memory isn't big enough for the
126 required number of samples. -> Either reduce the number of samples
127 (parameter *Samp*) or the number of active steps (parameter *Mask*) in
128 the previous call to function PruIo::config(). Or increase the
129 size of the external memory (see ChaMemory for details).
130 
131 \Item{"sample rate too big"} The specified sampling rate isn't
132 reachable with the current step configuration. -> Either reduce the
133 number of active steps (parameter *Mask*), or decrease the sampling
134 rate (increase parameter *Tmr*) in the previous call to function
135 PruIo::config(). Or decrease the step delays (Open and / or Sample
136 Delay in AdcSet::St_p) before that call.
137 
138 \Item{"failed loading Pru_Run instructions"} For safety reasons the PRU
139 instruction get (re-)loaded each time in function PruIo::config().
140 The function failed to load the instructions to the PRU. -> Make sure
141 that the library libprussdrv is working properly. (Follow the
142 documentation and test some examples.)
143 
144 \Item{"failed executing Pru_Run instructions"} The function failed to
145 execute the PRU instructions on the PRU. -> There's some internal error
146 in the PRU instructions due to customization. Re-install or re-compile
147 the libpruio library.
148 
149 
150 rb_start {#SubSecErrRbStart}
151 --------
152 
153 \Item{"ring buffer mode not ready"} Starting ring buffer (RB) mode is
154 required, but the PRU software isn't ready. -> Check if the ADC
155 subsystem is enabled. Check if there's at least one active step
156 (AdcUdt::ChAz `> 0`). Check the previous call to function
157 PruIo::config().
158 
159 
160 mm_start {#SubSecErrMmStart}
161 --------
162 
163 \Item{"measurement mode not ready"} Starting measurement (MM) mode is
164 required, but the PRU software isn't ready. -> First, call function
165 PruIo::config().
166 
167 \Item{"Trg...: too much pre-trigger samples"} (... replaced by trigger
168 number) The number of pre-trigger samples is too big. libpruio uses
169 the DRam area as ring buffer for pre-trigger values. Its maximun size
170 is `16 kB - PRUIO_DAT_ADC` -> Either reduce parameter *Samp* in the
171 previous call to AdcUdt::mm_trg_pre(). Or reduce the number of active
172 steps in parameter *Mask* in the previous call to PruIo::config().
173 
174 \Item{"Trg...: pre-trigger step must be active"} (... replaced by trigger number)
175 
176 \Item{"Trg...: unknown trigger pin number"} (... replaced by trigger
177 number) The ball number in the trigger specification is too big. This
178 means your trigger specification is brocken. (Did you customize it?) ->
179 Re-create a correct trigger specification.
180 
181 \Item{"Trg...: trigger pin must be in mode 7 (GPIO)"} (... replaced by
182 trigger number) The trigger specification `...` should wait for an
183 GPIO event, but the related header pin (CPU ball number) isn't in GPIO
184 mode. -> Re-create the trigger specification with appropriate parameter
185 *Ball*. Or change pin configuration by a call to function
186 GpioUdt::config(), first.
187 
188 
189 Pin {#SubSecPruIoPin}
190 ---
191 
192 \Item{"unknown pin number"} The specified ball number is too big. ->
193 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
194 
195 
196 setPin {#SubSecPruIoSetPin}
197 ------
198 
199 \Item{"unknown setPin ball number"} The specified ball number is too
200 big. -> Make sure that parameter *Ball* is less or equal \ref
201 PRUIO_AZ_BALL.
202 
203 \Item{"no ocp.* access"} The CPU ball isn't in the required modus and
204 needs a new pinmux setting, but libpruio has no access to the sysfs
205 folders. -> Either execute the code with administrator privileges. Or
206 make sure that digital lines are set to the required modi before you
207 execute the code.
208 
209 \Item{"no pin control"} The required CPU ball (parameter *Ball*) is not
210 specified in the libpruio device tree overlay or the overlay isn't
211 loaded. -> Check the parameter *Ball*. Check if the CPU ball is
212 specified in the libpruio device tree overlay. Extend the device tree
213 overlay if you need access to further CPU balls.
214 
215 \Item{"pinmux failed: P._.. -> x.." (points replaced by numbers)}
216 Pinmuxing isn't supported for that state. -> Check the parameters
217 *Ball* and *Mo*. Make sure that the required modus is defined in the
218 libpruio device tree overlay.
219 
220 
221 ADC {#SecErrAdc}
222 ===
223 
224 setStep {#SubSecErrSetStep}
225 -------
226 
227 \Item{"ADC not enabled"}
228 
229 \Item{"step number too big"} The specified step number is too big. ->
230 Make sure that parameter *Stp* is in the range of 0 to 16.
231 
232 \Item{"channel number too big"} The specified channel number is too
233 big. -> Make sure that parameter *ChN* is in the range of 0 to 7.
234 
235 
236 mm_trg_pin {#SubSecErrMmTrgPin}
237 ----------
238 
239 \Item{"ADC not enabled"}
240 
241 \Item{"too much values to skip"} The post trigger delay is too big. ->
242 Make sure that parameter *Skip* is in the range of 0 to 1023.
243 
244 \Item{"unknown trigger pin number"} The specified ball number is too
245 big. -> Make sure that parameter *Ball* is less or equal \ref
246 PRUIO_AZ_BALL.
247 
248 \Item{"GPIO subsystem not enabled"} The specified CPU ball is on a GPIO
249 subsystem that isn't enabled. -> Either check parameter *Ball*. Or make
250 sure that the GPIO subsystem is active (see constructor
251 PruIo::PruIo() ) and enabled (`PruIo->Gpio->Conf(n)->ClVa = 2` before
252 the call to PruIo::config() ).
253 
254 \Item{"pin must be in GPIO mode (mode 7)"} The specified CPU ball isn't
255 in GPIO mode. -> Either check parameter *Ball*. Or call function
256 GpioUdt::config() to set appropriate mode, receiver and resistor
257 configuration, first.
258 
259 
260 mm_trg_ain {#SubSecErrMmTrgAin}
261 ----------
262 
263 \Item{"ADC not enabled"}
264 
265 \Item{"invalid step number"} The specification should get created for a
266 non-valid step. -> Make sure to pass a number in the range of 1 to 16
267 as parameter *Stp* (the charge step - index 0 - cannot be used as
268 trigger).
269 
270 \Item{"trigger step not configured"} The specification should get
271 created for a step that isn't configured jet. -> Configure the desired
272 step, first, by calling function AdcUdt::setStep().
273 
274 \Item{"too much values to skip"} The post trigger delay is too big. ->
275 Make sure that parameter *Skip* is in the range of 0 to 1023.
276 
277 
278 mm_trg_pre {#SubSecErrMmTrgPre}
279 ----------
280 
281 \Item{"ADC not enabled"}
282 
283 \Item{"invalid step number"} The specification should get created for a
284 non-valid step. -> Make sure to pass a number in the range of 1 to 16
285 as parameter *Stp* (the charge step - index 0 - cannot be used as
286 trigger).
287 
288 \Item{"trigger step not configured"} The specification should get
289 created for a step that isn't configured jet. -> Configure the desired
290 step, first, by calling function AdcUdt::setStep().
291 
292 \Item{"trigger step not activated"} The specification should get
293 created for a step that isn't activated. -> Check parameter *Stp*. Make
294 sure that the desired step bit is set in parameter *Mask* in the
295 previous call to function PruIo::config().
296 
297 \Item{"too much pre-samples"} The number of pre-trigger samples is too
298 big. -> Make sure that parameter *Samp* is in the range of 0 to 1023.
299 
300 \Item{"more pre-samples than samples"} The number of pre-trigger
301 samples is too big. -> Make sure that parameter *Samp* isn't greater
302 then parameter *Samp* in the previous call to function
303 PruIo::config().
304 
305 
306 
307 GPIO {#SecErrGpio}
308 ====
309 
310 config {#SubSecErrGpioConfig}
311 ------
312 
313 \Item{"unknown GPIO pin number"} The specified ball number is too big. ->
314 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
315 
316 \Item{"GPIO subsystem not enabled"} Setting a header pin in GPIO mode
317 is required, but the related GPIO subsystem isn't enabled. -> Set
318 `PruIo->Gpio->Conf(n)->ClVa = 2` (n is the number of the GPIO subsystem
319 connected to that ball number) and call function PruIo::config(),
320 first.
321 
322 \Item{"no GPIO pin"} Setting a header pin in GPIO mode is required, but
323 the specified header pin (CPU ball number) isn't in the specified mode
324 and the pinmuxing failed. -> Check the parameter *Ball*. Make sure that
325 the CPU ball is in the appropriate mode before you execute the program.
326 Or make sure that pinmuxing is availible in libpruio.
327 
328 \Item{"no ocp.* access"}
329 
330 \Item{"no header pin"} The required CPU ball (parameter *Ball*) is not
331 connected to a header pin. libpruio pinmuxing is limited to a set of
332 CPU balls, specified in the libpruio device tree overlay. This set only
333 contains CPU balls connected to one of the headers P8 or P9. -> Check
334 the parameter *Ball*. Extend the device tree overlay if you need access
335 to further CPU balls.
336 
337 \Item{"no pin control"} The required CPU ball is not in the specified
338 mode. libpruio tried to change the mode, but failed. -> Check the
339 parameter *Ball*. Check if the user has access to pinmuxing and the CPU
340 ball is specified in the libpruio device tree overlay. And check if the
341 overlay isn't loaded. Extend the device tree overlay if you need access
342 to further CPU balls.
343 
344 \Item{"pinmux failed: P._.. -> x.." (points replaced by numbers)}
345 Pinmuxing cannot be done for that pin or that state.
346 
347 
348 Value {#SubSecErrGpioValue}
349 -----
350 
351 \Item{"unknown GPIO input pin number"} The specified ball number is too
352 big. -> Make sure that parameter *Ball* is less or equal \ref
354 
355 \Item{"GPIO subsystem not enabled"} Getting a GPIO input is required,
356 but the related GPIO subsystem isn't enabled. -> Set
357 `PruIo->Gpio->Conf(n)->ClVa = 2` (n is the number of the GPIO subsystem
358 connected to that ball number) and call function PruIo::config(),
359 first.
360 
361 \Item{"no GPIO pin"} Getting a GPIO input is required, but the
362 specified header pin (CPU ball number) isn't in GPIO mode. -> Check the
363 parameter *Ball*. Call function GpioUdt::config() to change the
364 pin configuration to GPIO in mode.
365 
366 
367 setValue {#SubSecErrGpioSetValue}
368 --------
369 
370 \Item{"unknown GPIO output pin number"} The specified ball number is
371 too big. -> Make sure that parameter *Ball* is less or equal \ref
373 
374 \Item{"GPIO subsystem not enabled"} Setting a GPIO output is required,
375 but the related GPIO subsystem isn't enabled. -> Set
376 `PruIo->Gpio->Conf(n)->ClVa = 2` (n is the number of the PWMSS
377 connected to that ball number) and call function PruIo::config(),
378 first.
379 
380 \Item{"no GPIO pin"} Setting a GPIO ouput is required, but the
381 specified header pin (CPU ball number) isn't in GPIO mode. -> Check the
382 parameter *Ball*. Call function GpioUdt::config() to change the
383 pin configuration to GPIO out mode.
384 
385 
386 PWM {#SecErrPwm}
387 ===
388 
389 setValue {#SubSecErrPwmSetValue}
390 --------
391 
392 \Item{"unknown PWM pin number"} The specified ball number is too big. ->
393 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
394 
395 \Item{"pin not in PWM mode"} Setting the values of a PWM output is
396 required, but the related header pin (CPU ball) isn't in PWM mode.
397 libruio tried to configure the CPU ball, but the call to function
398 PruIo::setPin() failed. -> Check the parameter *Ball*. Check if the CPU
399 ball is specified in the libpruio device tree overlay. Extend the
400 device tree overlay if you need access to further CPU balls.
401 
402 \Item{"PWMSS not enabled"} Setting a PWM output is required, but the
403 related PWMSS subsystem isn't enabled. -> Set
404 `PruIo->PwmSS->Conf(n)->ClVa = 2` (n is the number of the PWMSS
405 connected to that ball number) and call function PruIo::config(),
406 first.
407 
408 \Item{"set frequency in first call"}
409 
410 \Item{"frequency not supported"} The module (PWM or CAP) isn't capable
411 to generate output at the required frequency. -> Check the parameter
412 *Hz* and set an appropriate value (CAP and PWM modules have different
413 frequency ranges).
414 
415 
416 Value {#SubSecErrPwmValue}
417 -----
418 
419 \Item{"unknown PWM pin number"} The specified ball number is too big. ->
420 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
421 
422 \Item{"pin not in PWM mode"} Getting the values of a PWM output is
423 required, but the related header pin (CPU ball) isn't in PWM mode. ->
424 Call function PwmMod::Value() to configure then header pin, first.
425 
426 \Item{"PWMSS not enabled"} Getting the values of a PWM input is
427 required, but the related PWMSS subsystem isn't enabled. -> Set
428 `PruIo->PwmSS->Conf(n)->ClVa = 2` (n is the number of the PWMSS
429 connected to that ball number) and call function PruIo::config(),
430 first.
431 
432 \Item{"eCAP module not in output mode"} Getting the values of a PWM
433 output of a CAP module in a PWMSS is required, but the module is in
434 input mode. -> Check the previous configuration of that pin.
435 
436 
437 CAP {#SecErrCap}
438 ===
439 
440 config {#SubSecErrCapConfig}
441 ------
442 
443 \Item{"unknown CAP pin number"} The specified ball number is too big. ->
444 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
445 
446 \Item{"pin has no CAP capability"} Setting a CPU ball in CAP mode is
447 required, but it has no CAP capability. -> Check the parameter *Ball*.
448 (Only P9_28 and P9_42 have CAP capability on the BBB.)
449 
450 \Item{"CAP not enabled"} Setting a CPU ball for CAP is required, but the
451 related PWMSS subsystem isn't enabled. -> Set
452 `PruIo->PwmSS(n)->Conf->ClVa = 2` (n is the number of the PWMSS
453 connected to that ball number) and call function PruIo::config(),
454 first.
455 
456 
457 
458 Value {#SubSecErrCapValue}
459 -----
460 
461 \Item{"unknown CAP pin number"} The specified ball number is too big. ->
462 Make sure that parameter *Ball* is less or equal \ref PRUIO_AZ_BALL.
463 
464 \Item{"pin not in CAP mode"} Fetching a value is required, but the
465 header pin (CPU ball) isn't in CAP mode. -> Call function
466 CapMod::config(), first.
467 
468 
469 \Item{"IO/RB mode not running"} Fetching a value is required, but the
470 PRU software isn't running. -> Call function PruIo::config(),
471 first.
472 
473 \Item{"CAP not enabled"} Fetching a value is required, but the related
474 PWMSS subsystem isn't enabled. -> Set `PruIo->PwmSS->Conf(n)->ClVa = 2`
475 (n is the number of the PWMSS connected to that ball number) and call
476 function PruIo::config(), first.
477 
478 
479 QEP {#SecErrQep}
480 ===
481 
482 config {#SubSecErrQepConfig}
483 ------
484 
485 \Item{To be continued ...}
486 
487 
488 Value {#SubSecErrQepValue}
489 -----
490 
491 \Item{To be continued ...}
492 
493 
494 
Main structure, binding all components together.
Definition: pruio.bi:118
PruIo(BYVAL_AS_UInt16, BYVAL_AS_UInt8, BYVAL_AS_UInt32, BYVAL_AS_UInt8)
Constructor, initialize subsystems, create default configuration.
Definition: pruio.bas:190
Structure for ADC subsystem registers.
Definition: pruio_adc.bi:51
Structure for ADC subsystem features, containing all functions and variables to handle the subsystem...
Definition: pruio_adc.bi:95
#define PRUIO_DAT_ADC
The offset to store ADC data in PruIo::DRam (IO, 4+2*17 bytes).
Definition: pruio.hp:95
GpioUdt_PTR Gpio
Pointer to GPIO subsystems structure.
Definition: pruio.bi:120
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
#define PRUIO_AZ_BALL
The number of CPU balls to handle (minus one).
Definition: pruio.hp:81
VAR n
The active channel number.
Definition: pwm_adc.bas:107
FUNCTION_CDECL_AS_ZSTRING_PTR Value(BYVAL_AS_UInt8, BYVAL_AS_Float_t_PTR, BYVAL_AS_Float_t_PTR)
Compute header pin PWM output configuration.
FUNCTION_CDECL_AS_Int32 Value(BYVAL_AS_UInt8)
Get the state of a GPIO.
Definition: pruio_gpio.bas:225
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
int main(int argc, char **argv)
The main function.
Definition: 1.c:23
#define PRUIO_MSG_INIT_OK
Message send after constructor PruIo::~PruIo.
Definition: pruio.hp:100
FUNCTION_CDECL_AS_UInt32 mm_trg_ain(BYVAL_AS_UInt8, BYVAL_AS_Int32, BYVAL_AS_UInt8, BYVAL_AS_UInt16)
Create a trigger configuration for an analog input trigger.
Definition: pruio_adc.bas:314
FUNCTION_CDECL_AS_ZSTRING_PTR setStep(BYVAL_AS_UInt8, BYVAL_AS_UInt8, BYVAL_AS_UInt8, BYVAL_AS_UInt8, BYVAL_AS_UInt32)
Customize a single configuration step.
Definition: pruio_adc.bas:183
UInt32_PTR DRam
Pointer to access PRU DRam.
Definition: pruio.bi:128
FUNCTION_CDECL_AS_UInt32 mm_trg_pre(BYVAL_AS_UInt8, BYVAL_AS_Int32, BYVAL_AS_UInt16, BYVAL_AS_UInt8)
Create a trigger configuration for an analog input trigger.
Definition: pruio_adc.bas:398
ZSTRING_PTR Errr
Pointer for error messages.
Definition: pruio.bi:127
FUNCTION_CDECL_AS_ZSTRING_PTR config(BYVAL_AS_UInt8, BYVAL_AS_UInt8)
Configure a GPIO.
Definition: pruio_gpio.bas:110
PwmssUdt_PTR PwmSS
Pointer to PWMSS subsystems structure.
Definition: pruio.bi:121