Statistics
| Branch: | Revision:

urtware / urt_osal.h @ b247db3f

History | View | Annotate | Download (29.173 KB)

1
/*
2
µRtWare is a lightweight publish/subscribe middleware for real-time
3
applications. It was developed as part of the software habitat for the
4
Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well.
5

6
Copyright (C) 2018..2020  Thomas Schöpping et al.
7

8
This program is free software: you can redistribute it and/or modify
9
it under the terms of the GNU General Public License as published by
10
the Free Software Foundation, either version 3 of the License, or
11
(at your option) any later version.
12

13
This program is distributed in the hope that it will be useful,
14
but WITHOUT ANY WARRANTY; without even the implied warranty of
15
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16
GNU General Public License for more details.
17

18
You should have received a copy of the GNU General Public License
19
along with this program.  If not, see <http://www.gnu.org/licenses/>.
20
*/
21

    
22
#ifndef URT_OSAL_H
23
#define URT_OSAL_H
24

    
25
#include <urtware.h>
26

    
27
/*============================================================================*/
28
/* VERSION                                                                    */
29
/*============================================================================*/
30

    
31
/**
32
 * @brief   The µRtWare operating system abstraction layer interface major version.
33
 * @note    Changes of the major version imply incompatibilities.
34
 */
35
#define URT_OSAL_VERSION_MAJOR                  0
36

    
37
/**
38
 * @brief   The µRtWare operating system abstraction layer interface minor version.
39
 * @note    A higher minor version implies new functionalty, but all old interfaces are still available.
40
 */
41
#define URT_OSAL_VERSION_MINOR                  1
42

    
43
/*============================================================================*/
44
/* DEPENDENCIES                                                               */
45
/*============================================================================*/
46

    
47
#include <stdint.h>
48

    
49
/*============================================================================*/
50
/* DEBUG                                                                      */
51
/*============================================================================*/
52

    
53
#if defined(__cplusplus)
54
extern "C" {
55
#endif /* defined(__cplusplus) */
56

    
57
#if !defined(urtDebugAssert) || defined(__DOXYGEN__)
58
  /**
59
   * @brief Assert function to check a given condition.
60
   *
61
   * @param[in] condition   The condition to check.
62
   */
63
  void urtDebugAssert(const bool condition);
64
#endif /* !defined(urtDebugAssert) */
65

    
66
#if defined(__cplusplus)
67
}
68
#endif /* defined(__cplusplus) */
69

    
70
/*============================================================================*/
71
/* MUTEX                                                                      */
72
/*============================================================================*/
73

    
74
/*
75
 * The following type must be defined by the implementation:
76
 *
77
 * urt_osMutex_t
78
 *    Type to represent a mutex lock object.
79
 *    Is only used via pointers by the API.
80
 */
81

    
82
#if defined(__cplusplus)
83
extern "C" {
84
#endif /* defined(__cplusplus) */
85

    
86
#if !defined(urtMutexInit) || defined(__DOXYGEN__)
87
  /**
88
   * @brief   Initialize a mutex lock object.
89
   *
90
   * @param[in] mutex   Pointer to the mutex lock object to initialize.
91
   *                    Must not be NULL.
92
   */
93
  void urtMutexInit(urt_osMutex_t* mutex);
94
#endif /* !defined(urtMutexInit) */
95

    
96
#if !defined(urtMutexLock) || defined(__DOXYGEN__)
97
  /**
98
   * @brief   Lock a mutex lock.
99
   * @details The calling thread is blocked until the mutex lock could be acquired.
100
   *
101
   * @param[in] mutex   Pointer to the mutex lock to acquire.
102
   *                    Must not be NULL.
103
   */
104
  void urtMutexLock(urt_osMutex_t* mutex);
105
#endif /* !defined(urtMutexLock) */
106

    
107
#if !defined(urtMutexTryLock) || defined(__DOXYGEN__)
108
  /**
109
   * @brief   Try to lock a mutex lock.
110
   * @details This function does not block but returns immediately.
111
   *
112
   * @param[in] mutex   Pointer to the mutex lock to acquire.
113
   *
114
   * @return  Indicator whether the lock was acquired.
115
   * @retval true   The lock was acquired successfully.
116
   * @retval false  The lock could not be acquired.
117
   */
118
  bool urtMutexTryLock(urt_osMutex_t* mutex);
119
#endif /* !defined(urtMutexTryLock) */
120

    
121
#if !defined(urtMutexUnlock) || defined(__DOXYGEN__)
122
  /**
123
   * @brief   Unlock an owned mutex lock.
124
   *
125
   * @param[in] mutex   Pointer to the mutex lock to unlock.
126
   *                    Must not be NULL.
127
   */
128
  void urtMutexUnlock(urt_osMutex_t* mutex);
129
#endif /* !defined(urtMutexUnlock) */
130

    
131
#if defined(__cplusplus)
132
}
133
#endif /* defined(__cplusplus) */
134

    
135
/*============================================================================*/
136
/* CONDITION VARIABLE                                                         */
137
/*============================================================================*/
138

    
139
/*
140
 * The following type must be defined by the implementation:
141
 *
142
 * urt_osCondvar_t
143
 *    Type to represent a condition variable object.
144
 *    Is only used via pointers by the API.
145
 */
146

    
147
/**
148
 * @brief   Status type of condition variables.
149
 */
150
typedef enum {
151
  URT_CONDVAR_WAITSTATUS_SIGNAL = 1,    /**< The condition variable has been signaled individually. */
152
  URT_CONDVAR_WAITSTATUS_BROADCAST = 2, /**< The condition variable has been signal via broadcast. */
153
  URT_CONDVAR_WAITSTATUS_TIMEOUT = 0,   /**< Waiting for the condition variable timed out. */
154
} urt_osCondvarWaitStatus_t;
155

    
156
#if defined(__cplusplus)
157
extern "C" {
158
#endif /* defined(__cplusplus) */
159

    
160
#if !defined(urtCondvarInit) || defined(__DOXYGEN__)
161
  /**
162
   * @brief   Initialize a condition variable object.
163
   *
164
   * @param[in] condvar   Pointer to the object to initialize.
165
   *                      Must not be NULL.
166
   */
167
  void urtCondvarInit(urt_osCondvar_t* condvar);
168
#endif /* !defined(urtCondvarInit) */
169

    
170
#if !defined(urtCondvarSignal) || defined(__DOXYGEN__)
171
  /**
172
   * @brief   Signal a condition variable (wake one waiting thread).
173
   *
174
   * @param[in] condvar   Pointer to the condition variable to signal.
175
   *                      Must not be NULL.
176
   */
177
  void urtCondvarSignal(urt_osCondvar_t* condvar);
178
#endif /* !defined(urtCondvarSignal) */
179

    
180
#if !defined(urtCondvarBroadcast) || defined(__DOXYGEN__)
181
  /**
182
   * @brief   Signal a condition variable via broadcast (wake all waiting threads).
183
   *
184
   * @param[in] condvar   Pointer to the condition variable to signal via broadcast.
185
   *                      Must not be NULL.
186
   */
187
  void urtCondvarBroadcast(urt_osCondvar_t* condvar);
188
#endif /* !defined(urtCondvarBroadcast) */
189

    
190
#if (!defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true)) || defined(__DOXYGEN__)
191
  /**
192
   * @brief   Wait for a condition variable to be signaled or timeout.
193
   *
194
   * @param[in] condvar   Pointer to the condition variabel to wait for.
195
   *                      Must not be NULL.
196
   * @param[in] mutex     Pointer to the associated mutex lock.
197
   *                      Must not be NULL.
198
   *                      Mutex must be acquired when this function is called.
199
   * @param[in] timeout   Timeout (in microseconds) when the function will return even without the condition variable being signaled.
200
   *                      Use URT_DELAY_INFINITE to deactivate timeout.
201
   * @return
202
   */
203
  urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex, urt_delay_t timeout);
204
#else /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */
205
  urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex);
206
#endif /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */
207

    
208
#if defined(__cplusplus)
209
}
210
#endif /* defined(__cplusplus) */
211

    
212
/*============================================================================*/
213
/* EVENTS                                                                     */
214
/*============================================================================*/
215

    
216
/*
217
 * The following types and constants must be defined by the implementation:
218
 *
219
 * urt_osEventSource_t
220
 *    Type to represent an event source object.
221
 *    Is only used via pointers by the API.
222
 *
223
 * urt_osEventListener_t
224
 *    Type to represent an event listener object.
225
 *    Is only used via pointers by the API.
226
 *
227
 * urt_osEventMask_t
228
 *    Integer type to represent event masks.
229
 *
230
 * urt_osEventFlags_t
231
 *    Integer type to represent event flags.
232
 *
233
 * URT_EVENTMASK_MAXPRIO
234
 *    Constant of type urt_osEventMask_t to specify the event mask that is
235
 *    handled with maximum priority.
236
 *    This constant is typically either 0x0..1 (low values have high priority)
237
 *    or 0x8..0 (high values have high priority).
238
 *    A value of 0 indicates that priorities are not supported.
239
 */
240

    
241
/**
242
 * @brief   Enum type to distinguish differnt variants how to wait for events.
243
 */
244
typedef enum {
245
  URT_EVENT_WAIT_ONE = 0,   /**< Wait for exactly one of the specified events. */
246
  URT_EVENT_WAIT_ANY = 1,   /**< Wait for any (one or more) of the specified events. */
247
  URT_EVENT_WAIT_ALL = 2,   /**< Wait for all of the specified events. */
248
} urt_osEventWait_t;
249

    
250
#if defined(__cplusplus)
251
extern "C" {
252
#endif /* defined(__cplusplus) */
253

    
254
#if !defined(urtEventSourceInit) || defined(__DOXYGEN__)
255
  /**
256
   * @brief   Initialize an event source object.
257
   *
258
   * @param[in] source  Pointer to the event source object to initialize.
259
   *                    Must not be NULL.
260
   */
261
  void urtEventSourceInit(urt_osEventSource_t* source);
262
#endif /* !defined(urtEventSourceInit) */
263

    
264
#if !defined(urtEventSourceBroadcast) || defined(__DOXYGEN__)
265
  /**
266
   * @brief   Broadcast an event with specified flags.
267
   *
268
   * @param[in] source  Pointer to the event source to broadcast the event.
269
   *                    Must not be NULL.
270
   * @param[in] flags   Flags to be set at the recieveing listeners.
271
   */
272
  void urtEventSourceBroadcast(urt_osEventSource_t* source, urt_osEventFlags_t flags);
273
#endif /* !defined(urtEventSourceBroadcast) */
274

    
275
#if !defined(urtEventListenerInit) || defined(__DOXYGEN__)
276
  /**
277
   * @brief   Initialize an event listener object.
278
   *          Must not be NULL.
279
   *
280
   * @param[in] listener  Pointer to the event listener object to initialize.
281
   */
282
  void urtEventListenerInit(urt_osEventListener_t* listener);
283
#endif /* !defined(urtEventListenerInit) */
284

    
285
#if !defined(urtEventListenerGetFlags) || defined(__DOXYGEN__)
286
  /**
287
   * @brief   Retrieve the currently set flags of an event listener.
288
   * @details Flags are not cleared in the listener.
289
   *
290
   * @param[in] listener  Pointer to the event listener to recieve the flags from.
291
   *                      Must not be NULL.
292
   *
293
   * @return  Currently set flags.
294
   */
295
  urt_osEventFlags_t urtEventListenerGetFlags(urt_osEventListener_t* listener);
296
#endif /* !defined(urtEventListenerGetFlags) */
297

    
298
#if !defined(urtEventListenerClearFlags) || defined(__DOXYGEN__)
299
  /**
300
   * @brief   Retrieve and clear the currently set flags from an event listener.
301
   *
302
   * @param[in] listener  Pointer to the event listener to recieve the flags from.
303
   *                      Must not be NULL.
304
   *
305
   * @return  The flags that had been set at the listener.
306
   */
307
  urt_osEventFlags_t urtEventListenerClearFlags(urt_osEventListener_t* listener);
308
#endif /* !defined(urtEventListenerClearFlags) */
309

    
310
#if !defined(urtEventRegister) || defined(__DOXYGEN__)
311
  /**
312
   * @brief   Register an event source to a listener.
313
   *
314
   * @param[in] source    Pointer to the event source to register.
315
   *                      Must not be NULL.
316
   * @param[in] listener  Pointer to the event listener to register.
317
   *                      Must not be NULL.
318
   * @param[in] mask      Mask to be set at the listening thread on an event.
319
   * @param[in] flags     Flags to be set by default at the listener on an event,
320
   */
321
  void urtEventRegister(urt_osEventSource_t* source, urt_osEventListener_t* listener, urt_osEventMask_t mask, urt_osEventFlags_t flags);
322
#endif /* !defined(urtEventRegister) */
323

    
324
#if !defined(urtEventUnregister) || defined(__DOXYGEN__)
325
  /**
326
   * @brief   Unregister an associated event source and listener.
327
   *
328
   * @param[in] source    Pointer to the event source to unregister.
329
   *                      Must not be NULL.
330
   * @param[in] listener  Pointer to the event listener to unregister.
331
   *                      Must not be NULL.
332
   */
333
  void urtEventUnregister(urt_osEventSource_t* source, urt_osEventListener_t* listener);
334
#endif /* !defined(urtEventUnregister) */
335

    
336
#if !defined(urtEventWait) || defined(__DOXYGEN__)
337
  /**
338
   * @brief   Wait for one/any/all event(s) to be recieved or a timeout.
339
   *
340
   * @param[in] mask      The mask of event to wait for.
341
   * @param[in] type      Specificator whether to wait for exactly one, any combination or all of the specified mask flags.
342
   * @param[in] timeout   Timeout when the function shall return even if no event was recieved.
343
   *
344
   * @return  The recieved event mask.
345
   */
346
  urt_osEventMask_t urtEventWait(urt_osEventMask_t mask, urt_osEventWait_t type, urt_delay_t timeout);
347
#endif /* !defined(urtEventWait) */
348

    
349
#if defined(__cplusplus)
350
}
351
#endif /* defined(__cplusplus) */
352

    
353
/*============================================================================*/
354
/* STREAMS                                                                    */
355
/*============================================================================*/
356

    
357
#if defined(__cplusplus)
358
extern "C" {
359
#endif /* defined(__cplusplus) */
360

    
361
#if !defined(urtPrintf) || defined(__DOXYGEN__)
362
  /**
363
   * @brief   Prints a formatted string to standard output.
364
   *
365
   * @param[in] fmt   The formatted string to be printed.
366
   *
367
   * @return  Number of characters printed.
368
   */
369
  int urtPrintf(char* fmt, ...);
370
#endif /* !defined(urtPrintf) */
371

    
372
#if !defined(urtErrPrintf) || defined(__DOXYGEN__)
373
  /**
374
   * @brief   Prints a formatted string to error output.
375
   *
376
   * @param[in] fmt   The formatted string to be printed.
377
   *
378
   * @return  Number of characters printed.
379
   */
380
  int urtErrPrintf(char* fmt, ...);
381
#endif /* !defined(urtErrPrintf) */
382

    
383
#if defined(__cplusplus)
384
}
385
#endif /* defined(__cplusplus) */
386

    
387
/*============================================================================*/
388
/* TIME                                                                       */
389
/*============================================================================*/
390

    
391
/*
392
 * The following type must be defined by the implementation:
393
 *
394
 * urt_osTime_t
395
 *    Type to represent a time object.
396
 *    This type may be of any precision.
397
 *    Is only used via pointers by the API.
398
 */
399

    
400
#if defined(__cplusplus)
401
extern "C" {
402
#endif /* defined(__cplusplus) */
403

    
404
#if !defined(urtTime2Us) || defined(__DOXYGEN__)
405
  /**
406
   * @brief   Convert an OS time to microsecond value.
407
   *
408
   * @param[in] t   The time to convert.
409
   *                Must not be NULL
410
   *
411
   * @return  The equivalent time in microseconds.
412
   */
413
  uint64_t urtTime2Us(urt_osTime_t* t);
414
#endif /* !defined(urtTime2Us) */
415

    
416
#if !defined(urtTimeNow) || defined(__DOXYGEN__)
417
  /**
418
   * @brief   Get the current system time.
419
   *
420
   * @return  Current system time as provide by the operating system.
421
   */
422
  urt_osTime_t urtTimeNow(void);
423
#endif /* !defined(urtTimeNow) */
424

    
425
#if !defined(urtTimeAddUs) || defined(__DOXYGEN__)
426
  /**
427
   * @brief   Add microseconds to a specified system time.
428
   *
429
   * @param[in] time    Pointer to the time value to be incremented.
430
   *                    Must not be NULL.
431
   * @param[in] offset  Amount of microseconds to add.
432
   */
433
  void urtTimeAddUs(urt_osTime_t* time, urt_delay_t offset);
434
#endif /* !defined(urtTimeAddUs) */
435

    
436
#if defined(__cplusplus)
437
}
438
#endif /* defined(__cplusplus) */
439

    
440
/*============================================================================*/
441
/* THREAD                                                                     */
442
/*============================================================================*/
443

    
444
/*
445
 * The following types, constants and macros must be defined by the
446
 * implementation:
447
 *
448
 * urt_osThread_t
449
 *    Type to represent an thread object.
450
 *    Is only used via pointers by the API.
451
 *
452
 * urt_osThreadPrio_t
453
 *    Integer type to represent thread priorities.
454
 *
455
 * URT_THREAD_PRIO_LOW_MIN
456
 *    Constant of type urt_osThreadPrio_t, specifying the minimum priority for
457
 *    low-priority threads.
458
 *    Must be greater than the idle thread priority.
459
 *
460
 * URT_THREAD_PRIO_LOW_MAX
461
 *    Constant of type urt_osThreadPrio_t, specifying the maximum priority for
462
 *    low-priority threads.
463
 *    Must be greater or equal URT_THREAD_PRIO_LOW_MIN.
464
 *
465
 * URT_THREAD_PRIO_NORMAL_MIN
466
 *    Constant of type urt_osThreadPrio_t, specifying the minimum priority for
467
 *    normal-priority threads.
468
 *    Must be greater than URT_THREAD_PRIO_LOW_MAX.
469
 *
470
 * URT_THREAD_PRIO_NORMAL_MAX
471
 *    Constant of type urt_osThreadPrio_t, specifying the maximum priority for
472
 *    normal-priority threads.
473
 *    Must be greater or equal URT_THREAD_PRIO_NORMAL_MIN.
474
 *
475
 * URT_THREAD_PRIO_HIGH_MIN
476
 *    Constant of type urt_osThreadPrio_t, specifying the minimum priority for
477
 *    high-priority threads.
478
 *    Must be greater than URT_THREAD_PRIO_NORMAL_MAX.
479
 *
480
 * URT_THREAD_PRIO_HIGH_MAX
481
 *    Constant of type urt_osThreadPrio_t, specifying the maximum priority for
482
 *    high-priority threads.
483
 *    Must be greater or equal URT_THREAD_PRIO_HIGH_MIN.
484
 *
485
 * URT_THREAD_PRIO_RT_MIN
486
 *    Constant of type urt_osThreadPrio_t, specifying the minimum priority for
487
 *    real-time threads.
488
 *    Must be greater than URT_THREAD_PRIO_HIGH_MAX.
489
 *
490
 * URT_THREAD_PRIO_RT_MAX
491
 *    Constant of type urt_osThreadPrio_t, specifying the maximum priority for
492
 *    real-time threads.
493
 *    Must be greater or equal URT_THREAD_PRIO_HIGH_MIN but lower than the
494
 *    control/root thread priority.
495
 *
496
 * URT_THREAD_SLEEP_MAX
497
 *    Constant of type float specifying the maximum time (in seconds) a thread
498
 *    may sleep via the urtThreadSleep() function.
499
 *
500
 * URT_THREAD_SSLEEP_MAX
501
 *    Constant of type urt_delay_t specifying the maximum number of seconds a
502
 *    thread may sleep via the urtThreadSSleep() function.
503
 *
504
 * URT_THREAD_MSLEEP_MAX
505
 *    Constant of type urt_delay_t specifying the maximum number of milliseconds
506
 *    a thread may sleep via the urtThreadMSleep() function.
507
 *
508
 * URT_THREAD_USLEEP_MAX
509
 *    Constant of type urt_delay_t specifying the maximum number of microseconds
510
 *    a thread may sleep via the urtThreadUSleep() function.
511
 *
512
 * URT_THREAD_MEMORY(varname, stacksize)
513
 *    Macro function to staically allocate a variable 'varname', which holds all
514
 *    memory required to hold a thread object with the specified stacksize.
515
 */
516

    
517
/**
518
 * @brief   Enum type for various thread states.
519
 */
520
typedef enum {
521
  URT_THREAD_STATE_INACTIVE = 0,    /**< The thread has not been started yet. */
522
  URT_THREAD_STATE_RUNNING = 1,     /**< The thread is currently being executed on a CPU. */
523
  URT_THREAD_STATE_READY = 2,       /**< The thread is ready to be scheduled for execution. */
524
  URT_THREAD_STATE_SLEEPING = 3,    /**< The thread is currently sleeping for a defined amount of time. */
525
  URT_THREAD_STATE_SUSPENDED = 4,   /**< Execution of the thread has been suspended. */
526
  URT_THREAD_STATE_WAITING = 5,     /**< The thread is currently waiting for an event. */
527
  URT_THREAD_STATE_TERMINATED = 6,  /**< The thread has been terminated. */
528
} urt_osThreadState_t;
529

    
530
/**
531
 * @brief   Enum type for various termination signals.
532
 */
533
typedef enum {
534
  URT_THREAD_TERMINATE_REQUEST = 15,  /**< Request a thread to terminate in a cooperative manner. */
535
  URT_THREAD_TERMINATE_KILL = 9,      /**< Terminate a thread in a non-cooperative manner (force). */
536
} urt_osThreadTerminateSignal_t;
537

    
538
/**
539
 * @brief   Thread function.
540
 *
541
 * @param[in] arg   Pointer to optional arguments.
542
 *                  May be NULL.
543
 */
544
typedef void (*urt_osThreadFunction_t)(void* arg);
545

    
546
#if defined(__cplusplus)
547
extern "C" {
548
#endif /* defined(__cplusplus) */
549

    
550
#if !defined(urtThreadInit) || defined(__DOXYGEN__)
551
  /**
552
   * @brief   Initialize a thread object.
553
   * @details The new thread becomes a child of the calling thread.
554
   *
555
   * @param[in] memory  Pointer to the memory where to create the thread object.
556
   *                    Must not be NULL.
557
   * @param[in] size    Size of the memory.
558
   * @param[in] prio    Initial priority of the thread.
559
   * @param[in] func    Pointer to the thread function the thread shall execute.
560
   *                    Must not be NULL.
561
   * @param[in] arg     Pointer to optional function arguments.
562
   *                    May be NULL.
563
   *
564
   * @return  Pointer to the created thread object.
565
   */
566
  urt_osThread_t* urtThreadInit(void* memory, size_t size, urt_osThreadPrio_t prio, urt_osThreadFunction_t func, void* arg);
567
#endif /* !defined(urtThreadInit) */
568

    
569
#if !defined(urtThreadStart) || defined(__DOXYGEN__)
570
  /**
571
   * @brief   Start execution of a thread.
572
   *
573
   * @param[in] thread  Pointer to the thread to start.
574
   *                    Must not be NULL.
575
   */
576
  void urtThreadStart(urt_osThread_t* thread);
577
#endif /* !defined(urtThreadStart) */
578

    
579
#if !defined(urtThreadYield) || defined(__DOXYGEN__)
580
  /**
581
   * @brief   Yield execution of the calling thread.
582
   */
583
  void urtThreadYield(void);
584
#endif /* !defined(urtThreadYield) */
585

    
586
#if !defined(urtThreadGetPriority) || defined(__DOXYGEN__)
587
  /**
588
   * @brief   Retrieve the current priority of the calling thread.
589
   *
590
   * @return  Current priority.
591
   */
592
  urt_osThreadPrio_t urtThreadGetPriority(void);
593
#endif /* !defined(urtThreadGetPriority) */
594

    
595
#if !defined(urtThreadSetPriority) || defined(__DOXYGEN__)
596
  /**
597
   * @brief   Set the priority of the calling thread.
598
   *
599
   * @param[in] prio  The new priority to set.
600
   */
601
  void urtThreadSetPriority(urt_osThreadPrio_t prio);
602
#endif /* !defined(urtThreadSetPriority) */
603

    
604
#if !defined(urtThreadSleep) || defined(__DOXYGEN__)
605
  /**
606
   * @brief   The calling thread sleeps for the given amount of time.
607
   *
608
   * @param[in] seconds   Time in seconds to sleep.
609
   *                      Must not be greater than URT_THREAD_SLEEP_MAX.
610
   */
611
  void urtThreadSleep(float seconds);
612
#endif /* !defined(urtThreadSleep) */
613

    
614
#if !defined(urtThreadSSleep) || defined(__DOXYGEN__)
615
  /**
616
   * @brief   The calling thread sleeps for the given amount of seconds.
617
   *
618
   * @param[in] seconds   Time in seconds to sleep.
619
   *                      Must not be greater than URT_THREAD_SSLEP_MAX.
620
   */
621
  void urtThreadSSleep(unsigned int seconds);
622
#endif /* !defined(urtThreadSSleep) */
623

    
624
#if !defined(urtThreadMSleep) || defined(__DOXYGEN__)
625
  /**
626
   * @brief   The calling thread sleeps for the given amount of milliseconds.
627
   *
628
   * @param[in] milliseconds  Time in milliseconds to sleep.
629
   *                          Must not be greater than URT_THREAD_MSLEP_MAX.
630
   */
631
  void urtThreadMSleep(unsigned int milliseconds);
632
#endif /* !defined(urtThreadMSleep) */
633

    
634
#if !defined(urtThreadUSleep) || defined(__DOXYGEN__)
635
  /**
636
   * @brief   The calling thread sleeps for the gven amount of microseconds.
637
   *
638
   * @param[in] microseconds  Time in microseconds to sleep.
639
   *                          Must not be greater than URT_THREAD_USLEP_MAX.
640
   */
641
  void urtThreadUSleep(urt_delay_t microseconds);
642
#endif /* !defined(urtThreadUSleep) */
643

    
644
#if !defined(urtThreadSleepUntil) || defined(__DOXYGEN__)
645
  /**
646
   * @brief   The calling thread sleeps until the given point in time.
647
   *
648
   * @param[in] time  Time when the thread shall wake up.
649
   *                  If the current is already beyond the argument, the thread will not sleep at all.
650
   */
651
  void urtThreadSleepUntil(urt_osTime_t time);
652
#endif /* !defined(urtThreadSleepUntil) */
653

    
654
#if !defined(urtThreadExit) || defined(__DOXYGEN__)
655
  /**
656
   * @brief   The calling thread stops execution and terminates.
657
   */
658
  void urtThreadExit(void);
659
#endif /* !defined(urtThreadExit) */
660

    
661
#if !defined(urtThreadTerminate) || defined(__DOXYGEN__)
662
  /**
663
   * @brief   Send a termination signal to a thread.
664
   *
665
   * @param[in] thread  Thread to be signaled.
666
   *                    Must not be NULL.
667
   * @param[in] sig     Type of termination.
668
   */
669
  void urtThreadTerminate(urt_osThread_t* thread, urt_osThreadTerminateSignal_t sig);
670
#endif /* !defined(urtThreadTerminate) */
671

    
672
#if !defined(urtThreadJoin) || defined(__DOXYGEN__)
673
  /**
674
   * @brief   Wait for a thread to terminate.
675
   *
676
   * @param[in] thread  Pointer to the thread to wait for.
677
   *                    Must not be NULL.
678
   */
679
  void urtThreadJoin(urt_osThread_t* thread);
680
#endif /* !defined(urtThreadJoin) */
681

    
682
#if !defined(urtThreadGetState) || defined(__DOXYGEN__)
683
  /**
684
   * @brief   Get the current execution status of a thread.
685
   *
686
   * @param[in] thread  Pointer to the thread to get the status for.
687
   *                    Must not be NULL.
688
   *
689
   * @return  Execution status of the secified thread.
690
   */
691
  urt_osThreadState_t urtThreadGetState(urt_osThread_t* thread);
692
#endif /* !defined(urtThreadGetState) */
693

    
694
#if !defined(urtThreadGetSelf) || defined(__DOXYGEN__)
695
  /**
696
   * @brief   Retrieve the thread object of the calling thread.
697
   *
698
   * @return  Pointer to the thread that is currrently executed.
699
   */
700
  urt_osThread_t* urtThreadGetSelf(void);
701
#endif /* !defined(urtThreadGetSelf) */
702

    
703
#if !defined(urtThreadGetChildren) || defined(__DOXYGEN__)
704
  /**
705
   * @brief   Retrieve the first child of a thread.
706
   *
707
   * @param[in] thread  Pointer to the thread to retrieve the child from.
708
   *                    Must not be NULL.
709
   *
710
   * @return  Pointer to the first child thread.
711
   *          May be NULL if the thread has no children.
712
   */
713
  urt_osThread_t* urtThreadGetChildren(urt_osThread_t* thread);
714
#endif /* !defined(urtThreadGetChildren) */
715

    
716
#if !defined(urtThreadGetSibling) || defined(__DOXYGEN__)
717
  /**
718
   * @brief   Retrieve the next sibling of a thread.
719
   *
720
   * @param[in] thread  Pointer to the thread to retrieve the sibling from.
721
   *
722
   * @return  Pointer to the next sibling of the thread.
723
   *          May be NULL if the thread does not have any more siblings.
724
   */
725
  urt_osThread_t* urtThreadGetSibling(urt_osThread_t* thread);
726
#endif /* !defined(urtThreadGetSibling) */
727

    
728
#if !defined(urtThreadGetParent) || defined(__DOXYGEN__)
729
  /**
730
   * @brief   Retrieve the parent of a thread.
731
   *
732
   * @param[in] thread  Pointer to the thread to retrieve the parent from.
733
   *
734
   * @return  Pointer to the parent thread.
735
   *          May be NULL if the specified thread is root.
736
   */
737
  urt_osThread_t* urtThreadGetParent(urt_osThread_t* thread);
738
#endif /* !defined(urtThreadGetParent) */
739

    
740
#if defined(__cplusplus)
741
}
742
#endif /* defined(__cplusplus) */
743

    
744
/*============================================================================*/
745
/* TIMER                                                                      */
746
/*============================================================================*/
747

    
748
/*
749
 * The following type must be defined by the implementation:
750
 *
751
 * urt_osTimer_t
752
 *    Type to represent a timer object.
753
 *    Is only used via pointers by the API.
754
 */
755

    
756
/**
757
 * @brief   Timer callback function type.
758
 * @details A timer executes a callback when its time ran out and it fires.
759
 *
760
 * @param[in] params  Pointer to optional parameters for the callback function.
761
 *                    May be NULL.
762
 */
763
typedef void (*urt_osTimerCallback_t)(void* parameter);
764

    
765
#if defined(__cplusplus)
766
extern "C" {
767
#endif /* defined(__cplusplus) */
768

    
769
#if !defined(urtTimerInit) || defined(__DOXYGEN__)
770
  /**
771
   * @brief   Initialize a timer object.
772
   *
773
   * @param[in] timer   Pointer to the timer object to initialize.
774
   *                    Must not be NULL.
775
   */
776
  void urtTimerInit(urt_osTimer_t* timer);
777
#endif /* !defined(urtTimerInit) */
778

    
779
#if !defined(urtTimerSet) || defined(__DOXYGEN__)
780
  /**
781
   * @brief   Set a timer in single-shot mode.
782
   *
783
   * @param[in] timer     Pointer to the timer to be armed.
784
   *                      Must not be NULL.
785
   * @param[in] delay     Time after which the timer shall fire.
786
   * @param[in] callback  Pointer to the function to be called when the timer fires.
787
   *                      Must not be NULL.
788
   * @param[in] cbparams  Optional parameters for the callback function.
789
   *                      May be NULL.
790
   */
791
  void urtTimerSet(urt_osTimer_t* timer, urt_delay_t delay, urt_osTimerCallback_t callback, void* cbparams);
792
#endif /* !defined(urtTimerSet) */
793

    
794
#if !defined(urtTimerSetPeriodic) || defined(__DOXYGEN__)
795
  /**
796
   * @brief   Set a timer in periodic mode.
797
   *
798
   * @param[in] timer     Pointer to the timer to be armed.
799
   *                      Must not be NULL.
800
   * @param[in] period    Time after which the timer shall fire periodically.
801
   * @param[in] callback  Pointer to the function to be called each time the timer fires.
802
   *                      Must not be NULL.
803
   * @param[in] cbparams  Optional parameters for the callback function.
804
   *                      May be NULL.
805
   */
806
  void urtTimerSetPeriodic(urt_osTimer_t* timer, urt_delay_t period, urt_osTimerCallback_t callback, void* cbparams);
807
#endif /* !defined(urtTimerSetPeriodic) */
808

    
809
#if !defined(urtTimerReset) || defined(__DOXYGEN__)
810
  /**
811
   * @brief   Reset and disarm a timer.
812
   *
813
   * @param[in] timer   Pointer to the timer to be reset.
814
   *                    Must not be NULL.
815
   */
816
  void urtTimerReset(urt_osTimer_t* timer);
817
#endif /* !defined(urtTimerReset) */
818

    
819
#if !defined(urtTimerIsArmed) || defined(__DOXYGEN__)
820
  /**
821
   * @brief   Retrieve the current status of a timer.
822
   *
823
   * @param[in] timer   Pointer to the timer to inspect.
824
   *                    Must not be NULL.
825
   *
826
   * @return  Flag, indicating whether or not the timer is currently armed.
827
   */
828
  bool urtTimerIsArmed(urt_osTimer_t* timer);
829
#endif /* !defined(urtTimerIsArmed) */
830

    
831
#if defined(__cplusplus)
832
}
833
#endif /* defined(__cplusplus) */
834

    
835
#endif /* URT_OSAL_H */