RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
osapi_system.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_system.h - Definition of System API
3  *
4  * Copyright 2012-2014 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  * 22mar2014,tk Updated API and documentation
14  * 01deb2014,tk MICRO-716: Abstract system API
15  * 12mar2012,tk Written
16  */
17 /*ce
18  * \file
19  * \brief System API definition
20  */
21 #ifndef osapi_system_h
22 #define osapi_system_h
23 
24 #ifndef osapi_dll_h
25 #include "osapi/osapi_dll.h"
26 #endif
27 #ifndef osapi_time_h
28 #include "osapi/osapi_time.h"
29 #endif
30 #ifndef osapi_timer_h
31 #include "osapi/osapi_timer.h"
32 #endif
33 
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38 
39 #define OSAPI_SYSTEM_MAX_HOSTNAME (64)
40 
41 struct OSAPI_System;
42 
43 /*e \defgroup OSAPI_SystemClass OSAPI System
44  \ingroup OSAPIModule
45 
46  \brief Abstract System API.
47 
48  \details The System is defined as the physical or virtual
49  execution environment and implements functions that are not necessarily
50  provided by the operating system. For example, a custom embedded board may
51  include a special real-time clock which is synchronized via GPS, but is
52  not available via a regular OS system call.
53 */
54 
55 
56 /*e \ingroup OSAPI_SystemClass
57  *
58  * start timer definition
59  */
60 FUNCTION_MUST_TYPEDEF(
62 (*OSAPI_System_start_timer_T)(OSAPI_Timer_T self,
63  OSAPI_TimerTickHandlerFunction tick_handler)
64 )
65 
66 /*e \ingroup OSAPI_SystemClass
67  *
68  * stop timer definition
69  */
70 FUNCTION_SHOULD_TYPEDEF(
72 (*OSAPI_System_stop_timer_T)(OSAPI_Timer_T self)
73 )
74 
75 /*e \ingroup OSAPI_SystemClass
76  *
77  * get timer resolution
78  */
79 FUNCTION_SHOULD_TYPEDEF(
80 RTI_INT32
82 )
83 
84 /*e \ingroup OSAPI_SystemClass
85  *
86  * get time
87  */
88 FUNCTION_SHOULD_TYPEDEF(
91 )
92 
93 /*e \ingroup OSAPI_SystemClass
94  *
95  * initialize
96  */
97 FUNCTION_SHOULD_TYPEDEF(
100 )
101 
102 /*e \ingroup OSAPI_SystemClass
103  *
104  * finalize
105  */
106 FUNCTION_SHOULD_TYPEDEF(
107 RTI_BOOL
109 )
110 
111 /*e \ingroup OSAPI_SystemClass
112  *
113  * get_hostname
114  */
115 FUNCTION_MUST_TYPEDEF(
116 RTI_BOOL
117 (*OSAPI_System_get_hostname_T)(char *const hostname)
118 )
119 
120 struct OSAPI_SystemUUID;
121 
122 typedef void
123 (*OSAPI_System_generate_uuid_T)(struct OSAPI_SystemUUID *uuid_out);
124 
125 /*e \ingroup OSAPI_SystemClass
126  *
127  * System Interface class
128  *
129  * The methods in this interface are called by the corresponding
130  * OSAPI_System function. For example, OSAPI_System_get_time() calls
131  * system->get_time().
132  *
133  */
135 {
136  /*e \ingroup OSAPI_SystemClass
137  *
138  * Refer to \ref OSAPI_System_start_timer for signature
139  * and semantics.
140  */
142 
143  /*e \ingroup OSAPI_SystemClass
144  *
145  * Refer to \ref OSAPI_System_stop_timer for signature
146  * and semantics.
147  */
149 
150  /*e \ingroup OSAPI_SystemClass
151  *
152  * Refer to \ref OSAPI_System_get_timer_resolution for signature
153  * and semantics.
154  */
156 
157  /*e \ingroup OSAPI_SystemClass
158  *
159  * Refer to \ref OSAPI_System_get_time for signature
160  * and semantics.
161  */
163 
164  /*e \ingroup OSAPI_SystemClass
165  *
166  * Refer to \ref OSAPI_System_initialize for signature
167  * and semantics.
168  */
170 
171  /*e \ingroup OSAPI_SystemClass
172  *
173  * Refer to \ref OSAPI_System_finalize for signature
174  * and semantics.
175  */
177 
178  /*e \ingroup OSAPI_SystemClass
179  *
180  * Refer to \ref OSAPI_System_generate_uuid for signature
181  * and semantics.
182  */
183  OSAPI_System_generate_uuid_T generate_uuid;
184 
185  /*e\ingroup OSAPI_SystemClass
186  *
187  * Refer to \ref OSAPI_System_get_hostname for signature
188  * and semantics.
189  */
191 };
192 
193 #define OSAPI_SystemI_INITIALIZER \
194 {\
195  NULL,\
196  NULL,\
197  NULL,\
198  NULL,\
199  NULL,\
200  NULL,\
201  NULL,\
202  NULL \
203 }
204 
205 extern OSAPIDllVariable struct OSAPI_System *OSAPI_System_gv_System;
206 
207 /*e \ingroup OSAPI_SystemClass
208  * \brief Set system interface
209  *
210  * \details
211  * This function sets the system interface, overriding the current system
212  * interace.
213  *
214  * \param [in] intf - The new system interface
215  *
216  * \return RTI_TRUE on success, RTI_FALSE on failure.
217  */
218 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
220 
221 /*e \ingroup OSAPI_SystemClass
222  * \brief Get the current system interface
223  *
224  * \details
225  * This function returns the current system interface
226  *
227  * \param [out] intf - The current system interface
228  *
229  * \return RTI_TRUE on success, RTI_FALSE on failure.
230  */
231 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
233 
234 /*e \ingroup OSAPI_SystemClass
235  *
236  * System listener
237  */
238 FUNCTION_MUST_TYPEDEF(
239 RTI_BOOL
240 (*OSAPI_System_on_system_initialize_T)(void *listener_data,struct OSAPI_System *system)
241 )
242 
243 typedef void
244 (*OSAPI_System_on_system_finalize_T)(void *listener_data,struct OSAPI_System *system);
245 
246 /*e \ingroup OSAPI_SystemClass
247  *
248  * System listener
249  */
251 {
252  void *listener_data;
253  OSAPI_System_on_system_initialize_T on_system_initialize;
254  OSAPI_System_on_system_finalize_T on_system_finalize;
255 };
256 
257 #define OSAPI_SystemListener_INITIALIZER \
258 {\
259  NULL,\
260  NULL,\
261  NULL,\
262 }
263 
264 /*e \ingroup OSAPI_SystemClass
265  * \brief Install a system listeners
266  *
267  * \details
268  *
269  * The system listers gets called during the life-time of the system
270  * Only listeners which are non-NULL are called, thus it is ok to install
271  * a partially set listener structure. System listeners can be installed
272  * until the system has been initialized by calling OSAPI_System_initialize.
273  * This function is not considered thread-safe. The listener value should
274  * always be initialized with OSAPI_SystemListener_DEFAULT before use.
275  *
276  * \param [in] listener System listeners to call
277  *
278  * \return RTI_TRUE on success, RTI_FALSE on failure
279  */
280 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
282 
283 /*e \ingroup OSAPI_SystemClass
284  * \brief Get current system listeners
285  *
286  * \details
287  * Return the current set of system listeners. This function is not thread-safe.
288  *
289  * \param[in] listener System listeners structure to fill in.
290  *
291  * \return RTI_TRUE on success, RTI_FALSE on failure.
292  */
293 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
295 
296 /*e \ingroup OSAPI_SystemClass
297  *
298  * System properties
299  */
301 {
302  /*e
303  * \brief Set the timer properties
304  */
305  struct OSAPI_TimerProperty timer_property;
306 
307  /*e
308  * \brief Set the hostname for the node.
309  *
310  * \details
311  * \rtime uses this name when it announces itself on the
312  * network. This name is used by other RTI products.
313  */
314  char hostname[OSAPI_SYSTEM_MAX_HOSTNAME];
315 };
316 
317 #define OSAPI_SystemProperty_INITIALIZER \
318 {\
319  OSAPI_TimerProperty_INITIALIZER,\
320  {0}\
321 }
322 
323 /*e \ingroup OSAPI_SystemClass
324  * \brief UUID definition
325  *
326  * Abstract UUID object. 128-bit value.
327  */
329 {
330  RTI_UINT32 value[4];
331 };
332 
333 struct OSAPI_System;
334 
335 /*e \ingroup OSAPI_SystemClass
336  \brief Generate a unique universal identifier (UUID)
337 */
338 OSAPIDllExport void
340 
341 /*e \ingroup OSAPI_SystemClass
342  \brief Get the current system time.
343 
344  \details In general, the system time is used by components to correlate both
345  internal and external events, such as data reception and ordering. Thus,
346  it is recommended that this function returns the real time. However, it is not
347  strictly required.
348 
349  Notes:
350  - It is assumed that the time returned by get_time is monotonically
351  increasing. It it up to the implementation of this function to ensure this
352  holds true.
353  - It is ok to return the same time as the last call.
354  - The clock used to report real-time can be different than the clock used to
355  support start_timer and stop_timer.
356 
357  @param[out] now Time in NtpTime format.
358 
359  @return RTI_TRUE on success, RTI_FALSE on failure.
360 
361  @pre Initialized system.
362 
363  @exception None.
364 
365  @mtsafety SAFE
366 */
367 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
369 
370 /*e \ingroup OSAPI_SystemClass
371  \brief Get the resolution of the clock driving the timer in nano seconds.
372 
373  \details
374 
375  This function must return the frequency of the system timer used to implement
376  OSAPI_SystemI::start_timer and OSAPI_SystemI::stop_timer API.
377 
378  @return timer resolution in nanoseconds.
379 
380 */
381 OSAPIDllExport RTI_INT32
383 
384 /*e \ingroup OSAPI_SystemClass
385 
386  \brief Start the timer.
387 
388  @param [in] self Timer object.
389 
390  @param [in] tick_handler Timer handle.
391 
392  @pre Initialized system.
393 */
394 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
395 OSAPI_System_start_timer(OSAPI_Timer_T self,
396  OSAPI_TimerTickHandlerFunction tick_handler);
397 
398 /*e \ingroup OSAPI_SystemClass
399  \brief Stop the timer.
400 
401  @param [in] self Timer
402 
403  @return RTI_TRUE on success, RTI_FALSE on failure.
404 
405  @pre Initialized system.
406 */
407 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
408 OSAPI_System_stop_timer(OSAPI_Timer_T self);
409 
410 /*e \ingroup OSAPI_SystemClass
411  \brief Initialize the system.
412 
413  \details
414 
415  This function initializes the system and calls the port specific initialize
416  method first. The port specific initialization method must return RTI_TRUE
417  on success and RTI_FALSE on failure. A system can only be initialized once.
418 
419  @return RTI_TRUE on success, RTI_FALSE on failure.
420 */
421 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
423 
424 /*e \ingroup OSAPI_SystemClass
425  \brief Finalize the system.
426 
427  \details
428 
429  This function finalizes the system and calls the port specific finalize
430  method last. The port specific initialization method must return RTI_TRUE
431  on success and RTI_FALSE on failure.
432 
433  @return RTI_TRUE on success, RTI_FALSE on failure.
434 */
435 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
437 
438 /*e \ingroup OSAPI_SystemClass
439  \brief Get the system properties
440 
441  @param [out] property
442 
443  @return RTI_TRUE on success, RTI_FALSE on failure.
444 */
445 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
447 
448 /*e \ingroup OSAPI_SystemClass
449  \brief Set the system properties.
450 
451  \details
452  The system properties can be set until the system is initialized by
453  calling \ref OSAPI_System_initialize()
454 
455  @param [in] property
456 
457  @return RTI_TRUE on success, RTI_FALSE on failure.
458 */
459 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
461 
462 /*e \ingroup OSAPI_SystemClass
463  \brief Get the native system interface
464 
465  \details
466 
467  This function must fill in the interface structure and assign the
468  following methods:
469 
470  <ul>
471  <li> \ref OSAPI_SystemI::get_timer_resolution
472  <li> \ref OSAPI_SystemI::get_time
473  <li> \ref OSAPI_SystemI::start_timer
474  <li> \ref OSAPI_SystemI::stop_timer
475  <li> \ref OSAPI_SystemI::generate_uuid
476  <li> \ref OSAPI_SystemI::get_hostname
477  <li> \ref OSAPI_SystemI::initialize
478  <li> \ref OSAPI_SystemI::finalize
479  </ul>
480 
481  @param [out] intf The native system interface
482 */
483 OSAPIDllExport void
485 
486 /*e \ingroup OSAPI_SystemClass
487  \brief Return next ID
488 
489  @mtsafety UNSAFE
490 */
491 OSAPIDllExport RTI_INT32
493 
494 /*e \ingroup OSAPI_SystemClass
495  \brief Get the hostname
496 
497  \details Get the hostname
498 
499  @param[inout] hostname The buffer to store the hostname. Must be at
500  least OSAPI_SYSTEM_MAX_HOSTNAME bytes. If the
501  actual hostname is longer than
502  OSAPI_SYSTEM_MAX_HOSTNAME bytes (including \0) the
503  hostname is truncated.
504 
505  @pre Initialized system.
506 
507  @exception None.
508 
509  @return RTI_TRUE on success, RTI_FALSE on failure.
510 
511  @mtsafety SAFE
512 */
513 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
514 OSAPI_System_get_hostname(char *const hostname);
515 
516 #ifdef __cplusplus
517 } /* extern "C" */
518 #endif
519 
520 #endif /* osapi_system_h */

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc