urtware / doc / classdiagrams / osal.uml @ 056e40d2
History | View | Annotate | Download (11.5 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 |
/'### INTRO ##################################################################'/ |
23 |
|
24 |
@startuml |
25 |
|
26 |
title **µRtWare**\nOperating System Abstraction Layer (OSAL) |
27 |
|
28 |
!include ../functions.iuml |
29 |
|
30 |
/'### ENTITIES ###############################################################'/ |
31 |
|
32 |
!startsub ENTITIES |
33 |
|
34 |
/' OS time type with arbitrary resolution. '/ |
35 |
$type("urt_osTime_t") { |
36 |
'Converts an OS time to 64 bit microsecond precise value. |
37 |
+ {method} urtTime2Us (t : urt_osTime_t*) : uint64_t |
38 |
'Retrieves the current time. |
39 |
+ {method} urtTimeNow (void) : urt_osTime_t |
40 |
'Increase a system time object. |
41 |
+ {method} urtTimeAddUs (time : urt_osTime_t*, offset : uint32_t) : urt_osTime_t* |
42 |
} |
43 |
|
44 |
/' OS mutex lock interface. '/ |
45 |
$type("urt_osMutex_t") { |
46 |
'Initializes a urt_osMutex_t object. |
47 |
+ {method} urtMutexInit (mutex : urt_osMutex_t*) : void |
48 |
'Block the thread until the mutex could be locked. |
49 |
+ {method} urtMutexLock (mutex : urt_osMutex_t*) : void |
50 |
'Tries to lock the mutex, but does not block but immediately returns an indicator. |
51 |
+ {method} urtMutexTryLock (mutex : urt_osMutex_t*) : bool |
52 |
'Unlocks a previously locked mutex. |
53 |
+ {method} urtMutexUnlock (mutex : urt_osMutex_t*) : void |
54 |
} |
55 |
|
56 |
/' OS condition variable feature. '/ |
57 |
$group("condition variable") { |
58 |
/' Return type for the wait function on condition variables. '/ |
59 |
$enumeration("urt_osCondvarWaitStatus_t") { |
60 |
'The condition variable has been signaled. |
61 |
URT_CONDVAR_WAITSTATUS_SIGNAL = 1 |
62 |
'The condition variable has been broadcasted. |
63 |
URT_CONDVAR_WAITSTATUS_BROADCAST = 2 |
64 |
'The wait function timed out. |
65 |
URT_CONDVAR_WAITSTATUS_TIMEOUT = 0 |
66 |
} |
67 |
|
68 |
/' Condition variable interface. '/ |
69 |
$type("urt_osCondvar_t") { |
70 |
'Initializes a urt_osCondvar_t object. |
71 |
+ {method} urtCondvarInit (condvar : urt_osCondvar_t*) : void |
72 |
'Signals one thread that is waiting for the condition variable. |
73 |
+ {method} urtCondvarSignal (condvar : urt_osCondvar_t*) : void |
74 |
'Signals all threads that are waiting for the condition variable. |
75 |
+ {method} urtCondvarBroadcast (condvar : urt_osCondvar_t*) : void |
76 |
'Waits for the condition variable. |
77 |
+ {method} urtCondvarWait (condvar : urt_osCondvar_t*, mutex : urt_osMutex_t*, timeout : urt_delay_t) : urt_osCondvarWaitStatus_t |
78 |
} |
79 |
} |
80 |
|
81 |
/' OS timer feature. '/ |
82 |
$group("timer") { |
83 |
/' Timer callback definition. '/ |
84 |
$type("urt_osTimerCallback_t") { |
85 |
urt_osTimerCallback_t (parameter : void*) : void |
86 |
} |
87 |
|
88 |
/' OS timer interface. '/ |
89 |
$type("urt_osTimer_t") { |
90 |
'Initializes an urt_osTimer_t object. |
91 |
+ {method} urtTimerInit (timer : urt_osTimer_t*) : void |
92 |
'Sets the timer to a specified delay with specified callback and arguments. |
93 |
+ {method} urtTimerSet (timer : urt_osTimer_t*, delay : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : urt_status_t |
94 |
'Sets the timer to a specified period with specified callback and arguments. |
95 |
+ {method} urtTimerSetPeriodic (timer : urt_osTimer_t*, period : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : urt_status_t |
96 |
'Resets the timer. |
97 |
+ {method} urtTimerReset (timer : urt_osTimer_t*) : urt_status_t |
98 |
'Check whether the timer is already armed. |
99 |
+ {method} urtTimerIsArmed (timer : urt_osTimer_t*) : bool |
100 |
} |
101 |
} /'condition variable'/ |
102 |
|
103 |
/' OS thread feature. '/ |
104 |
$group("thread") { |
105 |
/' Thread priority type. '/ |
106 |
$type("urt_osThreadPrio_t") { |
107 |
'Minimum priority for low priority threads. |
108 |
URT_THREAD_PRIO_LOW_MIN |
109 |
'Maximum priority for low priority threads. |
110 |
URT_THREAD_PRIO_LOW_MAX |
111 |
'Minimum priority for normal priority threads. |
112 |
URT_THREAD_PRIO_NORMAL_MIN |
113 |
'Maximum priority for normal priority threads. |
114 |
URT_THREAD_PRIO_NORMAL_MAX |
115 |
'Minimum priority for high priority threads. |
116 |
URT_THREAD_PRIO_HIGH_MIN |
117 |
'Maximum priority for high priority threads. |
118 |
URT_THREAD_PRIO_HIGH_MAX |
119 |
'Minimum priority for real-time threads. |
120 |
URT_THREAD_PRIO_RT_MIN |
121 |
'Maximum priority for real-time threads. |
122 |
URT_THREAD_PRIO_RT_MAX |
123 |
} |
124 |
|
125 |
/' Thread main function type. '/ |
126 |
$type("urt_osThreadFunction_t") { |
127 |
urt_osThreadFunction_t (arg : void*) : void |
128 |
} |
129 |
|
130 |
/' Thread terminate signals. '/ |
131 |
$enumeration("urt_osThreadTerminateSignal_t") { |
132 |
'Signal to request termination asap. |
133 |
URT_THREAD_TERMINATE_REQUEST = 15 |
134 |
'Signal to kill a thread immediately. |
135 |
URT_THREAD_TERMINATE_KILL = 9 |
136 |
} |
137 |
|
138 |
/' Thread execution states. '/ |
139 |
$enumeration("urt_osThreadState_t") { |
140 |
'Thread has not been started yet. |
141 |
URT_THREAD_STATE_INACTIVE = 0 |
142 |
'Thread is currently being executed. |
143 |
URT_THREAD_STATE_RUNNING = 1 |
144 |
'Thread is ready but waiting to be scheduled. |
145 |
URT_THREAD_STATE_READY = 2 |
146 |
'Thread is actively sleeping. |
147 |
URT_THREAD_STATE_SLEEPING = 3 |
148 |
'Thread has ben suspended explicitely. |
149 |
URT_THREAD_STATE_SUSPENDED = 4 |
150 |
'Thread is waiting for something (e.g. Mutex, event, etc.). |
151 |
URT_THREAD_STATE_WAITING = 5 |
152 |
'Thread has terminated. |
153 |
URT_THREAD_STATE_TERMINATED = 6 |
154 |
} |
155 |
|
156 |
/' OS thread interface. '/ |
157 |
$type("urt_osThread_t") { |
158 |
'Maximum sleep interval in seconds (as float). |
159 |
URT_THREAD_SLEEP_MAX : float |
160 |
'Maximum sleep interval in seconds. |
161 |
URT_THREAD_SSLEP_MAX : urt_delay_t |
162 |
'Maximum sleep interval in milliseconds. |
163 |
URT_THREAD_MSLEEP_MAX : urt_delay_t |
164 |
'Maximum sleep interval in microseconds. |
165 |
URT_THREAD_USLEEP_MAX : urt_delay_t |
166 |
-- |
167 |
'Macro to setup working area as static variable (handles alignment if required). |
168 |
+ {method} URT_THREAD_MEMORY (varname, stacksize) |
169 |
.. |
170 |
'Initializes an urt_osThread_t object. |
171 |
+ {method} urtThreadInit (memory : void*, size : size_t, func : urt_osThreadFunction_t*) : urt_osThread_t* |
172 |
'Starts a thread. |
173 |
+ {method} urtThreadStart (thread : urt_osThread_t*, prio : urt_osThreadPrio_t, arg : void*) : void |
174 |
'The calling threads yields. |
175 |
+ {method} urtThreadYield (void) : void |
176 |
'Retrieves the priority of the calling thread. |
177 |
+ {method} urtThreadGetPriority (void) : urt_osThreadPrio_t |
178 |
'Sets the priority of the calling thread. |
179 |
+ {method} urtThreadSetPriority (prio : urt_osThreadPrio_t) : void |
180 |
'Suspends a thread so it will no longer be executed. |
181 |
+ {method} urtThreadSuspend (thread : urt_osThread_t*) : void |
182 |
'Wakes a suspended thread. |
183 |
+ {method} urtThreadResume (thread : urt_osThread_t*) : urt_status_t |
184 |
'Suspends the calling thread for the specified time. |
185 |
+ {method} urtThreadSleep (seconds : float) : void |
186 |
'Suspends the calling thread for the specified time. |
187 |
+ {method} urtThreadSSleep (seconds : urt_delay_t) : void |
188 |
'Suspends the calling thread for the specified time. |
189 |
+ {method} urtThreadMSleep (milliseconds : urt_delay_t) : void |
190 |
'Suspends the calling thread for the specified time. |
191 |
+ {method} urtThreadUSleep (microseconds : urt_delay_t) : void |
192 |
'Suspends the calling thread until the specified time. |
193 |
+ {method} urtThreadSleepUntil (time : urt_osTime_t) : void |
194 |
'The calling thread exits execution (terminates). |
195 |
+ {method} urtThreadExit (void) : void |
196 |
'Terminates a specified thread. |
197 |
+ {method} urtThreadTerminate (thread : urt_osThread_t*, sig : urt_osThreadTerminateSignal_t) : void |
198 |
'Waits until the specified thread terminates. |
199 |
+ {method} urtThreadJoin (thread : urt_osThread_t*) : void |
200 |
'Retrieves the execution state of the specified thread. |
201 |
+ {method} urtThreadGetState (thread : urt_osThread_t*) : urt_osThreadState_t |
202 |
'Retrieves the calling thread itself. |
203 |
+ {method} urtThreadGetSelf (void) : urt_osThread_t* |
204 |
} |
205 |
} /'thread'/ |
206 |
|
207 |
/' OS event feature. '/ |
208 |
$group("events") { |
209 |
/' OS event mask type. '/ |
210 |
$type("urt_osEventMask_t") { |
211 |
'The event mask, which will be handled with maximum priority by the event system. |
212 |
URT_EVENTMASK_MAXPRIO : urt_osEventMask_t |
213 |
} |
214 |
|
215 |
/' OS event flag type. '/ |
216 |
$type("urt_osEventFlags_t") { |
217 |
} |
218 |
|
219 |
/' OS event wait type. '/ |
220 |
$enumeration("urt_osEventWait_t") { |
221 |
'Wait for exactly one event. |
222 |
URT_EVENT_WAIT_ONE = 0 |
223 |
'Wait for at least one event. |
224 |
URT_EVENT_WAIT_ANY = 1 |
225 |
'Wait for all events. |
226 |
URT_EVENT_WAIT_ALL = 2 |
227 |
} |
228 |
|
229 |
/' OS event listener interface. '/ |
230 |
$type("urt_osEventListener_t") { |
231 |
'Initializes an urt_osEventListener_t object. |
232 |
+ {method} urtEventListenerInit (listener : urt_osEventListener_t*) : void |
233 |
'Retrieves the flags of the event listener. |
234 |
+ {method} urtEventListenerGetFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t |
235 |
'Retrieves and clears the flags of the event listener. |
236 |
+ {method} urtEventListenerClearFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t |
237 |
} |
238 |
|
239 |
/' OS event source interface. '/ |
240 |
$type("urt_osEventSource_t") { |
241 |
'Initializes an urt_osEventSource_t object. |
242 |
+ {method} urtEventSourceInit (source : urt_osEventSource_t*) : void |
243 |
'Emits an event. |
244 |
+ {method} urtEventSourceBroadcast (source : urt_osEventSource_t*, flags : urt_osEventFlags_t) : void |
245 |
} |
246 |
|
247 |
/' Not a class/type but a set of static event-related functions. '/ |
248 |
$function("urt_events") { |
249 |
'Registers a lister to a source. |
250 |
+ {method} urtEventRegister (source : urt_osEventSource_t*, listener : urt_osEventListener_t*, mask : urt_osEventMask_t, flags : urt_osEventFlags_t) : urt_status_t |
251 |
'Unregisters a listener from a source. |
252 |
+ {method} urtEventUnregister (source _ urt_osEventSource_t*, listener : urt_osEventListener_t*) : urt_status_t |
253 |
'Blocks the thread until any event occurs or the timeout expires. |
254 |
+ {method} urtEventWait (mask : urt_osEventMask_t, type : urt_osEventWait_t, timeout : urt_delay_t) : urt_osEventMask_t |
255 |
} |
256 |
} /'events'/ |
257 |
|
258 |
/' Not a class/type but a set of output-related functions. '/ |
259 |
$function("urt_streams") { |
260 |
'Prints a formatted string to the standard output stream (stdout). |
261 |
+ {method} urtPrintf(fmt : char*, ... ) : int |
262 |
'Prints a formatted string to the standard error stream (stderr). |
263 |
+ {method} urtErrPrintf(fmt : char*, ... ) : int |
264 |
} |
265 |
|
266 |
!endsub |
267 |
|
268 |
/'### DEPENDENCIES & LAYOUT ##################################################'/ |
269 |
|
270 |
!startsub DEPENDENCIES |
271 |
|
272 |
urt_osCondvar_t ..> urt_osCondvarWaitStatus_t |
273 |
urt_osCondvar_t .> urt_osMutex_t |
274 |
|
275 |
urt_osTimer_t ..> urt_osTimerCallback_t |
276 |
|
277 |
urt_osThread_t ..> urt_osThreadPrio_t |
278 |
urt_osThread_t ..> urt_osThreadFunction_t |
279 |
urt_osThread_t ..> urt_osThreadTerminateSignal_t |
280 |
urt_osThread_t ..> urt_osThreadState_t |
281 |
urt_osThread_t .> urt_osTime_t |
282 |
|
283 |
urt_osEventListener_t ..> urt_osEventFlags_t |
284 |
urt_osEventSource_t ..> urt_osEventFlags_t |
285 |
urt_events ..> urt_osEventSource_t |
286 |
urt_events ..> urt_osEventListener_t |
287 |
urt_events ..> urt_osEventMask_t |
288 |
urt_events ..> urt_osEventFlags_t |
289 |
urt_events ..> urt_osEventWait_t |
290 |
|
291 |
!endsub |
292 |
|
293 |
/'### OUTRO ##################################################################'/ |
294 |
|
295 |
@enduml |
296 |
|