urtware / urt_osal.h @ 46471486
History | View | Annotate | Download (28.9 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) || 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 |
#endif /* !defined(urtCondvarWait) */ |
205 |
|
206 |
#if defined(__cplusplus)
|
207 |
} |
208 |
#endif /* defined(__cplusplus) */ |
209 |
|
210 |
/*============================================================================*/
|
211 |
/* EVENTS */
|
212 |
/*============================================================================*/
|
213 |
|
214 |
/*
|
215 |
* The following types and constants must be defined by the implementation:
|
216 |
*
|
217 |
* urt_osEventSource_t
|
218 |
* Type to represent an event source object.
|
219 |
* Is only used via pointers by the API.
|
220 |
*
|
221 |
* urt_osEventListener_t
|
222 |
* Type to represent an event listener object.
|
223 |
* Is only used via pointers by the API.
|
224 |
*
|
225 |
* urt_osEventMask_t
|
226 |
* Integer type to represent event masks.
|
227 |
*
|
228 |
* urt_osEventFlags_t
|
229 |
* Integer type to represent event flags.
|
230 |
*
|
231 |
* URT_EVENTMASK_MAXPRIO
|
232 |
* Constant of type urt_osEventMask_t to specify the event mask that is
|
233 |
* handled with maximum priority.
|
234 |
* This constant is typically either 0x0..1 (low values have high priority)
|
235 |
* or 0x8..0 (high values have high priority).
|
236 |
* A value of 0 indicates that priorities are not supported.
|
237 |
*/
|
238 |
|
239 |
/**
|
240 |
* @brief Enum type to distinguish differnt variants how to wait for events.
|
241 |
*/
|
242 |
typedef enum { |
243 |
URT_EVENT_WAIT_ONE = 0, /**< Wait for exactly one of the specified events. */ |
244 |
URT_EVENT_WAIT_ANY = 1, /**< Wait for any (one or more) of the specified events. */ |
245 |
URT_EVENT_WAIT_ALL = 2, /**< Wait for all of the specified events. */ |
246 |
} urt_osEventWait_t; |
247 |
|
248 |
#if defined(__cplusplus)
|
249 |
extern "C" { |
250 |
#endif /* defined(__cplusplus) */ |
251 |
|
252 |
#if !defined(urtEventSourceInit) || defined(__DOXYGEN__)
|
253 |
/**
|
254 |
* @brief Initialize an event source object.
|
255 |
*
|
256 |
* @param[in] source Pointer to the event source object to initialize.
|
257 |
* Must not be NULL.
|
258 |
*/
|
259 |
void urtEventSourceInit(urt_osEventSource_t* source);
|
260 |
#endif /* !defined(urtEventSourceInit) */ |
261 |
|
262 |
#if !defined(urtEventSourceBroadcast) || defined(__DOXYGEN__)
|
263 |
/**
|
264 |
* @brief Broadcast an event with specified flags.
|
265 |
*
|
266 |
* @param[in] source Pointer to the event source to broadcast the event.
|
267 |
* Must not be NULL.
|
268 |
* @param[in] flags Flags to be set at the recieveing listeners.
|
269 |
*/
|
270 |
void urtEventSourceBroadcast(urt_osEventSource_t* source, urt_osEventFlags_t flags);
|
271 |
#endif /* !defined(urtEventSourceBroadcast) */ |
272 |
|
273 |
#if !defined(urtEventListenerInit) || defined(__DOXYGEN__)
|
274 |
/**
|
275 |
* @brief Initialize an event listener object.
|
276 |
* Must not be NULL.
|
277 |
*
|
278 |
* @param[in] listener Pointer to the event listener object to initialize.
|
279 |
*/
|
280 |
void urtEventListenerInit(urt_osEventListener_t* listener);
|
281 |
#endif /* !defined(urtEventListenerInit) */ |
282 |
|
283 |
#if !defined(urtEventListenerGetFlags) || defined(__DOXYGEN__)
|
284 |
/**
|
285 |
* @brief Retrieve the currently set flags of an event listener.
|
286 |
* @details Flags are not cleared in the listener.
|
287 |
*
|
288 |
* @param[in] listener Pointer to the event listener to recieve the flags from.
|
289 |
* Must not be NULL.
|
290 |
*
|
291 |
* @return Currently set flags.
|
292 |
*/
|
293 |
urt_osEventFlags_t urtEventListenerGetFlags(urt_osEventListener_t* listener); |
294 |
#endif /* !defined(urtEventListenerGetFlags) */ |
295 |
|
296 |
#if !defined(urtEventListenerClearFlags) || defined(__DOXYGEN__)
|
297 |
/**
|
298 |
* @brief Retrieve and clear the currently set flags from an event listener.
|
299 |
*
|
300 |
* @param[in] listener Pointer to the event listener to recieve the flags from.
|
301 |
* Must not be NULL.
|
302 |
*
|
303 |
* @return The flags that had been set at the listener.
|
304 |
*/
|
305 |
urt_osEventFlags_t urtEventListenerClearFlags(urt_osEventListener_t* listener); |
306 |
#endif /* !defined(urtEventListenerClearFlags) */ |
307 |
|
308 |
#if !defined(urtEventRegister) || defined(__DOXYGEN__)
|
309 |
/**
|
310 |
* @brief Register an event source to a listener.
|
311 |
*
|
312 |
* @param[in] source Pointer to the event source to register.
|
313 |
* Must not be NULL.
|
314 |
* @param[in] listener Pointer to the event listener to register.
|
315 |
* Must not be NULL.
|
316 |
* @param[in] mask Mask to be set at the listening thread on an event.
|
317 |
* @param[in] flags Flags to be set by default at the listener on an event,
|
318 |
*/
|
319 |
void urtEventRegister(urt_osEventSource_t* source, urt_osEventListener_t* listener, urt_osEventMask_t mask, urt_osEventFlags_t flags);
|
320 |
#endif /* !defined(urtEventRegister) */ |
321 |
|
322 |
#if !defined(urtEventUnregister) || defined(__DOXYGEN__)
|
323 |
/**
|
324 |
* @brief Unregister an associated event source and listener.
|
325 |
*
|
326 |
* @param[in] source Pointer to the event source to unregister.
|
327 |
* Must not be NULL.
|
328 |
* @param[in] listener Pointer to the event listener to unregister.
|
329 |
* Must not be NULL.
|
330 |
*/
|
331 |
void urtEventUnregister(urt_osEventSource_t* source, urt_osEventListener_t* listener);
|
332 |
#endif /* !defined(urtEventUnregister) */ |
333 |
|
334 |
#if !defined(urtEventWait) || defined(__DOXYGEN__)
|
335 |
/**
|
336 |
* @brief Wait for one/any/all event(s) to be recieved or a timeout.
|
337 |
*
|
338 |
* @param[in] mask The mask of event to wait for.
|
339 |
* @param[in] type Specificator whether to wait for exactly one, any combination or all of the specified mask flags.
|
340 |
* @param[in] timeout Timeout when the function shall return even if no event was recieved.
|
341 |
*
|
342 |
* @return The recieved event mask.
|
343 |
*/
|
344 |
urt_osEventMask_t urtEventWait(urt_osEventMask_t mask, urt_osEventWait_t type, urt_delay_t timeout); |
345 |
#endif /* !defined(urtEventWait) */ |
346 |
|
347 |
#if defined(__cplusplus)
|
348 |
} |
349 |
#endif /* defined(__cplusplus) */ |
350 |
|
351 |
/*============================================================================*/
|
352 |
/* STREAMS */
|
353 |
/*============================================================================*/
|
354 |
|
355 |
#if defined(__cplusplus)
|
356 |
extern "C" { |
357 |
#endif /* defined(__cplusplus) */ |
358 |
|
359 |
#if !defined(urtPrintf) || defined(__DOXYGEN__)
|
360 |
/**
|
361 |
* @brief Prints a formatted string to standard output.
|
362 |
*
|
363 |
* @param[in] fmt The formatted string to be printed.
|
364 |
*
|
365 |
* @return Number of characters printed.
|
366 |
*/
|
367 |
int urtPrintf(char* fmt, ...); |
368 |
#endif /* !defined(urtPrintf) */ |
369 |
|
370 |
#if !defined(urtErrPrintf) || defined(__DOXYGEN__)
|
371 |
/**
|
372 |
* @brief Prints a formatted string to error output.
|
373 |
*
|
374 |
* @param[in] fmt The formatted string to be printed.
|
375 |
*
|
376 |
* @return Number of characters printed.
|
377 |
*/
|
378 |
int urtErrPrintf(char* fmt, ...); |
379 |
#endif /* !defined(urtErrPrintf) */ |
380 |
|
381 |
#if defined(__cplusplus)
|
382 |
} |
383 |
#endif /* defined(__cplusplus) */ |
384 |
|
385 |
/*============================================================================*/
|
386 |
/* TIME */
|
387 |
/*============================================================================*/
|
388 |
|
389 |
/*
|
390 |
* The following type must be defined by the implementation:
|
391 |
*
|
392 |
* urt_osTime_t
|
393 |
* Type to represent a time object.
|
394 |
* This type may be of any precision.
|
395 |
* Is only used via pointers by the API.
|
396 |
*/
|
397 |
|
398 |
#if defined(__cplusplus)
|
399 |
extern "C" { |
400 |
#endif /* defined(__cplusplus) */ |
401 |
|
402 |
#if !defined(urtTime2Us) || defined(__DOXYGEN__)
|
403 |
/**
|
404 |
* @brief Convert an OS time to microsecond value.
|
405 |
*
|
406 |
* @param[in] t The time to convert.
|
407 |
* Must not be NULL
|
408 |
*
|
409 |
* @return The equivalent time in microseconds.
|
410 |
*/
|
411 |
uint64_t urtTime2Us(urt_osTime_t* t); |
412 |
#endif /* !defined(urtTime2Us) */ |
413 |
|
414 |
#if !defined(urtTimeNow) || defined(__DOXYGEN__)
|
415 |
/**
|
416 |
* @brief Get the current system time.
|
417 |
*
|
418 |
* @return Current system time as provide by the operating system.
|
419 |
*/
|
420 |
urt_osTime_t urtTimeNow(void);
|
421 |
#endif /* !defined(urtTimeNow) */ |
422 |
|
423 |
#if !defined(urtTimeAddUs) || defined(__DOXYGEN__)
|
424 |
/**
|
425 |
* @brief Add microseconds to a specified system time.
|
426 |
*
|
427 |
* @param[in] time Pointer to the time value to be incremented.
|
428 |
* Must not be NULL.
|
429 |
* @param[in] offset Amount of microseconds to add.
|
430 |
*/
|
431 |
void urtTimeAddUs(urt_osTime_t* time, urt_delay_t offset);
|
432 |
#endif /* !defined(urtTimeAddUs) */ |
433 |
|
434 |
#if defined(__cplusplus)
|
435 |
} |
436 |
#endif /* defined(__cplusplus) */ |
437 |
|
438 |
/*============================================================================*/
|
439 |
/* THREAD */
|
440 |
/*============================================================================*/
|
441 |
|
442 |
/*
|
443 |
* The following types, constants and macros must be defined by the
|
444 |
* implementation:
|
445 |
*
|
446 |
* urt_osThread_t
|
447 |
* Type to represent an thread object.
|
448 |
* Is only used via pointers by the API.
|
449 |
*
|
450 |
* urt_osThreadPrio_t
|
451 |
* Integer type to represent thread priorities.
|
452 |
*
|
453 |
* URT_THREAD_PRIO_LOW_MIN
|
454 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
455 |
* low-priority threads.
|
456 |
* Must be greater than the idle thread priority.
|
457 |
*
|
458 |
* URT_THREAD_PRIO_LOW_MAX
|
459 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
460 |
* low-priority threads.
|
461 |
* Must be greater or equal URT_THREAD_PRIO_LOW_MIN.
|
462 |
*
|
463 |
* URT_THREAD_PRIO_NORMAL_MIN
|
464 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
465 |
* normal-priority threads.
|
466 |
* Must be greater than URT_THREAD_PRIO_LOW_MAX.
|
467 |
*
|
468 |
* URT_THREAD_PRIO_NORMAL_MAX
|
469 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
470 |
* normal-priority threads.
|
471 |
* Must be greater or equal URT_THREAD_PRIO_NORMAL_MIN.
|
472 |
*
|
473 |
* URT_THREAD_PRIO_HIGH_MIN
|
474 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
475 |
* high-priority threads.
|
476 |
* Must be greater than URT_THREAD_PRIO_NORMAL_MAX.
|
477 |
*
|
478 |
* URT_THREAD_PRIO_HIGH_MAX
|
479 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
480 |
* high-priority threads.
|
481 |
* Must be greater or equal URT_THREAD_PRIO_HIGH_MIN.
|
482 |
*
|
483 |
* URT_THREAD_PRIO_RT_MIN
|
484 |
* Constant of type urt_osThreadPrio_t, specifying the minimum priority for
|
485 |
* real-time threads.
|
486 |
* Must be greater than URT_THREAD_PRIO_HIGH_MAX.
|
487 |
*
|
488 |
* URT_THREAD_PRIO_RT_MAX
|
489 |
* Constant of type urt_osThreadPrio_t, specifying the maximum priority for
|
490 |
* real-time threads.
|
491 |
* Must be greater or equal URT_THREAD_PRIO_HIGH_MIN but lower than the
|
492 |
* control/root thread priority.
|
493 |
*
|
494 |
* URT_THREAD_SLEEP_MAX
|
495 |
* Constant of type float specifying the maximum time (in seconds) a thread
|
496 |
* may sleep via the urtThreadSleep() function.
|
497 |
*
|
498 |
* URT_THREAD_SSLEEP_MAX
|
499 |
* Constant of type urt_delay_t specifying the maximum number of seconds a
|
500 |
* thread may sleep via the urtThreadSSleep() function.
|
501 |
*
|
502 |
* URT_THREAD_MSLEEP_MAX
|
503 |
* Constant of type urt_delay_t specifying the maximum number of milliseconds
|
504 |
* a thread may sleep via the urtThreadMSleep() function.
|
505 |
*
|
506 |
* URT_THREAD_USLEEP_MAX
|
507 |
* Constant of type urt_delay_t specifying the maximum number of microseconds
|
508 |
* a thread may sleep via the urtThreadUSleep() function.
|
509 |
*
|
510 |
* URT_THREAD_MEMORY(varname, stacksize)
|
511 |
* Macro function to staically allocate a variable 'varname', which holds all
|
512 |
* memory required to hold a thread object with the specified stacksize.
|
513 |
*/
|
514 |
|
515 |
/**
|
516 |
* @brief Enum type for various thread states.
|
517 |
*/
|
518 |
typedef enum { |
519 |
URT_THREAD_STATE_INACTIVE = 0, /**< The thread has not been started yet. */ |
520 |
URT_THREAD_STATE_RUNNING = 1, /**< The thread is currently being executed on a CPU. */ |
521 |
URT_THREAD_STATE_READY = 2, /**< The thread is ready to be scheduled for execution. */ |
522 |
URT_THREAD_STATE_SLEEPING = 3, /**< The thread is currently sleeping for a defined amount of time. */ |
523 |
URT_THREAD_STATE_SUSPENDED = 4, /**< Execution of the thread has been suspended. */ |
524 |
URT_THREAD_STATE_WAITING = 5, /**< The thread is currently waiting for an event. */ |
525 |
URT_THREAD_STATE_TERMINATED = 6, /**< The thread has been terminated. */ |
526 |
} urt_osThreadState_t; |
527 |
|
528 |
/**
|
529 |
* @brief Enum type for various termination signals.
|
530 |
*/
|
531 |
typedef enum { |
532 |
URT_THREAD_TERMINATE_REQUEST = 15, /**< Request a thread to terminate in a cooperative manner. */ |
533 |
URT_THREAD_TERMINATE_KILL = 9, /**< Terminate a thread in a non-cooperative manner (force). */ |
534 |
} urt_osThreadTerminateSignal_t; |
535 |
|
536 |
/**
|
537 |
* @brief Thread function.
|
538 |
*
|
539 |
* @param[in] arg Pointer to optional arguments.
|
540 |
* May be NULL.
|
541 |
*/
|
542 |
typedef void (*urt_osThreadFunction_t)(void* arg); |
543 |
|
544 |
#if defined(__cplusplus)
|
545 |
extern "C" { |
546 |
#endif /* defined(__cplusplus) */ |
547 |
|
548 |
#if !defined(urtThreadInit) || defined(__DOXYGEN__)
|
549 |
/**
|
550 |
* @brief Initialize a thread object.
|
551 |
* @details The new thread becomes a child of the calling thread.
|
552 |
*
|
553 |
* @param[in] memory Pointer to the memory where to create the thread object.
|
554 |
* Must not be NULL.
|
555 |
* @param[in] size Size of the memory.
|
556 |
* @param[in] prio Initial priority of the thread.
|
557 |
* @param[in] func Pointer to the thread function the thread shall execute.
|
558 |
* Must not be NULL.
|
559 |
* @param[in] arg Pointer to optional function arguments.
|
560 |
* May be NULL.
|
561 |
*
|
562 |
* @return Pointer to the created thread object.
|
563 |
*/
|
564 |
urt_osThread_t* urtThreadInit(void* memory, size_t size, urt_osThreadPrio_t prio, urt_osThreadFunction_t func, void* arg); |
565 |
#endif /* !defined(urtThreadInit) */ |
566 |
|
567 |
#if !defined(urtThreadStart) || defined(__DOXYGEN__)
|
568 |
/**
|
569 |
* @brief Start execution of a thread.
|
570 |
*
|
571 |
* @param[in] thread Pointer to the thread to start.
|
572 |
* Must not be NULL.
|
573 |
*/
|
574 |
void urtThreadStart(urt_osThread_t* thread);
|
575 |
#endif /* !defined(urtThreadStart) */ |
576 |
|
577 |
#if !defined(urtThreadYield) || defined(__DOXYGEN__)
|
578 |
/**
|
579 |
* @brief Yield execution of the calling thread.
|
580 |
*/
|
581 |
void urtThreadYield(void); |
582 |
#endif /* !defined(urtThreadYield) */ |
583 |
|
584 |
#if !defined(urtThreadGetPriority) || defined(__DOXYGEN__)
|
585 |
/**
|
586 |
* @brief Retrieve the current priority of the calling thread.
|
587 |
*
|
588 |
* @return Current priority.
|
589 |
*/
|
590 |
urt_osThreadPrio_t urtThreadGetPriority(void);
|
591 |
#endif /* !defined(urtThreadGetPriority) */ |
592 |
|
593 |
#if !defined(urtThreadSetPriority) || defined(__DOXYGEN__)
|
594 |
/**
|
595 |
* @brief Set the priority of the calling thread.
|
596 |
*
|
597 |
* @param[in] prio The new priority to set.
|
598 |
*/
|
599 |
void urtThreadSetPriority(urt_osThreadPrio_t prio);
|
600 |
#endif /* !defined(urtThreadSetPriority) */ |
601 |
|
602 |
#if !defined(urtThreadSleep) || defined(__DOXYGEN__)
|
603 |
/**
|
604 |
* @brief The calling thread sleeps for the given amount of time.
|
605 |
*
|
606 |
* @param[in] seconds Time in seconds to sleep.
|
607 |
* Must not be greater than URT_THREAD_SLEEP_MAX.
|
608 |
*/
|
609 |
void urtThreadSleep(float seconds); |
610 |
#endif /* !defined(urtThreadSleep) */ |
611 |
|
612 |
#if !defined(urtThreadSSleep) || defined(__DOXYGEN__)
|
613 |
/**
|
614 |
* @brief The calling thread sleeps for the given amount of seconds.
|
615 |
*
|
616 |
* @param[in] seconds Time in seconds to sleep.
|
617 |
* Must not be greater than URT_THREAD_SSLEP_MAX.
|
618 |
*/
|
619 |
void urtThreadSSleep(unsigned int seconds); |
620 |
#endif /* !defined(urtThreadSSleep) */ |
621 |
|
622 |
#if !defined(urtThreadMSleep) || defined(__DOXYGEN__)
|
623 |
/**
|
624 |
* @brief The calling thread sleeps for the given amount of milliseconds.
|
625 |
*
|
626 |
* @param[in] milliseconds Time in milliseconds to sleep.
|
627 |
* Must not be greater than URT_THREAD_MSLEP_MAX.
|
628 |
*/
|
629 |
void urtThreadMSleep(unsigned int milliseconds); |
630 |
#endif /* !defined(urtThreadMSleep) */ |
631 |
|
632 |
#if !defined(urtThreadUSleep) || defined(__DOXYGEN__)
|
633 |
/**
|
634 |
* @brief The calling thread sleeps for the gven amount of microseconds.
|
635 |
*
|
636 |
* @param[in] microseconds Time in microseconds to sleep.
|
637 |
* Must not be greater than URT_THREAD_USLEP_MAX.
|
638 |
*/
|
639 |
void urtThreadUSleep(urt_delay_t microseconds);
|
640 |
#endif /* !defined(urtThreadUSleep) */ |
641 |
|
642 |
#if !defined(urtThreadSleepUntil) || defined(__DOXYGEN__)
|
643 |
/**
|
644 |
* @brief The calling thread sleeps until the given point in time.
|
645 |
*
|
646 |
* @param[in] time Time when the thread shall wake up.
|
647 |
* If the current is already beyond the argument, the thread will not sleep at all.
|
648 |
*/
|
649 |
void urtThreadSleepUntil(urt_osTime_t time);
|
650 |
#endif /* !defined(urtThreadSleepUntil) */ |
651 |
|
652 |
#if !defined(urtThreadExit) || defined(__DOXYGEN__)
|
653 |
/**
|
654 |
* @brief The calling thread stops execution and terminates.
|
655 |
*/
|
656 |
void urtThreadExit(void); |
657 |
#endif /* !defined(urtThreadExit) */ |
658 |
|
659 |
#if !defined(urtThreadTerminate) || defined(__DOXYGEN__)
|
660 |
/**
|
661 |
* @brief Send a termination signal to a thread.
|
662 |
*
|
663 |
* @param[in] thread Thread to be signaled.
|
664 |
* Must not be NULL.
|
665 |
* @param[in] sig Type of termination.
|
666 |
*/
|
667 |
void urtThreadTerminate(urt_osThread_t* thread, urt_osThreadTerminateSignal_t sig);
|
668 |
#endif /* !defined(urtThreadTerminate) */ |
669 |
|
670 |
#if !defined(urtThreadJoin) || defined(__DOXYGEN__)
|
671 |
/**
|
672 |
* @brief Wait for a thread to terminate.
|
673 |
*
|
674 |
* @param[in] thread Pointer to the thread to wait for.
|
675 |
* Must not be NULL.
|
676 |
*/
|
677 |
void urtThreadJoin(urt_osThread_t* thread);
|
678 |
#endif /* !defined(urtThreadJoin) */ |
679 |
|
680 |
#if !defined(urtThreadGetState) || defined(__DOXYGEN__)
|
681 |
/**
|
682 |
* @brief Get the current execution status of a thread.
|
683 |
*
|
684 |
* @param[in] thread Pointer to the thread to get the status for.
|
685 |
* Must not be NULL.
|
686 |
*
|
687 |
* @return Execution status of the secified thread.
|
688 |
*/
|
689 |
urt_osThreadState_t urtThreadGetState(urt_osThread_t* thread); |
690 |
#endif /* !defined(urtThreadGetState) */ |
691 |
|
692 |
#if !defined(urtThreadGetSelf) || defined(__DOXYGEN__)
|
693 |
/**
|
694 |
* @brief Retrieve the thread object of the calling thread.
|
695 |
*
|
696 |
* @return Pointer to the thread that is currrently executed.
|
697 |
*/
|
698 |
urt_osThread_t* urtThreadGetSelf(void);
|
699 |
#endif /* !defined(urtThreadGetSelf) */ |
700 |
|
701 |
#if !defined(urtThreadGetChildren) || defined(__DOXYGEN__)
|
702 |
/**
|
703 |
* @brief Retrieve the first child of a thread.
|
704 |
*
|
705 |
* @param[in] thread Pointer to the thread to retrieve the child from.
|
706 |
* Must not be NULL.
|
707 |
*
|
708 |
* @return Pointer to the first child thread.
|
709 |
* May be NULL if the thread has no children.
|
710 |
*/
|
711 |
urt_osThread_t* urtThreadGetChildren(urt_osThread_t* thread); |
712 |
#endif /* !defined(urtThreadGetChildren) */ |
713 |
|
714 |
#if !defined(urtThreadGetSibling) || defined(__DOXYGEN__)
|
715 |
/**
|
716 |
* @brief Retrieve the next sibling of a thread.
|
717 |
*
|
718 |
* @param[in] thread Pointer to the thread to retrieve the sibling from.
|
719 |
*
|
720 |
* @return Pointer to the next sibling of the thread.
|
721 |
* May be NULL if the thread does not have any more siblings.
|
722 |
*/
|
723 |
urt_osThread_t* urtThreadGetSibling(urt_osThread_t* thread); |
724 |
#endif /* !defined(urtThreadGetSibling) */ |
725 |
|
726 |
#if !defined(urtThreadGetParent) || defined(__DOXYGEN__)
|
727 |
/**
|
728 |
* @brief Retrieve the parent of a thread.
|
729 |
*
|
730 |
* @param[in] thread Pointer to the thread to retrieve the parent from.
|
731 |
*
|
732 |
* @return Pointer to the parent thread.
|
733 |
* May be NULL if the specified thread is root.
|
734 |
*/
|
735 |
urt_osThread_t* urtThreadGetParent(urt_osThread_t* thread); |
736 |
#endif /* !defined(urtThreadGetParent) */ |
737 |
|
738 |
#if defined(__cplusplus)
|
739 |
} |
740 |
#endif /* defined(__cplusplus) */ |
741 |
|
742 |
/*============================================================================*/
|
743 |
/* TIMER */
|
744 |
/*============================================================================*/
|
745 |
|
746 |
/*
|
747 |
* The following type must be defined by the implementation:
|
748 |
*
|
749 |
* urt_osTimer_t
|
750 |
* Type to represent a timer object.
|
751 |
* Is only used via pointers by the API.
|
752 |
*/
|
753 |
|
754 |
/**
|
755 |
* @brief Timer callback function type.
|
756 |
* @details A timer executes a callback when its time ran out and it fires.
|
757 |
*
|
758 |
* @param[in] params Pointer to optional parameters for the callback function.
|
759 |
* May be NULL.
|
760 |
*/
|
761 |
typedef void (*urt_osTimerCallback_t)(void* parameter); |
762 |
|
763 |
#if defined(__cplusplus)
|
764 |
extern "C" { |
765 |
#endif /* defined(__cplusplus) */ |
766 |
|
767 |
#if !defined(urtTimerInit) || defined(__DOXYGEN__)
|
768 |
/**
|
769 |
* @brief Initialize a timer object.
|
770 |
*
|
771 |
* @param[in] timer Pointer to the timer object to initialize.
|
772 |
* Must not be NULL.
|
773 |
*/
|
774 |
void urtTimerInit(urt_osTimer_t* timer);
|
775 |
#endif /* !defined(urtTimerInit) */ |
776 |
|
777 |
#if !defined(urtTimerSet) || defined(__DOXYGEN__)
|
778 |
/**
|
779 |
* @brief Set a timer in single-shot mode.
|
780 |
*
|
781 |
* @param[in] timer Pointer to the timer to be armed.
|
782 |
* Must not be NULL.
|
783 |
* @param[in] delay Time after which the timer shall fire.
|
784 |
* @param[in] callback Pointer to the function to be called when the timer fires.
|
785 |
* Must not be NULL.
|
786 |
* @param[in] cbparams Optional parameters for the callback function.
|
787 |
* May be NULL.
|
788 |
*/
|
789 |
void urtTimerSet(urt_osTimer_t* timer, urt_delay_t delay, urt_osTimerCallback_t callback, void* cbparams); |
790 |
#endif /* !defined(urtTimerSet) */ |
791 |
|
792 |
#if !defined(urtTimerSetPeriodic) || defined(__DOXYGEN__)
|
793 |
/**
|
794 |
* @brief Set a timer in periodic mode.
|
795 |
*
|
796 |
* @param[in] timer Pointer to the timer to be armed.
|
797 |
* Must not be NULL.
|
798 |
* @param[in] period Time after which the timer shall fire periodically.
|
799 |
* @param[in] callback Pointer to the function to be called each time the timer fires.
|
800 |
* Must not be NULL.
|
801 |
* @param[in] cbparams Optional parameters for the callback function.
|
802 |
* May be NULL.
|
803 |
*/
|
804 |
void urtTimerSetPeriodic(urt_osTimer_t* timer, urt_delay_t period, urt_osTimerCallback_t callback, void* cbparams); |
805 |
#endif /* !defined(urtTimerSetPeriodic) */ |
806 |
|
807 |
#if !defined(urtTimerReset) || defined(__DOXYGEN__)
|
808 |
/**
|
809 |
* @brief Reset and disarm a timer.
|
810 |
*
|
811 |
* @param[in] timer Pointer to the timer to be reset.
|
812 |
* Must not be NULL.
|
813 |
*/
|
814 |
void urtTimerReset(urt_osTimer_t* timer);
|
815 |
#endif /* !defined(urtTimerReset) */ |
816 |
|
817 |
#if !defined(urtTimerIsArmed) || defined(__DOXYGEN__)
|
818 |
/**
|
819 |
* @brief Retrieve the current status of a timer.
|
820 |
*
|
821 |
* @param[in] timer Pointer to the timer to inspect.
|
822 |
* Must not be NULL.
|
823 |
*
|
824 |
* @return Flag, indicating whether or not the timer is currently armed.
|
825 |
*/
|
826 |
bool urtTimerIsArmed(urt_osTimer_t* timer);
|
827 |
#endif /* !defined(urtTimerIsArmed) */ |
828 |
|
829 |
#if defined(__cplusplus)
|
830 |
} |
831 |
#endif /* defined(__cplusplus) */ |
832 |
|
833 |
#endif /* URT_OSAL_H */ |