RTI Connext DDS Micro
Version 2.4.8
Main Page
Related Pages
Manuals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
osapi_porting.h
Go to the documentation of this file.
1
/*
2
* FILE: osapi_porting.h - Porting Guide
3
*
4
* Copyright 2012-2015 Real-Time Innovations, Inc.
5
*
6
* No duplications, whole or partial, manual or electronic, may be made
7
* without express written permission. Any such copies, or
8
* revisions thereof, must display this notice unaltered.
9
* This code contains trade secrets of Real-Time Innovations, Inc.
10
*
11
* Modification History
12
* --------------------
13
* 22mar14,tk Written
14
* 12mar12,tk Written
15
*/
16
#ifndef osapi_porting_h
17
#define osapi_porting_h
18
19
/*e \file
20
* \brief Porting Guide
21
*/
22
/*e \addtogroup OSAPIUserManuals_PortingModule
23
*/
24
25
/*e \defgroup OSAPIPortingIntroClass Introduction
26
\ingroup OSAPIUserManuals_PortingModule
27
28
\details
29
30
\rtime has been engineered for reasonable portability to platforms and
31
environments which RTI does not have access to. This porting
32
guide describes the features required by \rtime to run.
33
34
The source tree shipped with \rtime is identical to the development tree
35
used by RTI. However, the internal file structure has been modified to
36
make it easier to import and compile the source as part of a project.
37
38
\rtime uses an abstraction layer to support running on a number
39
of platforms. The abstraction layer, OSAPI, is an abstraction of
40
functionality typically found in one or more of the following
41
libraries and services:
42
43
<ul>
44
<li> Operating System calls
45
<li> Device drivers
46
<li> Standard C library
47
</ul>
48
49
The OSAPI module is designed to be relatively easy to move to a new
50
platform. All functionality, with the exception of NETIO (which must be
51
ported) is contained within this single module, even though the functionality
52
typically spans different libraries. It should be noted that although
53
some functions may not seem relevant on a particular platform, they must
54
still be implemented, as they are used by other modules. For example,
55
the port running on Stellaris with no OS support still needs to implement
56
a threading model.
57
58
Please note that the OSAPI module is not designed to be a general purpose
59
abstraction layer; its sole purpose is to support the execution of \rtime.
60
61
Before porting the OSAPI module, you are expected to be familiar with
62
general OS concepts, the standard C library, and embedded systems. This
63
guide covers the following topics:
64
65
<ul>
66
<li> \ref OSAPIPortingConfigClass
67
<li> \ref OSAPIModuleHeap
68
<li> \ref OSAPIPortingMutexClass
69
<li> \ref OSAPIPortingSemaphoreClass
70
<li> \ref OSAPIPortingProcessClass
71
<li> \ref OSAPIPortingSystemClass
72
<li> \ref OSAPIPortingThreadClass
73
</ul>
74
75
The directory structure for the OS API module is as follows:
76
77
<ul>
78
<li> include/osapi/
79
<li> srcC/osapi/common/
80
<ul>
81
<li>/<platform>/<file>.c
82
</ul>
83
</ul>
84
85
The 'include' directory contains the external interfaces, those that are
86
assumed by other modules. The only files that may need modification in the
87
include directory are files ending in _impl.h and config.h.
88
89
The srcC directory contains a sub-directory `common` which contains source
90
code that is independent of any specific OS, but depends on functions
91
implemented by exactly one of the other sub-modules, such as posix or
92
windows.
93
94
NOTE: It is <em> not </em> recommended to modify source files shipped with
95
\rtime. Instead if it is desired to start with code supplied by RTI
96
it is recommended to <em> copy </em> the corresponding sub-directory,
97
for example posix, and rename it. This way it is easier to upgrade \rtime
98
while keeping existing ports.
99
*/
100
101
/*e \defgroup OSAPIPortingConfigClass Configuration files
102
\ingroup OSAPIUserManuals_PortingModule
103
104
The include/osapi/osapi_config.h file contains platform-specific settings
105
used by OSAPI and other modules. A new platform needs its settings defined
106
there. Please refer to the existing file for details.
107
108
It should be noted that \rtime does not currently use auto-detection
109
programs to detect the host and target build environment. \rtime relies
110
on predefined macros to determine the target environment. If \rtime
111
cannot determine the target environment it is necessary to manually
112
configure the target environment in osapi_config.
113
*/
114
115
/*e \defgroup OSAPIModuleHeap Heap Porting Guide
116
* \ingroup OSAPIUserManuals_PortingModule
117
*
118
* \details
119
*
120
* \rtime uses the heap to allocate memory for internal data-structures. With
121
* a few exceptions, \rtime does _not_ return memory to the heap. Instead,
122
* \rtime uses internal pools to quickly allocate and free memory for specific
123
* types. Only the initial memory is allocated directly from the heap.
124
* The following functions must be ported:
125
*
126
* <ul>
127
* <li> \ref OSAPI_Heap_allocate
128
* <li> \ref OSAPI_Heap_free
129
* </ul>
130
*
131
* Please refer to the \ref OSAPI_HeapClass API for definition of the behavior.
132
* The available source code contains implementation in the file:
133
*
134
* srcC/osapi/<platform>/Heap.c
135
*
136
*/
137
138
/*e \defgroup OSAPIPortingMutexClass Mutex Porting Guide
139
* \ingroup OSAPIUserManuals_PortingModule
140
*
141
* \details
142
*
143
* \rtime relies on mutex support to protect internal data-structures from
144
* corruption when accessed from multiple threads.
145
*
146
* The following functions must be ported:
147
*
148
* <ul>
149
* <li> \ref OSAPI_Mutex_new
150
* <li> \ref OSAPI_Mutex_delete
151
* <li> \ref OSAPI_Mutex_take
152
* <li> \ref OSAPI_Mutex_give
153
* </ul>
154
*
155
* Please refer to the \ref OSAPI_MutexClass API for definition of the behavior.
156
* The available source code contains implementation in the file:
157
*
158
* srcC/osapi/<platform>/Mutex.c
159
*/
160
161
/*e \defgroup OSAPIPortingSemaphoreClass Semaphore Porting Guide
162
* \ingroup OSAPIUserManuals_PortingModule
163
*
164
* \details
165
*
166
* \rtime relies on semaphore support for thread control. If \rtime is running
167
* on a non pre-emptive operating system with no support for IPC and
168
* thread synchronization, it is possible to implement these functions as
169
* no-ops. Please refer to \ref OSAPIPortingThreadClass for details regarding
170
* threading.
171
*
172
* The following functions must be ported:
173
*
174
* <ul>
175
* <li> \ref OSAPI_Semaphore_new
176
* <li> \ref OSAPI_Semaphore_delete
177
* <li> \ref OSAPI_Semaphore_take
178
* <li> \ref OSAPI_Semaphore_give
179
* </ul>
180
*
181
* Please refer to the \ref OSAPI_SemaphoreClass API for definition of the
182
* behavior. The available source code contains implementation in the file:
183
*
184
* srcC/osapi/<platform>/Semaphore.c
185
*/
186
187
/*e \defgroup OSAPIPortingProcessClass Process Porting Guide
188
* \ingroup OSAPIUserManuals_PortingModule
189
*
190
* \details
191
*
192
* \rtime only uses the process API to retrieve a unique ID for the
193
* applications.
194
*
195
* The following functions must be ported:
196
*
197
* <ul>
198
* <li> \ref OSAPI_Process_getpid
199
* </ul>
200
*
201
* Please refer to the \ref OSAPI_Process_getpid API for definition of the
202
* behavior. The available source code contains implementation in the file:
203
*
204
* srcC/osapi/<platform>/Process.c
205
*/
206
207
/* \defgroup OSAPIPortingStdioClass Stdio Porting Guide
208
* \ingroup OSAPIUserManuals_PortingModule
209
*
210
* \details
211
*
212
* \rtime uses the stdio functions for logging purposes.
213
*
214
* The following functions must be ported:
215
*
216
* <ul>
217
* <li> \ref OSAPI_Stdio_puts
218
* <li> \ref OSAPI_Stdio_printf
219
* <li> \ref OSAPI_Stdio_snprintf
220
* <li> \ref OSAPI_Stdio_vsnprintf
221
* </ul>
222
*/
223
224
/*e \defgroup OSAPIPortingSystemClass System Porting Guide
225
* \ingroup OSAPIUserManuals_PortingModule
226
*
227
* \details
228
*
229
* The system API consists of functions which are more related to the
230
* hardware on which \rtime is running than on the operating system. As of
231
* \rtime 2.3.1 the system API is implemented as an interface as opposed
232
* to the previous pure function implementation. This change makes it easier
233
* to adapt \rtime to different hardware platforms without having to write a
234
* new port.
235
*
236
* The system interface is defined in OSAPI_SystemI, and a port must implement
237
* all the methods in this structure. In addition, the function
238
* \ref OSAPI_System_get_native_interface must be implemented. This function
239
* must return the system interface for the port (called the native system
240
* interface).
241
*
242
* The semantics for the methods in the interface are exactly as defined
243
* by the corresponding system function. For example, the method
244
* \ref OSAPI_SystemI::get_time must behave exactly as that described by
245
* OSAPI_System_get_time.
246
*
247
* The following system interface methods must be implemented in the
248
* OSAPI_SystemI structure:
249
*
250
* <ul>
251
* <li> \ref OSAPI_SystemI::get_timer_resolution
252
* <li> \ref OSAPI_SystemI::get_time
253
* <li> \ref OSAPI_SystemI::start_timer
254
* <li> \ref OSAPI_SystemI::stop_timer
255
* <li> \ref OSAPI_SystemI::generate_uuid
256
* <li> \ref OSAPI_SystemI::get_hostname
257
* <li> \ref OSAPI_SystemI::initialize
258
* <li> \ref OSAPI_SystemI::finalize
259
* </ul>
260
*
261
*
262
* Please refer to the \ref OSAPI_SystemClass API for definition of the
263
* behavior. The available source code contains implementation in the file:
264
*
265
* srcC/osapi/<platform>/System.c
266
*
267
* \defgroup OSAPIPortingSystemClassUpgrade Migrating a 2.2.x port to 2.3.x
268
* \ingroup OSAPIPortingSystemClass
269
270
In \rtime 2.3.x changes where made to how the system API is
271
implemented. Because of these changes existing ports must be updated, and
272
this section describes how to make a \rtime 2.2.x port compatible with \rtime
273
2.3.x.
274
275
If you have ported \rtime 2.2.x the following steps will make it compatible
276
with version 2.3.x:
277
278
<ul>
279
<li> Rename the following functions and make them private to your
280
source code. For example, rename OSAPI_System_get_time
281
to OSAPI_MyPortSystem_get_time etc.
282
<ul>
283
<li> \ref OSAPI_System_get_time
284
<li> \ref OSAPI_System_get_timer_resolution
285
<li> \ref OSAPI_System_start_timer
286
<li> \ref OSAPI_System_stop_timer
287
<li> \ref OSAPI_System_generate_uuid
288
</ul>
289
<li> Implement the following new methods.
290
<ul>
291
<li> \ref OSAPI_SystemI::get_hostname
292
<li> \ref OSAPI_SystemI::initialize
293
<li> \ref OSAPI_SystemI::finalize
294
</ul>
295
<li> Create a system structure for your port using the following
296
template:
297
\code
298
struct OSAPI_MyPortSystem
299
{
300
struct OSAPI_System _parent;
301
302
Your system variable
303
};
304
305
static struct OSAPI_MyPortSystem OSAPI_System_g;
306
307
/* OSAPI_System_gv_system is a global system variable used by the
308
* generic system API. Thus, the name must be exactly as
309
* shown here.
310
*/
311
struct
OSAPI_System * OSAPI_System_gv_system = &OSAPI_System_g._parent;
312
313
\endcode
314
<li> Implement \ref
OSAPI_System_get_native_interface
method and fill
315
the
OSAPI_SystemI
structure with all the system methods.
316
</ul>
317
*/
318
319
/*e \defgroup OSAPIPortingThreadClass Thread Porting Guide
320
* \ingroup OSAPIUserManuals_PortingModule
321
*
322
* \details
323
*
324
* The thread API is used by \rtime to create threads. Currently only the
325
* UDP transport uses threads and it is a goal to keep the generic \rtime
326
* core library free of threads. Thus, if \rtime is ported to an environment
327
* with no thread support the thread API can be stubbed out. However, note that
328
* the UDP transport must be ported accordingly in this case; that is all
329
* thread code must be removed and replaced with code appropriate for the
330
* environment.
331
*
332
* The following functions must be ported:
333
*
334
* <ul>
335
* <li> \ref OSAPI_Thread_create
336
* <li> \ref OSAPI_Thread_sleep
337
* </ul>
338
*
339
* Please refer to the \ref OSAPI_ThreadClass API for definition of the
340
* behavior. The available source code contains implementation in the file:
341
*
342
* srcC/osapi/<platform>/Thread.c
343
*/
344
345
#endif
/* osapi_porting_h */
RTI Connext DDS Micro Version 2.4.8
Copyright © Tue Apr 12 2016
Real-Time Innovations, Inc