1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
|
/*
ChibiOS/RT - Copyright (C) 2006-2014 Giovanni Di Sirio
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/**
* @file osal.h
* @brief OSAL module header.
*
* @addtogroup OSAL
* @{
*/
#ifndef _OSAL_H_
#define _OSAL_H_
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
/*===========================================================================*/
/* Module constants. */
/*===========================================================================*/
/**
* @name Common constants
* @{
*/
#if !defined(FALSE) || defined(__DOXYGEN__)
#define FALSE 0
#endif
#if !defined(TRUE) || defined(__DOXYGEN__)
#define TRUE (!FALSE)
#endif
#define OSAL_SUCCESS FALSE
#define OSAL_FAILED TRUE
/** @} */
/**
* @name Messages
* @{
*/
#define MSG_OK 0
#define MSG_RESET -1
#define MSG_TIMEOUT -2
/** @} */
/**
* @name Special time constants
* @{
*/
#define TIME_IMMEDIATE ((systime_t)0)
#define TIME_INFINITE ((systime_t)-1)
/** @} */
/*===========================================================================*/
/* Module pre-compile time settings. */
/*===========================================================================*/
/*===========================================================================*/
/* Derived constants and error checks. */
/*===========================================================================*/
/*===========================================================================*/
/* Module data structures and types. */
/*===========================================================================*/
/**
* @brief Type of a machine status register.
*/
typedef uint32_t osal_sts_t;
/**
* @brief Type of a message.
*/
typedef int32_t msg_t;
/**
* @brief Type of system time counter.
*/
typedef uint32_t systime_t;
/**
* @brief Type of a thread reference.
*/
typedef thread_t * thread_reference_t;
/**
* @brief Type of an event flags mask.
*/
typedef uint32_t eventflags_t;
/**
* @brief Type of an event flags object.
* @note The content of this structure is not part of the API and should
* not be relied upon. Implementers may define this structure in
* an entirely different way.
* @note Retrieval and clearing of the flags are not defined in this
* API and are implementation-dependent.
*/
typedef struct {
volatile eventflags_t flags; /**< @brief Flags stored into the
object. */
} eventsource_t;
/**
* @brief Type of a mutex.
* @note If the OS does not support mutexes or there is no OS then them
* mechanism can be simulated.
*/
typedef uint32_t mutex_t;
/**
* @brief Type of a thread queue.
* @details A thread queue is a queue of sleeping threads, queued threads
* can be dequeued one at time or all together.
* @note In this implementation it is implemented as a single reference
* because there are no real threads.
*/
typedef struct {
thread_reference_t tr;
} threads_queue_t;
/*===========================================================================*/
/* Module macros. */
/*===========================================================================*/
/**
* @brief Condition assertion.
* @details If the condition check fails then the OSAL panics with the
* specified message and halts.
* @note The condition is tested only if the @p OSAL_ENABLE_ASSERTIONS
* switch is enabled.
* @note The convention for the message is the following:<br>
* @<function_name@>(), #@<assert_number@>
* @note The remark string is not currently used except for putting a
* comment in the code about the assertion.
*
* @param[in] c the condition to be verified to be true
* @param[in] msg the text message
* @param[in] remark a remark string
*
* @api
*/
#define osalDbgAssert(c, msg, remark)
/**
* @brief Function parameters check.
* @details If the condition check fails then the OSAL panics and halts.
* @note The condition is tested only if the @p OSAL_ENABLE_CHECKS switch
* is enabled.
*
* @param[in] c the condition to be verified to be true
*
* @api
*/
#define osalDbgCheck(c)
/**
* @brief I-Class state check.
* @note Not implemented in this simplified OSAL.
*/
#define osalDbgCheckClassI()
/**
* @brief S-Class state check.
* @note Not implemented in this simplified OSAL.
*/
#define osalDbgCheckClassS()
/**
* @brief IRQ prologue code.
* @details This macro must be inserted at the start of all IRQ handlers.
*/
#define OSAL_IRQ_PROLOGUE()
/**
* @brief IRQ epilogue code.
* @details This macro must be inserted at the end of all IRQ handlers.
*/
#define OSAL_IRQ_EPILOGUE()
/**
* @brief IRQ handler function declaration.
* @details This macro hides the details of an ISR function declaration.
*
* @param[in] id a vector name as defined in @p vectors.s
*/
#define OSAL_IRQ_HANDLER(id) void id(void)
/*===========================================================================*/
/* External declarations. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
void osalInit(void);
void osalSysHalt(const char *reason);
msg_t osalQueueGoSleepTimeoutS(threads_queue_t *tqp, systime_t time);
#ifdef __cplusplus
}
#endif
/*===========================================================================*/
/* Module inline functions. */
/*===========================================================================*/
/**
* @brief Enters a critical zone from thread context.
* @note This function cannot be used for reentrant critical zones.
*
* @special
*/
static inline void osalSysLock(void) {
}
/**
* @brief Leaves a critical zone from thread context.
* @note This function cannot be used for reentrant critical zones.
*
* @special
*/
static inline void osalSysUnlock(void) {
}
/**
* @brief Enters a critical zone from ISR context.
* @note This function cannot be used for reentrant critical zones.
*
* @special
*/
static inline void osalSysLockFromISR(void) {
}
/**
* @brief Leaves a critical zone from ISR context.
* @note This function cannot be used for reentrant critical zones.
*
* @special
*/
static inline void osalSysUnlockFromISR(void) {
}
/**
* @brief Enters a critical zone returning the previous machine status.
*
* @return The previous status.
*
* @special
*/
static inline osal_sts_t osalSysGetStatusAndLock(void) {
}
/**
* @brief Restores a machine status.
*
* @param[in] sts the previous status. This value must be something
* returned by the function @p osalSysGetStatusAndLock().
* Arbitrary values are not allowed.
*
* @special
*/
static inline void osalSysSetStatus(osal_sts_t sts) {
}
/**
* @brief Checks if a reschedule is required and performs it.
* @note I-Class functions invoked from thread context must not reschedule
* by themselves, an explicit reschedule using this function is
* required in this scenario.
* @note Not implemented in this simplified OSAL.
*
* @sclass
*/
static inline void osalOsRescheduleS(void) {
}
/**
* @brief Suspends the invoking thread for the specified time.
*
* @param[in] time the delay in system ticks, the special values are
* handled as follow:
* - @a TIME_INFINITE is allowed but interpreted as a
* normal time specification.
* - @a TIME_IMMEDIATE this value is not allowed.
* .
*
* @sclass
*/
inline void osalThreadSleepS(systime_t time) {
}
/**
* @brief Suspends the invoking thread for the specified time.
*
* @param[in] time the delay in system ticks, the special values are
* handled as follow:
* - @a TIME_INFINITE is allowed but interpreted as a
* normal time specification.
* - @a TIME_IMMEDIATE this value is not allowed.
* .
*
* @api
*/
void osalThreadSleep(systime_t time) {
}
/**
* @brief Initializes an event flags object.
*
* @param[out] esp pointer to the event flags object
*
* @init
*/
static inline void osalEventInit(eventsource_t *esp) {
osalDbgCheck(esp != NULL);
esp->flags = 0;
}
/**
* @brief Add flags to an event source object.
*
* @param[in] esp pointer to the event flags object
* @param[in] flags flags to be ORed to the flags mask
*
* @iclass
*/
static inline void osalEventBroadcastFlagsI(eventsource_t *esp,
eventflags_t flags) {
osalDbgCheck(esp != NULL);
esp->flags |= flags;
}
/**
* @brief Add flags to an event source object.
*
* @param[in] esp pointer to the event flags object
* @param[in] flags flags to be ORed to the flags mask
*
* @iclass
*/
static inline void osalEventBroadcastFlags(eventsource_t *esp,
eventflags_t flags) {
osalDbgCheck(esp != NULL);
osalSysLock();
esp->flags |= flags;
osalSysUnlock();
}
/**
* @brief Returns the flags associated to the event object then clears them.
* @note This function is not part of the OSAL API and is provided
* exclusively as an example and for convenience.
*
* @param[in] esp pointer to the event flags object
* @return The flags.
*
* @iclass
*/
static inline eventflags_t osalEventGetAndClearFlagsI(eventsource_t *esp) {
eventflags_t flags;
osalDbgCheck(esp != NULL);
flags = esp->flags;
esp->flags = 0;
return flags;
}
/**
* @brief Returns the flags associated to the event object and clears them.
* @note This function is not part of the OSAL API and is provided
* exclusively as an example and for convenience.
*
* @param[in] esp pointer to the event flags object
* @return The flags.
*
* @api
*/
static inline eventflags_t osalEventGetAndClearFlags(eventsource_t *esp) {
eventflags_t flags;
osalSysLock();
flags = osalEventGetAndClearFlagsI(esp);
osalSysUnlock();
return flags;
}
/**
* @brief Initializes s @p mutex_t object.
*
* @param[out] mp pointer to the @p mutex_t object
*
* @init
*/
static inline void osalMutexInit(mutex_t *mp) {
*mp = 0;
}
/*
* @brief Locks the specified mutex.
* @post The mutex is locked and inserted in the per-thread stack of owned
* mutexes.
*
* @param[in,out] mp pointer to the @p mutex_t object
*
* @api
*/
static inline void osalMutexLock(mutex_t *mp) {
*mp = 1;
}
/**
* @brief Unlocks the specified mutex.
* @note The HAL guarantees to release mutex in reverse lock order. The
* mutex being unlocked is guaranteed to be the last locked mutex
* by the invoking thread.
* The implementation can rely on this behavior and eventually
* ignore the @p mp parameter which is supplied in order to support
* those OSes not supporting a stack of the owned mutexes.
*
* @param[in,out] mp pointer to the @p mutex_t object
*
* @api
*/
static inline void osalMutexUnlock(mutex_t *mp) {
*mp = 0;
}
/**
* @brief Initializes a threads queue object.
*
* @param[out] tqp pointer to the threads queue object
*
* @init
*/
static inline void osalQueueInit(threads_queue_t *tqp) {
}
/**
* @brief Dequeues and wakes up one thread from the queue, if any.
*
* @param[in] tqp pointer to the threads queue object
* @param[in] msg the message code
*
* @iclass
*/
static inline void osalQueueWakeupOneI(threads_queue_t *tqp, msg_t msg) {
}
/**
* @brief Dequeues and wakes up all threads from the queue.
*
* @param[in] tqp pointer to the threads queue object
* @param[in] msg the message code
*
* @iclass
*/
static inline void osalQueueWakeupAllI(threads_queue_t *tqp, msg_t msg) {
}
#endif /* _OSAL_H_ */
/** @} */
|