/' µRtWare is a lightweight publish/subscribe middleware for real-time applications. It was developed as part of the software habitat for the Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well. Copyright (C) 2018..2020 Thomas Schöpping et al. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . '/ /'### INTRO ##################################################################'/ @startuml title **µRtWare**\nOperating System Abstraction Layer (OSAL) !include ../functions.iuml /'### ENTITIES ###############################################################'/ !startsub ENTITIES /' OS time type with arbitrary resolution. '/ $type("urt_osTime_t") { 'Converts an OS time to 64 bit microsecond precise value. + {method} urtTime2Us (t : urt_osTime_t*) : uint64_t 'Retrieves the current time. + {method} urtTimeNow (void) : urt_osTime_t 'Increase a system time object. + {method} urtTimeAddUs (time : urt_osTime_t*, offset : uint32_t) : urt_osTime_t* } /' OS mutex lock interface. '/ $type("urt_osMutex_t") { 'Initializes a urt_osMutex_t object. + {method} urtMutexInit (mutex : urt_osMutex_t*) : void 'Block the thread until the mutex could be locked. + {method} urtMutexLock (mutex : urt_osMutex_t*) : void 'Tries to lock the mutex, but does not block but immediately returns an indicator. + {method} urtMutexTryLock (mutex : urt_osMutex_t*) : bool 'Unlocks a previously locked mutex. + {method} urtMutexUnlock (mutex : urt_osMutex_t*) : void } /' OS condition variable feature. '/ $group("condition variable") { /' Return type for the wait function on condition variables. '/ $enumeration("urt_osCondvarWaitStatus_t") { 'The condition variable has been signaled. URT_CONDVAR_WAITSTATUS_SIGNAL = 1 'The condition variable has been broadcasted. URT_CONDVAR_WAITSTATUS_BROADCAST = 2 'The wait function timed out. URT_CONDVAR_WAITSTATUS_TIMEOUT = 0 } /' Condition variable interface. '/ $type("urt_osCondvar_t") { 'Initializes a urt_osCondvar_t object. + {method} urtCondvarInit (condvar : urt_osCondvar_t*) : void 'Signals one thread that is waiting for the condition variable. + {method} urtCondvarSignal (condvar : urt_osCondvar_t*) : void 'Signals all threads that are waiting for the condition variable. + {method} urtCondvarBroadcast (condvar : urt_osCondvar_t*) : void 'Waits for the condition variable. + {method} urtCondvarWait (condvar : urt_osCondvar_t*, mutex : urt_osMutex_t*, timeout : urt_delay_t) : urt_osCondvarWaitStatus_t } } /' OS timer feature. '/ $group("timer") { /' Timer callback definition. '/ $type("urt_osTimerCallback_t") { urt_osTimerCallback_t (parameter : void*) : void } /' OS timer interface. '/ $type("urt_osTimer_t") { 'Initializes an urt_osTimer_t object. + {method} urtTimerInit (timer : urt_osTimer_t*) : void 'Sets the timer to a specified delay with specified callback and arguments. + {method} urtTimerSet (timer : urt_osTimer_t*, delay : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : urt_status_t 'Sets the timer to a specified period with specified callback and arguments. + {method} urtTimerSetPeriodic (timer : urt_osTimer_t*, period : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : urt_status_t 'Resets the timer. + {method} urtTimerReset (timer : urt_osTimer_t*) : urt_status_t 'Check whether the timer is already armed. + {method} urtTimerIsArmed (timer : urt_osTimer_t*) : bool } } /'condition variable'/ /' OS thread feature. '/ $group("thread") { /' Thread priority type. '/ $type("urt_osThreadPrio_t") { 'Minimum priority for low priority threads. URT_THREAD_PRIO_LOW_MIN 'Maximum priority for low priority threads. URT_THREAD_PRIO_LOW_MAX 'Minimum priority for normal priority threads. URT_THREAD_PRIO_NORMAL_MIN 'Maximum priority for normal priority threads. URT_THREAD_PRIO_NORMAL_MAX 'Minimum priority for high priority threads. URT_THREAD_PRIO_HIGH_MIN 'Maximum priority for high priority threads. URT_THREAD_PRIO_HIGH_MAX 'Minimum priority for real-time threads. URT_THREAD_PRIO_RT_MIN 'Maximum priority for real-time threads. URT_THREAD_PRIO_RT_MAX } /' Thread main function type. '/ $type("urt_osThreadFunction_t") { urt_osThreadFunction_t (arg : void*) : void } /' Thread terminate signals. '/ $enumeration("urt_osThreadTerminateSignal_t") { 'Signal to request termination asap. URT_THREAD_TERMINATE_REQUEST = 15 'Signal to kill a thread immediately. URT_THREAD_TERMINATE_KILL = 9 } /' Thread execution states. '/ $enumeration("urt_osThreadState_t") { 'Thread has not been started yet. URT_THREAD_STATE_INACTIVE = 0 'Thread is currently being executed. URT_THREAD_STATE_RUNNING = 1 'Thread is ready but waiting to be scheduled. URT_THREAD_STATE_READY = 2 'Thread is actively sleeping. URT_THREAD_STATE_SLEEPING = 3 'Thread has ben suspended explicitely. URT_THREAD_STATE_SUSPENDED = 4 'Thread is waiting for something (e.g. Mutex, event, etc.). URT_THREAD_STATE_WAITING = 5 'Thread has terminated. URT_THREAD_STATE_TERMINATED = 6 } /' OS thread interface. '/ $type("urt_osThread_t") { 'Maximum sleep interval in seconds (as float). URT_THREAD_SLEEP_MAX : float 'Maximum sleep interval in seconds. URT_THREAD_SSLEP_MAX : urt_delay_t 'Maximum sleep interval in milliseconds. URT_THREAD_MSLEEP_MAX : urt_delay_t 'Maximum sleep interval in microseconds. URT_THREAD_USLEEP_MAX : urt_delay_t -- 'Macro to setup working area as static variable (handles alignment if required). + {method} URT_THREAD_MEMORY (varname, stacksize) .. 'Initializes an urt_osThread_t object. + {method} urtThreadInit (memory : void*, size : size_t, func : urt_osThreadFunction_t*) : urt_osThread_t* 'Starts a thread. + {method} urtThreadStart (thread : urt_osThread_t*, prio : urt_osThreadPrio_t, arg : void*) : void 'The calling threads yields. + {method} urtThreadYield (void) : void 'Retrieves the priority of the calling thread. + {method} urtThreadGetPriority (void) : urt_osThreadPrio_t 'Sets the priority of the calling thread. + {method} urtThreadSetPriority (prio : urt_osThreadPrio_t) : void 'Suspends a thread so it will no longer be executed. + {method} urtThreadSuspend (thread : urt_osThread_t*) : void 'Wakes a suspended thread. + {method} urtThreadResume (thread : urt_osThread_t*) : urt_status_t 'Suspends the calling thread for the specified time. + {method} urtThreadSleep (seconds : float) : void 'Suspends the calling thread for the specified time. + {method} urtThreadSSleep (seconds : urt_delay_t) : void 'Suspends the calling thread for the specified time. + {method} urtThreadMSleep (milliseconds : urt_delay_t) : void 'Suspends the calling thread for the specified time. + {method} urtThreadUSleep (microseconds : urt_delay_t) : void 'Suspends the calling thread until the specified time. + {method} urtThreadSleepUntil (time : urt_osTime_t) : void 'The calling thread exits execution (terminates). + {method} urtThreadExit (void) : void 'Terminates a specified thread. + {method} urtThreadTerminate (thread : urt_osThread_t*, sig : urt_osThreadTerminateSignal_t) : void 'Waits until the specified thread terminates. + {method} urtThreadJoin (thread : urt_osThread_t*) : void 'Retrieves the execution state of the specified thread. + {method} urtThreadGetState (thread : urt_osThread_t*) : urt_osThreadState_t 'Retrieves the calling thread itself. + {method} urtThreadGetSelf (void) : urt_osThread_t* } } /'thread'/ /' OS event feature. '/ $group("events") { /' OS event mask type. '/ $type("urt_osEventMask_t") { 'The event mask, which will be handled with maximum priority by the event system. URT_EVENTMASK_MAXPRIO : urt_osEventMask_t } /' OS event flag type. '/ $type("urt_osEventFlags_t") { } /' OS event wait type. '/ $enumeration("urt_osEventWait_t") { 'Wait for exactly one event. URT_EVENT_WAIT_ONE = 0 'Wait for at least one event. URT_EVENT_WAIT_ANY = 1 'Wait for all events. URT_EVENT_WAIT_ALL = 2 } /' OS event listener interface. '/ $type("urt_osEventListener_t") { 'Initializes an urt_osEventListener_t object. + {method} urtEventListenerInit (listener : urt_osEventListener_t*) : void 'Retrieves the flags of the event listener. + {method} urtEventListenerGetFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t 'Retrieves and clears the flags of the event listener. + {method} urtEventListenerClearFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t } /' OS event source interface. '/ $type("urt_osEventSource_t") { 'Initializes an urt_osEventSource_t object. + {method} urtEventSourceInit (source : urt_osEventSource_t*) : void 'Emits an event. + {method} urtEventSourceBroadcast (source : urt_osEventSource_t*, flags : urt_osEventFlags_t) : void } /' Not a class/type but a set of static event-related functions. '/ $function("urt_events") { 'Registers a lister to a source. + {method} urtEventRegister (source : urt_osEventSource_t*, listener : urt_osEventListener_t*, mask : urt_osEventMask_t, flags : urt_osEventFlags_t) : urt_status_t 'Unregisters a listener from a source. + {method} urtEventUnregister (source _ urt_osEventSource_t*, listener : urt_osEventListener_t*) : urt_status_t 'Blocks the thread until any event occurs or the timeout expires. + {method} urtEventWait (mask : urt_osEventMask_t, type : urt_osEventWait_t, timeout : urt_delay_t) : urt_osEventMask_t } } /'events'/ /' Not a class/type but a set of output-related functions. '/ $function("urt_streams") { 'Prints a formatted string to the standard output stream (stdout). + {method} urtPrintf(fmt : char*, ... ) : int 'Prints a formatted string to the standard error stream (stderr). + {method} urtErrPrintf(fmt : char*, ... ) : int } !endsub /'### DEPENDENCIES & LAYOUT ##################################################'/ !startsub DEPENDENCIES urt_osCondvar_t ..> urt_osCondvarWaitStatus_t urt_osCondvar_t .> urt_osMutex_t urt_osTimer_t ..> urt_osTimerCallback_t urt_osThread_t ..> urt_osThreadPrio_t urt_osThread_t ..> urt_osThreadFunction_t urt_osThread_t ..> urt_osThreadTerminateSignal_t urt_osThread_t ..> urt_osThreadState_t urt_osThread_t .> urt_osTime_t urt_osEventListener_t ..> urt_osEventFlags_t urt_osEventSource_t ..> urt_osEventFlags_t urt_events ..> urt_osEventSource_t urt_events ..> urt_osEventListener_t urt_events ..> urt_osEventMask_t urt_events ..> urt_osEventFlags_t urt_events ..> urt_osEventWait_t !endsub /'### OUTRO ##################################################################'/ @enduml