urtware / urt_osal.h @ b247db3f
History | View | Annotate | Download (29.173 KB)
1 |
/*
|
---|---|
2 |
µRtWare is a lightweight publish/subscribe middleware for real-time
|
3 |
applications. It was developed as part of the software habitat for the
|
4 |
Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well.
|
5 |
|
6 |
Copyright (C) 2018..2020 Thomas Schöpping et al.
|
7 |
|
8 |
This program is free software: you can redistribute it and/or modify
|
9 |
it under the terms of the GNU General Public License as published by
|
10 |
the Free Software Foundation, either version 3 of the License, or
|
11 |
(at your option) any later version.
|
12 |
|
13 |
This program is distributed in the hope that it will be useful,
|
14 |
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
15 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
16 |
GNU General Public License for more details.
|
17 |
|
18 |
You should have received a copy of the GNU General Public License
|
19 |
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
20 |
*/
|
21 |
|
22 |
#ifndef URT_OSAL_H
|
23 |
#define URT_OSAL_H
|
24 |
|
25 |
#include <urtware.h> |
26 |
|
27 |
/*============================================================================*/
|
28 |
/* VERSION */
|
29 |
/*============================================================================*/
|
30 |
|
31 |
/**
|
32 |
* @brief The µRtWare operating system abstraction layer interface major version.
|
33 |
* @note Changes of the major version imply incompatibilities.
|
34 |
*/
|
35 |
#define URT_OSAL_VERSION_MAJOR 0 |
36 |
|
37 |
/**
|
38 |
* @brief The µRtWare operating system abstraction layer interface minor version.
|
39 |
* @note A higher minor version implies new functionalty, but all old interfaces are still available.
|
40 |
*/
|
41 |
#define URT_OSAL_VERSION_MINOR 1 |
42 |
|
43 |
/*============================================================================*/
|
44 |
/* DEPENDENCIES */
|
45 |
/*============================================================================*/
|
46 |
|
47 |
#include <stdint.h> |
48 |
|
49 |
/*============================================================================*/
|
50 |
/* DEBUG */
|
51 |
/*============================================================================*/
|
52 |
|
53 |
#if defined(__cplusplus)
|
54 |
extern "C" { |
55 |
#endif /* defined(__cplusplus) */ |
56 |
|
57 |
#if !defined(urtDebugAssert) || defined(__DOXYGEN__)
|
58 |
/**
|
59 |
* @brief Assert function to check a given condition.
|
60 |
*
|
61 |
* @param[in] condition The condition to check.
|
62 |
*/
|
63 |
void urtDebugAssert(const bool condition); |
64 |
#endif /* !defined(urtDebugAssert) */ |
65 |
|
66 |
#if defined(__cplusplus)
|
67 |
} |
68 |
#endif /* defined(__cplusplus) */ |
69 |
|
70 |
/*============================================================================*/
|
71 |
/* MUTEX */
|
72 |
/*============================================================================*/
|
73 |
|
74 |
/*
|
75 |
* The following type must be defined by the implementation:
|
76 |
*
|
77 |
* urt_osMutex_t
|
78 |
* Type to represent a mutex lock object.
|
79 |
* Is only used via pointers by the API.
|
80 |
*/
|
81 |
|
82 |
#if defined(__cplusplus)
|
83 |
extern "C" { |
84 |
#endif /* defined(__cplusplus) */ |
85 |
|
86 |
#if !defined(urtMutexInit) || defined(__DOXYGEN__)
|
87 |
/**
|
88 |
* @brief Initialize a mutex lock object.
|
89 |
*
|
90 |
* @param[in] mutex Pointer to the mutex lock object to initialize.
|
91 |
* Must not be NULL.
|
92 |
*/
|
93 |
void urtMutexInit(urt_osMutex_t* mutex);
|
94 |
#endif /* !defined(urtMutexInit) */ |
95 |
|
96 |
#if !defined(urtMutexLock) || defined(__DOXYGEN__)
|
97 |
/**
|
98 |
* @brief Lock a mutex lock.
|
99 |
* @details The calling thread is blocked until the mutex lock could be acquired.
|
100 |
*
|
101 |
* @param[in] mutex Pointer to the mutex lock to acquire.
|
102 |
* Must not be NULL.
|
103 |
*/
|
104 |
void urtMutexLock(urt_osMutex_t* mutex);
|
105 |
#endif /* !defined(urtMutexLock) */ |
106 |
|
107 |
#if !defined(urtMutexTryLock) || defined(__DOXYGEN__)
|
108 |
/**
|
109 |
* @brief Try to lock a mutex lock.
|
110 |
* @details This function does not block but returns immediately.
|
111 |
*
|
112 |
* @param[in] mutex Pointer to the mutex lock to acquire.
|
113 |
*
|
114 |
* @return Indicator whether the lock was acquired.
|
115 |
* @retval true The lock was acquired successfully.
|
116 |
* @retval false The lock could not be acquired.
|
117 |
*/
|
118 |
bool urtMutexTryLock(urt_osMutex_t* mutex);
|
119 |
#endif /* !defined(urtMutexTryLock) */ |
120 |
|
121 |
#if !defined(urtMutexUnlock) || defined(__DOXYGEN__)
|
122 |
/**
|
123 |
* @brief Unlock an owned mutex lock.
|
124 |
*
|
125 |
* @param[in] mutex Pointer to the mutex lock to unlock.
|
126 |
* Must not be NULL.
|
127 |
*/
|
128 |
void urtMutexUnlock(urt_osMutex_t* mutex);
|
129 |
#endif /* !defined(urtMutexUnlock) */ |
130 |
|
131 |
#if defined(__cplusplus)
|
132 |
} |
133 |
#endif /* defined(__cplusplus) */ |
134 |
|
135 |
/*============================================================================*/
|
136 |
/* CONDITION VARIABLE */
|
137 |
/*============================================================================*/
|
138 |
|
139 |
/*
|
140 |
* The following type must be defined by the implementation:
|
141 |
*
|
142 |
* urt_osCondvar_t
|
143 |
* Type to represent a condition variable object.
|
144 |
* Is only used via pointers by the API.
|
145 |
*/
|
146 |
|
147 |
/**
|
148 |
* @brief Status type of condition variables.
|
149 |
*/
|
150 |
typedef enum { |
151 |
URT_CONDVAR_WAITSTATUS_SIGNAL = 1, /**< The condition variable has been signaled individually. */ |
152 |
URT_CONDVAR_WAITSTATUS_BROADCAST = 2, /**< The condition variable has been signal via broadcast. */ |
153 |
URT_CONDVAR_WAITSTATUS_TIMEOUT = 0, /**< Waiting for the condition variable timed out. */ |
154 |
} urt_osCondvarWaitStatus_t; |
155 |
|
156 |
#if defined(__cplusplus)
|
157 |
extern "C" { |
158 |
#endif /* defined(__cplusplus) */ |
159 |
|
160 |
#if !defined(urtCondvarInit) || defined(__DOXYGEN__)
|
161 |
/**
|
162 |
* @brief Initialize a condition variable object.
|
163 |
*
|
164 |
* @param[in] condvar Pointer to the object to initialize.
|
165 |
* Must not be NULL.
|
166 |
*/
|
167 |
void urtCondvarInit(urt_osCondvar_t* condvar);
|
168 |
#endif /* !defined(urtCondvarInit) */ |
169 |
|
170 |
#if !defined(urtCondvarSignal) || defined(__DOXYGEN__)
|
171 |
/**
|
172 |
* @brief Signal a condition variable (wake one waiting thread).
|
173 |
*
|
174 |
* @param[in] condvar Pointer to the condition variable to signal.
|
175 |
* Must not be NULL.
|
176 |
*/
|
177 |
void urtCondvarSignal(urt_osCondvar_t* condvar);
|
178 |
#endif /* !defined(urtCondvarSignal) */ |
179 |
|
180 |
#if !defined(urtCondvarBroadcast) || defined(__DOXYGEN__)
|
181 |
/**
|
182 |
* @brief Signal a condition variable via broadcast (wake all waiting threads).
|
183 |
*
|
184 |
* @param[in] condvar Pointer to the condition variable to signal via broadcast.
|
185 |
* Must not be NULL.
|
186 |
*/
|
187 |
void urtCondvarBroadcast(urt_osCondvar_t* condvar);
|
188 |
#endif /* !defined(urtCondvarBroadcast) */ |
189 |
|
190 |
#if (!defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true)) || defined(__DOXYGEN__) |
191 |
/**
|
192 |
* @brief Wait for a condition variable to be signaled or timeout.
|
193 |
*
|
194 |
* @param[in] condvar Pointer to the condition variabel to wait for.
|
195 |
* Must not be NULL.
|
196 |
* @param[in] mutex Pointer to the associated mutex lock.
|
197 |
* Must not be NULL.
|
198 |
* Mutex must be acquired when this function is called.
|
199 |
* @param[in] timeout Timeout (in microseconds) when the function will return even without the condition variable being signaled.
|
200 |
* Use URT_DELAY_INFINITE to deactivate timeout.
|
201 |
* @return
|
202 |
*/
|
203 |
urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex, urt_delay_t timeout); |
204 |
#else /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */ |
205 |
urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex); |
206 |
#endif /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */ |
207 |
|
208 |
#if defined(__cplusplus)
|
209 |
} |
210 |
#endif /* defined(__cplusplus) */ |
211 |
|
212 |
/*============================================================================*/
|
213 |
/* EVENTS */
|
214 |
/*============================================================================*/
|
215 |
|
216 |
/*
|
217 |
* The following types and constants must be defined by the implementation:
|
218 |
*
|
219 |
* urt_osEventSource_t
|
220 |
* Type to represent an event source object.
|
221 |
* Is only used via pointers by the API.
|
222 |
*
|
223 |
* urt_osEventListener_t
|
224 |
* Type to represent an event listener object.
|
225 |
* Is only used via pointers by the API.
|
226 |
*
|
227 |
* urt_osEventMask_t
|
228 |
* Integer type to represent event masks.
|
229 |
*
|
230 |
* urt_osEventFlags_t
|
231 |
* Integer type to represent event flags.
|
232 |
*
|
233 |
* URT_EVENTMASK_MAXPRIO
|
234 |
* Constant of type urt_osEventMask_t to specify the event mask that is
|
235 |
* handled with maximum priority.
|
236 |
* This constant is typically either 0x0..1 (low values have high priority)
|
237 |
* or 0x8..0 (high values have high priority).
|
238 |
* A value of 0 indicates that priorities are not supported.
|
239 |
*/
|
240 |
|
241 |
/**
|
242 |
* @brief Enum type to distinguish differnt variants how to wait for events.
|
243 |
*/
|
244 |
typedef enum { |
245 |
URT_EVENT_WAIT_ONE = 0, /**< Wait for exactly one of the specified events. */ |
246 |
URT_EVENT_WAIT_ANY = 1, /**< Wait for any (one or more) of the specified events. */ |
247 |
URT_EVENT_WAIT_ALL = 2, /**< Wait for all of the specified events. */ |
248 |
} urt_osEventWait_t; |
249 |
|
250 |
#if defined(__cplusplus)
|
251 |
extern "C" { |
252 |
#endif /* defined(__cplusplus) */ |
253 |
|
254 |
#if !defined(urtEventSourceInit) || defined(__DOXYGEN__)
|
255 |
/**
|
256 |
* @brief Initialize an event source object.
|
257 |
*
|
258 |
* @param[in] source Pointer to the event source object to initialize.
|
259 |
* Must not be NULL.
|
260 |
*/
|
261 |
void urtEventSourceInit(urt_osEventSource_t* source);
|
262 |
#endif /* !defined(urtEventSourceInit) */ |
263 |
|
264 |
#if !defined(urtEventSourceBroadcast) || defined(__DOXYGEN__)
|
265 |
/**
|
266 |
* @brief Broadcast an event with specified flags.
|
267 |
*
|
268 |
* @param[in] source Pointer to the event source to broadcast the event.
|
269 |
* Must not be NULL.
|
270 |
* @param[in] flags Flags to be set at the recieveing listeners.
|
271 |
*/
|
272 |
void urtEventSourceBroadcast(urt_osEventSource_t* source, urt_osEventFlags_t flags);
|
273 |
#endif /* !defined(urtEventSourceBroadcast) */ |
274 |
|
275 |
#if !defined(urtEventListenerInit) || defined(__DOXYGEN__)
|
276 |
/**
|
277 |
* @brief Initialize an event listener object.
|
278 |
* Must not be NULL.
|
279 |
*
|
280 |
* @param[in] listener Pointer to the event listener object to initialize.
|
281 |
*/
|
282 |
void urtEventListenerInit(urt_osEventListener_t* listener);
|
283 |
#endif /* !defined(urtEventListenerInit) */ |
284 |
|
285 |
#if !defined(urtEventListenerGetFlags) || defined(__DOXYGEN__)
|
286 |
/**
|
287 |
* @brief Retrieve the currently set flags of an event listener.
|
288 |
* @details Flags are not cleared in the listener.
|
289 |
*
|
290 |
* @param[in] listener Pointer to the event listener to recieve the flags from.
|
291 |
* Must not be NULL.
|
292 |
*
|
293 |
* @return Currently set flags.
|
294 |
*/
|
295 |
urt_osEventFlags_t urtEventListenerGetFlags(urt_osEventListener_t* listener); |
296 |
#endif /* !defined(urtEventListenerGetFlags) */ |
297 |
|
298 |
#if !defined(urtEventListenerClearFlags) || defined(__DOXYGEN__)
|
299 |
/**
|
300 |
* @brief Retrieve and clear the currently set flags from an event listener.
|
301 |
*
|
302 |
* @param[in] listener Pointer to the event listener to recieve the flags from.
|
303 |
* Must not be NULL.
|
304 |
*
|
305 |
* @return The flags that had been set at the listener.
|
306 |
*/
|
307 |
urt_osEventFlags_t urtEventListenerClearFlags(urt_osEventListener_t* listener); |
308 |
#endif /* !defined(urtEventListenerClearFlags) */ |
309 |
|
310 |
#if !defined(urtEventRegister) || defined(__DOXYGEN__)
|
311 |
/**
|
312 |
* @brief Register an event source to a listener.
|
313 |
*
|
314 |
* @param[in] source Pointer to the event source to register.
|
315 |
* Must not be NULL.
|
316 |
* @param[in] listener Pointer to the event listener to register.
|
317 |
* Must not be NULL.
|
318 |
* @param[in] mask Mask to be set at the listening thread on an event.
|
319 |
* @param[in] flags Flags to be set by default at the listener on an event,
|
320 |
*/
|
321 |
void urtEventRegister(urt_osEventSource_t* source, urt_osEventListener_t* listener, urt_osEventMask_t mask, urt_osEventFlags_t flags);
|
322 |
#endif /* !defined(urtEventRegister) */ |
323 |
|
324 |
#if !defined(urtEventUnregister) || defined(__DOXYGEN__)
|
325 |
/**
|
326 |
* @brief Unregister an associated event source and listener.
|
327 |
*
|
328 |
* @param[in] source Pointer to the event source to unregister.
|
329 |
* Must not be NULL.
|
330 |
* @param[in] listener Pointer to the event listener to unregister.
|
331 |
* Must not be NULL.
|
332 |
*/
|
333 |
void urtEventUnregister(urt_osEventSource_t* source, urt_osEventListener_t* listener);
|
334 |
#endif /* !defined(urtEventUnregister) */ |
335 |
|
336 |
#if !defined(urtEventWait) || defined(__DOXYGEN__)
|
337 |
/**
|
338 |
* @brief Wait for one/any/all event(s) to be recieved or a timeout.
|
339 |
*
|
340 |
* @param[in] mask The mask of event to wait for.
|
341 |
* @param[in] type Specificator whether to wait for exactly one, any combination or all of the specified mask flags.
|
342 |
* @param[in] timeout Timeout when the function shall return even if no event was recieved.
|
343 |
*
|
344 |
* @return The recieved event mask.
|
345 |
*/
|
346 |
urt_osEventMask_t urtEventWait(urt_osEventMask_t mask, urt_osEventWait_t type, urt_delay_t timeout); |
347 |
#endif /* !defined(urtEventWait) */ |
348 |
|
349 |
#if defined(__cplusplus)
|
350 |
} |
351 |
#endif /* defined(__cplusplus) */ |
352 |
|
353 |
/*============================================================================*/
|
354 |
/* STREAMS */
|
355 |
/*============================================================================*/
|
356 |
|
357 |
#if defined(__cplusplus)
|
358 |
extern "C" { |
359 |
#endif /* defined(__cplusplus) */ |
360 |
|
361 |
#if !defined(urtPrintf) || defined(__DOXYGEN__)
|
362 |
/**
|
363 |
* @brief Prints a formatted string to standard output.
|
364 |
*
|
365 |
* @param[in] fmt The formatted string to be printed.
|
366 |
*
|
367 |
* @return Number of characters printed.
|
368 |
*/
|
369 |
int urtPrintf(char* fmt, ...); |
370 |
#endif /* !defined(urtPrintf) */ |
371 |
|
372 |
#if !defined(urtErrPrintf) || defined(__DOXYGEN__)
|
373 |
/**
|
374 |
* @brief Prints a formatted string to error output.
|
375 |
*
|
376 |
* @param[in] fmt The formatted string to be printed.
|
377 |
*
|
378 |
* @return Number of characters printed.
|
379 |
*/
|
380 |
int urtErrPrintf(char* fmt, ...); |
381 |
#endif /* !defined(urtErrPrintf) */ |
382 |
|
383 |
#if defined(__cplusplus)
|
384 |
} |
385 |
#endif /* defined(__cplusplus) */ |
386 |
|
387 |
/*============================================================================*/
|
388 |
/* TIME */
|
389 |
/*============================================================================*/
|
390 |
|
391 |
/*
|
392 |
* The following type must be defined by the implementation:
|
393 |
*
|
394 |
* urt_osTime_t
|
395 |
* Type to represent a time object.
|
396 |
* This type may be of any precision.
|
397 |
* Is only used via pointers by the API.
|
398 |
*/
|
399 |
|
400 |
#if defined(__cplusplus)
|
401 |
extern "C" { |
402 |
#endif /* defined(__cplusplus) */ |
403 |
|
404 |
#if !defined(urtTime2Us) || defined(__DOXYGEN__)
|
405 |
/**
|
406 |
* @brief Convert an OS time to microsecond value.
|
407 |
*
|
408 |
* @param[in] t The time to convert.
|
409 |
* Must not be NULL
|
410 |
*
|
411 |
* @return The equivalent time in microseconds.
|
412 |
*/
|
413 |
uint64_t urtTime2Us(urt_osTime_t* t); |
414 |
#endif /* !defined(urtTime2Us) */ |
415 |
|
416 |
#if !defined(urtTimeNow) || defined(__DOXYGEN__)
|
417 |
/**
|
418 |
* @brief Get the current system time.
|
419 |
*
|
420 |
* @return Current system time as provide by the operating system.
|
421 |
*/
|
422 |
urt_osTime_t urtTimeNow(void);
|
423 |
#endif /* !defined(urtTimeNow) */ |
424 |
|
425 |
#if !defined(urtTimeAddUs) || defined(__DOXYGEN__)
|
426 |
/**
|
427 |
* @brief Add microseconds to a specified system time.
|
428 |
*
|
429 |
* @param[in] time Pointer to the time value to be incremented.
|
430 |
* Must not be NULL.
|
431 |
* @param[in] offset Amount of microseconds to add.
|
432 |
*/
|
433 |
void urtTimeAddUs(urt_osTime_t* time, urt_delay_t offset);
|
434 |
#endif /* !defined(urtTimeAddUs) */ |
435 |
|
436 |
#if defined(__cplusplus)
|
437 |
} |
438 |
#endif /* defined(__cplusplus) */ |
439 |
|
440 |
/*============================================================================*/
|
441 |
/* THREAD */
|
442 |
/*============================================================================*/
|
443 |
|
444 |
/*
|
445 |
* The following types, constants and macros must be defined by the
|
446 |
* implementation:
|
447 |
*
|
448 |
* urt_osThread_t
|
449 |
* Type to represent an thread object.
|
450 |
* Is only used via pointers by the API.
|
451 |
*
|
452 |
* urt_osThreadPrio_t
|
453 |
* Integer type to represent thread priorities.
|
454 |
*
|
455 |
* URT_THREAD_PRIO_LOW_MIN
|
456 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
457 |
* low-priority threads.
|
458 |
* Must be greater than the idle thread priority.
|
459 |
*
|
460 |
* URT_THREAD_PRIO_LOW_MAX
|
461 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
462 |
* low-priority threads.
|
463 |
* Must be greater or equal URT_THREAD_PRIO_LOW_MIN.
|
464 |
*
|
465 |
* URT_THREAD_PRIO_NORMAL_MIN
|
466 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
467 |
* normal-priority threads.
|
468 |
* Must be greater than URT_THREAD_PRIO_LOW_MAX.
|
469 |
*
|
470 |
* URT_THREAD_PRIO_NORMAL_MAX
|
471 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
472 |
* normal-priority threads.
|
473 |
* Must be greater or equal URT_THREAD_PRIO_NORMAL_MIN.
|
474 |
*
|
475 |
* URT_THREAD_PRIO_HIGH_MIN
|
476 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
477 |
* high-priority threads.
|
478 |
* Must be greater than URT_THREAD_PRIO_NORMAL_MAX.
|
479 |
*
|
480 |
* URT_THREAD_PRIO_HIGH_MAX
|
481 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
482 |
* high-priority threads.
|
483 |
* Must be greater or equal URT_THREAD_PRIO_HIGH_MIN.
|
484 |
*
|
485 |
* URT_THREAD_PRIO_RT_MIN
|
486 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
487 |
* real-time threads.
|
488 |
* Must be greater than URT_THREAD_PRIO_HIGH_MAX.
|
489 |
*
|
490 |
* URT_THREAD_PRIO_RT_MAX
|
491 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
492 |
* real-time threads.
|
493 |
* Must be greater or equal URT_THREAD_PRIO_HIGH_MIN but lower than the
|
494 |
* control/root thread priority.
|
495 |
*
|
496 |
* URT_THREAD_SLEEP_MAX
|
497 |
* Constant of type float specifying the maximum time (in seconds) a thread
|
498 |
* may sleep via the urtThreadSleep() function.
|
499 |
*
|
500 |
* URT_THREAD_SSLEEP_MAX
|
501 |
* Constant of type urt_delay_t specifying the maximum number of seconds a
|
502 |
* thread may sleep via the urtThreadSSleep() function.
|
503 |
*
|
504 |
* URT_THREAD_MSLEEP_MAX
|
505 |
* Constant of type urt_delay_t specifying the maximum number of milliseconds
|
506 |
* a thread may sleep via the urtThreadMSleep() function.
|
507 |
*
|
508 |
* URT_THREAD_USLEEP_MAX
|
509 |
* Constant of type urt_delay_t specifying the maximum number of microseconds
|
510 |
* a thread may sleep via the urtThreadUSleep() function.
|
511 |
*
|
512 |
* URT_THREAD_MEMORY(varname, stacksize)
|
513 |
* Macro function to staically allocate a variable 'varname', which holds all
|
514 |
* memory required to hold a thread object with the specified stacksize.
|
515 |
*/
|
516 |
|
517 |
/**
|
518 |
* @brief Enum type for various thread states.
|
519 |
*/
|
520 |
typedef enum { |
521 |
URT_THREAD_STATE_INACTIVE = 0, /**< The thread has not been started yet. */ |
522 |
URT_THREAD_STATE_RUNNING = 1, /**< The thread is currently being executed on a CPU. */ |
523 |
URT_THREAD_STATE_READY = 2, /**< The thread is ready to be scheduled for execution. */ |
524 |
URT_THREAD_STATE_SLEEPING = 3, /**< The thread is currently sleeping for a defined amount of time. */ |
525 |
URT_THREAD_STATE_SUSPENDED = 4, /**< Execution of the thread has been suspended. */ |
526 |
URT_THREAD_STATE_WAITING = 5, /**< The thread is currently waiting for an event. */ |
527 |
URT_THREAD_STATE_TERMINATED = 6, /**< The thread has been terminated. */ |
528 |
} urt_osThreadState_t; |
529 |
|
530 |
/**
|
531 |
* @brief Enum type for various termination signals.
|
532 |
*/
|
533 |
typedef enum { |
534 |
URT_THREAD_TERMINATE_REQUEST = 15, /**< Request a thread to terminate in a cooperative manner. */ |
535 |
URT_THREAD_TERMINATE_KILL = 9, /**< Terminate a thread in a non-cooperative manner (force). */ |
536 |
} urt_osThreadTerminateSignal_t; |
537 |
|
538 |
/**
|
539 |
* @brief Thread function.
|
540 |
*
|
541 |
* @param[in] arg Pointer to optional arguments.
|
542 |
* May be NULL.
|
543 |
*/
|
544 |
typedef void (*urt_osThreadFunction_t)(void* arg); |
545 |
|
546 |
#if defined(__cplusplus)
|
547 |
extern "C" { |
548 |
#endif /* defined(__cplusplus) */ |
549 |
|
550 |
#if !defined(urtThreadInit) || defined(__DOXYGEN__)
|
551 |
/**
|
552 |
* @brief Initialize a thread object.
|
553 |
* @details The new thread becomes a child of the calling thread.
|
554 |
*
|
555 |
* @param[in] memory Pointer to the memory where to create the thread object.
|
556 |
* Must not be NULL.
|
557 |
* @param[in] size Size of the memory.
|
558 |
* @param[in] prio Initial priority of the thread.
|
559 |
* @param[in] func Pointer to the thread function the thread shall execute.
|
560 |
* Must not be NULL.
|
561 |
* @param[in] arg Pointer to optional function arguments.
|
562 |
* May be NULL.
|
563 |
*
|
564 |
* @return Pointer to the created thread object.
|
565 |
*/
|
566 |
urt_osThread_t* urtThreadInit(void* memory, size_t size, urt_osThreadPrio_t prio, urt_osThreadFunction_t func, void* arg); |
567 |
#endif /* !defined(urtThreadInit) */ |
568 |
|
569 |
#if !defined(urtThreadStart) || defined(__DOXYGEN__)
|
570 |
/**
|
571 |
* @brief Start execution of a thread.
|
572 |
*
|
573 |
* @param[in] thread Pointer to the thread to start.
|
574 |
* Must not be NULL.
|
575 |
*/
|
576 |
void urtThreadStart(urt_osThread_t* thread);
|
577 |
#endif /* !defined(urtThreadStart) */ |
578 |
|
579 |
#if !defined(urtThreadYield) || defined(__DOXYGEN__)
|
580 |
/**
|
581 |
* @brief Yield execution of the calling thread.
|
582 |
*/
|
583 |
void urtThreadYield(void); |
584 |
#endif /* !defined(urtThreadYield) */ |
585 |
|
586 |
#if !defined(urtThreadGetPriority) || defined(__DOXYGEN__)
|
587 |
/**
|
588 |
* @brief Retrieve the current priority of the calling thread.
|
589 |
*
|
590 |
* @return Current priority.
|
591 |
*/
|
592 |
urt_osThreadPrio_t urtThreadGetPriority(void);
|
593 |
#endif /* !defined(urtThreadGetPriority) */ |
594 |
|
595 |
#if !defined(urtThreadSetPriority) || defined(__DOXYGEN__)
|
596 |
/**
|
597 |
* @brief Set the priority of the calling thread.
|
598 |
*
|
599 |
* @param[in] prio The new priority to set.
|
600 |
*/
|
601 |
void urtThreadSetPriority(urt_osThreadPrio_t prio);
|
602 |
#endif /* !defined(urtThreadSetPriority) */ |
603 |
|
604 |
#if !defined(urtThreadSleep) || defined(__DOXYGEN__)
|
605 |
/**
|
606 |
* @brief The calling thread sleeps for the given amount of time.
|
607 |
*
|
608 |
* @param[in] seconds Time in seconds to sleep.
|
609 |
* Must not be greater than URT_THREAD_SLEEP_MAX.
|
610 |
*/
|
611 |
void urtThreadSleep(float seconds); |
612 |
#endif /* !defined(urtThreadSleep) */ |
613 |
|
614 |
#if !defined(urtThreadSSleep) || defined(__DOXYGEN__)
|
615 |
/**
|
616 |
* @brief The calling thread sleeps for the given amount of seconds.
|
617 |
*
|
618 |
* @param[in] seconds Time in seconds to sleep.
|
619 |
* Must not be greater than URT_THREAD_SSLEP_MAX.
|
620 |
*/
|
621 |
void urtThreadSSleep(unsigned int seconds); |
622 |
#endif /* !defined(urtThreadSSleep) */ |
623 |
|
624 |
#if !defined(urtThreadMSleep) || defined(__DOXYGEN__)
|
625 |
/**
|
626 |
* @brief The calling thread sleeps for the given amount of milliseconds.
|
627 |
*
|
628 |
* @param[in] milliseconds Time in milliseconds to sleep.
|
629 |
* Must not be greater than URT_THREAD_MSLEP_MAX.
|
630 |
*/
|
631 |
void urtThreadMSleep(unsigned int milliseconds); |
632 |
#endif /* !defined(urtThreadMSleep) */ |
633 |
|
634 |
#if !defined(urtThreadUSleep) || defined(__DOXYGEN__)
|
635 |
/**
|
636 |
* @brief The calling thread sleeps for the gven amount of microseconds.
|
637 |
*
|
638 |
* @param[in] microseconds Time in microseconds to sleep.
|
639 |
* Must not be greater than URT_THREAD_USLEP_MAX.
|
640 |
*/
|
641 |
void urtThreadUSleep(urt_delay_t microseconds);
|
642 |
#endif /* !defined(urtThreadUSleep) */ |
643 |
|
644 |
#if !defined(urtThreadSleepUntil) || defined(__DOXYGEN__)
|
645 |
/**
|
646 |
* @brief The calling thread sleeps until the given point in time.
|
647 |
*
|
648 |
* @param[in] time Time when the thread shall wake up.
|
649 |
* If the current is already beyond the argument, the thread will not sleep at all.
|
650 |
*/
|
651 |
void urtThreadSleepUntil(urt_osTime_t time);
|
652 |
#endif /* !defined(urtThreadSleepUntil) */ |
653 |
|
654 |
#if !defined(urtThreadExit) || defined(__DOXYGEN__)
|
655 |
/**
|
656 |
* @brief The calling thread stops execution and terminates.
|
657 |
*/
|
658 |
void urtThreadExit(void); |
659 |
#endif /* !defined(urtThreadExit) */ |
660 |
|
661 |
#if !defined(urtThreadTerminate) || defined(__DOXYGEN__)
|
662 |
/**
|
663 |
* @brief Send a termination signal to a thread.
|
664 |
*
|
665 |
* @param[in] thread Thread to be signaled.
|
666 |
* Must not be NULL.
|
667 |
* @param[in] sig Type of termination.
|
668 |
*/
|
669 |
void urtThreadTerminate(urt_osThread_t* thread, urt_osThreadTerminateSignal_t sig);
|
670 |
#endif /* !defined(urtThreadTerminate) */ |
671 |
|
672 |
#if !defined(urtThreadJoin) || defined(__DOXYGEN__)
|
673 |
/**
|
674 |
* @brief Wait for a thread to terminate.
|
675 |
*
|
676 |
* @param[in] thread Pointer to the thread to wait for.
|
677 |
* Must not be NULL.
|
678 |
*/
|
679 |
void urtThreadJoin(urt_osThread_t* thread);
|
680 |
#endif /* !defined(urtThreadJoin) */ |
681 |
|
682 |
#if !defined(urtThreadGetState) || defined(__DOXYGEN__)
|
683 |
/**
|
684 |
* @brief Get the current execution status of a thread.
|
685 |
*
|
686 |
* @param[in] thread Pointer to the thread to get the status for.
|
687 |
* Must not be NULL.
|
688 |
*
|
689 |
* @return Execution status of the secified thread.
|
690 |
*/
|
691 |
urt_osThreadState_t urtThreadGetState(urt_osThread_t* thread); |
692 |
#endif /* !defined(urtThreadGetState) */ |
693 |
|
694 |
#if !defined(urtThreadGetSelf) || defined(__DOXYGEN__)
|
695 |
/**
|
696 |
* @brief Retrieve the thread object of the calling thread.
|
697 |
*
|
698 |
* @return Pointer to the thread that is currrently executed.
|
699 |
*/
|
700 |
urt_osThread_t* urtThreadGetSelf(void);
|
701 |
#endif /* !defined(urtThreadGetSelf) */ |
702 |
|
703 |
#if !defined(urtThreadGetChildren) || defined(__DOXYGEN__)
|
704 |
/**
|
705 |
* @brief Retrieve the first child of a thread.
|
706 |
*
|
707 |
* @param[in] thread Pointer to the thread to retrieve the child from.
|
708 |
* Must not be NULL.
|
709 |
*
|
710 |
* @return Pointer to the first child thread.
|
711 |
* May be NULL if the thread has no children.
|
712 |
*/
|
713 |
urt_osThread_t* urtThreadGetChildren(urt_osThread_t* thread); |
714 |
#endif /* !defined(urtThreadGetChildren) */ |
715 |
|
716 |
#if !defined(urtThreadGetSibling) || defined(__DOXYGEN__)
|
717 |
/**
|
718 |
* @brief Retrieve the next sibling of a thread.
|
719 |
*
|
720 |
* @param[in] thread Pointer to the thread to retrieve the sibling from.
|
721 |
*
|
722 |
* @return Pointer to the next sibling of the thread.
|
723 |
* May be NULL if the thread does not have any more siblings.
|
724 |
*/
|
725 |
urt_osThread_t* urtThreadGetSibling(urt_osThread_t* thread); |
726 |
#endif /* !defined(urtThreadGetSibling) */ |
727 |
|
728 |
#if !defined(urtThreadGetParent) || defined(__DOXYGEN__)
|
729 |
/**
|
730 |
* @brief Retrieve the parent of a thread.
|
731 |
*
|
732 |
* @param[in] thread Pointer to the thread to retrieve the parent from.
|
733 |
*
|
734 |
* @return Pointer to the parent thread.
|
735 |
* May be NULL if the specified thread is root.
|
736 |
*/
|
737 |
urt_osThread_t* urtThreadGetParent(urt_osThread_t* thread); |
738 |
#endif /* !defined(urtThreadGetParent) */ |
739 |
|
740 |
#if defined(__cplusplus)
|
741 |
} |
742 |
#endif /* defined(__cplusplus) */ |
743 |
|
744 |
/*============================================================================*/
|
745 |
/* TIMER */
|
746 |
/*============================================================================*/
|
747 |
|
748 |
/*
|
749 |
* The following type must be defined by the implementation:
|
750 |
*
|
751 |
* urt_osTimer_t
|
752 |
* Type to represent a timer object.
|
753 |
* Is only used via pointers by the API.
|
754 |
*/
|
755 |
|
756 |
/**
|
757 |
* @brief Timer callback function type.
|
758 |
* @details A timer executes a callback when its time ran out and it fires.
|
759 |
*
|
760 |
* @param[in] params Pointer to optional parameters for the callback function.
|
761 |
* May be NULL.
|
762 |
*/
|
763 |
typedef void (*urt_osTimerCallback_t)(void* parameter); |
764 |
|
765 |
#if defined(__cplusplus)
|
766 |
extern "C" { |
767 |
#endif /* defined(__cplusplus) */ |
768 |
|
769 |
#if !defined(urtTimerInit) || defined(__DOXYGEN__)
|
770 |
/**
|
771 |
* @brief Initialize a timer object.
|
772 |
*
|
773 |
* @param[in] timer Pointer to the timer object to initialize.
|
774 |
* Must not be NULL.
|
775 |
*/
|
776 |
void urtTimerInit(urt_osTimer_t* timer);
|
777 |
#endif /* !defined(urtTimerInit) */ |
778 |
|
779 |
#if !defined(urtTimerSet) || defined(__DOXYGEN__)
|
780 |
/**
|
781 |
* @brief Set a timer in single-shot mode.
|
782 |
*
|
783 |
* @param[in] timer Pointer to the timer to be armed.
|
784 |
* Must not be NULL.
|
785 |
* @param[in] delay Time after which the timer shall fire.
|
786 |
* @param[in] callback Pointer to the function to be called when the timer fires.
|
787 |
* Must not be NULL.
|
788 |
* @param[in] cbparams Optional parameters for the callback function.
|
789 |
* May be NULL.
|
790 |
*/
|
791 |
void urtTimerSet(urt_osTimer_t* timer, urt_delay_t delay, urt_osTimerCallback_t callback, void* cbparams); |
792 |
#endif /* !defined(urtTimerSet) */ |
793 |
|
794 |
#if !defined(urtTimerSetPeriodic) || defined(__DOXYGEN__)
|
795 |
/**
|
796 |
* @brief Set a timer in periodic mode.
|
797 |
*
|
798 |
* @param[in] timer Pointer to the timer to be armed.
|
799 |
* Must not be NULL.
|
800 |
* @param[in] period Time after which the timer shall fire periodically.
|
801 |
* @param[in] callback Pointer to the function to be called each time the timer fires.
|
802 |
* Must not be NULL.
|
803 |
* @param[in] cbparams Optional parameters for the callback function.
|
804 |
* May be NULL.
|
805 |
*/
|
806 |
void urtTimerSetPeriodic(urt_osTimer_t* timer, urt_delay_t period, urt_osTimerCallback_t callback, void* cbparams); |
807 |
#endif /* !defined(urtTimerSetPeriodic) */ |
808 |
|
809 |
#if !defined(urtTimerReset) || defined(__DOXYGEN__)
|
810 |
/**
|
811 |
* @brief Reset and disarm a timer.
|
812 |
*
|
813 |
* @param[in] timer Pointer to the timer to be reset.
|
814 |
* Must not be NULL.
|
815 |
*/
|
816 |
void urtTimerReset(urt_osTimer_t* timer);
|
817 |
#endif /* !defined(urtTimerReset) */ |
818 |
|
819 |
#if !defined(urtTimerIsArmed) || defined(__DOXYGEN__)
|
820 |
/**
|
821 |
* @brief Retrieve the current status of a timer.
|
822 |
*
|
823 |
* @param[in] timer Pointer to the timer to inspect.
|
824 |
* Must not be NULL.
|
825 |
*
|
826 |
* @return Flag, indicating whether or not the timer is currently armed.
|
827 |
*/
|
828 |
bool urtTimerIsArmed(urt_osTimer_t* timer);
|
829 |
#endif /* !defined(urtTimerIsArmed) */ |
830 |
|
831 |
#if defined(__cplusplus)
|
832 |
} |
833 |
#endif /* defined(__cplusplus) */ |
834 |
|
835 |
#endif /* URT_OSAL_H */ |