urtware / urt_osal.h @ b247db3f
History | View | Annotate | Download (29.173 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 | 0de5bed8 | Thomas Schöpping | #if (!defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true)) || defined(__DOXYGEN__) |
191 | 46471486 | Thomas Schöpping | /**
|
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 | 0de5bed8 | Thomas Schöpping | #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 | 46471486 | Thomas Schöpping | |
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 */ |