Statistics
| Branch: | Revision:

urtware / doc / classdiagrams / osal.uml @ 056e40d2

History | View | Annotate | Download (11.5 KB)

1 4d55cea4 Thomas Schöpping
/'
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