urtware / urt_osal.h @ 67844205
History | View | Annotate | Download (28.922 KB)
1 | 46471486 | Thomas Schöpping | /*
|
---|---|---|---|
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 */ |