include/dlt/dlt_user_macros.h

   1 /**
   2  * @licence app begin@
   3  * Copyright (C) 2012  BMW AG
   4  *
   5  * This file is part of GENIVI Project Dlt - Diagnostic Log and Trace console apps.
   6  *
   7  * Contributions are licensed to the GENIVI Alliance under one or more
   8  * Contribution License Agreements.
   9  *
  10  * \copyright
  11  * This Source Code Form is subject to the terms of the
  12  * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
  13  * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
  14  *
  15  *
  16  * \author Alexander Wenzel <alexander.aw.wenzel@bmw.de> BMW 2011-2012
  17  *
  18  * \file dlt_user_macros.h
  19  * For further information see http://www.genivi.org/.
  20  * @licence end@
  21  */
  22
  23 /*******************************************************************************
  24  **                                                                            **
  25  **  SRC-MODULE: dlt_user_macros.h                                             **
  26  **                                                                            **
  27  **  TARGET    : linux                                                         **
  28  **                                                                            **
  29  **  PROJECT   : DLT                                                           **
  30  **                                                                            **
  31  **  AUTHOR    : Alexander Wenzel Alexander.AW.Wenzel@bmw.de                   **
  32  **              Markus Klein                                                  **
  33  **                                                                            **
  34  **  PURPOSE   :                                                               **
  35  **                                                                            **
  36  **  REMARKS   :                                                               **
  37  **                                                                            **
  38  **  PLATFORM DEPENDANT [yes/no]: yes                                          **
  39  **                                                                            **
  40  **  TO BE CHANGED BY USER [yes/no]: no                                        **
  41  **                                                                            **
  42  *******************************************************************************/
  43
  44 /*******************************************************************************
  45  **                      Author Identity                                       **
  46  ********************************************************************************
  47  **                                                                            **
  48  ** Initials     Name                       Company                            **
  49  ** --------     -------------------------  ---------------------------------- **
  50  **  aw          Alexander Wenzel           BMW                                **
  51  **  mk          Markus Klein               Fraunhofer ESK                     **
  52  *******************************************************************************/
  53
  54 /*******************************************************************************
  55  **                      Revision Control History                              **
  56  *******************************************************************************/
  57
  58 /*
  59  * $LastChangedRevision: 1515 $
  60  * $LastChangedDate: 2010-12-13 09:18:54 +0100 (Mon, 13 Dec 2010) $
  61  * $LastChangedBy$
  62  Initials    Date         Comment
  63  aw          13.01.2010   initial
  64  */
  65
  66 #ifndef DLT_USER_MACROS_H
  67 #define DLT_USER_MACORS_H
  68
  69 #include "dlt_version.h"
  70
  71 /**
  72  \defgroup userapi DLT User API
  73  \addtogroup userapi
  74  \{
  75  */
  76
  77 /**************************************************************************************************
  78  * The folowing macros define a macro interface for DLT
  79  **************************************************************************************************/
  80
  81 /**
  82  * Create an object for a new context.
  83  * This macro has to be called first for every.
  84  * @param CONTEXT object containing information about one special logging context
  85  */
  86 #define DLT_DECLARE_CONTEXT(CONTEXT) \
  87 DltContext CONTEXT;
  88
  89 /**
  90  * Use an object of a new context created in another module.
  91  * This macro has to be called first for every.
  92  * @param CONTEXT object containing information about one special logging context
  93  */
  94 #define DLT_IMPORT_CONTEXT(CONTEXT) \
  95 extern DltContext CONTEXT;
  96
  97 /**
  98  * Register application.
  99  * @param APPID application id with maximal four characters
 100  * @param DESCRIPTION ASCII string containing description
 101  */
 102 #define DLT_REGISTER_APP(APPID,DESCRIPTION) do {\
 103                 dlt_check_library_version(_DLT_PACKAGE_MAJOR_VERSION, _DLT_PACKAGE_MINOR_VERSION ); \
 104                 dlt_register_app( APPID, DESCRIPTION);} while(0)
 105
 106
 107 /**
 108  * Unregister application.
 109  */
 110 #define DLT_UNREGISTER_APP() do{\
 111         dlt_unregister_app();} while(0)
 112
 113 /**
 114  * Register context (with default log level and default trace status)
 115  * @param CONTEXT object containing information about one special logging context
 116  * @param CONTEXTID context id with maximal four characters
 117  * @param DESCRIPTION ASCII string containing description
 118  */
 119 #define DLT_REGISTER_CONTEXT(CONTEXT,CONTEXTID,DESCRIPTION) do{\
 120         dlt_register_context(&(CONTEXT), CONTEXTID, DESCRIPTION);} while(0)
 121
 122 /**
 123  * Register context with pre-defined log level and pre-defined trace status.
 124  * @param CONTEXT object containing information about one special logging context
 125  * @param CONTEXTID context id with maximal four characters
 126  * @param DESCRIPTION ASCII string containing description
 127  * @param LOGLEVEL log level to be pre-set for this context
 128  (DLT_LOG_DEFAULT is not allowed here)
 129  * @param TRACESTATUS trace status to be pre-set for this context
 130  (DLT_TRACE_STATUS_DEFAULT is not allowed here)
 131  */
 132 #define DLT_REGISTER_CONTEXT_LL_TS(CONTEXT,CONTEXTID,DESCRIPTION,LOGLEVEL,TRACESTATUS) do{\
 133         dlt_register_context_ll_ts(&(CONTEXT), CONTEXTID, DESCRIPTION, LOGLEVEL, TRACESTATUS);} while(0)
 134
 135 /**
 136  * Unregister context.
 137  * @param CONTEXT object containing information about one special logging context
 138  */
 139 #define DLT_UNREGISTER_CONTEXT(CONTEXT) do{\
 140         dlt_unregister_context(&(CONTEXT));} while(0)
 141
 142 /**
 143  * Register callback function called when injection message was received
 144  * @param CONTEXT object containing information about one special logging context
 145  * @param SERVICEID service id of the injection message
 146  * @param CALLBACK function pointer to callback function
 147  */
 148 #define DLT_REGISTER_INJECTION_CALLBACK(CONTEXT, SERVICEID, CALLBACK) do{\
 149         dlt_register_injection_callback(&(CONTEXT),SERVICEID, CALLBACK);} while(0)
 150
 151 /**
 152  * Send log message with variable list of messages (intended for verbose mode)
 153  * @param CONTEXT object containing information about one special logging context
 154  * @param LOGLEVEL the log level of the log message
 155  * @param ARGS variable list of arguments
 156  */
 157 #ifdef _MSC_VER
 158 /* DLT_LOG is not supported by MS Visual C++ */
 159 /* use function interface instead            */
 160 #else
 161 #define DLT_LOG(CONTEXT,LOGLEVEL,ARGS...) \
 162         do { \
 163                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 164                 { \
 165                         DltContextData log; \
 166                         if (dlt_user_log_write_start(&CONTEXT,&log,LOGLEVEL)>0) \
 167                         { \
 168                                 ARGS; \
 169                                 dlt_user_log_write_finish(&log); \
 170                         } \
 171                 } \
 172         } while(0)
 173 #endif
 174
 175 /**
 176  * Send log message with variable list of messages (intended for non-verbose mode)
 177  * @param CONTEXT object containing information about one special logging context
 178  * @param LOGLEVEL the log level of the log message
 179  * @param MSGID the message id of log message
 180  * @param ARGS variable list of arguments:
 181  calls to DLT_STRING(), DLT_BOOL(), DLT_FLOAT32(), DLT_FLOAT64(),
 182  DLT_INT(), DLT_UINT(), DLT_RAW()
 183  */
 184 #ifdef _MSC_VER
 185 /* DLT_LOG_ID is not supported by MS Visual C++ */
 186 /* use function interface instead               */
 187 #else
 188 #define DLT_LOG_ID(CONTEXT,LOGLEVEL,MSGID,ARGS...) \
 189         do { \
 190                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 191                 { \
 192                         DltContextData log; \
 193                         if (dlt_user_log_write_start_id(&CONTEXT,&log,LOGLEVEL,MSGID)>0) \
 194                         { \
 195                                 ARGS; \
 196                                 dlt_user_log_write_finish(&log); \
 197                         } \
 198                 } \
 199         } while(0)
 200 #endif
 201
 202 /**
 203  * Add string parameter to the log messsage.
 204  * @param TEXT ASCII string
 205  */
 206 #define DLT_STRING(TEXT) \
 207         dlt_user_log_write_string(&log,TEXT)
 208
 209 /**
 210  * Add constant string parameter to the log messsage.
 211  * @param TEXT Constant ASCII string
 212  */
 213 #define DLT_CSTRING(TEXT) \
 214         dlt_user_log_write_constant_string(&log,TEXT)
 215
 216 /**
 217  * Add utf8-encoded string parameter to the log messsage.
 218  * @param TEXT UTF8-encoded string
 219  */
 220 #define DLT_UTF8(TEXT) \
 221         dlt_user_log_write_utf8_string(&log,TEXT)
 222
 223 /**
 224  * Add boolean parameter to the log messsage.
 225  * @param BOOL_VAR Boolean value (mapped to uint8)
 226  */
 227 #define DLT_BOOL(BOOL_VAR) \
 228         dlt_user_log_write_bool(&log,BOOL_VAR)
 229
 230 /**
 231  * Add float32 parameter to the log messsage.
 232  * @param FLOAT32_VAR Float32 value (mapped to float)
 233  */
 234 #define DLT_FLOAT32(FLOAT32_VAR) \
 235         dlt_user_log_write_float32(&log,FLOAT32_VAR)
 236
 237 /**
 238  * Add float64 parameter to the log messsage.
 239  * @param FLOAT64_VAR Float64 value (mapped to double)
 240  */
 241 #define DLT_FLOAT64(FLOAT64_VAR) \
 242         dlt_user_log_write_float64(&log,FLOAT64_VAR)
 243
 244 /**
 245  * Add integer parameter to the log messsage.
 246  * @param INT_VAR integer value
 247  */
 248 #define DLT_INT(INT_VAR) \
 249         dlt_user_log_write_int(&log,INT_VAR)
 250
 251 #define DLT_INT8(INT_VAR) \
 252         dlt_user_log_write_int8(&log,INT_VAR)
 253
 254 #define DLT_INT16(INT_VAR) \
 255         dlt_user_log_write_int16(&log,INT_VAR)
 256
 257 #define DLT_INT32(INT_VAR) \
 258         dlt_user_log_write_int32(&log,INT_VAR)
 259
 260 #define DLT_INT64(INT_VAR) \
 261         dlt_user_log_write_int64(&log,INT_VAR)
 262
 263 /**
 264  * Add unsigned integer parameter to the log messsage.
 265  * @param UINT_VAR unsigned integer value
 266  */
 267 #define DLT_UINT(UINT_VAR) \
 268         dlt_user_log_write_uint(&log,UINT_VAR)
 269
 270 #define DLT_UINT8(UINT_VAR) \
 271         dlt_user_log_write_uint8(&log,UINT_VAR)
 272
 273 #define DLT_UINT16(UINT_VAR) \
 274         dlt_user_log_write_uint16(&log,UINT_VAR)
 275
 276 #define DLT_UINT32(UINT_VAR) \
 277         dlt_user_log_write_uint32(&log,UINT_VAR)
 278
 279 #define DLT_UINT64(UINT_VAR) \
 280         dlt_user_log_write_uint64(&log,UINT_VAR)
 281
 282 /**
 283  * Add binary memory block to the log messages.
 284  * @param BUF pointer to memory block
 285  * @param LEN length of memory block
 286  */
 287 #define DLT_RAW(BUF,LEN) \
 288         dlt_user_log_write_raw(&log,BUF,LEN)
 289
 290 /**
 291  * Trace network message
 292  * @param CONTEXT object containing information about one special logging context
 293  * @param TYPE type of network trace message
 294  * @param HEADERLEN length of network message header
 295  * @param HEADER pointer to network message header
 296  * @param PAYLOADLEN length of network message payload
 297  * @param PAYLOAD pointer to network message payload
 298  */
 299 #define DLT_TRACE_NETWORK(CONTEXT,TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD) \
 300     do { \
 301         if ((CONTEXT).trace_status_ptr && *((CONTEXT).trace_status_ptr)==DLT_TRACE_STATUS_ON) \
 302         { \
 303                 dlt_user_trace_network(&(CONTEXT),TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD); \
 304                 } \
 305     }while(0)
 306
 307 /**
 308  * Trace network message, allow truncation
 309  * @param CONTEXT object containing information about one special logging context
 310  * @param TYPE type of network trace message
 311  * @param HEADERLEN length of network message header
 312  * @param HEADER pointer to network message header
 313  * @param PAYLOADLEN length of network message payload
 314  * @param PAYLOAD pointer to network message payload
 315  */
 316 #define DLT_TRACE_NETWORK_TRUNCATED(CONTEXT,TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD) \
 317     do { \
 318         if ((CONTEXT).trace_status_ptr && *((CONTEXT).trace_status_ptr)==DLT_TRACE_STATUS_ON) \
 319         { \
 320                 dlt_user_trace_network_truncated(&(CONTEXT),TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD, 1); \
 321                 } \
 322     }while(0)
 323
 324 /**
 325  * Trace network message, segment large messages
 326  * @param CONTEXT object containing information about one special logging context
 327  * @param TYPE type of network trace message
 328  * @param HEADERLEN length of network message header
 329  * @param HEADER pointer to network message header
 330  * @param PAYLOADLEN length of network message payload
 331  * @param PAYLOAD pointer to network message payload
 332  */
 333 #define DLT_TRACE_NETWORK_SEGMENTED(CONTEXT,TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD) \
 334     do { \
 335         if ((CONTEXT).trace_status_ptr && *((CONTEXT).trace_status_ptr)==DLT_TRACE_STATUS_ON) \
 336         { \
 337                 dlt_user_trace_network_segmented(&(CONTEXT),TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD); \
 338         } \
 339     }while(0)
 340
 341 /**
 342  * Send log message with string parameter.
 343  * @param CONTEXT object containing information about one special logging context
 344  * @param LOGLEVEL the log level of the log message
 345  * @param TEXT ASCII string
 346  */
 347 #define DLT_LOG_STRING(CONTEXT,LOGLEVEL,TEXT) \
 348     do { \
 349                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 350                 { \
 351                         dlt_log_string(&(CONTEXT), LOGLEVEL, TEXT); \
 352                 } \
 353     } while(0)
 354
 355 /**
 356  * Send log message with string parameter and integer parameter.
 357  * @param CONTEXT object containing information about one special logging context
 358  * @param LOGLEVEL the log level of the log messages
 359  * @param TEXT ASCII string
 360  * @param INT_VAR integer value
 361  */
 362 #define DLT_LOG_STRING_INT(CONTEXT,LOGLEVEL,TEXT,INT_VAR) \
 363         do { \
 364                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 365                 { \
 366                         dlt_log_string_int(&(CONTEXT), LOGLEVEL, TEXT, INT_VAR); \
 367                 } \
 368         } while(0)
 369
 370 /**
 371  * Send log message with string parameter and unsigned integer parameter.
 372  * @param CONTEXT object containing information about one special logging context
 373  * @param LOGLEVEL the log level of the log message
 374  * @param TEXT ASCII string
 375  * @param UINT_VAR unsigned integer value
 376  */
 377 #define DLT_LOG_STRING_UINT(CONTEXT,LOGLEVEL,TEXT,UINT_VAR) \
 378         do { \
 379                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 380                 { \
 381                         dlt_log_string_uint(&(CONTEXT),LOGLEVEL,TEXT,UINT_VAR); \
 382                 } \
 383         } while(0)
 384
 385 /**
 386  * Send log message with unsigned integer parameter.
 387  * @param CONTEXT object containing information about one special logging context
 388  * @param LOGLEVEL the log level of the log message
 389  * @param UINT_VAR unsigned integer value
 390  */
 391 #define DLT_LOG_UINT(CONTEXT,LOGLEVEL,UINT_VAR) \
 392         do { \
 393                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 394                 { \
 395                         dlt_log_uint(&(CONTEXT),LOGLEVEL,UINT_VAR); \
 396                 } \
 397         } while(0)
 398
 399 /**
 400  * Send log message with integer parameter.
 401  * @param CONTEXT object containing information about one special logging context
 402  * @param LOGLEVEL the log level of the log message
 403  * @param INT_VAR integer value
 404  */
 405 #define DLT_LOG_INT(CONTEXT,LOGLEVEL,INT_VAR) \
 406         do { \
 407                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 408                 { \
 409                         dlt_log_int(&(CONTEXT),LOGLEVEL,INT_VAR); \
 410                 } \
 411         } while(0)
 412
 413 /**
 414  * Send log message with binary memory block.
 415  * @param CONTEXT object containing information about one special logging context
 416  * @param LOGLEVEL the log level of the log message
 417  * @param BUF pointer to memory block
 418  * @param LEN length of memory block
 419  */
 420 #define DLT_LOG_RAW(CONTEXT,LOGLEVEL,BUF,LEN) \
 421         do { \
 422                 if((CONTEXT).log_level_ptr && ((LOGLEVEL)<=(int)*((CONTEXT).log_level_ptr) ) && ((LOGLEVEL)!=0)) \
 423                 { \
 424                         dlt_log_raw(&(CONTEXT),LOGLEVEL,BUF,LEN); \
 425                 } \
 426         } while(0)
 427
 428 /**
 429  * Switch to verbose mode
 430  *
 431  */
 432 #define DLT_VERBOSE_MODE() do { \
 433         dlt_verbose_mode();} while(0)
 434
 435 /**
 436  * Switch to non-verbose mode
 437  *
 438  */
 439 #define DLT_NONVERBOSE_MODE() do {\
 440         dlt_nonverbose_mode();} while(0)
 441
 442 /**
 443  * Set maximum logged log level and trace status of application
 444  *
 445  * @param LOGLEVEL This is the log level to be set for the whole application
 446  * @param TRACESTATUS This is the trace status to be set for the whole application
 447  */
 448 #define DLT_SET_APPLICATION_LL_TS_LIMIT(LOGLEVEL, TRACESTATUS) do {\
 449     dlt_set_application_ll_ts_limit(LOGLEVEL, TRACESTATUS);} while(0)
 450
 451 /**
 452  * Enable local printing of messages
 453  *
 454  */
 455 #define DLT_ENABLE_LOCAL_PRINT() do {\
 456         dlt_enable_local_print();} while(0)
 457
 458 /**
 459  * Disable local printing of messages
 460  *
 461  */
 462 #define DLT_DISABLE_LOCAL_PRINT() do {\
 463         dlt_disable_local_print();} while(0)
 464
 465 /**
 466  \}
 467  */
 468
 469 #endif /* DLT_USER_MACROS_H */