Statistics
| Branch: | Revision:

urtware / urt_osal.h @ 46471486

History | View | Annotate | Download (28.9 KB)

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

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

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

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

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

    
22
#ifndef URT_OSAL_H
23
#define URT_OSAL_H
24

    
25
#include <urtware.h>
26

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

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

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

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

    
47
#include <stdint.h>
48

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
206
#if defined(__cplusplus)
207
}
208
#endif /* defined(__cplusplus) */
209

    
210
/*============================================================================*/
211
/* EVENTS                                                                     */
212
/*============================================================================*/
213

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

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

    
248
#if defined(__cplusplus)
249
extern "C" {
250
#endif /* defined(__cplusplus) */
251

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

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

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

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

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

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

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

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

    
347
#if defined(__cplusplus)
348
}
349
#endif /* defined(__cplusplus) */
350

    
351
/*============================================================================*/
352
/* STREAMS                                                                    */
353
/*============================================================================*/
354

    
355
#if defined(__cplusplus)
356
extern "C" {
357
#endif /* defined(__cplusplus) */
358

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

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

    
381
#if defined(__cplusplus)
382
}
383
#endif /* defined(__cplusplus) */
384

    
385
/*============================================================================*/
386
/* TIME                                                                       */
387
/*============================================================================*/
388

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

    
398
#if defined(__cplusplus)
399
extern "C" {
400
#endif /* defined(__cplusplus) */
401

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

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

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

    
434
#if defined(__cplusplus)
435
}
436
#endif /* defined(__cplusplus) */
437

    
438
/*============================================================================*/
439
/* THREAD                                                                     */
440
/*============================================================================*/
441

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

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

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

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

    
544
#if defined(__cplusplus)
545
extern "C" {
546
#endif /* defined(__cplusplus) */
547

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
738
#if defined(__cplusplus)
739
}
740
#endif /* defined(__cplusplus) */
741

    
742
/*============================================================================*/
743
/* TIMER                                                                      */
744
/*============================================================================*/
745

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

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

    
763
#if defined(__cplusplus)
764
extern "C" {
765
#endif /* defined(__cplusplus) */
766

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

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

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

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

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

    
829
#if defined(__cplusplus)
830
}
831
#endif /* defined(__cplusplus) */
832

    
833
#endif /* URT_OSAL_H */