RTI Connext DDS Micro  Version 2.4.8
 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