include/dlt/dlt_user_macros.h

   1 /*
   2  * Dlt- Diagnostic Log and Trace console apps
   3  * @licence app begin@
   4  *
   5  * Copyright (C) 2011, BMW AG - Alexander Wenzel <alexander.wenzel@bmw.de>
   6  *
   7  * This program is free software; you can redistribute it and/or modify it under the terms of the
   8  * GNU Lesser General Public License, version 2.1, as published by the Free Software Foundation.
   9  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
  10  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
  11  * Public License, version 2.1, for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License, version 2.1, along
  14  * with this program; if not, see <http://www.gnu.org/licenses/lgpl-2.1.html>.
  15  *
  16  * Note that the copyright holders assume that the GNU Lesser General Public License, version 2.1, may
  17  * also be applicable to programs even in cases in which the program is not a library in the technical sense.
  18  *
  19  * Linking DLT statically or dynamically with other modules is making a combined work based on DLT. You may
  20  * license such other modules under the GNU Lesser General Public License, version 2.1. If you do not want to
  21  * license your linked modules under the GNU Lesser General Public License, version 2.1, you
  22  * may use the program under the following exception.
  23  *
  24  * As a special exception, the copyright holders of DLT give you permission to combine DLT
  25  * with software programs or libraries that are released under any license unless such a combination is not
  26  * permitted by the license of such a software program or library. You may copy and distribute such a
  27  * system following the terms of the GNU Lesser General Public License, version 2.1, including this
  28  * special exception, for DLT and the licenses of the other code concerned.
  29  *
  30  * Note that people who make modified versions of DLT are not obligated to grant this special exception
  31  * for their modified versions; it is their choice whether to do so. The GNU Lesser General Public License,
  32  * version 2.1, gives permission to release a modified version without this exception; this exception
  33  * also makes it possible to release a modified version which carries forward this exception.
  34  *
  35  * @licence end@
  36  */
  37
  38 /*******************************************************************************
  39  **                                                                            **
  40  **  SRC-MODULE: dlt_user_macros.h                                             **
  41  **                                                                            **
  42  **  TARGET    : linux                                                         **
  43  **                                                                            **
  44  **  PROJECT   : DLT                                                           **
  45  **                                                                            **
  46  **  AUTHOR    : Alexander Wenzel Alexander.AW.Wenzel@bmw.de                   **
  47  **              Markus Klein                                                  **
  48  **                                                                            **
  49  **  PURPOSE   :                                                               **
  50  **                                                                            **
  51  **  REMARKS   :                                                               **
  52  **                                                                            **
  53  **  PLATFORM DEPENDANT [yes/no]: yes                                          **
  54  **                                                                            **
  55  **  TO BE CHANGED BY USER [yes/no]: no                                        **
  56  **                                                                            **
  57  *******************************************************************************/
  58
  59 /*******************************************************************************
  60  **                      Author Identity                                       **
  61  ********************************************************************************
  62  **                                                                            **
  63  ** Initials     Name                       Company                            **
  64  ** --------     -------------------------  ---------------------------------- **
  65  **  aw          Alexander Wenzel           BMW                                **
  66  **  mk          Markus Klein               Fraunhofer ESK                     **
  67  *******************************************************************************/
  68
  69 /*******************************************************************************
  70  **                      Revision Control History                              **
  71  *******************************************************************************/
  72
  73 /*
  74  * $LastChangedRevision: 1515 $
  75  * $LastChangedDate: 2010-12-13 09:18:54 +0100 (Mon, 13 Dec 2010) $
  76  * $LastChangedBy$
  77  Initials    Date         Comment
  78  aw          13.01.2010   initial
  79  */
  80
  81 #ifndef DLT_USER_MACROS_H
  82 #define DLT_USER_MACORS_H
  83
  84 #include "dlt_version.h"
  85
  86 /**
  87  \defgroup userapi DLT User API
  88  \addtogroup userapi
  89  \{
  90  */
  91
  92 /**************************************************************************************************
  93  * The folowing macros define a macro interface for DLT
  94  **************************************************************************************************/
  95
  96 /**
  97  * Create an object for a new context.
  98  * This macro has to be called first for every.
  99  * @param CONTEXT object containing information about one special logging context
 100  */
 101 #define DLT_DECLARE_CONTEXT(CONTEXT) \
 102 DltContext CONTEXT;
 103
 104 /**
 105  * Use an object of a new context created in another module.
 106  * This macro has to be called first for every.
 107  * @param CONTEXT object containing information about one special logging context
 108  */
 109 #define DLT_IMPORT_CONTEXT(CONTEXT) \
 110 extern DltContext CONTEXT;
 111
 112 /**
 113  * Register application.
 114  * @param APPID application id with maximal four characters
 115  * @param DESCRIPTION ASCII string containing description
 116  */
 117 #define DLT_REGISTER_APP(APPID,DESCRIPTION) \
 118                 dlt_check_library_version(PACKAGE_MAJOR_VERSION, PACKAGE_MINOR_VERSION ); \
 119                 dlt_register_app( APPID, DESCRIPTION);
 120
 121
 122 /**
 123  * Unregister application.
 124  */
 125 #define DLT_UNREGISTER_APP() \
 126         dlt_unregister_app();
 127
 128 /**
 129  * Register context (with default log level and default trace status)
 130  * @param CONTEXT object containing information about one special logging context
 131  * @param CONTEXTID context id with maximal four characters
 132  * @param DESCRIPTION ASCII string containing description
 133  */
 134 #define DLT_REGISTER_CONTEXT(CONTEXT,CONTEXTID,DESCRIPTION) \
 135         dlt_register_context(&(CONTEXT), CONTEXTID, DESCRIPTION);
 136
 137 /**
 138  * Register context with pre-defined log level and pre-defined trace status.
 139  * @param CONTEXT object containing information about one special logging context
 140  * @param CONTEXTID context id with maximal four characters
 141  * @param DESCRIPTION ASCII string containing description
 142  * @param LOGLEVEL log level to be pre-set for this context
 143  (DLT_LOG_DEFAULT is not allowed here)
 144  * @param TRACESTATUS trace status to be pre-set for this context
 145  (DLT_TRACE_STATUS_DEFAULT is not allowed here)
 146  */
 147 #define DLT_REGISTER_CONTEXT_LL_TS(CONTEXT,CONTEXTID,DESCRIPTION,LOGLEVEL,TRACESTATUS) \
 148         dlt_register_context_ll_ts(&(CONTEXT), CONTEXTID, DESCRIPTION, LOGLEVEL, TRACESTATUS);
 149
 150 /**
 151  * Unregister context.
 152  * @param CONTEXT object containing information about one special logging context
 153  */
 154 #define DLT_UNREGISTER_CONTEXT(CONTEXT) \
 155         dlt_unregister_context(&(CONTEXT));
 156
 157 /**
 158  * Register callback function called when injection message was received
 159  * @param CONTEXT object containing information about one special logging context
 160  * @param SERVICEID service id of the injection message
 161  * @param CALLBACK function pointer to callback function
 162  */
 163 #define DLT_REGISTER_INJECTION_CALLBACK(CONTEXT, SERVICEID, CALLBACK) \
 164         dlt_register_injection_callback(&(CONTEXT),SERVICEID, CALLBACK);
 165
 166 /**
 167  * Send log message with variable list of messages (intended for verbose mode)
 168  * @param CONTEXT object containing information about one special logging context
 169  * @param LOGLEVEL the log level of the log message
 170  * @param ARGS variable list of arguments
 171  */
 172 #ifdef _MSC_VER
 173 /* DLT_LOG is not supported by MS Visual C++ */
 174 /* use function interface instead            */
 175 #else
 176 #define DLT_LOG(CONTEXT,LOGLEVEL,ARGS...) \
 177         { \
 178                 DltContextData log; \
 179                 if (dlt_user_log_write_start(&CONTEXT,&log,LOGLEVEL)) \
 180                 { \
 181             ARGS; \
 182             dlt_user_log_write_finish(&log); \
 183                 } \
 184         }
 185 #endif
 186
 187 /**
 188  * Send log message with variable list of messages (intended for non-verbose mode)
 189  * @param CONTEXT object containing information about one special logging context
 190  * @param LOGLEVEL the log level of the log message
 191  * @param MSGID the message id of log message
 192  * @param ARGS variable list of arguments:
 193  calls to DLT_STRING(), DLT_BOOL(), DLT_FLOAT32(), DLT_FLOAT64(),
 194  DLT_INT(), DLT_UINT(), DLT_RAW()
 195  */
 196 #ifdef _MSC_VER
 197 /* DLT_LOG_ID is not supported by MS Visual C++ */
 198 /* use function interface instead               */
 199 #else
 200 #define DLT_LOG_ID(CONTEXT,LOGLEVEL,MSGID,ARGS...) \
 201         { \
 202                 DltContextData log; \
 203                 if (dlt_user_log_write_start_id(&CONTEXT,&log,LOGLEVEL,MSGID)) \
 204                 { \
 205             ARGS; \
 206             dlt_user_log_write_finish(&log); \
 207                 } \
 208         }
 209 #endif
 210
 211 /**
 212  * Add string parameter to the log messsage.
 213  * @param TEXT ASCII string
 214  */
 215 #define DLT_STRING(TEXT) ({ \
 216         dlt_user_log_write_string(&log,TEXT); \
 217         })
 218
 219 /**
 220  * Add boolean parameter to the log messsage.
 221  * @param BOOL_VAR Boolean value (mapped to uint8)
 222  */
 223 #define DLT_BOOL(BOOL_VAR) ({ \
 224         dlt_user_log_write_bool(&log,BOOL_VAR); \
 225         })
 226
 227 /**
 228  * Add float32 parameter to the log messsage.
 229  * @param FLOAT32_VAR Float32 value (mapped to float)
 230  */
 231 #define DLT_FLOAT32(FLOAT32_VAR) ({ \
 232         dlt_user_log_write_float32(&log,FLOAT32_VAR); \
 233         })
 234
 235 /**
 236  * Add float64 parameter to the log messsage.
 237  * @param FLOAT64_VAR Float64 value (mapped to double)
 238  */
 239 #define DLT_FLOAT64(FLOAT64_VAR) ({ \
 240         dlt_user_log_write_float64(&log,FLOAT64_VAR); \
 241         })
 242
 243 /**
 244  * Add integer parameter to the log messsage.
 245  * @param INT_VAR integer value
 246  */
 247 #define DLT_INT(INT_VAR) ({ \
 248         dlt_user_log_write_int(&log,INT_VAR); \
 249         })
 250 #define DLT_INT8(INT_VAR) ({ \
 251         dlt_user_log_write_int8(&log,INT_VAR); \
 252         })
 253 #define DLT_INT16(INT_VAR) ({ \
 254         dlt_user_log_write_int16(&log,INT_VAR); \
 255         })
 256 #define DLT_INT32(INT_VAR) ({ \
 257         dlt_user_log_write_int32(&log,INT_VAR); \
 258         })
 259 #define DLT_INT64(INT_VAR) ({ \
 260         dlt_user_log_write_int64(&log,INT_VAR); \
 261         })
 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 /**
 284  * Add binary memory block to the log messages.
 285  * @param BUF pointer to memory block
 286  * @param LEN length of memory block
 287  */
 288 #define DLT_RAW(BUF,LEN) ({ \
 289         dlt_user_log_write_raw(&log,BUF,LEN); \
 290         })
 291
 292 /**
 293  * Trace network message
 294  * @param CONTEXT object containing information about one special logging context
 295  * @param TYPE type of network trace message
 296  * @param HEADERLEN length of network message header
 297  * @param HEADER pointer to network message header
 298  * @param PAYLOADLEN length of network message payload
 299  * @param PAYLOAD pointer to network message payload
 300  */
 301 #define DLT_TRACE_NETWORK(CONTEXT,TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD) \
 302     { \
 303         dlt_user_trace_network(&(CONTEXT),TYPE,HEADERLEN,HEADER,PAYLOADLEN,PAYLOAD); \
 304     }
 305
 306 /**
 307  * Send log message with string parameter.
 308  * @param CONTEXT object containing information about one special logging context
 309  * @param LOGLEVEL the log level of the log message
 310  * @param TEXT ASCII string
 311  */
 312 #define DLT_LOG_STRING(CONTEXT,LOGLEVEL,TEXT) \
 313     { \
 314         dlt_log_string(&(CONTEXT), LOGLEVEL, TEXT); \
 315     }
 316
 317 /**
 318  * Send log message with string parameter and integer parameter.
 319  * @param CONTEXT object containing information about one special logging context
 320  * @param LOGLEVEL the log level of the log messages
 321  * @param TEXT ASCII string
 322  * @param INT_VAR integer value
 323  */
 324 #define DLT_LOG_STRING_INT(CONTEXT,LOGLEVEL,TEXT,INT_VAR) \
 325         { \
 326         dlt_log_string_int(&(CONTEXT), LOGLEVEL, TEXT, INT_VAR); \
 327         }
 328
 329 /**
 330  * Send log message with string parameter and unsigned integer parameter.
 331  * @param CONTEXT object containing information about one special logging context
 332  * @param LOGLEVEL the log level of the log message
 333  * @param TEXT ASCII string
 334  * @param UINT_VAR unsigned integer value
 335  */
 336 #define DLT_LOG_STRING_UINT(CONTEXT,LOGLEVEL,TEXT,UINT_VAR) \
 337         { \
 338                 dlt_log_string_uint(&(CONTEXT),LOGLEVEL,TEXT,UINT_VAR); \
 339         }
 340
 341 /**
 342  * Send log message with unsigned integer parameter.
 343  * @param CONTEXT object containing information about one special logging context
 344  * @param LOGLEVEL the log level of the log message
 345  * @param UINT_VAR unsigned integer value
 346  */
 347 #define DLT_LOG_UINT(CONTEXT,LOGLEVEL,UINT_VAR) \
 348         { \
 349                 dlt_log_uint(&(CONTEXT),LOGLEVEL,UINT_VAR); \
 350         }
 351
 352 /**
 353  * Send log message with integer parameter.
 354  * @param CONTEXT object containing information about one special logging context
 355  * @param LOGLEVEL the log level of the log message
 356  * @param INT_VAR integer value
 357  */
 358 #define DLT_LOG_INT(CONTEXT,LOGLEVEL,INT_VAR) \
 359         { \
 360                 dlt_log_int(&(CONTEXT),LOGLEVEL,INT_VAR); \
 361         }
 362
 363 /**
 364  * Send log message with binary memory block.
 365  * @param CONTEXT object containing information about one special logging context
 366  * @param LOGLEVEL the log level of the log message
 367  * @param BUF pointer to memory block
 368  * @param LEN length of memory block
 369  */
 370 #define DLT_LOG_RAW(CONTEXT,LOGLEVEL,BUF,LEN) \
 371         { \
 372                 dlt_log_raw(&(CONTEXT),LOGLEVEL,BUF,LEN); \
 373         }
 374
 375 /**
 376  * Switch to verbose mode
 377  *
 378  */
 379 #define DLT_VERBOSE_MODE() \
 380         dlt_verbose_mode();
 381
 382 /**
 383  * Switch to non-verbose mode
 384  *
 385  */
 386 #define DLT_NONVERBOSE_MODE() \
 387         dlt_nonverbose_mode();
 388
 389 /**
 390  * Set maximum logged log level and trace status of application
 391  *
 392  * @param LOGLEVEL This is the log level to be set for the whole application
 393  * @param TRACESTATUS This is the trace status to be set for the whole application
 394  */
 395 #define DLT_SET_APPLICATION_LL_TS_LIMIT(LOGLEVEL, TRACESTATUS) \
 396     dlt_set_application_ll_ts_limit(LOGLEVEL, TRACESTATUS);
 397
 398 /**
 399  * Enable local printing of messages
 400  *
 401  */
 402 #define DLT_ENABLE_LOCAL_PRINT() \
 403         dlt_enable_local_print();
 404
 405 /**
 406  * Disable local printing of messages
 407  *
 408  */
 409 #define DLT_DISABLE_LOCAL_PRINT() \
 410         dlt_disable_local_print();
 411
 412 /**
 413  \}
 414  */
 415
 416 #endif /* DLT_USER_MACROS_H */