RTI Connext DDS Micro  Version 2.4.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_system.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_system.h - Definition of System API
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  * 15jul2015,tk MICRO-1426/PR#15358 Added support for OSAPI_System_get_ticktime
14  * 22mar2014,tk Updated API and documentation
15  * 01deb2014,tk MICRO-716: Abstract system API
16  * 12mar2012,tk Written
17  */
18 /*ce
19  * \file
20  * \brief System API definition
21  */
22 #ifndef osapi_system_h
23 #define osapi_system_h
24 
25 #ifndef osapi_dll_h
26 #include "osapi/osapi_dll.h"
27 #endif
28 #ifndef osapi_time_h
29 #include "osapi/osapi_time.h"
30 #endif
31 #ifndef osapi_timer_h
32 #include "osapi/osapi_timer.h"
33 #endif
34 
35 #ifdef __cplusplus
36 extern "C"
37 {
38 #endif
39 
40 #define OSAPI_SYSTEM_MAX_HOSTNAME (64)
41 
42 struct OSAPI_System;
43 
44 /*ci
45  * \brief The first object-id returned by OSAPI_System_get_next_object_id()
46  */
47 #define OSAPI_SYSTEM_OBJECTID_START 0x01000000
48 
49 /*ci
50  * \brief The maximum returned valid object-id from
51  * OSAPI_System_get_next_object_id() is OSAPI_SYSTEM_OBJECTID_MAX-1.
52  */
53 #define OSAPI_SYSTEM_OBJECTID_MAX 0x7fffffff
54 
55 /*e \defgroup OSAPI_SystemClass OSAPI System
56  * \ingroup OSAPIModule
57  * \brief Abstract System API.
58  *
59  * \details
60  *
61  * The System is defined as the physical or virtual
62  * execution environment and implements functions that are not necessarily
63  * provided by the operating system. For example, a custom embedded board may
64  * include a special real-time clock which is synchronized via GPS, but is
65  * not available via a regular OS system call.
66  */
67 
68 /*e \ingroup OSAPI_SystemClass
69  *
70  * start timer definition
71  */
72 FUNCTION_MUST_TYPEDEF(
74 (*OSAPI_System_start_timer_T)(OSAPI_Timer_T self,
75  OSAPI_TimerTickHandlerFunction tick_handler)
76 )
77 
78 /*e \ingroup OSAPI_SystemClass
79  *
80  * stop timer definition
81  */
82 FUNCTION_SHOULD_TYPEDEF(
84 (*OSAPI_System_stop_timer_T)(OSAPI_Timer_T self)
85 )
86 
87 /*e \ingroup OSAPI_SystemClass
88  *
89  * get timer resolution
90  */
91 FUNCTION_SHOULD_TYPEDEF(
92 RTI_INT32
94 )
95 
96 /*e \ingroup OSAPI_SystemClass
97  *
98  * get time
99  */
100 FUNCTION_SHOULD_TYPEDEF(
101 RTI_BOOL
103 )
104 
105 /*e \ingroup OSAPI_SystemClass
106  *
107  * initialize
108  */
109 FUNCTION_SHOULD_TYPEDEF(
110 RTI_BOOL
112 )
113 
114 /*e \ingroup OSAPI_SystemClass
115  *
116  * finalize
117  */
118 FUNCTION_SHOULD_TYPEDEF(
119 RTI_BOOL
121 )
122 
123 /*e \ingroup OSAPI_SystemClass
124  *
125  * get_hostname
126  */
127 FUNCTION_MUST_TYPEDEF(
128 RTI_BOOL
129 (*OSAPI_System_get_hostname_T)(char *const hostname)
130 )
131 
132 struct OSAPI_SystemUUID;
133 
134 FUNCTION_MUST_TYPEDEF(
135 RTI_BOOL
136 (*OSAPI_System_generate_uuid_T)(struct OSAPI_SystemUUID *uuid_out);
137 )
138 
139 FUNCTION_MUST_TYPEDEF(
140 RTI_BOOL
141 (*OSAPI_System_get_ticktime_T)(RTI_INT32 *sec,RTI_UINT32 *nanosec);
142 )
143 
144 /*e \ingroup OSAPI_SystemClass
145  *
146  * System Interface class
147  *
148  * The methods in this interface are called by the corresponding
149  * OSAPI_System function. For example, OSAPI_System_get_time() calls
150  * system->get_time().
151  *
152  */
154 {
155  /*e \ingroup OSAPI_SystemClass
156  *
157  * Refer to \ref OSAPI_System_start_timer for signature
158  * and semantics.
159  */
161 
162  /*e \ingroup OSAPI_SystemClass
163  *
164  * Refer to \ref OSAPI_System_stop_timer for signature
165  * and semantics.
166  */
168 
169  /*e \ingroup OSAPI_SystemClass
170  *
171  * Refer to \ref OSAPI_System_get_timer_resolution for signature
172  * and semantics.
173  */
175 
176  /*e \ingroup OSAPI_SystemClass
177  *
178  * Refer to \ref OSAPI_System_get_time for signature
179  * and semantics.
180  */
182 
183  /*e \ingroup OSAPI_SystemClass
184  *
185  * Refer to \ref OSAPI_System_initialize for signature
186  * and semantics.
187  */
189 
190  /*e \ingroup OSAPI_SystemClass
191  *
192  * Refer to \ref OSAPI_System_finalize for signature
193  * and semantics.
194  */
196 
197  /*e \ingroup OSAPI_SystemClass
198  *
199  * Refer to \ref OSAPI_System_generate_uuid for signature
200  * and semantics.
201  */
202  OSAPI_System_generate_uuid_T generate_uuid;
203 
204  /*e\ingroup OSAPI_SystemClass
205  *
206  * Refer to \ref OSAPI_System_get_hostname for signature
207  * and semantics.
208  */
210 
211  /*e\ingroup OSAPI_SystemClass
212  *
213  * Refer to \ref OSAPI_System_get_ticktime for signature
214  * and semantics.
215  */
216  OSAPI_System_get_ticktime_T get_ticktime;
217 };
218 
219 #define OSAPI_SystemI_INITIALIZER \
220 {\
221  NULL,\
222  NULL,\
223  NULL,\
224  NULL,\
225  NULL,\
226  NULL,\
227  NULL,\
228  NULL,\
229  NULL\
230 }
231 
232 extern OSAPIDllVariable struct OSAPI_System *OSAPI_System_gv_System;
233 
234 /*e \ingroup OSAPI_SystemClass
235  * \brief Set system interface
236  *
237  * \details
238  * This function sets the system interface, overriding the current system
239  * interface.
240  *
241  * \param [in] intf - The new system interface
242  *
243  * \return RTI_TRUE on success, RTI_FALSE on failure.
244  */
245 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
247 
248 /*e \ingroup OSAPI_SystemClass
249  * \brief Get the current system interface
250  *
251  * \details
252  * This function returns the current system interface
253  *
254  * \param [out] intf - The current system interface
255  *
256  * \return RTI_TRUE on success, RTI_FALSE on failure.
257  */
258 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
260 
261 /*e \ingroup OSAPI_SystemClass
262  *
263  * System listener
264  */
265 FUNCTION_MUST_TYPEDEF(
266 RTI_BOOL
267 (*OSAPI_System_on_system_initialize_T)(void *listener_data,struct OSAPI_System *system)
268 )
269 
270 typedef void
271 (*OSAPI_System_on_system_finalize_T)(void *listener_data,struct OSAPI_System *system);
272 
273 /*e \ingroup OSAPI_SystemClass
274  *
275  * System listener
276  */
278 {
279  void *listener_data;
280  OSAPI_System_on_system_initialize_T on_system_initialize;
281  OSAPI_System_on_system_finalize_T on_system_finalize;
282 };
283 
284 #define OSAPI_SystemListener_INITIALIZER \
285 {\
286  NULL,\
287  NULL,\
288  NULL,\
289 }
290 
291 /*e \ingroup OSAPI_SystemClass
292  * \brief Install a system listeners
293  *
294  * \details
295  *
296  * The system listeners are called during the life-time of the system.
297  * Only listeners which are non-NULL are called, thus it is ok to install
298  * a partially set listener structure. System listeners can be installed
299  * until the system has been initialized by calling OSAPI_System_initialize.
300  * This function is not considered thread-safe. The listener value should
301  * always be initialized with OSAPI_SystemListener_DEFAULT before use.
302  *
303  * \param [in] listener System listeners to call
304  *
305  * \return RTI_TRUE on success, RTI_FALSE on failure
306  */
307 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
309 
310 /*e \ingroup OSAPI_SystemClass
311  * \brief Get current system listeners
312  *
313  * \details
314  * Return the current set of system listeners. This function is not thread-safe.
315  *
316  * \param[in] listener System listener structure to fill in.
317  *
318  * \return RTI_TRUE on success, RTI_FALSE on failure.
319  */
320 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
322 
323 /*e \ingroup OSAPI_SystemClass
324  *
325  * System properties
326  */
328 {
329  /*e
330  * \brief Set the timer properties
331  */
333 
334  /*e
335  * \brief Set the hostname for the node.
336  *
337  * \details
338  * \rtime uses this name when it announces itself on the
339  * network. This name is used by other RTI products. The
340  * hostname must not exceed OSAPI_SYSTEM_MAX_HOSTNAME,
341  * including the \0 character.
342  */
343  char hostname[OSAPI_SYSTEM_MAX_HOSTNAME];
344 };
345 
346 #define OSAPI_SystemProperty_INITIALIZER \
347 {\
348  OSAPI_TimerProperty_INITIALIZER,\
349  {0}\
350 }
351 
352 /*e \ingroup OSAPI_SystemClass
353  * \brief UUID definition
354  *
355  * Abstract UUID object,a 128-bit value.
356  */
358 {
359  RTI_UINT32 value[4];
360 };
361 
362 struct OSAPI_System;
363 
364 /*e \ingroup OSAPI_SystemClass
365  * \brief Generate a unique universal identifier (UUID)
366  *
367  * \param [out] uuid_out The generated UUID value
368  *
369  * \return RTI_TRUE on success, RTI_FALSE on failure
370  */
371 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
373 
374 /*e \ingroup OSAPI_SystemClass
375  * \brief Get the current system time.
376  *
377  * \details
378  * In general, the system time is used by components to correlate both
379  * internal and external events, such as data reception and ordering. Thus,
380  * it is recommended that this function returns the real time. However, it is not
381  * strictly required.
382  *
383  * Notes:
384  * - It is assumed that the time returned by get_time is monotonically
385  * increasing. It is up to the implementation of this function to ensure
386  * this holds true.
387  * - It is ok to return the same time as the last call.
388  * - The clock used to report real-time can be different than the clock used to
389  * support start_timer and stop_timer.
390  *
391  * @param [out] now Time in NtpTime format.
392  *
393  * @return RTI_TRUE on success, RTI_FALSE on failure.
394  *
395  * @pre Initialized system.
396  *
397  * @exception None.
398  */
399 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
401 
402 /*e \ingroup OSAPI_SystemClass
403  * \brief Get the resolution of the clock driving the timer in nano seconds.
404  *
405  * \details
406  *
407  * This function must return the frequency of the system timer used to implement
408  * OSAPI_SystemI::start_timer and OSAPI_SystemI::stop_timer API.
409  *
410  * @return timer resolution in nanoseconds.
411  */
412 OSAPIDllExport RTI_INT32
414 
415 /*e \ingroup OSAPI_SystemClass
416  *
417  * \brief Start the timer.
418  *
419  * @param [in] self Timer object.
420  * @param [in] tick_handler Timer handle.
421  *
422  * @pre Initialized system.
423  */
424 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
425 OSAPI_System_start_timer(OSAPI_Timer_T self,
426  OSAPI_TimerTickHandlerFunction tick_handler);
427 
428 /*e \ingroup OSAPI_SystemClass
429  * \brief Stop the timer.
430  *
431  * @param [in] self Timer
432  *
433  * @return RTI_TRUE on success, RTI_FALSE on failure.
434  *
435  * @pre Initialized system.
436  */
437 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
438 OSAPI_System_stop_timer(OSAPI_Timer_T self);
439 
440 /*e \ingroup OSAPI_SystemClass
441  * \brief Initialize the system.
442  *
443  * \details
444  *
445  * This function initializes the system and calls the port specific initialize
446  * method first. The port specific initialization method must return RTI_TRUE
447  * on success and RTI_FALSE on failure. A system can only be initialized once.
448  *
449  * @return RTI_TRUE on success, RTI_FALSE on failure.
450  */
451 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
453 
454 #ifndef RTI_CERT
455 /*e \ingroup OSAPI_SystemClass
456  \brief Finalize the system.
457 
458  \details
459 
460  This function finalizes the system and calls the port specific finalize
461  method last. The port specific initialization method must return RTI_TRUE
462  on success and RTI_FALSE on failure.
463 
464  @return RTI_TRUE on success, RTI_FALSE on failure.
465 */
466 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
468 #endif /* !RTI_CERT */
469 
470 /*e \ingroup OSAPI_SystemClass
471  * \brief Get the system properties
472  *
473  * @param [out] property
474  *
475  * @return RTI_TRUE on success, RTI_FALSE on failure.
476  */
477 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
479 
480 /*e \ingroup OSAPI_SystemClass
481  * \brief Set the system properties.
482  *
483  * \details
484  * The system properties can be set until the system is initialized by
485  * calling \ref OSAPI_System_initialize()
486  *
487  * @param [in] property
488  *
489  * @return RTI_TRUE on success, RTI_FALSE on failure.
490  */
491 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
493 
494 /*e \ingroup OSAPI_SystemClass
495  * \brief Get the native system interface
496  *
497  * \details
498  *
499  * This function must fill in the interface structure and assign the
500  * following methods:
501  *
502  * <ul>
503  * <li> \ref OSAPI_SystemI::get_timer_resolution
504  * <li> \ref OSAPI_SystemI::get_time
505  * <li> \ref OSAPI_SystemI::start_timer
506  * <li> \ref OSAPI_SystemI::stop_timer
507  * <li> \ref OSAPI_SystemI::generate_uuid
508  * <li> \ref OSAPI_SystemI::get_hostname
509  * <li> \ref OSAPI_SystemI::initialize
510  * <li> \ref OSAPI_SystemI::finalize
511  * <li> \ref OSAPI_SystemI::get_ticktime
512  * </ul>
513  *
514  * @param [out] intf The native system interface
515  */
516 OSAPIDllExport void
518 
519 /*e \ingroup OSAPI_SystemClass
520  *
521  * \brief Return next object ID
522  *
523  * \details
524  * This function return the next available object if. Object Id are never
525  * reused, thus it is possible to run out of object ids.
526  *
527  * \return new object on success, -1 on failure
528  */
529 OSAPIDllExport RTI_INT32
531 
532 /*e \ingroup OSAPI_SystemClass
533  * \brief Get the hostname
534  *
535  * \details
536  * Get the hostname
537  *
538  * @param [out] hostname The buffer to store the hostname. Must be at
539  * least OSAPI_SYSTEM_MAX_HOSTNAME bytes. If the
540  * actual hostname is longer than
541  * OSAPI_SYSTEM_MAX_HOSTNAME bytes (including \0) the
542  * hostname is truncated.
543  *
544  * @pre Initialized system.
545  *
546  * @exception None.
547  *
548  * @return RTI_TRUE on success, RTI_FALSE on failure.
549  *
550  * @mtsafety SAFE
551  */
552 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
553 OSAPI_System_get_hostname(char *const hostname);
554 
555 
556 /*e \ingroup OSAPI_SystemClass
557  *
558  * \brief Get current tick time
559  *
560  * \details
561  *
562  * The ticktime is a time measurement used by Micro to determine how much
563  * time has elapsed in a period. It does not have to be an absolute time,
564  * but it _must_ be monotonically increasing. For this reason it is important
565  * to choose the time source with care. For example, the system time may
566  * mbe adjusted backward or forward and this could affect the measure time
567  * lapse. The resolution of the tick time is expected to be no less than the
568  * system timer, although it is not a requirement.
569  *
570  * @param[out] sec The current ticktime in seconds
571  *
572  * @param[out] nanosec Additional nanoseconds in the current ticktime
573  *
574  * @pre Initialized system.
575  *
576  * @return RTI_TRUE on success, RTI_FALSE on failure.
577  */
578 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
579 OSAPI_System_get_ticktime(RTI_INT32 *sec,RTI_UINT32 *nanosec);
580 
581 
582 #ifdef __cplusplus
583 } /* extern "C" */
584 #endif
585 
586 #endif /* osapi_system_h */

RTI Connext DDS Micro Version 2.4.6 Copyright © Mon Jan 25 2016 Real-Time Innovations, Inc