Statistics
| Branch: | Revision:

urtware / doc / classdiagrams / osal.uml @ 6c5df8c1

History | View | Annotate | Download (12.4 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 measurement feature. '/
35
$group("time") {
36
  /' OS time type with arbitrary resolution. '/
37
  $type("urt_osTime_t") {
38
      'Converts an OS time to 64 bit microsecond precise value.
39
    + {method} urtTime2Us (t : urt_osTime_t*) : uint64_t
40
      'Retrieves the current time.
41
    + {method} urtTimeNow (void) : urt_osTime_t
42
      'Increase a system time object.
43
    + {method} urtTimeAddUs (time : urt_osTime_t*, offset : urt_delay_t) : void
44
  }
45
}
46

    
47
/' OS mutex lock feature. '/
48
$group("mutex") {
49
  /' OS mutex lock interface. '/
50
  $type("urt_osMutex_t") {
51
      'Initializes a urt_osMutex_t object.
52
    + {method} urtMutexInit (mutex : urt_osMutex_t*) : void
53
      'Block the thread until the mutex could be locked.
54
    + {method} urtMutexLock (mutex : urt_osMutex_t*) : void
55
      'Tries to lock the mutex, but does not block but immediately returns an indicator.
56
    + {method} urtMutexTryLock (mutex : urt_osMutex_t*) : bool
57
      'Unlocks a previously locked mutex.
58
    + {method} urtMutexUnlock (mutex : urt_osMutex_t*) : void
59
  }
60
}
61

    
62
/' OS condition variable feature. '/
63
$group("condition variable") {
64
  /' Return type for the wait function on condition variables. '/
65
  $enumeration("urt_osCondvarWaitStatus_t") {
66
      'The condition variable has been signaled.
67
    URT_CONDVAR_WAITSTATUS_SIGNAL = 1
68
      'The condition variable has been broadcasted.
69
    URT_CONDVAR_WAITSTATUS_BROADCAST = 2
70
      'The wait function timed out.
71
    URT_CONDVAR_WAITSTATUS_TIMEOUT = 0
72
  }
73

    
74
  /' Condition variable interface. '/
75
  $type("urt_osCondvar_t") {
76
      'Initializes a urt_osCondvar_t object.
77
    + {method} urtCondvarInit (condvar : urt_osCondvar_t*) : void
78
      'Signals one thread that is waiting for the condition variable.
79
    + {method} urtCondvarSignal (condvar : urt_osCondvar_t*) : void
80
      'Signals all threads that are waiting for the condition variable.
81
    + {method} urtCondvarBroadcast (condvar : urt_osCondvar_t*) : void
82
    .. URT_CFG_OSAL_CONDVAR_TIMEOUT == false ..
83
      'Waits for the condition variable.
84
    + {method} urtCondvarWait (condvar : urt_osCondvar_t*, mutex : urt_osMutex_t*) : urt_osCondvarWaitStatus_t
85
    .. URT_CFG_OSAL_CONDVAR_TIMEOUT == true ..
86
      'Waits for the condition variable with timeout.
87
    + {method} urtCondvarWait (condvar : urt_osCondvar_t*, mutex : urt_osMutex_t*, timeout : urt_delay_t) : urt_osCondvarWaitStatus_t
88
  }
89
}
90

    
91
/' OS timer feature. '/
92
$group("timer") {
93
  /' Timer callback definition. '/
94
  $type("urt_osTimerCallback_t") {
95
    urt_osTimerCallback_t (parameter : void*) : void
96
  }
97

    
98
  /' OS timer interface. '/
99
  $type("urt_osTimer_t") {
100
      'Initializes an urt_osTimer_t object.
101
    + {method} urtTimerInit (timer : urt_osTimer_t*) : void
102
      'Sets the timer to a specified delay with specified callback and arguments.
103
    + {method} urtTimerSet (timer : urt_osTimer_t*, delay : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : void
104
      'Sets the timer to a specified period with specified callback and arguments.
105
    + {method} urtTimerSetPeriodic (timer : urt_osTimer_t*, period : urt_delay_t, callback : urt_osTimerCallback_t*, parameter : void*) : void
106
      'Resets the timer.
107
    + {method} urtTimerReset (timer : urt_osTimer_t*) : void
108
      'Check whether the timer is already armed.
109
    + {method} urtTimerIsArmed (timer : urt_osTimer_t*) : bool
110
  }
111
} /'condition variable'/
112

    
113
/' OS thread feature. '/
114
$group("thread") {
115
  /' Thread priority type. '/
116
  $type("urt_osThreadPrio_t") {
117
      'Minimum priority for low priority threads.
118
    URT_THREAD_PRIO_LOW_MIN
119
      'Maximum priority for low priority threads.
120
    URT_THREAD_PRIO_LOW_MAX
121
      'Minimum priority for normal priority threads.
122
    URT_THREAD_PRIO_NORMAL_MIN
123
      'Maximum priority for normal priority threads.
124
    URT_THREAD_PRIO_NORMAL_MAX
125
      'Minimum priority for high priority threads.
126
    URT_THREAD_PRIO_HIGH_MIN
127
      'Maximum priority for high priority threads.
128
    URT_THREAD_PRIO_HIGH_MAX
129
      'Minimum priority for real-time threads.
130
    URT_THREAD_PRIO_RT_MIN
131
      'Maximum priority for real-time threads.
132
    URT_THREAD_PRIO_RT_MAX
133
  }
134

    
135
  /' Thread main function type. '/
136
  $type("urt_osThreadFunction_t") {
137
    urt_osThreadFunction_t (arg : void*) : void
138
  }
139

    
140
  /' Thread terminate signals. '/
141
  $enumeration("urt_osThreadTerminateSignal_t") {
142
      'Signal to request termination asap.
143
    URT_THREAD_TERMINATE_REQUEST = 15
144
      'Signal to kill a thread immediately.
145
    URT_THREAD_TERMINATE_KILL = 9
146
  }
147

    
148
  /' Thread execution states. '/
149
  $enumeration("urt_osThreadState_t") {
150
      'Thread has not been started yet.
151
    URT_THREAD_STATE_INACTIVE = 0
152
      'Thread is currently being executed.
153
    URT_THREAD_STATE_RUNNING = 1
154
      'Thread is ready but waiting to be scheduled.
155
    URT_THREAD_STATE_READY = 2
156
      'Thread is actively sleeping.
157
    URT_THREAD_STATE_SLEEPING = 3
158
      'Thread has ben suspended explicitely.
159
    URT_THREAD_STATE_SUSPENDED = 4
160
      'Thread is waiting for something (e.g. Mutex, event, etc.).
161
    URT_THREAD_STATE_WAITING = 5
162
      'Thread has terminated.
163
    URT_THREAD_STATE_TERMINATED = 6
164
  }
165

    
166
  /' OS thread interface. '/
167
  $type("urt_osThread_t") {
168
     'Maximum sleep interval in seconds (as float).
169
    URT_THREAD_SLEEP_MAX : float
170
      'Maximum sleep interval in seconds.
171
    URT_THREAD_SSLEP_MAX : unsigned int
172
      'Maximum sleep interval in milliseconds.
173
    URT_THREAD_MSLEEP_MAX : unsigned int
174
      'Maximum sleep interval in microseconds.
175
    URT_THREAD_USLEEP_MAX : urt_delay_t
176
    --
177
      'Macro to setup working area as static variable (handles alignment if required).
178
    + {method} URT_THREAD_MEMORY (varname, stacksize)
179
    ..
180
      'Initializes an urt_osThread_t object.
181
    + {method} urtThreadInit (memory : void*, size : size_t, prio : urt_osThreadPrio_t, func : urt_osThreadFunction_t*, arg : void*) : urt_osThread_t*
182
      'Starts a thread.
183
    + {method} urtThreadStart (thread : urt_osThread_t*) : void
184
      'The calling threads yields.
185
    + {method} urtThreadYield (void) : void
186
      'Retrieves the priority of the calling thread.
187
    + {method} urtThreadGetPriority (void) : urt_osThreadPrio_t
188
      'Sets the priority of the calling thread.
189
    + {method} urtThreadSetPriority (prio : urt_osThreadPrio_t) : void
190
      'Suspends the calling thread for the specified time.
191
    + {method} urtThreadSleep (seconds : float) : void
192
      'Suspends the calling thread for the specified time.
193
    + {method} urtThreadSSleep (seconds : unsigned int) : void
194
      'Suspends the calling thread for the specified time.
195
    + {method} urtThreadMSleep (milliseconds : unsigned int) : void
196
      'Suspends the calling thread for the specified time.
197
    + {method} urtThreadUSleep (microseconds : urt_delay_t) : void
198
      'Suspends the calling thread until the specified time.
199
    + {method} urtThreadSleepUntil (time : urt_osTime_t) : void
200
      'The calling thread exits execution (terminates).
201
    + {method} urtThreadExit (void) : void
202
      'Terminates a specified thread.
203
    + {method} urtThreadTerminate (thread : urt_osThread_t*, sig : urt_osThreadTerminateSignal_t) : void
204
      'Retrieves whether the calling thread has been requested to terminate.
205
    + {method} urtThreadShouldTerminate (void) : bool
206
      'Waits until the specified thread terminates.
207
    + {method} urtThreadJoin (thread : urt_osThread_t*) : void
208
      'Retrieves the execution state of the specified thread.
209
    + {method} urtThreadGetState (thread : urt_osThread_t*) : urt_osThreadState_t
210
      'Retrieves the calling thread itself.
211
    + {method} urtThreadGetSelf (void) : urt_osThread_t*
212
      'Retrieves the first child of a thread or ""NULL"".
213
    + urtThreadGetChildren (thread : urt_osThread_t*) : urt_osThread_t*
214
      'Retrieves a sibling (next child in a list) of the thread or ""NULL"".
215
    + urtThreadGetSibling (thread : urt_osThread_t*) : urt_osThread_t*
216
      'Retrieves the parent thread.
217
    + urtThreadGetParent (thread : urt_osThread_t*) : urt_osThread_t*
218
  }
219
} /'thread'/
220

    
221
/' OS event feature. '/
222
$group("events") {
223
  /' OS event mask type. '/
224
  $type("urt_osEventMask_t") {
225
      'The event mask, which will be handled with maximum priority by the event system.
226
    URT_EVENTMASK_MAXPRIO : urt_osEventMask_t
227
  }
228

    
229
  /' OS event flag type. '/
230
  $type("urt_osEventFlags_t") {
231
  }
232

    
233
  /' OS event wait type. '/
234
  $enumeration("urt_osEventWait_t") {
235
      'Wait for exactly one event.
236
    URT_EVENT_WAIT_ONE = 0
237
      'Wait for at least one event.
238
    URT_EVENT_WAIT_ANY = 1
239
      'Wait for all events.
240
    URT_EVENT_WAIT_ALL = 2
241
  }
242

    
243
  /' OS event listener interface. '/
244
  $type("urt_osEventListener_t") {
245
      'Initializes an urt_osEventListener_t object.
246
    + {method} urtEventListenerInit (listener : urt_osEventListener_t*) : void
247
      'Retrieves the flags of the event listener.
248
    + {method} urtEventListenerGetFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t
249
      'Retrieves and clears the flags of the event listener.
250
    + {method} urtEventListenerClearFlags (listener : urt_osEventListener_t*) : urt_osEventFlags_t
251
  }
252

    
253
  /' OS event source interface. '/
254
  $type("urt_osEventSource_t") {
255
      'Initializes an urt_osEventSource_t object.
256
    + {method} urtEventSourceInit (source : urt_osEventSource_t*) : void
257
      'Emits an event.
258
    + {method} urtEventSourceBroadcast (source : urt_osEventSource_t*, flags : urt_osEventFlags_t) : void
259
  }
260

    
261
  /' Not a class/type but a set of static event-related functions. '/
262
  $function("urt_events") {
263
      'Registers a lister to a source.
264
    + {method} urtEventRegister (source : urt_osEventSource_t*, listener : urt_osEventListener_t*, mask : urt_osEventMask_t, flags : urt_osEventFlags_t) : void
265
      'Unregisters a listener from a source.
266
    + {method} urtEventUnregister (source _ urt_osEventSource_t*, listener : urt_osEventListener_t*) : void
267
      'Blocks the thread until any event occurs or the timeout expires.
268
    + {method} urtEventWait (mask : urt_osEventMask_t, type : urt_osEventWait_t, timeout : urt_delay_t) : urt_osEventMask_t
269
  }
270
} /'events'/
271

    
272
/' OS streams feature. '/
273
$group("streams") {
274
  /' Not a class/type but a set of output-related functions. '/
275
  $function("urt_streams") {
276
      'Prints a formatted string to the standard output stream (stdout).
277
    + {method} urtPrintf (fmt : char*, ... ) : int
278
      'Prints a formatted string to the standard error stream (stderr).
279
    + {method} urtErrPrintf (fmt : char*, ... ) : int
280
  }
281
}
282

    
283
/' OS debugging feature. '/
284
$group("debug") {
285
  /' Just a function for debugging. '/
286
  $function("urt_debug") {
287
      'Checks the condition in debug mode.
288
    + {method} urtDebugAssert (condition : bool) : void
289
  }
290
}
291

    
292
!endsub
293

    
294
/'### DEPENDENCIES & LAYOUT ##################################################'/
295

    
296
!startsub DEPENDENCIES
297

    
298
urt_osCondvar_t ..> urt_osCondvarWaitStatus_t
299
urt_osCondvar_t .> urt_osMutex_t
300

    
301
urt_osTimer_t ..> urt_osTimerCallback_t
302

    
303
urt_osThread_t ..> urt_osThreadPrio_t
304
urt_osThread_t ..> urt_osThreadFunction_t
305
urt_osThread_t ..> urt_osThreadTerminateSignal_t
306
urt_osThread_t ..> urt_osThreadState_t
307
urt_osThread_t .> urt_osTime_t
308

    
309
urt_osEventListener_t ..> urt_osEventFlags_t
310
urt_osEventSource_t ..> urt_osEventFlags_t
311
urt_events ..> urt_osEventSource_t
312
urt_events ..> urt_osEventListener_t
313
urt_events ..> urt_osEventMask_t
314
urt_events ..> urt_osEventFlags_t
315
urt_events ..> urt_osEventWait_t
316

    
317
!endsub
318

    
319
/'### OUTRO ##################################################################'/
320

    
321
@enduml
322