include/dlt/dlt_user.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 **                                                                            **
  41 **  SRC-MODULE: dlt_user.h                                                    **
  42 **                                                                            **
  43 **  TARGET    : linux                                                         **
  44 **                                                                            **
  45 **  PROJECT   : DLT                                                           **
  46 **                                                                            **
  47 **  AUTHOR    : Alexander Wenzel Alexander.AW.Wenzel@bmw.de                   **
  48 **              Markus Klein                                                  **
  49 **                                                                            **
  50 **  PURPOSE   :                                                               **
  51 **                                                                            **
  52 **  REMARKS   :                                                               **
  53 **                                                                            **
  54 **  PLATFORM DEPENDANT [yes/no]: yes                                          **
  55 **                                                                            **
  56 **  TO BE CHANGED BY USER [yes/no]: no                                        **
  57 **                                                                            **
  58 *******************************************************************************/
  59
  60 /*******************************************************************************
  61 **                      Author Identity                                       **
  62 ********************************************************************************
  63 **                                                                            **
  64 ** Initials     Name                       Company                            **
  65 ** --------     -------------------------  ---------------------------------- **
  66 **  aw          Alexander Wenzel           BMW                                **
  67 **  mk          Markus Klein               Fraunhofer ESK                     **
  68 *******************************************************************************/
  69
  70 /*******************************************************************************
  71 **                      Revision Control History                              **
  72 *******************************************************************************/
  73
  74 /*
  75  * $LastChangedRevision: 1670 $
  76  * $LastChangedDate: 2011-04-08 15:12:06 +0200 (Fr, 08. Apr 2011) $
  77  * $LastChangedBy$
  78  Initials    Date         Comment
  79  aw          13.01.2010   initial
  80  */
  81
  82 #ifndef DLT_USER_H
  83 #define DLT_USER_H
  84
  85 /**
  86   \defgroup userapi DLT User API
  87   \addtogroup userapi
  88   \{
  89 */
  90
  91 #include "dlt_types.h"
  92 #include "dlt_common.h"
  93 #include "dlt_user_macros.h"
  94
  95 #if !defined (__WIN32__)
  96 #include <semaphore.h>
  97 #endif
  98
  99 #ifdef __cplusplus
 100 extern "C" {
 101 #endif
 102
 103 /**
 104  * Definitions of DLT log level
 105  */
 106 typedef enum
 107 {
 108         DLT_LOG_DEFAULT =                 -1,   /**< Default log level */
 109         DLT_LOG_OFF     =               0x00,   /**< Log level off */
 110         DLT_LOG_FATAL   =               0x01,   /**< fatal system error */
 111         DLT_LOG_ERROR   =               0x02,   /**< error with impact to correct functionality */
 112         DLT_LOG_WARN    =               0x03,   /**< warning, correct behaviour could not be ensured */
 113         DLT_LOG_INFO    =               0x04,   /**< informational */
 114         DLT_LOG_DEBUG   =               0x05,   /**< debug  */
 115         DLT_LOG_VERBOSE =               0x06    /**< highest grade of information */
 116 } DltLogLevelType;
 117
 118 /**
 119  * Definitions of DLT trace status
 120  */
 121 typedef enum
 122 {
 123         DLT_TRACE_STATUS_DEFAULT =   -1,        /**< Default trace status */
 124         DLT_TRACE_STATUS_OFF     = 0x00,        /**< Trace status: Off */
 125         DLT_TRACE_STATUS_ON      = 0x01         /**< Trace status: On */
 126 } DltTraceStatusType;
 127
 128 /**
 129  * Definitions for  dlt_user_trace_network/DLT_TRACE_NETWORK()
 130  * as defined in the DLT protocol
 131  */
 132 typedef enum
 133 {
 134         DLT_NW_TRACE_IPC     = 0x01,    /**< Interprocess communication */
 135         DLT_NW_TRACE_CAN     = 0x02,    /**< Controller Area Network Bus */
 136         DLT_NW_TRACE_FLEXRAY = 0x03,    /**< Flexray Bus */
 137         DLT_NW_TRACE_MOST    = 0x04,    /**< Media Oriented System Transport Bus */
 138         DLT_NW_TRACE_RESERVED0 = 0x05,
 139         DLT_NW_TRACE_RESERVED1 = 0x06,
 140         DLT_NW_TRACE_RESERVED2 = 0x07,
 141         DLT_NW_TRACE_USER_DEFINED0 = 0x08,
 142         DLT_NW_TRACE_USER_DEFINED1 = 0x09,
 143         DLT_NW_TRACE_USER_DEFINED2 = 0x0A,
 144         DLT_NW_TRACE_USER_DEFINED3 = 0x0B,
 145         DLT_NW_TRACE_USER_DEFINED4 = 0x0C,
 146         DLT_NW_TRACE_USER_DEFINED5 = 0x0D,
 147         DLT_NW_TRACE_USER_DEFINED6 = 0x0E,
 148         DLT_NW_TRACE_USER_DEFINED7 = 0x0F
 149 } DltNetworkTraceType;
 150
 151 #define DLT_USER_BUF_MAX_SIZE 2048               /**< maximum size of each user buffer, also used for injection buffer */
 152
 153 /* Use a semaphore or mutex from your OS to prevent concurrent access to the DLT buffer. */
 154 #define DLT_SEM_LOCK() { sem_wait(&dlt_mutex); }
 155 #define DLT_SEM_FREE() { sem_post(&dlt_mutex); }
 156
 157 /**
 158  * This structure is used for every context used in an application.
 159  */
 160 typedef struct
 161 {
 162         char contextID[4];                            /**< context id */
 163     int32_t log_level_pos;                        /**< offset in user-application context field */
 164 } DltContext;
 165
 166 /**
 167  * This structure is used for context data used in an application.
 168  */
 169 typedef struct
 170 {
 171     DltContext *handle;                           /**< pointer to DltContext */
 172         unsigned char buffer[DLT_USER_BUF_MAX_SIZE];  /**< buffer for building log message*/
 173         int32_t size;                                 /**< payload size */
 174         int32_t log_level;                            /**< log level */
 175         int32_t trace_status;                         /**< trace status */
 176         int32_t args_num;                             /**< number of arguments for extended header*/
 177         uint8_t mcnt;                                 /**< message counter */
 178         char* context_description;                    /**< description of context */
 179 } DltContextData;
 180
 181 typedef struct
 182 {
 183         uint32_t service_id;
 184         int (*injection_callback)(uint32_t service_id, void *data, uint32_t length);
 185 } DltUserInjectionCallback;
 186
 187 /**
 188  * This structure is used in a table managing all contexts and the corresponding log levels in an application.
 189  */
 190 typedef struct
 191 {
 192     char contextID[DLT_ID_SIZE];      /**< Context ID */
 193     int8_t log_level;                 /**< Log level */
 194     int8_t trace_status;              /**< Trace status */
 195     char *context_description;        /**< description of context */
 196     DltUserInjectionCallback *injection_table; /**< Table with pointer to injection functions and service ids */
 197     uint32_t nrcallbacks;
 198 } dlt_ll_ts_type;
 199
 200 /**
 201  * This structure is used once for one application.
 202  */
 203 typedef struct
 204 {
 205     char ecuID[DLT_ID_SIZE];             /**< ECU ID */
 206     char appID[DLT_ID_SIZE];             /**< Application ID */
 207     int dlt_log_handle;                  /**< Handle to fifo of dlt daemon */
 208     int dlt_user_handle;                 /**< Handle to own fifo */
 209
 210     int8_t dlt_is_file;                  /**< Target of logging: 1 to file, 0 to daemon */
 211
 212     dlt_ll_ts_type *dlt_ll_ts; //[MAX_DLT_LL_TS_ENTRIES]; /**< Internal management struct for all contexts */
 213     uint32_t dlt_ll_ts_max_num_entries;   /**< Maximum number of contexts */
 214
 215     uint32_t dlt_ll_ts_num_entries;       /**< Number of used contexts */
 216
 217     int8_t overflow;                     /**< Overflow marker, set to 1 on overflow, 0 otherwise */
 218
 219     char *application_description;        /**< description of application */
 220
 221     DltReceiver receiver;                 /**< Receiver for internal user-defined messages from daemon */
 222
 223     int8_t verbose_mode;                                  /**< Verbose mode enabled: 1 enabled, 0 disabled */
 224
 225     int8_t enable_local_print;            /**< Local printing of log messages: 1 enabled, 0 disabled */
 226     int8_t local_print_mode;              /**< Local print mode, controlled by environment variable */
 227
 228     DltRingBuffer rbuf;                   /**< Ring-buffer for buffering messages during startup and missing connection */
 229 } DltUser;
 230
 231 /**************************************************************************************************
 232 * The folowing API functions define a low level function interface for DLT
 233 **************************************************************************************************/
 234
 235 /**
 236  * Initialise the generation of a DLT log message (intended for usage in non-verbose mode)
 237  * This function has to be called first, when an application wants to send a new log messages.
 238  * @param handle pointer to an object containing information about one special logging context
 239  * @param log pointer to an object containing information about logging context data
 240  * @param loglevel this is the current log level of the log message to be sent
 241  * @return negative value if there was an error
 242  */
 243 int dlt_user_log_write_start(DltContext *handle, DltContextData *log, DltLogLevelType loglevel);
 244
 245 /**
 246  * Initialise the generation of a DLT log message (intended for usage in verbose mode)
 247  * This function has to be called first, when an application wants to send a new log messages.
 248  * @param handle pointer to an object containing information about one special logging context
 249  * @param log pointer to an object containing information about logging context data
 250  * @param loglevel this is the current log level of the log message to be sent
 251  * @param messageid message id of message
 252  * @return negative value if there was an error
 253  */
 254 int dlt_user_log_write_start_id(DltContext *handle, DltContextData *log, DltLogLevelType loglevel, uint32_t messageid);
 255
 256 /**
 257  * Finishing the generation of a DLT log message and sending it to the DLT daemon.
 258  * This function has to be called after writing all the log attributes of a log message.
 259  * @param log pointer to an object containing information about logging context data
 260  * @return negative value if there was an error
 261  */
 262 int dlt_user_log_write_finish(DltContextData *log);
 263
 264 /**
 265  * Write a boolean parameter into a DLT log message.
 266  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 267  * Finish sending log message by calling dlt_user_log_write_finish.
 268  * @param log pointer to an object containing information about logging context data
 269  * @param data boolean parameter written into log message (mapped to uint8)
 270  * @return negative value if there was an error
 271  */
 272 int dlt_user_log_write_bool(DltContextData *log, uint8_t data);
 273
 274 /**
 275  * Write a float parameter into a DLT log message.
 276  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 277  * Finish sending log message by calling dlt_user_log_write_finish.
 278  * @param log pointer to an object containing information about logging context data
 279  * @param data float32_t parameter written into log message.
 280  * @return negative value if there was an error
 281  */
 282 int dlt_user_log_write_float32(DltContextData *log, float32_t data);
 283
 284 /**
 285  * Write a double parameter into a DLT log message.
 286  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 287  * Finish sending log message by calling dlt_user_log_write_finish.
 288  * @param log pointer to an object containing information about logging context data
 289  * @param data float64_t parameter written into log message.
 290  * @return negative value if there was an error
 291  */
 292 int dlt_user_log_write_float64(DltContextData *log, double data);
 293
 294 /**
 295  * Write a uint parameter into a DLT log message.
 296  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 297  * Finish sending log message by calling dlt_user_log_write_finish.
 298  * @param log pointer to an object containing information about logging context data
 299  * @param data unsigned int parameter written into log message.
 300  * @return negative value if there was an error
 301  */
 302 int dlt_user_log_write_uint(DltContextData *log, unsigned int data);
 303 int dlt_user_log_write_uint8(DltContextData *log, uint8_t data);
 304 int dlt_user_log_write_uint16(DltContextData *log, uint16_t data);
 305 int dlt_user_log_write_uint32(DltContextData *log, uint32_t data);
 306 int dlt_user_log_write_uint64(DltContextData *log, uint64_t data);
 307 /**
 308  * Write a int parameter into a DLT log message.
 309  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 310  * Finish sending log message by calling dlt_user_log_write_finish.
 311  * @param log pointer to an object containing information about logging context data
 312  * @param data int parameter written into log message.
 313  * @return negative value if there was an error
 314  */
 315 int dlt_user_log_write_int(DltContextData *log, int data);
 316 int dlt_user_log_write_int8(DltContextData *log, int8_t data);
 317 int dlt_user_log_write_int16(DltContextData *log, int16_t data);
 318 int dlt_user_log_write_int32(DltContextData *log, int32_t data);
 319 int dlt_user_log_write_int64(DltContextData *log, int64_t data);
 320 /**
 321  * Write a null terminated ASCII string into a DLT log message.
 322  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 323  * Finish sending log message by calling dlt_user_log_write_finish.
 324  * @param log pointer to an object containing information about logging context data
 325  * @param text pointer to the parameter written into log message containing null termination.
 326  * @return negative value if there was an error
 327  */
 328 int dlt_user_log_write_string( DltContextData *log, const char *text);
 329
 330 /**
 331  * Write a binary memory block into a DLT log message.
 332  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
 333  * Finish sending log message by calling dlt_user_log_write_finish.
 334  * @param log pointer to an object containing information about logging context data
 335  * @param data pointer to the parameter written into log message.
 336  * @param length length in bytes of the parameter written into log message.
 337  * @return negative value if there was an error
 338  */
 339 int dlt_user_log_write_raw(DltContextData *log,void *data,uint16_t length);
 340
 341 /**
 342  * Trace network message
 343  * @param handle pointer to an object containing information about one special logging context
 344  * @param nw_trace_type type of network trace (DLT_NW_TRACE_IPC, DLT_NW_TRACE_CAN, DLT_NW_TRACE_FLEXRAY, or DLT_NW_TRACE_MOST)
 345  * @param header_len length of network message header
 346  * @param header pointer to network message header
 347  * @param payload_len length of network message payload
 348  * @param payload pointer to network message payload
 349  * @return negative value if there was an error
 350  */
 351 int dlt_user_trace_network(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload);
 352
 353 /**************************************************************************************************
 354 * The folowing API functions define a high level function interface for DLT
 355 **************************************************************************************************/
 356
 357 /**
 358  * Initialise the user lib communication with daemon.
 359  * This function has to be called first, before using any DLT user lib functions.
 360  * @return negative value if there was an error
 361  */
 362 int dlt_init();
 363
 364 /**
 365  * Initialise the user lib writing only to file.
 366  * This function has to be called first, before using any DLT user lib functions.
 367  * @param name name of an optional log file
 368  * @return negative value if there was an error
 369  */
 370 int dlt_init_file(const char *name);
 371
 372 /**
 373  * Terminate the user lib.
 374  * This function has to be called when finishing using the DLT user lib.
 375  * @return negative value if there was an error
 376  */
 377 int dlt_free();
 378
 379 /**
 380  * Register an application in the daemon.
 381  * @param appid four byte long character array with the application id
 382  * @param description long name of the application
 383  * @return negative value if there was an error
 384  */
 385 int dlt_register_app(const char *appid, const char * description);
 386
 387 /**
 388  * Unregister an application in the daemon.
 389  * This function has to be called when finishing using an application.
 390  * @return negative value if there was an error
 391  */
 392 int dlt_unregister_app(void);
 393
 394 /**
 395  * Register a context in the daemon.
 396  * This function has to be called before first usage of the context.
 397  * @param handle pointer to an object containing information about one special logging context
 398  * @param contextid four byte long character array with the context id
 399  * @param description long name of the context
 400  * @return negative value if there was an error
 401  */
 402 int dlt_register_context(DltContext *handle, const char *contextid, const char * description);
 403
 404 /**
 405  * Register a context in the daemon with pre-defined log level and pre-defined trace status.
 406  * This function has to be called before first usage of the context.
 407  * @param handle pointer to an object containing information about one special logging context
 408  * @param contextid four byte long character array with the context id
 409  * @param description long name of the context
 410  * @param loglevel This is the log level to be pre-set for this context
 411           (DLT_LOG_DEFAULT is not allowed here)
 412  * @param tracestatus This is the trace status to be pre-set for this context
 413                   (DLT_TRACE_STATUS_DEFAULT is not allowed here)
 414  * @return negative value if there was an error
 415  */
 416 int dlt_register_context_ll_ts(DltContext *handle, const char *contextid, const char * description, int loglevel, int tracestatus);
 417
 418 /**
 419  * Unregister a context in the DLT daemon.
 420  * This function has to be called when finishing using a context.
 421  * @param handle pointer to an object containing information about one special logging context
 422  * @return negative value if there was an error
 423  */
 424 int dlt_unregister_context(DltContext *handle);
 425
 426 /**
 427  * Register callback function called when injection message was received
 428  * @param handle pointer to an object containing information about one special logging context
 429  * @param service_id the service id to be waited for
 430  * @param (*dlt_injection_callback) function pointer to callback function
 431  * @return negative value if there was an error
 432  */
 433 int dlt_register_injection_callback(DltContext *handle, uint32_t service_id,
 434       int (*dlt_injection_callback)(uint32_t service_id, void *data, uint32_t length));
 435
 436 /**
 437  * Switch to verbose mode
 438  *
 439  */
 440 int dlt_verbose_mode(void);
 441
 442 /**
 443  * Switch to non-verbose mode
 444  *
 445  */
 446 int dlt_nonverbose_mode(void);
 447
 448 /**
 449  * Set maximum logged log level and trace status of application
 450  *
 451  * @param loglevel This is the log level to be set for the whole application
 452  * @param tracestatus This is the trace status to be set for the whole application
 453  * @return negative value if there was an error
 454  */
 455 int dlt_set_application_ll_ts_limit(DltLogLevelType loglevel, DltTraceStatusType tracestatus);
 456
 457 /**
 458  * Enable local printing of messages
 459  *
 460  */
 461 int dlt_enable_local_print(void);
 462
 463 /**
 464  * Disable local printing of messages
 465  *
 466  */
 467 int dlt_disable_local_print(void);
 468
 469 /**
 470  * Write a null terminated ASCII string into a DLT log message.
 471  * @param handle pointer to an object containing information about one special logging context
 472  * @param loglevel this is the current log level of the log message to be sent
 473  * @param text pointer to the ASCII string written into log message containing null termination.
 474  * @return negative value if there was an error
 475  */
 476 int dlt_log_string(DltContext *handle,DltLogLevelType loglevel, const char *text);
 477
 478 /**
 479  * Write a null terminated ASCII string and an integer value into a DLT log message.
 480  * @param handle pointer to an object containing information about one special logging context
 481  * @param loglevel this is the current log level of the log message to be sent
 482  * @param text pointer to the ASCII string written into log message containing null termination.
 483  * @param data integer value written into the log message
 484  * @return negative value if there was an error
 485  */
 486 int dlt_log_string_int(DltContext *handle,DltLogLevelType loglevel, const char *text, int data);
 487
 488 /**
 489  * Write a null terminated ASCII string and an unsigned integer value into a DLT log message.
 490  * @param handle pointer to an object containing information about one special logging context
 491  * @param loglevel this is the current log level of the log message to be sent
 492  * @param text pointer to the ASCII string written into log message containing null termination.
 493  * @param data unsigned integer value written into the log message
 494  * @return negative value if there was an error
 495  */
 496 int dlt_log_string_uint(DltContext *handle,DltLogLevelType loglevel, const char *text, unsigned int data);
 497
 498 /**
 499  * Write an integer value into a DLT log message.
 500  * @param handle pointer to an object containing information about one special logging context
 501  * @param loglevel this is the current log level of the log message to be sent
 502  * @param data integer value written into the log message
 503  * @return negative value if there was an error
 504  */
 505 int dlt_log_int(DltContext *handle,DltLogLevelType loglevel, int data);
 506
 507 /**
 508  * Write an unsigned integer value into a DLT log message.
 509  * @param handle pointer to an object containing information about one special logging context
 510  * @param loglevel this is the current log level of the log message to be sent
 511  * @param data unsigned integer value written into the log message
 512  * @return negative value if there was an error
 513  */
 514 int dlt_log_uint(DltContext *handle,DltLogLevelType loglevel, unsigned int data);
 515
 516 /**
 517  * Write an unsigned integer value into a DLT log message.
 518  * @param handle pointer to an object containing information about one special logging context
 519  * @param loglevel this is the current log level of the log message to be sent
 520  * @param data pointer to the parameter written into log message.
 521  * @param length length in bytes of the parameter written into log message.
 522  * @return negative value if there was an error
 523  */
 524 int dlt_log_raw(DltContext *handle,DltLogLevelType loglevel, void *data,uint16_t length);
 525
 526 /**
 527  * Forward a complete DLT message to the DLT daemon
 528  * @param msgdata Message data of DLT message
 529  * @param size Size of DLT message
 530  * @return negative value if there was an error
 531  */
 532 int dlt_forward_msg(void *msgdata,size_t size);
 533
 534 #ifdef __cplusplus
 535 }
 536 #endif
 537
 538 /**
 539   \}
 540 */
 541
 542 #endif /* DLT_USER_H */