libpruio  0.0
AM33xx-PRU driver for digital input / output and analog input
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/_Messages.md
Go to the documentation of this file.
1 Messages {#ChaMessages}
2 ======
3 \tableofcontents
4 
5 There are three instances for sharing messages
6 
7 user <--> libpruio <--> PRU software
8 
9 Communication between user and libpruio is necessary in case of
10 problems (errors). This gets done by passing human readable strings.
11 Informations from the PRU (ie. its current state) are decoded as a
12 binary number.
13 
14 
15 PRU States {#SecPruState}
16 ==========
17 
18 The software on the PRU subsystem writes a code for its current state
19 to \ref PruIo::DRam[0]. The user can read this information and compare
20 it with the macros defined in file pruio.hp:
21 
22 | Message | Value | Mode | Meaning |
23 | -----------------: | :--------: | :----: | :-------------------------- |
24 | PRUIO_MSG_INIT_OK | 4294967295 | CTOR | init successfully done |
25 | PRUIO_MSG_EXIT_OK | 4294967294 | DTOR | exit successfully done |
26 | PRUIO_MSG_ADC_ERRR | 4294967293 | config | ADC device not ready |
27 | PRUIO_MSG_IO_OK | 4294967292 | IO | running in IO mode |
28 | PRUIO_MSG_MM_WAIT | 4294967291 | MM | waiting for mm_start call |
29 | PRUIO_MSG_MM_TRG1 | 4294967290 | MM | waiting for trigger 1 |
30 | PRUIO_MSG_MM_TRG2 | 4294967289 | MM | waiting for trigger 2 |
31 | PRUIO_MSG_MM_TRG3 | 4294967288 | MM | waiting for trigger 3 |
32 | PRUIO_MSG_MM_TRG4 | 4294967287 | MM | waiting for trigger 4 |
33 | Fetching sample | 0 to Samp | MM | executing measurement |
34 
35 In MM mode the PRU software reports the currently used pointer to store
36 a sample. This is the offset in the \ref PruIo::ERam aray. Its maximum
37 value is \ref PruIo::Samples * \ref PruIo::ChAz `SHL 1` and the amount
38 of finished measurement in percent is \ref PruIo::DRam[0] / \ref
39 PruIo::Samples / \ref PruIo::ChAz `/ 2 * 100 %` .
40 
41 When performing a pre-trigger, the value counts in the area of the
42 pre-trigger values (the ring buffer). It starts at zero and counts
43 upwards. When the upper border of the buffer is reached, it resets to
44 zero and counts upwards again, unless the trigger event happens. Then
45 it jumps to the real sample offset and counts in a continuous manner to
46 the end of the measurement.
47 
48 
49 Error Messages {#SecErrors}
50 ==============
51 
52 All member functions of the PruIo class provide error messages in case
53 of a problem. Functions without return value (procedure type) return
54 the error message directly (or zero on success). For other functions
55 the error message can get accessed in the member variable \ref
56 PruIo::Errr. These are functions \ref PruIo::gpio_get(), \ref
58 and the constructor. The function \ref PruIo::gpio_get_config() returns
59 either the error message or the configuration text.
60 
61 Furthermore the member variable \ref PruIo::Errr allways contain the
62 error message (even when the function returns the error message
63 directly). Error messages are internal (hard-coded) strings and must
64 not be freed. libpruio does not reset the value, it gets holded until
65 the next error occurs. So its up to the user to reset the pointer to
66 zero when done with the message, to avoid unintended error positives
67 for old errors.
68 
69 \note The destructor reports errors directly to the systems ERROUT pipe
70  (since it can't use \ref PruIo::Errr member variable any more).
71 
72 Here're all fuctions and their error messages, listed with the reason
73 for the problem and a hint how to solve it.
74 
75 
76 Constructor Errors {#SubErrCtor}
77 ------------------
78 
79 \Item{unknown PRUSS - select 0 or 1} A wrong PRU number was passed ->
80  select either 0 or 1 in the last parameter *Pru*.
81 \Item{failed opening uio5 interrupt} The interrupt to send messages from
82  the PRU to the host couldn't get opened -> check the kernel driver
83  and its configuration.
84 \Item{failed loading Pru_Init instructions} The driver couldn't load the
85  instructions for the initialization to the PRU subsystem -> test
86  function of prussdrv library.
87 \Item{failed executing Pru_Init instructions} Executing the
88  initialization instructions failed -> check if other software uses
89  this PRU.
90 \Item{failed starting ADC} The ADC device doesn't report a valid
91  REVISION information -> ADC device may be broken.
92 \Item{out of memory} The driver couldn't allocate memory to store the
93  original configuration of the divices -> make sure to have at least 1
94  kByte of additional memory.
95 
96 
97 config Errors {#SubErrConfig}
98 -------------
99 
100 \Item{no step active} All step bits in the mask are zero -> set at least
101  one step active, even if you don't need ADC values.
102 \Item{out of memory} The requested sample number needs more memory than
103  available in the external memory block -> reduce parameter *Samp* or
104  increase the size of the external memory. (See \ref ChaMemory for
105  details).
106 \Item{sample rate too big} The ADC device needs more time to run through
107  all active steps than available -> increase parameter *Tmr*.
108 \Item{failed loading parameters} The parameters for the driver couldn't
109  get uploaded -> check libprussdrv functions.
110 \Item{failed loading Pru_Run instructions} The driver couldn't load the
111  instructions to the PRU subsystem -> check libprussdrv functions.
112 \Item{failed executing Pru_Run instructions} The driver couldn't
113  initialize the devices -> ADC device may be broken or other software
114  uses the same PRU subsystem.
115 
116 
117 gpio_set Errors {#SubErrSet}
118 ---------------
119 
120 \Item{unknown pin number} The ball index is too big -> pass a correct
121  ball index in parameter *Ball*.
122 \Item{pin locked} New setting is forbidden since the ball is locked ->
123  check ball number (or call this function with a proper setting for
124  parameter *Lokk*).
125 
126 gpio_get Error {#SubErrGet}
127 --------------
128 
129 \Item{unknown pin number} The ball index is too big -> pass a correct
130  ball index in parameter *Ball*.
131 
132 
133 gpio_out Errors {#SubErrOut}
134 ---------------
135 
136 \Item{unknown output pin number} The ball index is too big -> pass a
137  correct ball index in parameter *Ball*.
138 \Item{input pin} You tried to set the state of an input CPU ball ->
139  check ball number (or call function \ref PruIo::gpio_set() with
140  proper setting for parameter *Modus* first).
141 \Item{output pin locked} Setting a new state is forbidden since the ball is
142  locked -> check ball number (or call function \ref PruIo::gpio_set()
143  with proper setting for parameter *Lokk* first).
144 
145 
146 gpio_get_config Error {#SubErrGetConf}
147 ---------------------
148 
149 \Item{unknown pin number} The ball index is too big -> pass a correct
150  ball index in parameter *Ball*.
151 
152 
153 adc_step Errors {#SubErrStep}
154 ---------------
155 
156 \Item{step number too big} The step index is too big -> pass a correct
157  step index in parameter *Stp* (0 = charge step, 1 to 16 = ADC steps,
158  17 = idle step).
159 \Item{channel number too big} The channel index is too big -> pass a
160  correct channel index in parameter *ChN* (0 = AIN0, 1 = AIN1, ..., 7
161  = AIN7).
162 
163 
164 mm_trg_pin Errors {#SubErrPin}
165 -----------------
166 
167 \Item{unknown trigger pin number} The ball index is too big -> pass a
168  correct ball index in parameter *Ball*.
169 \Item{pin must be in GPIO mode (mode 7)} The specified CPU ball is not
170  in mode 7 (GPIO) -> check ball number (or call function \ref
171  PruIo::gpio_set() with proper setting for parameter *Modus* first).
172 \Item{too much values to skip} The delay time is too big, this means too
173  much samples to skip -> set parameter *Skip* with proper (lower)
174  value (it's limited to the range of 0 to 1023). If you still need a
175  longer waiting time, consider to increase the parameter *Tmr* for the
176  next call to function \ref PruIo::config().
177 
178 
179 mm_trg_ain Errors {#SubErrAin}
180 -----------------
181 
182 \Item{invalid step number} The specified index for the trigger step is
183  too big -> choose a step index in the range 1 to 16.
184 \Item{trigger step not configured} The specified trigger step
185  is not configured -> either recreate the trigger specification or
186  call function \ref PruIo::config() again and active the trigger step
187  in parameter *Mask*.
188 \Item{too much values to skip} The delay time is too big, this means too
189  much samples to skip -> set parameter *Skip* with proper (lower)
190  value (it's limited to the range of 0 to 1023). If you still need a
191  longer waiting time, consider to increase the parameter *Tmr* for the
192  next call to function \ref PruIo::config().
193 
194 
195 mm_trg_pre Errors {#SubErrPre}
196 -----------------
197 
198 \Item{invalid step number} The specified index for the trigger step is
199  too big -> choose a step index in the range 0 to 16.
200 \Item{trigger step not configured} The specified trigger step
201  is not configured -> either recreate the trigger specification or
202  call function \ref PruIo::config() again and active the trigger step
203  in parameter *Mask*.
204 \Item{trigger step not activated} The trigger specification contains a
205  trigger step that is not active in the \ref PruIo::StepMask -> either
206  recreate the trigger specification or call function \ref
207  PruIo::config() again and active the trigger step in parameter
208  *Mask*.
209 \Item{too much pre-samples} There is not enough memory to sort the
210  pre-trigger samples -> call function \ref PruIo::config() again and
211  either reduce parameter *Samp* or choose less active steps in
212  parameter *Mask*.
213 \Item{more pre-samples than samples} There are less samples than
214  pre-trigger samples -> either reduce parameter *Samp* or call
215  function \ref PruIo::config() again with increased parameter
216  *Samp*.
217 
218 
219 mm_start Errors {#SubErrStart}
220 --------------
221 
222 \Item{Trg#: unknown trigger pin number} A digital trigger specifies a
223  CPU ball number greater than the maximum -> check the trigger
224  specification.
225 \Item{Trg#: trigger pin must be in mode 7 (GPIO)} A digital trigger
226  specifies a CPU ball number that is not in GPIO mode -> check ball
227  number, set CPU ball in mode 7.
228 \Item{Trg#: too much pre-trigger samples} There's not enough memory to
229  sort the pre-trigger ring buffer -> call function \ref
230  PruIo::config() again and reduce either parameter *Samp* or the
231  number of active steps parameter *Mask*.
232 \Item{Trg#: pre-trigger step must be active} The pre-trigger specifies a
233  step that isn't active in the \ref PruIo::StepMask -> either
234  re-create the trigger specification or call function \ref
235  PruIo::config() again with proper active steps parameter *Mask*
236 
237 
238 Destructor Errors {#SubErrDtor}
239 -----------------
240 
241 Destructor error messages cannot get passed in the \ref PruIo#Errr
242 variable (since this variable is invalid when the destructor returns).
243 These error messages get printed to the STDERR pipe directly.
244 
245 \Item{failed loading Pru_Exit instructions} The driver couldn't load the
246  exit instructions to the PRU subsystem -> test function of prussdrv
247  library.
248 \Item{failed executing Pru_Exit instructions} Executing the
249  exit instructions failed -> check if other software uses
250  this PRU.