MotorWare f2806x Module API Documentation

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

queue.h
Go to the documentation of this file.
1 /* --COPYRIGHT--,BSD
2 * Copyright (c) 2012, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * --/COPYRIGHT--*/
32 #ifndef _QUEUE_H_
33 #define _QUEUE_H_
34
40
41
42 // **************************************************************************
43 // the includes
44
45 #include "sw/modules/types/src/types.h"
46
47 // TEMP
48 #include "sw/modules/iqmath/src/32b/IQmathLib.h"
49
50 #include "sw/drivers/cpu/src/32b/f28x/f2803x/cpu.h"
51
56
57
58 // Include the algorithm overview defined in modules/<module>/docs/doxygen/doxygen.h
60
61
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65
66
67 // **************************************************************************
68 // the defines
69
70
73 #define EVENT_MAX_NUM_ARGS 4
74
75
78 #define QUEUE_MAX_NUM_EVENTS 8
79
80
81 // **************************************************************************
82 // the typedefs
83
86 typedef void (*EVENT_Fxn)();
87
88
91 typedef struct _EVENT_ArgList_
92 {
93 void *arg[EVENT_MAX_NUM_ARGS];
94 } EVENT_ArgList;
95
96
99 typedef struct _EVENT_Obj_
100 {
101 struct _EVENT_Obj_ *nextEvent;
102 struct _EVENT_Obj_ *prevEvent;
103 bool taken;
104 uint_least8_t queueNumber;
105 uint_least8_t numArgs;
106 EVENT_Fxn eventFxn;
107 EVENT_ArgList argList;
108 } EVENT_Obj;
109
110
113 typedef struct _EVENT_Obj_ *EVENT_Handle;
114
115
118 typedef struct _QUEUE_Obj_
119 {
120 EVENT_Handle firstEvent;
121 EVENT_Handle lastEvent;
122 } QUEUE_Obj;
123
124
127 typedef enum
128 {
129 QUEUE_STATUS_FIRST_EVENT_TAKEN=0,
130 QUEUE_STATUS_LAST_EVENT_TAKEN
131 } QUEUE_Status_e;
132
133
136 typedef struct _QUEUE_Obj_ *QUEUE_Handle;
137
138
139 // **************************************************************************
140 // the globals
141
144 extern uint32_t gEventIndex;
145
146
149 extern EVENT_Obj gEvents[QUEUE_MAX_NUM_EVENTS];
150
151
152 // **************************************************************************
153 // the function prototypes
154
155
158 static inline bool QUEUE_isEvent(QUEUE_Handle handle)
159 {
160 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
161
162 return(!(obj->firstEvent == (EVENT_Handle)obj));
163 } // end of QUEUE_isEvent() function
164
165
168 static inline bool QUEUE_isIdle(QUEUE_Handle handle)
169 {
170 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
171
172 return(obj->firstEvent == (EVENT_Handle)obj);
173 } // end of QUEUE_isIdle() function
174
175
180 extern QUEUE_Handle QUEUE_init(void *pMemory,const size_t numBytes);
181
182
184 // there is at least one event in the queue.
186 extern void QUEUE_listen(QUEUE_Handle handle);
187
188
194 static inline status QUEUE_postEventFirst(QUEUE_Handle handle,
195 const EVENT_Fxn eventFxn,
196 const EVENT_ArgList *pArgList,
197 const uint_least8_t numArgs)
198 {
199
200 if(numArgs > EVENT_MAX_NUM_ARGS)
201 {
202 return(ERROR);
203 }
204 else
205 {
206 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
207 EVENT_Obj *pEvent;
208 EVENT_Obj *pFirstEvent;
209
210 pEvent = &gEvents[gEventIndex];
211
212 if(pEvent->taken)
213 return(QUEUE_STATUS_FIRST_EVENT_TAKEN);
214
215 gEventIndex++;
216 gEventIndex &= QUEUE_MAX_NUM_EVENTS-1;
217
218 pEvent->taken = true;
219
220 pEvent->eventFxn = eventFxn;
221 pEvent->argList.arg[0] = pArgList->arg[0];
222 pEvent->argList.arg[1] = pArgList->arg[1];
223 pEvent->argList.arg[2] = pArgList->arg[2];
224 pEvent->argList.arg[3] = pArgList->arg[3];
225
226 // set the number of arguments
227 pEvent->numArgs = numArgs;
228
229 // insert the event at top of the queue
230 pFirstEvent = (EVENT_Obj *)obj->firstEvent;
231
232 pEvent->prevEvent = pFirstEvent->prevEvent;
233 pEvent->nextEvent = pFirstEvent;
234 pFirstEvent->prevEvent = pEvent;
235 obj->firstEvent = (EVENT_Handle)pEvent;
236
237 return(OK);
238 }
239 } // end of QUEUE_postEventFirst() function
240
241
247 static inline status QUEUE_postEventLast(QUEUE_Handle handle,
248 const EVENT_Fxn eventFxn,
249 const EVENT_ArgList *pArgList,
250 const uint_least8_t numArgs)
251 {
252
253 if(numArgs > EVENT_MAX_NUM_ARGS)
254 {
255 return(ERROR);
256 }
257 else
258 {
259 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
260 EVENT_Obj *pEvent;
261 EVENT_Obj *pLastEvent;
262
263 pEvent = &gEvents[gEventIndex];
264
265 if(pEvent->taken)
266 return(QUEUE_STATUS_LAST_EVENT_TAKEN);
267
268 gEventIndex++;
269 gEventIndex &= QUEUE_MAX_NUM_EVENTS-1;
270
271 pEvent->taken = true;
272
273 pEvent->eventFxn = eventFxn;
274 pEvent->argList.arg[0] = pArgList->arg[0];
275 pEvent->argList.arg[1] = pArgList->arg[1];
276 pEvent->argList.arg[2] = pArgList->arg[2];
277 pEvent->argList.arg[3] = pArgList->arg[3];
278
279 // set the number of arguments
280 pEvent->numArgs = numArgs;
281
282 // insert the event at the bottom of the queue
283 pLastEvent = (EVENT_Obj *)obj->lastEvent;
284
285 pEvent->prevEvent = pLastEvent;
286 pEvent->nextEvent = pLastEvent->nextEvent;
287 pLastEvent->nextEvent = pEvent;
288 obj->lastEvent = (EVENT_Handle)pEvent;
289
290 return(OK);
291 }
292
293 } // end of QUEUE_postEventLast() function
294
295
298 static inline void QUEUE_removeFirstEvent(QUEUE_Handle handle)
299 {
300 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
301 EVENT_Obj *pFirstEvent;
302 EVENT_Obj *pNextEvent;
303 EVENT_Obj *pPrevEvent;
304
305
306 // disable interrupts
307 DISABLE_INTERRUPTS;
308
309 pFirstEvent = (EVENT_Obj *)obj->firstEvent;
310
311 pNextEvent = pFirstEvent->nextEvent;
312 pPrevEvent = pFirstEvent->prevEvent;
313
314 pNextEvent->prevEvent = pPrevEvent;
315 pPrevEvent->nextEvent = pNextEvent;
316
317 obj->firstEvent = (EVENT_Handle)pNextEvent;
318
319 pFirstEvent->taken = false;
320
321 // enable maskable interrupts
322 ENABLE_INTERRUPTS;
323
324 return;
325 } // end of QUEUE_removeFirstEvent() function
326
327
330 //extern void QUEUE_removeLastEvent(QUEUE_Handle handle);
331 static inline void QUEUE_removeLastEvent(QUEUE_Handle handle)
332 {
333 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
334 EVENT_Obj *pLastEvent;
335 EVENT_Obj *pNextEvent;
336 EVENT_Obj *pPrevEvent;
337
338
339 // disable interrupts
340 DISABLE_INTERRUPTS;
341
342 pLastEvent = (EVENT_Obj *)obj->lastEvent;
343
344 pNextEvent = (EVENT_Obj *)pLastEvent->nextEvent;
345 pPrevEvent = (EVENT_Obj *)pLastEvent->prevEvent;
346
347 pNextEvent->prevEvent = pPrevEvent;
348 pPrevEvent->nextEvent = pNextEvent;
349
350 pLastEvent->taken = false;
351
352 obj->lastEvent = (EVENT_Handle)pPrevEvent;
353
354 // enable interrupts
355 ENABLE_INTERRUPTS;
356
357 return;
358 } // end of QUEUE_removeLastEvent() function
359
360
362 // it is executed.
364 static inline void QUEUE_executeEvent(QUEUE_Handle handle)
365 {
366 QUEUE_Obj *obj = (QUEUE_Obj *)handle;
367 EVENT_Obj *pEvent = (EVENT_Obj *)obj->firstEvent;
368 uint_least8_t numArgs = pEvent->numArgs;
369
370
371 // based on the number of event arguments, make the appropriate event call
372 if(numArgs == 4)
373 {
374 (pEvent->eventFxn)(pEvent->argList.arg[0],pEvent->argList.arg[1],pEvent->argList.arg[2],pEvent->argList.arg[3]);
375 }
376 else if(numArgs == 3)
377 {
378 (pEvent->eventFxn)(pEvent->argList.arg[0],pEvent->argList.arg[1],pEvent->argList.arg[2]);
379 }
380 else if(numArgs == 2)
381 {
382 (pEvent->eventFxn)(pEvent->argList.arg[0],pEvent->argList.arg[1]);
383 }
384 else if(numArgs == 1)
385 {
386 (pEvent->eventFxn)(pEvent->argList.arg[0]);
387 }
388 else if(numArgs == 0)
389 {
390 (pEvent->eventFxn)();
391 }
392
393
394 // remove the event from the queue
395 QUEUE_removeFirstEvent(handle);
396
397 return;
398 } // end of QUEUE_executeEvent() function
399
400
401 #ifdef __cplusplus
402 }
403 #endif // extern "C"
404
406 #endif // end of _QUEUE_H_ definition
407
408
EVENT_Handle
struct _EVENT_Obj_ * EVENT_Handle
Defines the EVENT handle.
Definition: queue.h:113
types.h
Contains the public interface to the types definitions.
EVENT_Obj
struct _EVENT_Obj_ EVENT_Obj
Defines the event queue object.
QUEUE_init
QUEUE_Handle QUEUE_init(void *pMemory, const size_t numBytes)
Initializes the queue.
Definition: queue.c:60
_EVENT_Obj_::nextEvent
struct _EVENT_Obj_ * nextEvent
the next event in the queue
Definition: queue.h:101
QUEUE_postEventFirst
static status QUEUE_postEventFirst(QUEUE_Handle handle, const EVENT_Fxn eventFxn, const EVENT_ArgList *pArgList, const uint_least8_t numArgs)
Posts an event to the beginning of the specified queue.
Definition: queue.h:194
_QUEUE_Obj_::lastEvent
EVENT_Handle lastEvent
the last event in the queue
Definition: queue.h:121
QUEUE_Obj
struct _QUEUE_Obj_ QUEUE_Obj
Defines the queue object structure.
EVENT_ArgList
struct _EVENT_ArgList_ EVENT_ArgList
Defines the event argument list.
QUEUE_Status_e
QUEUE_Status_e
Defines the queue status messages.
Definition: queue.h:127
_EVENT_ArgList_::arg
void * arg[EVENT_MAX_NUM_ARGS]
an array of the pointers to the event arguments
Definition: queue.h:93
_EVENT_Obj_::queueNumber
uint_least8_t queueNumber
the queue number
Definition: queue.h:104
QUEUE_MAX_NUM_EVENTS
#define QUEUE_MAX_NUM_EVENTS
Defines the maximum number of events per queue Note: must be a power of 2.
Definition: queue.h:78
_EVENT_Obj_::argList
EVENT_ArgList argList
the event function argument list
Definition: queue.h:107
QUEUE_postEventLast
static status QUEUE_postEventLast(QUEUE_Handle handle, const EVENT_Fxn eventFxn, const EVENT_ArgList *pArgList, const uint_least8_t numArgs)
Posts an event to the end of the specified queue.
Definition: queue.h:247
OK
#define OK
Defines ok.
Definition: types.h:89
_EVENT_Obj_::numArgs
uint_least8_t numArgs
the number of event arguments
Definition: queue.h:105
_EVENT_Obj_::eventFxn
EVENT_Fxn eventFxn
the event function that will be called
Definition: queue.h:106
_EVENT_Obj_::taken
bool taken
a flag to indicate if event is taken
Definition: queue.h:103
status
unsigned int status
Defines the portable data type for a status result.
Definition: types.h:116
_EVENT_Obj_::prevEvent
struct _EVENT_Obj_ * prevEvent
the previous event in the queue
Definition: queue.h:102
_EVENT_Obj_
Defines the event queue object.
Definition: queue.h:99
gEventIndex
uint32_t gEventIndex
The event index.
Definition: queue.c:52
gEvents
EVENT_Obj gEvents[QUEUE_MAX_NUM_EVENTS]
The array of events.
Definition: queue.c:54
QUEUE_STATUS_FIRST_EVENT_TAKEN
the first event taken message
Definition: queue.h:129
QUEUE_Handle
struct _QUEUE_Obj_ * QUEUE_Handle
Defines the queue handle.
Definition: queue.h:136
EVENT_MAX_NUM_ARGS
#define EVENT_MAX_NUM_ARGS
Defines the maximum number of event arguments.
Definition: queue.h:73
_QUEUE_Obj_::firstEvent
EVENT_Handle firstEvent
the first event in the queue
Definition: queue.h:120
ERROR
#define ERROR
Defines generic error.
Definition: types.h:99
QUEUE_STATUS_LAST_EVENT_TAKEN
the last event taken message
Definition: queue.h:130
EVENT_Fxn
void(* EVENT_Fxn)()
Defines the event function prototype.
Definition: queue.h:86
_EVENT_ArgList_
Defines the event argument list.
Definition: queue.h:91
QUEUE_removeFirstEvent
static void QUEUE_removeFirstEvent(QUEUE_Handle handle)
Removed the first event from the specified queue.
Definition: queue.h:298
QUEUE_listen
void QUEUE_listen(QUEUE_Handle handle)
Puts the calling process in a listen state. It loops until.
Definition: queue.c:91
QUEUE_executeEvent
static void QUEUE_executeEvent(QUEUE_Handle handle)
Checks the specified event queue for an event. If there is an event,.
Definition: queue.h:364
QUEUE_isIdle
static bool QUEUE_isIdle(QUEUE_Handle handle)
Checks if the specified queue is idle.
Definition: queue.h:168
IQmathLib.h
QUEUE_isEvent
static bool QUEUE_isEvent(QUEUE_Handle handle)
Checks if there is an event available in the queue.
Definition: queue.h:158
_QUEUE_Obj_
Defines the queue object structure.
Definition: queue.h:118
QUEUE_removeLastEvent
static void QUEUE_removeLastEvent(QUEUE_Handle handle)
Removed the last event from the specified queue.
Definition: queue.h:331