osapi_system.h

Go to the documentation of this file.

/*
 * FILE: osapi_system.h - Definition of System API
 *
 * Copyright 2012-2015 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
 * --------------------
 * 22mar2014,tk Updated API and documentation
 * 01deb2014,tk MICRO-716: Abstract system API
 * 12mar2012,tk Written
 */
/*ce
 * \file 
 * \brief System API definition
 */
#ifndef osapi_system_h
#define osapi_system_h

#ifndef osapi_dll_h
#include "osapi/osapi_dll.h"
#endif
#ifndef osapi_time_h
#include "osapi/osapi_time.h"
#endif
#ifndef osapi_timer_h
#include "osapi/osapi_timer.h"
#endif

#ifdef __cplusplus
extern "C"
{
#endif

#define OSAPI_SYSTEM_MAX_HOSTNAME (64)

struct OSAPI_System;

/*e \defgroup OSAPI_SystemClass OSAPI System
    \ingroup OSAPIModule

    \brief Abstract System API.

    \details The System is defined as the physical or virtual
    execution environment and implements functions that are not necessarily
    provided by the operating system. For example, a custom embedded board may
    include a special real-time clock which is synchronized via GPS, but is
    not available via a regular OS system call.
*/


/*e \ingroup OSAPI_SystemClass
 *
 *  start timer definition
 */
FUNCTION_MUST_TYPEDEF(
RTI_BOOL
(*OSAPI_System_start_timer_T)(OSAPI_Timer_T self,
                              OSAPI_TimerTickHandlerFunction tick_handler)
)

/*e \ingroup OSAPI_SystemClass
 *
 *  stop timer definition
 */
FUNCTION_SHOULD_TYPEDEF(
RTI_BOOL
(*OSAPI_System_stop_timer_T)(OSAPI_Timer_T self)
)

/*e \ingroup OSAPI_SystemClass
 *
 *  get timer resolution
 */
FUNCTION_SHOULD_TYPEDEF(
RTI_INT32
(*OSAPI_System_get_timer_resolution_T)(void)
)

/*e \ingroup OSAPI_SystemClass
 *
 * get time
 */
FUNCTION_SHOULD_TYPEDEF(
RTI_BOOL
(*OSAPI_System_get_time_T)(OSAPI_NtpTime *now)
)

/*e \ingroup OSAPI_SystemClass
 *
 * initialize
 */
FUNCTION_SHOULD_TYPEDEF(
RTI_BOOL
(*OSAPI_System_initialize_T)(void)
)

/*e \ingroup OSAPI_SystemClass
 *
 * finalize
 */
FUNCTION_SHOULD_TYPEDEF(
RTI_BOOL
(*OSAPI_System_finalize_T)(void)
)

/*e \ingroup OSAPI_SystemClass
 *
 * get_hostname
 */
FUNCTION_MUST_TYPEDEF(
RTI_BOOL
(*OSAPI_System_get_hostname_T)(char *const hostname)
)

struct OSAPI_SystemUUID;

typedef void
(*OSAPI_System_generate_uuid_T)(struct OSAPI_SystemUUID *uuid_out);

/*e \ingroup OSAPI_SystemClass
 *
 *  System Interface class
 *
 *  The methods in this interface are called by the corresponding
 *  OSAPI_System function. For example, OSAPI_System_get_time() calls
 *  system->get_time().
 *
 */
struct OSAPI_SystemI
{
    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_start_timer for signature
     * and semantics.
     */
    OSAPI_System_start_timer_T start_timer;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_stop_timer for signature
     * and semantics.
     */
    OSAPI_System_stop_timer_T stop_timer;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_get_timer_resolution for signature
     * and semantics.
     */
    OSAPI_System_get_timer_resolution_T get_timer_resolution;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_get_time for signature
     * and semantics.
     */
    OSAPI_System_get_time_T get_time;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_initialize for signature
     * and semantics.
     */
    OSAPI_System_initialize_T initialize;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_finalize for signature
     * and semantics.
     */
    OSAPI_System_finalize_T finalize;

    /*e \ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_generate_uuid for signature
     * and semantics.
     */
    OSAPI_System_generate_uuid_T generate_uuid;

    /*e\ingroup OSAPI_SystemClass
     *
     * Refer to \ref OSAPI_System_get_hostname for signature
     * and semantics.
     */
    OSAPI_System_get_hostname_T get_hostname;
};

#define OSAPI_SystemI_INITIALIZER \
{\
    NULL,\
    NULL,\
    NULL,\
    NULL,\
    NULL,\
    NULL,\
    NULL,\
    NULL \
}

extern OSAPIDllVariable struct OSAPI_System *OSAPI_System_gv_System;

/*e \ingroup OSAPI_SystemClass
 *  \brief Set system interface
 *
 *  \details
 *  This function sets the system interface, overriding the current system
 *  interace.
 *
 *  \param [in] intf - The new system interface
 *
 *  \return RTI_TRUE on success, RTI_FALSE on failure.
 */
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_set_interface(struct OSAPI_SystemI *intf);

/*e \ingroup OSAPI_SystemClass
 *  \brief Get the current system interface
 *
 *  \details
 *  This function returns the current system interface
 *
 *  \param [out] intf - The current system interface
 *
 *  \return RTI_TRUE on success, RTI_FALSE on failure.
 */
SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_get_interface(struct OSAPI_SystemI *intf);

/*e \ingroup OSAPI_SystemClass
 *
 *  System listener
 */
FUNCTION_MUST_TYPEDEF(
RTI_BOOL
(*OSAPI_System_on_system_initialize_T)(void *listener_data,struct OSAPI_System *system)
)

typedef void
(*OSAPI_System_on_system_finalize_T)(void *listener_data,struct OSAPI_System *system);

/*e \ingroup OSAPI_SystemClass
 *
 *  System listener
 */
struct OSAPI_SystemListener
{
    void *listener_data;
    OSAPI_System_on_system_initialize_T on_system_initialize;
    OSAPI_System_on_system_finalize_T on_system_finalize;
};

#define OSAPI_SystemListener_INITIALIZER \
{\
    NULL,\
    NULL,\
    NULL,\
}

/*e \ingroup OSAPI_SystemClass
 *  \brief Install a system listeners
 *
 *  \details
 *
 *  The system listers gets called during the life-time of the system
 *  Only listeners which are non-NULL are called, thus it is ok to install
 *  a partially set listener structure. System listeners can be installed
 *  until the system has been initialized by calling OSAPI_System_initialize.
 *  This function is not considered thread-safe. The listener value should
 *  always be initialized with OSAPI_SystemListener_DEFAULT before use.
 *
 *  \param [in] listener System listeners to call
 *
 *  \return RTI_TRUE on success, RTI_FALSE on failure
 */
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_set_listener(struct OSAPI_SystemListener *listener);

/*e \ingroup OSAPI_SystemClass
 *  \brief Get current system listeners
 *
 *  \details
 *  Return the current set of system listeners. This function is not thread-safe.
 *
 *  \param[in] listener System listeners structure to fill in.
 *
 *  \return RTI_TRUE on success, RTI_FALSE on failure.
 */
SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_get_listener(struct OSAPI_SystemListener *listener);

/*e \ingroup OSAPI_SystemClass
 *
 *  System properties
 */
struct OSAPI_SystemProperty
{
    /*e
     *  \brief Set the timer properties
     */
    struct OSAPI_TimerProperty timer_property;

    /*e
     *  \brief Set the hostname for the node.
     *
     *  \details
     *  \rtime uses this name when it announces itself on the
     *  network. This name is used by other RTI products. The
     *  hostname must not exceed OSAPI_SYSTEM_MAX_HOSTNAME,
     *  including the \0 character.
     */
    char hostname[OSAPI_SYSTEM_MAX_HOSTNAME];
};

#define OSAPI_SystemProperty_INITIALIZER \
{\
    OSAPI_TimerProperty_INITIALIZER,\
    {0}\
}

/*e \ingroup OSAPI_SystemClass
 * \brief UUID definition
 *
 *  Abstract UUID object.  128-bit value.
 */
struct OSAPI_SystemUUID
{
    RTI_UINT32 value[4];
};

struct OSAPI_System;

/*e \ingroup OSAPI_SystemClass
  \brief Generate a unique universal identifier (UUID)
*/
OSAPIDllExport void
OSAPI_System_generate_uuid(struct OSAPI_SystemUUID *uuid_out);

/*e \ingroup OSAPI_SystemClass
  \brief Get the current system time.

  \details In general, the system time is used by components to correlate both
  internal and external events, such as data reception and ordering. Thus,
  it is recommended that this function returns the real time. However, it is not
  strictly required.

  Notes:
   - It is assumed that the time returned by get_time is monotonically
     increasing. It it up to the implementation of this function to ensure this
     holds true.
   - It is ok to return the same time as the last call.
   - The clock used to report real-time can be different than the clock used to
     support start_timer and stop_timer.

  @param[out] now Time in NtpTime format.

  @return RTI_TRUE on success, RTI_FALSE on failure.

  @pre Initialized system.

  @exception None.

  @mtsafety SAFE
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_get_time(OSAPI_NtpTime *now);

/*e \ingroup OSAPI_SystemClass
    \brief Get the resolution of the clock driving the timer in nano seconds.

    \details

    This function must return the frequency of the system timer used to implement
    OSAPI_SystemI::start_timer and OSAPI_SystemI::stop_timer API.

    @return timer resolution in nanoseconds.

*/
OSAPIDllExport RTI_INT32
OSAPI_System_get_timer_resolution(void);

/*e \ingroup OSAPI_SystemClass

    \brief Start the timer.

    @param [in]  self Timer object.

    @param [in]  tick_handler Timer handle.

    @pre Initialized system.
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_start_timer(OSAPI_Timer_T self,
                        OSAPI_TimerTickHandlerFunction tick_handler);

/*e \ingroup OSAPI_SystemClass
    \brief Stop the timer.

    @param [in] self Timer

    @return RTI_TRUE on success, RTI_FALSE on failure.

    @pre Initialized system.
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_stop_timer(OSAPI_Timer_T self);

/*e \ingroup OSAPI_SystemClass
    \brief Initialize the system.

    \details

    This function initializes the system and calls the port specific initialize
    method first. The port specific initialization method must return RTI_TRUE
    on success and RTI_FALSE on failure. A system can only be initialized once.

    @return RTI_TRUE on success, RTI_FALSE on failure.
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_initialize(void);

#ifndef RTI_CERT
/*e \ingroup OSAPI_SystemClass
    \brief Finalize the system.

    \details

    This function finalizes the system and calls the port specific finalize
    method last. The port specific initialization method must return RTI_TRUE
    on success and RTI_FALSE on failure.

    @return RTI_TRUE on success, RTI_FALSE on failure.
*/
SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_finalize(void);
#endif /* !RTI_CERT */

/*e \ingroup OSAPI_SystemClass
    \brief Get the system properties

    @param [out] property

    @return RTI_TRUE on success, RTI_FALSE on failure.
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_get_property(struct OSAPI_SystemProperty *property);

/*e \ingroup OSAPI_SystemClass
    \brief Set the system properties.

    \details
    The system properties can be set until the system is initialized by
    calling \ref OSAPI_System_initialize()

    @param [in] property

    @return RTI_TRUE on success, RTI_FALSE on failure.
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_set_property(struct OSAPI_SystemProperty *property);

/*e \ingroup OSAPI_SystemClass
    \brief Get the native system interface

    \details

    This function must fill in the interface structure and assign the
    following methods:

    <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>

    @param [out] intf The native system interface
*/
OSAPIDllExport void
OSAPI_System_get_native_interface(struct OSAPI_SystemI *intf);

/*e \ingroup OSAPI_SystemClass
    \brief Return next ID

    @mtsafety UNSAFE
*/
OSAPIDllExport RTI_INT32
OSAPI_System_get_next_object_id(void);

/*e \ingroup OSAPI_SystemClass
  \brief Get the hostname

  \details Get the hostname

  @param[inout] hostname  The buffer to store the hostname. Must be at
                          least OSAPI_SYSTEM_MAX_HOSTNAME bytes. If the
                          actual hostname is longer than
                          OSAPI_SYSTEM_MAX_HOSTNAME bytes (including \0) the
                          hostname is truncated.

  @pre Initialized system.

  @exception None.

  @return RTI_TRUE on success, RTI_FALSE on failure.

  @mtsafety SAFE
*/
MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
OSAPI_System_get_hostname(char *const hostname);

#ifdef __cplusplus
}                               /* extern "C" */
#endif

#endif /* osapi_system_h */