RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
osapi_log.h
1 /*
2  * FILE: osapi_log.h - Logging API
3  *
4  * (c) Copyright, Real-Time Innovations, 2008-2014.
5  *
6  * All rights reserved.
7  *
8  * No duplications, whole or partial, manual or electronic, may be made
9  * without express written permission. Any such copies, or
10  * revisions thereof, must display this notice unaltered.
11  * This code contains trade secrets of Real-Time Innovations, Inc.
12  *
13  * modification history
14  * --------------------
15  * 16sep2014,tk MICRO-887/PR#10752 Removed reference to removed function
16  * 22sep2011,tk Updated
17  * 23sep2008,yy Created
18  *
19  */
20 /*ci
21  * \file
22  * \brief OSAPI Log API
23  * \defgroup OSAPILogClass OSAPI Logging
24  */
25 #ifndef osapi_log_h
26 #define osapi_log_h
27 
28 #ifndef osapi_dll_h
29 #include "osapi/osapi_dll.h"
30 #endif /* */
31 #ifndef osapi_thread_h
32 #include "osapi/osapi_thread.h"
33 #endif /* */
34 #ifndef osapi_heap_h
35 #include "osapi/osapi_heap.h"
36 #endif /* */
37 #ifndef osapi_system_h
38 #include "osapi/osapi_system.h"
39 #endif /* */
40 #ifndef osapi_stdio_h
41 #include "osapi/osapi_stdio.h"
42 #endif /* */
43 
44 #ifdef __cplusplus
45 extern "C"
46 {
47 #endif
48 
49 /******************************************************************************
50  * OSAPI Error codes
51  ******************************************************************************/
52 
53 #ifndef RTI_MODULE_NAME
54 #define RTI_MODULE_NAME "undefined"
55 #endif
56 
57 #define OSAPI_LOG_MSG_PN_X2_STD_PARAM RTI_MODULE_NAME,\
58  __FILE__,__FUNCTION__, __LINE__
59 
60 /*ce
61  * \defgroup OSAPILogCodesClass OSAPI
62  * \ingroup LoggingModule
63  *
64  * \details
65  * The logging API provides a number of functions for logging different
66  * types of events. There are 3 types of events:
67  *
68  * info - This type is for informational purposes
69  *
70  * warning - This type does not necessarily cause any functional behavior,
71  * but could indicate an unexpected situation has been handled
72  * or performance could be affected.
73  *
74  * error - This indicated an error condition that has functional impact
75  * and could not be dealt with.
76  *
77  * Each log message has a header using the following format:
78  *
79  * \verbatim
80  * 1 2 13 16
81  * %+--------------------------------+
82  * %|x| type | module | error_code |
83  * %|--------------------------------+
84  * %|MN|FN|LN|F| resvd | length |
85  * %|--------------------------------+
86  * %| line number (LN=1) |
87  * %|--------------------------------+
88  * %| module name (MN=1) |
89  * %|--------------------------------+
90  * %| function name (FN=1) |
91  * %|--------------------------------+
92  * %| format (F=1) |
93  * %|--------------------------------+
94  * %| payload (F=1) |
95  * %|--------------------------------+
96  * \endverbatim
97  *
98  * <ul>
99  * <li> 4 bits for length of payload, in 32-bit ints
100  * <li> 4 bits for message type (error, warning, etc)
101  * <li> 8 bits for module
102  * <li> 1 bit for extended format (not in use)
103  * <li> 15 bits for error code
104  * </ul>
105  *
106  * Example Log Header: 0x1203005d
107  * <ul>
108  * <li> length: 0x1 one parameter
109  * <li> type: 0x2 RTI Error
110  * <li> module: 0x03 DDS_C module
111  * <li> X=0: Not extended format
112  * <li> error code: 0x005d LOG_FAIL_CREATE_PUBLISHER_TABLE
113  * </ul>
114  *
115  * \brief OS API. ModuleID = 0
116  */
117 
118 /******************************************************************************
119  * OSAPI Log Modules
120  ******************************************************************************/
121 /*ce \def OSAPI_LOG_BASE
122  * \brief Log Id base-number
123  */
124 #define OSAPI_LOG_BASE (0)
125 
126 /*ce \def REDA_LOG_BASE
127  * \brief REDA Module
128  */
129 #define REDA_LOG_BASE (1 << 16)
130 
131 /*ce \def DB_LOG_BASE
132  * \brief DB Module
133  */
134 #define DB_LOG_BASE (2 << 16)
135 
136 /*ce \def RT_LOG_BASE
137  * \brief RT Module
138  */
139 #define RT_LOG_BASE (3 << 16)
140 
141 /*ce \def NETIO_LOG_BASE
142  * \brief NETIO Module
143  */
144 #define NETIO_LOG_BASE (4 << 16)
145 
146 /*ce \def UDP_LOG_BASE
147  * \brief UDP Module, same as NETIO
148  */
149 #define UDP_LOG_BASE NETIO_LOG_BASE
150 
151 /*ce \def CDR_LOG_BASE
152  * \brief CDR Module
153  */
154 #define CDR_LOG_BASE (5 << 16)
155 
156 /*ce \def RTPS_LOG_BASE
157  * \brief RTPS Module
158  */
159 #define RTPS_LOG_BASE (6 << 16)
160 
161 /*ce \def DDSC_LOG_BASE
162  * \brief DDS_C Module
163  */
164 #define DDSC_LOG_BASE (7 << 16)
165 
166 /*ce \def RHSM_LOG_BASE
167  * \brief RHSM Module
168  */
169 #define RHSM_LOG_BASE (8 << 16)
170 
171 /*ce \def WHSM_LOG_BASE
172  * \brief WHSM Module
173  */
174 #define WHSM_LOG_BASE (9 << 16)
175 
176 /*ce \def DPSE_LOG_BASE
177  * \brief DPSE Module
178  */
179 #define DPSE_LOG_BASE (10 << 16)
180 
181 /*ce \def DPDE_LOG_BASE
182  * \brief DPDE Module
183  */
184 #define DPDE_LOG_BASE (11 << 16)
185 
186 /*ce
187  * \brief Retrieving the next error code failed
188  * \ingroup OSAPILogCodesClass
189  */
190 #define OSAPI_LOG_GET_NEXT_OBJECT_ID (1)
191 #define OSAPI_Log_get_next_object_id(level_) \
192 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_GET_NEXT_OBJECT_ID ,\
193  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
194 
195 /* System messages */
196 
197 /*ce
198  * \brief An error occured while setting the system properties
199  * \ingroup OSAPILogCodesClass
200  */
201 #define OSAPI_LOG_SYSTEM_SET_PROPERTY (2)
202 #define OSAPI_Log_system_set_property(level_) \
203 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SYSTEM_SET_PROPERTY,\
204  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
205 
206 /*ce
207  * \brief An error occured when starting the system timer
208  * \ingroup OSAPILogCodesClass
209  */
210 #define OSAPI_LOG_SYSTEM_TIMER_START (4)
211 #define OSAPI_Log_system_timer_start(level_) \
212 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SYSTEM_TIMER_START,\
213  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
214 
215 /*ce
216  * \brief An error occured when stopping the system timer
217  * \ingroup OSAPILogCodesClass
218  */
219 #define OSAPI_LOG_SYSTEM_TIMER_STOP (5)
220 #define OSAPI_Log_system_timer_stop(level_) \
221 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SYSTEM_TIMER_STOP,\
222  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
223 
224 /* THREAD message */
225 /*ce
226  * \brief An error when allocating the a thread object
227  * \ingroup OSAPILogCodesClass
228  */
229 #define OSAPI_LOG_THREAD_NEW (6)
230 #define OSAPI_Log_thread_new(level_) \
231 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_NEW,\
232  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
233 
234 /*ce
235  * \brief An error when creating the a thread object
236  * \ingroup OSAPILogCodesClass
237  */
238 #define OSAPI_LOG_THREAD_CREATE (7)
239 #define OSAPI_Log_thread_create(level_) \
240 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_CREATE,\
241  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
242 
243 /*ce
244  * \brief An error when creating thread sync semaphore
245  * \ingroup OSAPILogCodesClass
246  */
247 #define OSAPI_LOG_THREAD_SEM (8)
248 #define OSAPI_Log_thread_sem(level_,cs_,ss_) \
249 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_SEM,\
250  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
251  "cs=%p,ss=%p",(cs_),(ss_))
252 
253 /*ce
254  * \brief Failed to signal that a thread has been created
255  * \ingroup OSAPILogCodesClass
256  */
257 #define OSAPI_LOG_THREAD_EXEC_CREATE (9)
258 #define OSAPI_Log_thread_exec_create(level_) \
259 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_EXEC_CREATE,\
260  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
261 
262 /*ce
263  * \brief Failed to signal the start a created thread
264  * \ingroup OSAPILogCodesClass
265  */
266 #define OSAPI_LOG_THREAD_EXEC_START (10)
267 #define OSAPI_Log_thread_exec_start(level_,ss_) \
268 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_EXEC_START,\
269  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
270  "ss=%p",(ss_))
271 
272 /*ce
273  * \brief Failed to start a thread
274  * \ingroup OSAPILogCodesClass
275  */
276 #define OSAPI_LOG_THREAD_START (11)
277 #define OSAPI_Log_thread_start(level_,ss_) \
278 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_START,\
279  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
280  "ss=%p",(ss_))
281 
282 /*ce
283  * \brief Failed to destroy a thread
284  * \ingroup OSAPILogCodesClass
285  */
286 #define OSAPI_LOG_THREAD_DESTROY (12)
287 #define OSAPI_Log_thread_destroy(level_,ss_) \
288 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_DESTROY,\
289  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
290  "ss=%p",(ss_))
291 
292 /*ce
293  * \brief Failed to start an unstarted thread being destroyed
294  * \ingroup OSAPILogCodesClass
295  */
296 #define OSAPI_LOG_THREAD_DESTROY_NO_START (13)
297 #define OSAPI_Log_thread_destroy_no_start(level_,ss_) \
298 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_DESTROY_NO_START,\
299  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
300  "ss=%p",(ss_))
301 
302 /*ce
303  * \brief Failed wakeup of a thread being destroyed
304  * \ingroup OSAPILogCodesClass
305  */
306 #define OSAPI_LOG_THREAD_DESTROY_NO_WAKEUP (14)
307 #define OSAPI_Log_thread_destroy_no_wakeup(level_,ss_) \
308 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_DESTROY_NO_WAKEUP,\
309  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
310  "ss=%p",(ss_))
311 
312 /*ce
313  * \brief Failed initializing a thread
314  * \ingroup OSAPILogCodesClass
315  */
316 #define OSAPI_LOG_THREAD_INIT (15)
317 #define OSAPI_Log_thread_init(level_,sysrc_) \
318 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_INIT,\
319  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
320  "sysrc=%d",(sysrc_))
321 
322 /*ce
323  * \brief Failed to set scheduling policy of a thread
324  * \ingroup OSAPILogCodesClass
325  */
326 #define OSAPI_LOG_THREAD_SCHEDPARAM (16)
327 #define OSAPI_Log_thread_schedparam(level_,sysrc_,prio_) \
328 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_SCHEDPARAM ,\
329  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
330  "sysrc=%d,prio=%d",(sysrc_),(prio_))
331 
332 /*ce
333  * \brief Failed to get the scheduling policy of a thread
334  * \ingroup OSAPILogCodesClass
335  */
336 #define OSAPI_LOG_THREAD_GET_POLICY (17)
337 #define OSAPI_Log_thread_get_policy(level_,sysrc_) \
338 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_GET_POLICY,\
339  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
340  "sysrc=%d",(sysrc_))
341 
342 /*ce
343  * \brief Mismatch of scheduling policy of a created thread and the application
344  * thread
345  * \ingroup OSAPILogCodesClass
346  */
347 #define OSAPI_LOG_THREAD_POLICY_DIFFER (18)
348 #define OSAPI_Log_thread_policy_differ(level_,get_policy_,set_policy_) \
349 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_POLICY_DIFFER,\
350  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
351  "get_policy=%d,set_policy=%d",(get_policy_),(set_policy_))
352 
353 /*ce
354  * \brief Failed to map to native thread priority values
355  * \ingroup OSAPILogCodesClass
356  */
357 #define OSAPI_LOG_THREAD_PRIORITY_MAP (19)
358 #define OSAPI_Log_thread_priority_map(level_,min_,max_) \
359 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_THREAD_PRIORITY_MAP,\
360  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
361  "min=%d,max=%d",(min_),(max_))
362 
363 /* TIMER messages */
364 
365 /*ce
366  * \brief Failed to delete the Timer object
367  * \ingroup OSAPILogCodesClass
368  */
369 #define OSAPI_LOG_TIMER_DELETE (20)
370 #define OSAPI_Log_timer_delete(level_) \
371 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_DELETE ,\
372  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
373 
374 #define OSAPI_LOG_TIMER_TICK (21)
375 
376 /*ce
377  * \brief Failed taking or giving the Timer mutex
378  * \ingroup OSAPILogCodesClass
379  */
380 #define OSAPI_LOG_TIMER_TICK_MUTEX (22)
381 #define OSAPI_Log_timer_tick_mutex(level_,mutex_,take_) \
382 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_TICK_MUTEX,\
383  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
384  "mutex=%p,take=%d",(mutex_),(take_))
385 
386 #define OSAPI_LOG_TIMER_CREATE_TIMEOUT (23)
387 
388 #define OSAPI_LOG_TIMER_UPDATE_TIMEOUT (24)
389 
390 #define OSAPI_LOG_TIMER_DELETE_TIMEOUT (25)
391 
392 
393 /*ce
394  * \brief Failed to return user data for a timeout due to mismatched epochs
395  * \ingroup OSAPILogCodesClass
396  */
397 #define OSAPI_LOG_TIMER_GET_USER_DATA_EPOCH (27)
398 #define OSAPI_Log_timer_get_user_data_epoch(level_,h_,e_,e1_,e2_) \
399 OSAPI_Log_msg_pN_X2( (level_),OSAPI_LOG_TIMER_GET_USER_DATA_EPOCH,\
400  OSAPI_LOG_MSG_PN_X2_STD_PARAM,4,\
401  "h=%p,e=%d,e1=%d,e2=%d",(h_),(e_),(e1_),(e2_))
402 
403 /*ce
404  * \brief Failed to allocate memory for a new Timer
405  * \ingroup OSAPILogCodesClass
406  */
407 #define OSAPI_LOG_TIMER_NEW (28)
408 #define OSAPI_Log_timer_new(level_) \
409 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_NEW,\
410  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
411 
412 /*ce
413  * \brief Failed to allocate memory for a new Timer entry
414  * \ingroup OSAPILogCodesClass
415  */
416 #define OSAPI_LOG_TIMER_NEW_ENTRY (29)
417 #define OSAPI_Log_timer_new_entry(level_) \
418 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_NEW_ENTRY,\
419  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
420 
421 /*ce
422  * \brief Failed to allocate memory for a new Timer wheel
423  * \ingroup OSAPILogCodesClass
424  */
425 #define OSAPI_LOG_TIMER_NEW_WHEEL (30)
426 #define OSAPI_Log_timer_new_wheel(level_,slots_) \
427 OSAPI_Log_msg_pN_X2( (level_),OSAPI_LOG_TIMER_NEW_WHEEL,\
428  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
429  "slots=%d",(slots_))
430 
431 /*ce
432  * \brief Failed to create a new Timer mutex
433  * \ingroup OSAPILogCodesClass
434  */
435 #define OSAPI_LOG_TIMER_NEW_MUTEX (31)
436 #define OSAPI_Log_timer_new_mutex(level_) \
437 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_NEW_MUTEX,\
438  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
439 
440 /*ce
441  * \brief Failed to start a new Timer being created
442  * \ingroup OSAPILogCodesClass
443  */
444 #define OSAPI_LOG_TIMER_NEW_START_TIMER (32)
445 #define OSAPI_Log_timer_new_start_timer(level_,timer_,ticr_) \
446 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_NEW_START_TIMER,\
447  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
448  "timer=%p,ticr=%d",(timer_),(ticr_))
449 
450 /*ce
451  * \brief Failed to stop a Timer being deleted
452  * \ingroup OSAPILogCodesClass
453  */
454 #define OSAPI_LOG_TIMER_DELETE_STOP_TIMER (33)
455 #define OSAPI_Log_timer_delete_stop_timer(level_,timer_) \
456 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_DELETE_STOP_TIMER,\
457  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
458  "timer=%p",(timer_))
459 
460 /*ce
461  * \brief Failed to delete the Timer mutex
462  * \ingroup OSAPILogCodesClass
463  */
464 #define OSAPI_LOG_TIMER_DELETE_MUTEX (34)
465 #define OSAPI_Log_timer_delete_mutex(level_,timer_) \
466 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_TIMER_DELETE_MUTEX ,\
467  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
468  "timer=%p",(timer_))
469 
470 /*ce
471  * \brief Failed to take or give a Timer mutex
472  * \ingroup OSAPILogCodesClass
473  */
474 #define OSAPI_LOG_TIMER_MUTEX (35)
475 #define OSAPI_Log_timer_mutex(level_,mutex_,take_) \
476 OSAPI_Log_msg_pN_X2( (level_),OSAPI_LOG_TIMER_MUTEX,\
477  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
478  "mutex=%p,take=%d",(mutex_),(take_))
479 
480 /* Semaphore messages */
481 
482 /*ce
483  * \brief Failed to delete a semaphore
484  * \ingroup OSAPILogCodesClass
485  */
486 #define OSAPI_LOG_SEMAPHORE_DELETE (36)
487 #define OSAPI_Log_semaphore_delete(level_,sysrc_) \
488 OSAPI_Log_msg_pN_X2( (level_),OSAPI_LOG_SEMAPHORE_DELETE,\
489  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
490  "sysrc=%d",(sysrc_))
491 
492 /*ce
493  * \brief Failed to create a semaphore
494  * \ingroup OSAPILogCodesClass
495  */
496 #define OSAPI_LOG_SEMAPHORE_NEW (37)
497 #define OSAPI_Log_semaphore_new(level_) \
498 OSAPI_Log_msg_pN_X2( (level_),OSAPI_LOG_SEMAPHORE_NEW,\
499  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
500 
501 /*ce
502  * \brief Failed to initialize a new semaphore
503  * \ingroup OSAPILogCodesClass
504  */
505 #define OSAPI_LOG_SEMAPHORE_NEW_INIT (38)
506 #define OSAPI_Log_semaphore_new_init(level_,sysrc_) \
507 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SEMAPHORE_NEW_INIT,\
508  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
509  "sysrc=%d",(sysrc_))
510 
511 /*ce
512  * \brief Failed to give a semaphore
513  * \ingroup OSAPILogCodesClass
514  */
515 #define OSAPI_LOG_SEMAPHORE_GIVE (39)
516 #define OSAPI_Log_semaphore_give(level_,sysrc_) \
517 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SEMAPHORE_GIVE,\
518  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
519  "sysrc=%d",(sysrc_))
520 
521 /*ce
522  * \brief Failed to take a semaphore
523  * \ingroup OSAPILogCodesClass
524  */
525 #define OSAPI_LOG_SEMAPHORE_TAKE (40)
526 #define OSAPI_Log_semaphore_take(level_,sysrc_) \
527 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SEMAPHORE_TAKE,\
528  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
529  "sysrc=%d",(sysrc_))
530 
531 /* Mutex messages */
532 
533 /*ce
534  * \brief Failed to delete a mutex
535  * \ingroup OSAPILogCodesClass
536  */
537 #define OSAPI_LOG_MUTEX_DELETE (41)
538 #define OSAPI_Log_mutex_delete(level_,sysrc_) \
539 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_MUTEX_DELETE,\
540  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
541  "sysrc=%d",(sysrc_))
542 
543 /*ce
544  * \brief Failed to create a mutex
545  * \ingroup OSAPILogCodesClass
546  */
547 #define OSAPI_LOG_MUTEX_NEW (42)
548 #define OSAPI_Log_mutex_new(level_) \
549 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_MUTEX_NEW,\
550  OSAPI_LOG_MSG_PN_X2_STD_PARAM,0)
551 
552 /*ce
553  * \brief Failed to take a mutex
554  * \ingroup OSAPILogCodesClass
555  */
556 #define OSAPI_LOG_MUTEX_TAKE (43)
557 #define OSAPI_Log_mutex_take(level_,sysrc_) \
558 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_MUTEX_TAKE,\
559  OSAPI_LOG_MSG_PN_X2_STD_PARAM , NULL, __LINE__,1,\
560  "sysrc=%d",(sysrc_))
561 
562 /*ce
563  * \brief Failed to give a mutex
564  * \ingroup OSAPILogCodesClass
565  */
566 #define OSAPI_LOG_MUTEX_GIVE (44)
567 #define OSAPI_Log_mutex_give(level_,sysrc_) \
568 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_MUTEX_GIVE,\
569  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
570  "sysrc=%d",(sysrc_))
571 
572 /*ce
573  * \brief Failed to initialize a mutex
574  * \ingroup OSAPILogCodesClass
575  */
576 #define OSAPI_LOG_MUTEX_INIT (45)
577 #define OSAPI_Log_mutex_init(level_,sysrc_) \
578 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_MUTEX_INIT,\
579  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
580  "sysrc=%d",(sysrc_))
581 
582 /* HEAP */
583 
584 /*ce
585  * \brief Failed to allocate a buffer from the heap
586  * \ingroup OSAPILogCodesClass
587  */
588 #define OSAPI_LOG_HEAP_INTERNAL_ALLOCATE (46)
589 #define OSAPI_Log_heap_internal_allocate(level_,s_,a_) \
590 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_HEAP_INTERNAL_ALLOCATE,\
591  OSAPI_LOG_MSG_PN_X2_STD_PARAM,2,\
592  "s=%u,a=%d",(s_),(a_))
593 
594 #define OSAPI_LOG_HEAP_FREE (47)
595 
596 /*ce
597  * \brief Failed to get current system time
598  * \ingroup OSAPILogCodesClass
599  */
600 #define OSAPI_LOG_SYSTEM_GET_TIME (48)
601 #define OSAPI_Log_system_get_time(level_,sysrc_) \
602 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_SYSTEM_GET_TIME,\
603  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
604  "sysrc=%d",(sysrc_))
605 
606 /*ce
607  * \brief Return the last recorded error-code for the calling thread
608  *
609  * \details
610  * This log-messages retrieves the last recorded error-code for the
611  * calling thread. It is used a function calls another function that
612  * fails.
613  *
614  * \ingroup OSAPILogCodesClass
615  */
616 #define OSAPI_LOG_LAST_RECORDED_ERROR (49)
617 #define OSAPI_Log_last_recorded_error(level_) \
618 OSAPI_Log_msg_pN_X2((level_),OSAPI_LOG_LAST_RECORDED_ERROR,\
619  OSAPI_LOG_MSG_PN_X2_STD_PARAM,1,\
620  "rc=%d",OSAPI_Log_get_last_error_code())
621 
622 /******************************************************************************/
623 
624 /******************************************************************************
625  * Log types
626  ******************************************************************************/
627 /*ci
628  * \ingroup OSAPILogClass
629  * \brief Log message as an error
630  */
631 typedef enum
632 {
633  OSAPI_LOGKIND_ERROR = 0,
634  OSAPI_LOGKIND_WARNING,
635  OSAPI_LOGKIND_INFO,
636  OSAPI_LOGKIND_PRECONDITION
637 } OSAPI_LogKind_T;
638 
639 typedef RTI_UINT32 OSAPI_LogEntryHeader_T;
640 typedef RTI_UINT32 OSAPI_LogEntryPayloadElement_T;
641 
642 #define OSAPI_LOG_HEADER_GET_X(hdr_) ((hdr_)>>31)
643 #define OSAPI_LOG_HEADER_GET_E(hdr_) ((hdr_)>>30 & 0x1)
644 #define OSAPI_LOG_HEADER_GET_TYPE(hdr_) (((hdr_) >>28) & 0x3)
645 #define OSAPI_LOG_HEADER_GET_MODULE(hdr_) (((hdr_) >>16) & 0xfff)
646 #define OSAPI_LOG_HEADER_GET_EC(hdr_) ((hdr_) & 0xffff)
647 
648 #define OSAPI_LOG_HEADER_SET_X(hdr_) ((hdr_) |= 0x80000000)
649 #define OSAPI_LOG_HEADER_CLR_X(hdr_) ((hdr_) &= ~0x80000000)
650 #define OSAPI_LOG_HEADER_SET_E(hdr_) ((hdr_) |= 0x40000000)
651 #define OSAPI_LOG_HEADER_SET_TYPE(hdr_,type_) ((hdr_) |= ((type_) << 28))
652 #define OSAPI_LOG_HEADER_SET_MODULE(hdr_,m_) ((hdr_) |= ((m_) << 16))
653 #define OSAPI_LOG_HEADER_SET_EC(hdr_,ec) ((hdr_) |= (ec_))
654 
655 #define OSAPI_LOG_STATUS_MN (0x80000000)
656 #define OSAPI_LOG_STATUS_SF (0x40000000)
657 #define OSAPI_LOG_STATUS_FN (0x20000000)
658 #define OSAPI_LOG_STATUS_LN (0x10000000)
659 #define OSAPI_LOG_STATUS_F (0x08000000)
660 
661 #define OSAPI_LOG_STATUS_ALL \
662  (OSAPI_LOG_STATUS_MN | \
663  OSAPI_LOG_STATUS_SF | \
664  OSAPI_LOG_STATUS_FN | \
665  OSAPI_LOG_STATUS_LN | \
666  OSAPI_LOG_STATUS_F)
667 
668 #define OSAPI_LOG_STATUS_NO_DATA \
669  (OSAPI_LOG_STATUS_MN | \
670  OSAPI_LOG_STATUS_SF | \
671  OSAPI_LOG_STATUS_FN | \
672  OSAPI_LOG_STATUS_LN)
673 
674 typedef struct OSAPI_LogEntry
675 {
676  /*ci
677  * \brief thread_id thread id of the thread that logged this
678  * message
679  */
680  OSAPI_ThreadId thread_id;
681 
682  /*ci
683  * \brief time this message was logged
684  */
685  OSAPI_NtpTime timestamp;
686 
687  /*ci
688  * \brief The error code
689  */
690  RTI_UINT32 error_code;
691 
692 } OSAPI_LogEntry_T;
693 
694 /*e
695  */
696 typedef enum
697 {
698  /* e \dref_LogVerbosity_OSAPI_LOG_VERBOSITY_SILENT */
699  OSAPI_LOG_VERBOSITY_SILENT = 0,
700  /* e \dref_LogVerbosity_OSAPI_LOG_VERBOSITY_ERROR */
701  OSAPI_LOG_VERBOSITY_ERROR = 1,
702  /* e \dref_LogVerbosity_OSAPI_LOG_VERBOSITY_WARNING */
703  OSAPI_LOG_VERBOSITY_WARNING = 2,
704  /* e \dref_LogVerbosity_OSAPI_LOG_VERBOSITY_DEBUG */
705  OSAPI_LOG_VERBOSITY_DEBUG = 3
706 } OSAPI_LogVerbosity_T;
707 
708 /*ce
709  * \ingroup OSAPILogClass
710  * \brief Configuration of logging functionality
711  */
712 struct OSAPI_LogProperty
713 {
714  /*ce
715  *
716  * \brief The maximum number of bytes allocated to the log buffer.
717  *
718  * \details
719  * Log entries are of variable length. When this limit has been reached,
720  * no more log entries can be stored unless the buffer is cleared.
721  */
722  RTI_SIZE_T max_buffer_size;
723 
724  /*ce \brief Bitmap to control the fidelity of what is stored in the log
725  * entry
726  */
727  RTI_INT32 log_detail;
728 };
729 
730 
731 #define OSAPI_LOG_DETAIL_MODULENAME (0x80000000)
732 #define OSAPI_LOG_DETAIL_SOURCEFILE (0x40000000)
733 #define OSAPI_LOG_DETAIL_LINENUMBER (0x20000000)
734 #define OSAPI_LOG_DETAIL_FUNCTIONAME (0x10000000)
735 #define OSAPI_LOG_DETAIL_FORMAT (0x08000000)
736 #define OSAPI_LOG_DETAIL_DATA_ONLY (0x04000000)
737 
738 #define OSAPI_LOG_DETAIL_ALL \
739  (OSAPI_LOG_DETAIL_MODULENAME | \
740  OSAPI_LOG_DETAIL_SOURCEFILE | \
741  OSAPI_LOG_DETAIL_LINENUMBER | \
742  OSAPI_LOG_DETAIL_FUNCTIONAME | \
743  OSAPI_LOG_DETAIL_FORMAT | \
744  OSAPI_LOG_DETAIL_DATA_ONLY)
745 
746 #define OSAPI_LOG_DETAIL_NO_DATA \
747  (OSAPI_LOG_DETAIL_MODULENAME | \
748  OSAPI_LOG_DETAIL_SOURCEFILE | \
749  OSAPI_LOG_DETAIL_LINENUMBER | \
750  OSAPI_LOG_DETAIL_FUNCTIONAME )
751 
752 #define OSAPI_LogProperty_INIITALIZER \
753 {\
754  16*1024,\
755  OSAPI_LOG_DETAIL_ALL\
756 }
757 
758 typedef void
759 (*OSAPI_TraceHandler_T)(RTI_UINT32 trace_mask,
760  void *param,
761  RTI_INT32 context,
762  const char *const module,
763  const char *const file,
764  const char *const function,
765 
766  RTI_INT32 line_no,...);
767 
768 OSAPIDllVariable extern OSAPI_TraceHandler_T OSAPI_gv_TraceFunction;
769 OSAPIDllVariable extern void* OSAPI_gv_TraceFunctionParam;
770 OSAPIDllVariable extern RTI_UINT32 OSAPI_gv_TraceMask;
771 
772 /*ce
773  * \ingroup OSAPILogClass
774  * \brief Optional user-defined function for processing new log messages
775  *
776  * \details Definition of a function that can be installed with the logger and
777  * that will be called for each new log event.
778  *
779  * The handler is set by OSAPI_Log_set_log_handler.
780  *
781  * When called, provides parameters containing the raw log entry and additional
782  * optional information.
783  *
784  *
785  * \param[in] param User-defined payload
786  * \param[in] msg Log entry
787  * \param[in] kind Kind of log message
788  * \param[in] ec Unique error code of log message
789  * \param[in] module Module of log message
790  * \param[in] file Name of source file. Optional.
791  * \param[in] func Name of function. Optional.
792  * \param[in] line Line number. Optional.
793  * \param[in] argc Variable length argument count
794  * \param[in] ap Variable length argument list
795  */
796 typedef void
797 (*OSAPI_LogHandler_T)(void *param,OSAPI_LogEntry_T *msg,OSAPI_LogKind_T kind,
798  RTI_INT32 ec,
799  const char *const module,
800  const char *const file,
801  const char *const func,
802  RTI_INT32 line,
803  RTI_INT32 argc,
804  va_list ap);
805 
806 typedef void
807 (*OSAPI_LogDisplay_T)(void *param,OSAPI_LogEntry_T *msg);
808 
809 OSAPIDllVariable extern OSAPI_LogHandler_T OSAPI_gv_LogFunction;
810 OSAPIDllVariable extern void* OSAPI_gv_LogFunctionParam;
811 
812 OSAPIDllVariable extern OSAPI_LogDisplay_T OSAPI_gv_LogDisplayFunction;
813 OSAPIDllVariable extern void* OSAPI_gv_LogDisplayFunctionParam;
814 
815 /*ce
816  * \ingroup OSAPILogClass
817  * \brief Install a log handler
818  *
819  * \details
820  * The log functionality allows the user to specify a log handler. The log
821  * handler is a function which is called for every logged event. It is up
822  * to the user to decide what to do with the log message. The handler is
823  * a global function pointer.
824  *
825  * \param [in] handler Pointer to log handler function
826  * \param [in] param Parameter passed to the log handler function. This
827  * parameter is transparent to the log functionality.
828  *
829  * \return RTI_TRUE on success, RTI_FALSE on failure
830  *
831  */
832 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
833 OSAPI_Log_set_log_handler(OSAPI_LogHandler_T handler,void *param);
834 
835 /*ce
836  * \ingroup OSAPILogClass
837  * \brief Return the current log handler
838  *
839  * \details
840  * Return the current log handler.
841  *
842  * \param [in] handler Pointer to store log handler function
843  * \param [in] param Pointer to store the current log handler parameter.
844  *
845  * \return RTI_TRUE on success, RTI_FALSE on failure
846  *
847  */
848 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
849 OSAPI_Log_get_log_handler(OSAPI_LogHandler_T *handler,void **param);
850 
851 /*ce
852  * \ingroup OSAPILogClass
853  * \brief Install a trace handler
854  *
855  * \details
856  * Install a custom trace handler. Traces are not stored in the log-buffer
857  * and is generally used to analyze behavior interactively. the default
858  * trace handler outputs the trace data to a console.
859  *
860  * \param [in] handler Pointer to trace handler function
861  * \param [in] param Parameter passed to the trace handler function. This
862  * parameter is transparent to the trace functionality.
863  *
864  * \return RTI_TRUE on success, RTI_FALSE on failure
865  *
866  */
867 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
868 OSAPI_Log_set_trace_handler(OSAPI_TraceHandler_T handler,void *param);
869 
870 /*ce
871  * \brief Return the trace handler
872  * \ingroup OSAPILogClass
873  *
874  * \details
875  * Return the current trace handler and trace parameter. This information
876  * can be used to daisy-chain calls to multiple trace-handlers.
877  *
878  * \param [in] handler Pointer to store trace handler function
879  * \param [in] param Pointer to store the trace handler parameter.
880  *
881  * \return RTI_TRUE on success, RTI_FALSE on failure
882  *
883  */
884 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
885 OSAPI_Log_get_trace_handler(OSAPI_TraceHandler_T *handler,void **param);
886 
887 /*ce
888  * \ingroup OSAPILogClass
889  * \brief Install a display handler
890  *
891  * \details
892  * The display handler is responsible for outputting log messages to a console.
893  *
894  * \param [in] handler Pointer to display function
895  * \param [in] param Parameter passed to the display handler function. This
896  * parameter is transparent to the log functionality.
897  *
898  * \return RTI_TRUE on success, RTI_FALSE on failure
899  *
900  */
901 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
902 OSAPI_Log_set_display_handler(OSAPI_LogDisplay_T handler,void *param);
903 
904 /*ce
905  * \brief Return the current display function
906  * \ingroup OSAPILogClass
907  *
908  * \details
909  * Return the current log handler.
910  *
911  * \param [in] handler Pointer to store display handler function
912  * \param [in] param Pointer to store the current display handler parameters.
913  *
914  * \return RTI_TRUE on success, RTI_FALSE on failure
915  *
916  */
917 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
918 OSAPI_Log_get_display_handler(OSAPI_LogDisplay_T *handler,void **param);
919 
920 /*ce
921  * \brief Initialize the log functionality
922  * \ingroup OSAPILogClass
923  *
924  * \details
925  * Dynamically allocates bytes for the log ring buffer. Also prints out endianness.
926  * If store_debug_logs is false, debug-level logs are printed to the console.
927  * 0Otherwise, the logs are stored in the log buffer.
928  * The log functionality must be initialized before any log messages can be
929  * stored. It should only be called once. Since debug logs can easily exhaust
930  * the log buffer, it can optionally be enabled. However, even if debug
931  * logging is disabled, the log handler function still has the option
932  * to store it.
933  *
934  * \param [in] property Configuration propery
935  *
936  * \return RTI_TRUE on success, RTI_FALSE on failure
937  */
938 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
939 OSAPI_Log_initialize(struct OSAPI_LogProperty *property);
940 
941 /*ce
942  * \ingroup OSAPILogClass
943  * \brief Finalize the log buffer
944  *
945  * \details
946  * This function release all memory allocated to the log buffer and release
947  * all resources associated with it.
948  *
949  * \return RTI_TRUE on success, RTI_FALSE on failure
950  *
951  * \sa \ref OSAPI_Log_initialize
952  */
953 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
954 OSAPI_Log_finalize(void);
955 
956 /*ce
957  * \ingroup OSAPILogClass
958  * \brief Set the log verbosity
959  *
960  * \details
961  * Change the log verbosity. The new setting takes immediate effect.
962  *
963  * \param [in] verbosity New log verbosity
964  *
965  */
966 OSAPIDllExport void
967 OSAPI_Log_set_verbosity(OSAPI_LogVerbosity_T verbosity);
968 
969 /*ce
970  * \ingroup OSAPILogClass
971  * \brief Set the trace mask
972  *
973  * \param [in] mask New trace mask
974  */
975 OSAPIDllExport void
976 OSAPI_Trace_set_trace_mask(RTI_UINT32 mask);
977 
978 
979 /*ci
980  * \ingroup OSAPILogClass
981  * \brief Create a log entry
982  *
983  * \details
984  * This function creates a new log entry.
985  *
986  * \param[in] kind The type of log message
987  * \param[in] error_code The error code to log
988  * \param[in] module The name of the module logging the error
989  * \param[in] file The name of the file the error occured
990  * \param[in] func The name of the function logging the error
991  * \param[in] line The line within file the error occured on
992  * \param[in] ... Optional list of additional error information
993  */
994 OSAPIDllExport void
995 OSAPI_Log_msg_pN_X2(OSAPI_LogKind_T kind,
996  RTI_INT32 error_code,
997  const char *const module,
998  const char *const file,
999  const char *const func,
1000  RTI_INT32 line,...);
1001 
1002 OSAPIDllExport void
1003 OSAPI_Log_precond(OSAPI_LogKind_T kind,
1004  RTI_INT32 error_code,
1005  const char *const module,
1006  const char *const file,
1007  const char *const func,
1008  RTI_INT32 line,...);
1009 
1010 /*ce
1011  * \ingroup OSAPILogClass
1012  * \brief Clear the log buffer
1013  *
1014  * \details
1015  * Clear the log buffer, all the current entries are lost
1016  *
1017  * \return RTI_TRUE on success, RTI_FALSE on failure
1018  */
1019 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
1020 OSAPI_Log_clear(void);
1021 
1022 
1023 /*ce
1024  * \ingroup OSAPILogClass
1025  * \brief Convert a log_entry to a string
1026  *
1027  * \details
1028  * This function converts a log entry to a string representation.
1029  *
1030  * \param[in] log_entry Log entry to convert to a string
1031  * \param[inout] buffer Pointer to string buffer to store the result in
1032  * \param[in] max_buffer The maximum size of buffer
1033  *
1034  * \return RTI_TRUE on success, RTI_FALSE on failure
1035  */
1036 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1037 OSAPI_Log_entry_to_string(OSAPI_LogEntry_T *log_entry,
1038  char *buffer,RTI_INT32 max_buffer);
1039 
1040 /*ce
1041  * \brief Returns the error code for a function that failed
1042  * \ingroup OSAPILogClass
1043  *
1044  * \details
1045  * Many functions returns RTI_FALSE or NULL on failure. In order to provide
1046  * additional information about reason for the failure fucntions may set
1047  * an additional error code. This function returns the last error-code
1048  * recorded for the calling thread.
1049  *
1050  * \return Last error-code recorded for this thread
1051  *
1052  */
1053 OSAPIDllExport RTI_INT32
1054 OSAPI_Log_get_last_error_code(void);
1055 
1056 /*ci
1057  * \brief Get the current log properties
1058  * \ingroup OSAPILogClass
1059  *
1060  * \details
1061  * Return the current log properties
1062  *
1063  * \param[out] property - Current log properties
1064  *
1065  * \sa OSAPI_Log_set_property
1066  */
1067 OSAPIDllExport void
1068 OSAPI_Log_get_property(struct OSAPI_LogProperty *property);
1069 
1070 /*ci
1071  * \brief Get the current log verbosity
1072  * \ingroup OSAPILogClass
1073  *
1074  * \return Current verbosity
1075  */
1076 OSAPIDllExport OSAPI_LogVerbosity_T
1077 OSAPI_Log_get_verbosity(void);
1078 
1079 #ifdef __cplusplus
1080 } /* extern "C" */
1081 #endif
1082 
1083 #include "osapi/osapi_log_impl.h"
1084 
1085 #endif /* osapi_log_h */
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc