osapi_porting.h

Go to the documentation of this file.

/*
 * FILE: osapi_porting.h - Porting Guide
 *
 * Copyright 2012-2014 Real-Time Innovations, Inc.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 *
 * Modification History
 * --------------------
 * 22mar14,tk Written
 * 12mar12,tk Written
 */
#ifndef osapi_porting_h
#define osapi_porting_h

/*e \file 
 *  \brief Porting Guide
 */
/*e \addtogroup OSAPIUserManuals_PortingModule
 */

/*e \defgroup OSAPIPortingIntroClass Introduction
    \ingroup OSAPIUserManuals_PortingModule

    \details

    \rtime has been engineered for reasonable portability to platforms and
    environments which RTI does not have access to. This porting
    guide describes the features required by \rtime to run.

    The source tree shipped with \rtime is identical to the development tree
    used by RTI. However, the internal file structure has been modified to
    make it easier to import and compile the source as part of a project.

    \rtime uses an abstraction layer to support running on a number
    of platforms. The abstraction layer, OSAPI, is an abstraction of
    functionality typically found in one or more of the following
    libraries and services:

    <ul>
        <li> Operating System calls
        <li> Device drivers
        <li> Standard C library
    </ul>

    The OSAPI module is designed to be relatively easy to move to a new
    platform. All functionality, with the exception of NETIO (which must be
    ported) is contained within this single module, even though the functionality
    typically spans different libraries. It should be noted that although
    some functions may not seem relevant on a particular platform, they must
    still be implemented, as they are used by other modules. For example,
    the port running on Stellaris with no OS support still needs to implement
    a threading model.

    Please note that the OSAPI module is not designed to be a general purpose
    abstraction layer; its sole purpose is to support the execution of \rtime.

    Before porting the OSAPI module, you are expected to be familiar with
    general OS concepts, the standard C library, and embedded systems. This
    guide covers the following topics:

    <ul>
        <li> \ref OSAPIPortingConfigClass
        <li> \ref OSAPIModuleHeap
        <li> \ref OSAPIPortingMutexClass
        <li> \ref OSAPIPortingSemaphoreClass
        <li> \ref OSAPIPortingProcessClass
        <li> \ref OSAPIPortingStdioClass
        <li> \ref OSAPIPortingSystemClass
        <li> \ref OSAPIPortingThreadClass
    </ul>

    The directory structure for the OS API module is as follows:

    <ul>
        <li> include/osapi/
        <li> srcC/osapi/common/
        <ul>
            <li>/<platform>/<file>.c
        </ul>
    </ul>

    The 'include' directory contains the external interfaces, those that are
    assumed by other modules. The only files that may need modification in the
    include directory are files ending in _impl.h and config.h.

    The srcC directory contains a sub-directory `common` which contains source
    code that is independent of any specific OS, but depends on functions
    implemented by exactly one of the other sub-modules, such as posix or
    windows.

    NOTE: It is <em> not </em> recommended to modify source files shipped with
    \rtime. Instead if it is desired to start with code supplied by RTI
    it is recommended to <em> copy </em> the corresponding sub-directory,
    for example posix, and rename it. This way it is easier to upgrade \rtime
    while keeping existing ports.
 */

/*e \defgroup OSAPIPortingConfigClass Configuration files
    \ingroup OSAPIUserManuals_PortingModule

    The include/osapi/osapi_config.h file contains platform-specific settings
    used by OSAPI and other modules. A new platform needs its settings defined
    there. Please refer to the existing file for details.

    It should be noted that \rtime does not currently use auto-detection
    programs to detect the host and target build environment. \rtime relies
    on predefined macros to determine the target environment. If \rtime
    cannot determine the target environment it is necessary to manually
    configure the target environment in osapi_config.
*/

/*e \defgroup  OSAPIModuleHeap Heap Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * \rtime uses the heap to allocate memory for internal data-structures. With
  * a few exceptions, \rtime does _not_ return memory to the heap. Instead,
  * \rtime uses internal pools to quickly allocate and free memory for specific
  * types. Only the initial memory is allocated directly from the heap.
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Heap_allocate
  *     <li> \ref OSAPI_Heap_free
  * </ul>
  *
  * Please refer to the \ref OSAPI_HeapClass API for definition of the behavior.
  * The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/Heap.c
  *
  */

 /*e \defgroup OSAPIPortingMutexClass Mutex Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * \rtime relies on mutex support to protect internal data-structures from
  * corruption when accessed from multiple threads.
  *
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Mutex_new
  *     <li> \ref OSAPI_Mutex_delete
  *     <li> \ref OSAPI_Mutex_take
  *     <li> \ref OSAPI_Mutex_give
  * </ul>
  *
  * Please refer to the \ref OSAPI_MutexClass API for definition of the behavior.
  * The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/Mutex.c
  */

 /*e \defgroup  OSAPIPortingSemaphoreClass Semaphore Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * \rtime relies on semaphore support for thread control. If \rtime is running
  * on a non pre-emptive operating system with no support for IPC and
  * thread synchronization, it is possible to implement these functions as
  * no-ops. Please refer to \ref OSAPIPortingThreadClass for details regarding
  * threading.
  *
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Semaphore_new
  *     <li> \ref OSAPI_Semaphore_delete
  *     <li> \ref OSAPI_Semaphore_take
  *     <li> \ref OSAPI_Semaphore_give
  * </ul>
  *
  * Please refer to the \ref OSAPI_SemaphoreClass API for definition of the
  * behavior. The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/Semaphore.c
  */

 /*e \defgroup  OSAPIPortingProcessClass Process Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * \rtime only uses the process API to retrieve a unique ID for the
  * applications.
  *
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Process_getpid
  * </ul>
  *
  * Please refer to the \ref OSAPI_Process_getpid API for definition of the
  * behavior. The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/Process.c
  */

 /*e \defgroup  OSAPIPortingStdioClass Stdio Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * \rtime uses the stdio functions for logging purposes.
  *
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Stdio_puts
  *     <li> \ref OSAPI_Stdio_printf
  *     <li> \ref OSAPI_Stdio_snprintf
  *     <li> \ref OSAPI_Stdio_vsnprintf
  * </ul>
  */

 /*e \defgroup  OSAPIPortingSystemClass System Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * The system API consists of functions which are more related to the
  * hardware on which \rtime is running than on the operating system. As of
  * \rtime 2.3.1 the system API is implemented as an interface as opposed
  * to the previous pure function implementation. This change makes it easier
  * to adapt \rtime to different hardware platforms without having to write a
  * new port.
  *
  * The system interface is defined in OSAPI_SystemI, and a port must implement
  * all the methods in this structure. In addition, the function
  * \ref OSAPI_System_get_native_interface must be implemented. This function
  * must return the system interface for the port (called the native system
  * interface).
  *
  * The semantics for the methods in the interface are exactly as defined
  * by the corresponding system function. For example, the method
  * \ref OSAPI_SystemI::get_time must behave exactly as that described by
  * OSAPI_System_get_time.
  *
  * The following system interface methods must be implemented in the
  * OSAPI_SystemI structure:
  *
  * <ul>
  *     <li> \ref OSAPI_SystemI::get_timer_resolution
  *     <li> \ref OSAPI_SystemI::get_time
  *     <li> \ref OSAPI_SystemI::start_timer
  *     <li> \ref OSAPI_SystemI::stop_timer
  *     <li> \ref OSAPI_SystemI::generate_uuid
  *     <li> \ref OSAPI_SystemI::get_hostname
  *     <li> \ref OSAPI_SystemI::initialize
  *     <li> \ref OSAPI_SystemI::finalize
  * </ul>
  *
  *
  * Please refer to the \ref OSAPI_SystemClass API for definition of the
  * behavior. The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/System.c
  *
  * \defgroup OSAPIPortingSystemClassUpgrade Migrating a 2.2.x port to 2.3.x
  * \ingroup OSAPIPortingSystemClass

  In \rtime 2.3.x changes where made to how the system API is
  implemented. Because of these changes existing ports must be updated, and
  this section describes how to make a \rtime 2.2.x port compatible with \rtime
  2.3.x.

  If you have ported \rtime 2.2.x the following steps will make it compatible
  with version 2.3.x:

    <ul>
        <li> Rename the following functions and make them private to your
             source code. For example, rename OSAPI_System_get_time
             to OSAPI_MyPortSystem_get_time etc.
            <ul>
               <li> \ref OSAPI_System_get_time
               <li> \ref OSAPI_System_get_timer_resolution
               <li> \ref OSAPI_System_start_timer
               <li> \ref OSAPI_System_stop_timer
               <li> \ref OSAPI_System_generate_uuid
            </ul>
        <li> Implement the following new methods.
            <ul>
                <li> \ref OSAPI_SystemI::get_hostname
                <li> \ref OSAPI_SystemI::initialize
                <li> \ref OSAPI_SystemI::finalize
            </ul>
        <li> Create a system structure for your port using the following
             template:
             \code
             struct OSAPI_MyPortSystem
            {
                struct OSAPI_System _parent;

                Your system variable
            };

            static struct OSAPI_MyPortSystem OSAPI_System_g;

            /* OSAPI_System_gv_system is a global system variable used by the
             * generic system API. Thus, the name must be exactly as
             * shown here.
             */
            struct OSAPI_System * OSAPI_System_gv_system = &OSAPI_System_g._parent;

            \endcode
        <li> Implement \ref OSAPI_System_get_native_interface method and fill
             the OSAPI_SystemI structure with all the system methods.
    </ul>
*/

 /*e \defgroup  OSAPIPortingThreadClass Thread Porting Guide
  * \ingroup OSAPIUserManuals_PortingModule
  *
  * \details
  *
  * The thread API is used by \rtime to create threads. Currently only the
  * UDP transport uses threads and it is a goal to keep the generic \rtime
  * core library free of threads. Thus, if \rtime is ported to an environment
  * with no thread support the thread API can be stubbed out. However, note that
  * the UDP transport must be ported accordingly in this case; that is all
  * thread code must be removed and replaced with code appropriate for the
  * environment.
  *
  * The following functions must be ported:
  *
  * <ul>
  *     <li> \ref OSAPI_Thread_create
  *     <li> \ref OSAPI_Thread_sleep
  * </ul>
  *
  * Please refer to the \ref OSAPI_ThreadClass API for definition of the
  * behavior. The available source code contains implementation in the file:
  *
  * srcC/osapi/<platform>/Thread.c
  */

#endif /* osapi_porting_h */