libpruio  0.0
AM33xx-PRU driver for digital input / output and analog input
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
pruio_c_wrapper.h
Go to the documentation of this file.
1 /** \file pruio_c_wrapper.h
2 \brief The main header code of the C wrapper for libpruio.
3 
4 This file provides the declarations of the \ref PruIo class member
5 functions in C syntax. It also can be used to create language bindings
6 for non-C languages to use libpruio in polyglot applications.
7 
8 \note The includes pruio.h and pruio_pins.h are not shown in this
9  documentation because they confuse Doxygen. It mixes up
10  references with the original headers pruio/pruio.bi and
11  pruio/pruio_pins.bi.
12 
13 Licence: LGPLv2 (http://www.gnu.org/licenses/lgpl-2.0.html)
14 
15 Copyright 2014 by Thomas{ dOt ]Freiherr[ At ]gmx[ DoT }net
16 
17 */
18 
19 //#include "../pruio/pruio.hp"
20 #define PRUIO_BALL_AZ 109
21 #define PRUIO_BALL_OFFS 256
22 
23 #define PRUIO_GPIO_AZ 3
24 #define PRUIO_GPIO_OFFS 64
25 #define PRUIO_GPIO_DATA 24
26 #define PRUIO_GPIO_BLCK 32
27 
28 #define PRUIO_ADC_OFFS 512
29 #define PRUIO_ADC_DATA 228
30 #define PRUIO_ADC_EMPTY 12
31 #define PRUIO_ADC_BUFF 16
32 #define PRUIO_TRG_PARA 4
33 
34 #define PRUIO_IRPT 25
35 
36 #define PRUIO_MSG_INIT_OK 4294967295
37 #define PRUIO_MSG_EXIT_OK 4294967294
38 #define PRUIO_MSG_ADC_ERRR 4294967293
39 #define PRUIO_MSG_IO_OK 4294967292
40 #define PRUIO_MSG_MM_WAIT 4294967291
41 #define PRUIO_MSG_MM_TRG1 4294967290
42 #define PRUIO_MSG_MM_TRG2 4294967289
43 #define PRUIO_MSG_MM_TRG3 4294967288
44 #define PRUIO_MSG_MM_TRG4 4294967287
45 
46 
47 //#include "../pruio/pruio.bi" (transformed)
48 //! tell pruss_intc_mapping.bi that we use ARM33xx
49 #define AM33XX
50 
51 //! the PRUSS driver library
52 #include "prussdrv.h"
53 //! PRUSS driver interrupt settings
54 #include "pruss_intc_mapping.h"
55 
56 //! the channel for PRU messages (must match PRUIO_IRPT)
57 #define PRUIO_CHAN CHANNEL5
58 //! the mask to enable PRU interrupts (must match PRUIO_IRPT)
59 #define PRUIO_MASK PRU_EVTOUT5_HOSTEN_MASK
60 //! the event for PRU messages (mapping, must match PRUIO_IRPT)
61 #define PRUIO_EMAP PRU_EVTOUT5
62 //! the event for PRU messages (must match PRUIO_IRPT)
63 #define PRUIO_EVNT PRU_EVTOUT_5
64 
65 //! the default setting for avaraging
66 #define PRUIO_DEF_AVRAGE 4
67 //! the default value for open delay in channel settings
68 #define PRUIO_DEF_ODELAY 183
69 //! the default value for sample delay in channel settings
70 #define PRUIO_DEF_SDELAY 0
71 //! the default PRU subsystem to use
72 #define PRUIO_DEF_PRUSS 1
73 //! the default number of samples to use (configures single mode)
74 #define PRUIO_DEF_SAMPLS 0
75 //! the default step mask (steps 1 to 8 for AIN0 to AIN7, no charge step)
76 #define PRUIO_DEF_STPMSK 0x1FE /* &b111111110 */
77 //! the default timer value (sampling rate)
78 #define PRUIO_DEF_TIMERV 0
79 //! the default bit mode (4 = 16 bit encoding)
80 #define PRUIO_DEF_LSLMOD 4
81 //! the default clock divisor (0 = full speed AFE = 2.4 MHz)
82 #define PRUIO_DEF_CLKDIV 0
83 
84 //! convenience macro to configure an input pin without pullup or pulldown
85 #define PRUIO_IN 0x2F /* &b00101111 */
86 //! convenience macro to configure an low input pin (with pulldown resistor)
87 #define PRUIO_IN_0 0x27 /* &b00100111 */
88 //! convenience macro to configure an high input pin (with pullup resistor)
89 #define PRUIO_IN_1 0x37 /* &b00110111 */
90 //! convenience macro to configure an output pin initial low
91 #define PRUIO_OUT0 0xF /* &b00001111 */
92 //! convenience macro to configure an output pin initial high
93 #define PRUIO_OUT1 0x8F /* &b10001111 */
94 //! convenience macro to re-configure a pin to its original (initial) state
95 #define PRUIO_PIN_RESET 0xFF /* &b11111111 */
96 
98  PRUIO_UNLOCK_CURR, //!< unlock a pin, don't change the configuration
99  PRUIO_UNLOCK_ORIG, //!< unlock a pin, change to original (initial) configuration
100  PRUIO_UNLOCK_NEW, //!< unlock a pin, change to parameter configuration
101  PRUIO_LOCK_CURR, //!< lock a pin, don't change the configuration
102  PRUIO_LOCK_ORIG, //!< lock a pin, change to original (initial) configuration
103  PRUIO_LOCK_NEW, //!< lock a pin, change to parameter configuration
104  PRUIO_LOCK_CHECK //!< don't change pin locking, skip operation if pin is locked
105 };
106 
107 typedef unsigned int uint32; //!< 32 bit unsigned integer data type
108 typedef unsigned short uint16; //!< 16 bit unsigned integer data type
109 typedef unsigned char uint8; //!< 8 bit unsigned integer data type
110 typedef int int32; //!< 32 bit signed integer data type
111 typedef short int16; //!< 16 bit signed integer data type
112 typedef signed char int8; //!< 8 bit signed integer data type
113 
114 //! user defined type for a step setting
115 struct AdcSteps{
116  uint32 Confg, //!< context for configuration register
117  Delay; //!< context for delay register
118 };
119 
120 //! user defined type for a GPIO setting
121 struct GpioSet{
122  uint32
123  Addr, //!< base address of GPIO device
124  ClrM, //!< mask to clear pins to low
125  SetM, //!< mask to set pins to high
126  OutE, //!< mask to enable pins for output
127  Stat, //!< current state of pins (mixed)
128  StaO, //!< current state of output pins
129  fe1, //!< future expansion
130  fe2;
131 };
132 
133 //! user defined type (class) for the driver structure
134 typedef struct PruIo{
135 
136  uint32
137  Samples, //!< number of samples
138  TimerVal, //!< timer value in [ns]
139  StepMask; //!< mask to specify active channels
140  uint16
141  LslMode, //!< bit shift modus (0 to 4)
142  ClockDiv; //!< divisor for ADC input clock (register 0x4C)
143 
144  uint32
145  AdcReg24 //!< ADC register IRQ_STATUS_RAW
146  ,AdcReg28 //!< ADC register IRQ_STATUS
147  ,AdcReg2C //!< ADC register IRQENABLE_SET
148  ,AdcReg30 //!< ADC register IRQENABLE_CLR
149  ,AdcReg34 //!< ADC register IRQWAKEUP
150  ,AdcReg38 //!< ADC register DMAENABLE_SET
151  ,AdcReg3C //!< ADC register DMAENABLE_CLR
152  ,AdcReg40; //!< ADC register CRTL (bits 0, 1 and 2 gets set by driver)
153 
154 //! step configuration (charge step + 16 steps + idle step, by default steps 1 to 8 are used for AIN0 to AIN7)
155  struct AdcSteps St_p[17 + 1];
156 
157  uint32* DRam; //!< pointer to access PRU DRam
158  void *ERam, //!< pointer to read PRU external ram
159  *BallOrg; //!< buffer pointer for original Ball configuration
160  uint32* AdcOrg, //!< buffer pointer for original ADC configuration (= 0 in case of ADC down at startup)
161  *GpioOrg; //!< buffer pointer for original GPIO configuration
162  uint16* Value; //!< pointer to read sampled ADC input data
163  uint8* BallRef, //!< pointer to ball reference (GPIO# for CPU pins or lock)
164  *BallConf; //!< pointer to ball configuration (CPU pin muxing)
165  char* Errr; //!< pointer for error messages
166  uint32
167  EOffs, //!< the offset of the external PRUSS-DDR
168  ESize, //!< the size of the external PRUSS-DDR
169  CSize, //!< the size of the original configuration block
170  PruNo, //!< the PRU number to use
171  PruEvtout, //!< the interrupt channel to send commands to PRU
172  PruIRam, //!< the PRU instruction ram to load
173  PruDRam; //!< the PRU data ram
174  int16
175  ArmPruInt, //!< the interrupt to send
176  ChAz; //!< number of active channels
177 
178 //! interrupt settings (we also set default interrupts, so that the other PRUSS can be used in parallel)
179  struct __pruss_intc_initdata IntcInit;
180  struct GpioSet* Gpio; //!< pointer to GPIO structure (current values)
181  struct GpioSet GpioInit[PRUIO_GPIO_AZ + 1]; //!< initial GPIO definitions
182  uint8 BallGpio[PRUIO_BALL_AZ + 1]; //!< list of GPIO numbers, corresponding to ball index
183 
184 } PruIo;
185 
186 
187 /** \brief C wrapper to create a \ref PruIo instance.
188 \param Av avaraging for default steps (0 to 16, defaults to 0)
189 \param OpD open delay for default steps (0 to 0x3FFFF, defaults to 0x98)
190 \param SaD sample delay for default steps (0 to 255, defaults to 0)
191 \param Pru number of PRU subsystem to use (0 or 1, defaults to 1)
192 \returns A pointer for the new instance.
193 
194 This function wraps the constructor, check \ref PruIo::PruIo() for
195 details.
196 
197 Since the constructor reads the original devices configurations and the
198 destructor restores them, it's recommended to create and use just one
199 \ref PruIo instance at the same time.
200 
201 */
202 PruIo* pruio_new(uint8 Av, uint32 OpD, uint8 SaD, uint8 Pru);
203 
204 /** \brief C wrapper to destroy a \ref PruIo instance.
205 \param Io The pointer of the instance.
206 
207 This function wraps the destructor, check \ref PruIo::~PruIo() for
208 details. (Doxygen should create a link here?!)
209 
210 */
211 void pruio_destroy(PruIo* Io);
212 
213 /** \brief C wrapper for function \ref PruIo::config().
214 \param Io The pointer of the \ref PruIo instance
215 \param Samp number of samples to fetch (defaults to zero)
216 \param Mask mask for active steps (defaults to all 8 channels active in steps 1 to 8)
217 \param Tmr timer value in [ns] to specify the sampling rate (defaults to zero, MM only)
218 \param Mds modus for output (defaults to 4 = 16 bit)
219 \param ClDv divisor for ADC input clock (defaults to 0 = full speed = 2.4 MHz)
220 \returns zero on success (otherwise a string with an error message)
221 
222 This function wraps the member function config, check \ref
223 PruIo::config() for details.
224 
225 */
226 char* pruio_config(PruIo* Io, uint32 Samp, uint32 Mask, uint32 Tmr, uint16 Mds, uint16 ClDv);
227 
228 /** \brief C wrapper for function \ref PruIo::adc_step().
229 \param Io The pointer of the \ref PruIo instance
230 \param Stp step index (0 = step 0 => charge step, 1 = step 1 (=> AIN0 by default), ..., 17 = idle step)
231 \param ChN channel number to scan (0 = AIN0, 1 = AIN1, ...)
232 \param Av new value for avaraging (defaults to 4)
233 \param SaD new value for sample delay (defaults to 0)
234 \param OpD new value for open delay (defaults to 0x98)
235 \returns zero on success (otherwise a string with an error message)
236 
237 This function wraps the member function adc_step, check \ref
238 PruIo::adc_step() for details.
239 
240 */
241 char* pruio_adc_step(PruIo* Io, uint8 Stp, uint8 ChN, uint8 Av, uint8 SaD, uint32 OpD);
242 
243 /** \brief C wrapper for function \ref PruIo::gpio_get_config().
244 \param Io The pointer of the \ref PruIo instance
245 \param Ball the CPU ball number to describe
246 \returns a human-readable text string (internal string, never free it)
247 
248 This function wraps the member function gpio_get_config, check \ref
249 PruIo::gpio_get_config() for details.
250 
251 */
252 char* pruio_gpio_get_config(PruIo* Io, uint8 Ball);
253 
254 /** \brief C wrapper for function \ref PruIo::gpio_set().
255 \param Io The pointer of the \ref PruIo instance
256 \param Ball the CPU ball number to set
257 \param Modus the mode for the GPIO
258 \param Lokk the locking specification
259 \returns zero on success (otherwise a pionter to an error message)
260 
261 This function wraps the member function gpio_set, check \ref
262 PruIo::gpio_set() for details.
263 
264 */
265 char* pruio_gpio_set(PruIo* Io, uint8 Ball, uint8 Modus, uint8 Lokk);
266 
267 /** \brief C wrapper for function \ref PruIo::gpio_get().
268 \param Io The pointer of the \ref PruIo instance
269 \param Ball the CPU ball number to test
270 \returns GPIO state (otherwise -1, check \ref PruIo::Errr for an error message)
271 
272 This function wraps the member function gpio_get, check \ref
273 PruIo::gpio_get() for details.
274 
275 */
276 uint32 pruio_gpio_get(PruIo* Io, uint8 Ball);
277 
278 /** \brief C wrapper for function \ref PruIo::gpio_out().
279 \param Io The pointer of the \ref PruIo instance
280 \param Ball the CPU ball number to test
281 \param Modus the state to set (0 = low, high otherwise)
282 \returns zero on success (otherwise a pointer to an error message)
283 
284 This function wraps the member function gpio_out, check \ref
285 PruIo::gpio_out() for details.
286 
287 */
288 char* pruio_gpio_out(PruIo* Io, uint8 Ball, uint8 Modus);
289 
290 /** \brief C wrapper for function \ref PruIo::mm_trg_pin().
291 \param Io The pointer of the \ref PruIo instance
292 \param Ball the CPU ball number to test
293 \param GpioV the state to check (defaults to high = 1)
294 \param Skip the number of samples to skip (defaults to 0 = zero, max. 1023)
295 \returns the trigger configuration (or zero in case of an error, check \ref PruIo::Errr)
296 
297 This function wraps the member function mm_trg_pin, check \ref
298 PruIo::mm_trg_pin() for details.
299 
300 */
301 uint32 pruio_mm_trg_pin(PruIo* Io, uint8 Ball, uint8 GpioV, uint16 Skip);
302 
303 /** \brief C wrapper for function \ref PruIo::mm_trg_ain().
304 \param Io The pointer of the \ref PruIo instance
305 \param Stp the step number to use for trigger input
306 \param AdcV the sample value to match (positive check greater than, negative check less than)
307 \param Rela if AdcV is relative to the current input
308 \param Skip the number of samples to skip (defaults to 0 = zero, max. 1023)
309 \returns the trigger configuration (or zero in case of an error, check \ref PruIo::Errr)
310 
311 This function wraps the member function mm_trg_ain, check \ref
312 PruIo::mm_trg_ain() for details.
313 
314 */
315 uint32 pruio_mm_trg_ain(PruIo* Io, uint8 Stp, int32 AdcV, uint8 Rela, uint16 Skip);
316 
317 /** \brief C wrapper for function \ref PruIo::mm_trg_pre().
318 \param Io The pointer of the \ref PruIo instance
319 \param Stp the step number to use for trigger input
320 \param AdcV the sample value to match (positive check greater than, negative check less than)
321 \param Samp the number of samples for the pre-trigger
322 \param Rela if AdcV is relative to the current input
323 \returns the trigger configuration (or zero in case of an error, check \ref PruIo::Errr)
324 
325 This function wraps the member function mm_trg_pre, check \ref
326 PruIo::mm_trg_pre() for details.
327 
328 */
329 uint32 pruio_mm_trg_pre(PruIo* Io, uint8 Stp, int32 AdcV, uint16 Samp, uint8 Rela);
330 
331 /** \brief C wrapper for function \ref PruIo::mm_start().
332 \param Io The pointer of the \ref PruIo instance
333 \param Trg1 settings for first trigger (default = no trigger)
334 \param Trg2 settings for second trigger (default = no trigger)
335 \param Trg3 settings for third trigger (default = no trigger)
336 \param Trg4 settings for fourth trigger (default = no trigger)
337 \returns zero on success (otherwise a string with an error message)
338 
339 This function wraps the member function mm_start, check \ref
340 PruIo::mm_start() for details.
341 
342 */
343 char* pruio_mm_start(PruIo* Io, uint32 Trg1, uint32 Trg2, uint32 Trg3, uint32 Trg4);