include/dlt/dlt_common.h

   1 /*
   2  * Dlt- Diagnostic Log and Trace
   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_common.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 #ifndef DLT_COMMON_H
  82 #define DLT_COMMON_H
  83
  84 /**
  85   \defgroup commonapi DLT Common API
  86   \addtogroup commonapi
  87   \{
  88 */
  89
  90 #include <stdio.h>
  91
  92 #if !defined(_MSC_VER)
  93 #include <unistd.h>
  94 #include <time.h>
  95 #endif
  96
  97 #if !defined (__WIN32__) && !defined(_MSC_VER)
  98 #include <termios.h>
  99 #endif
 100
 101 #include "dlt_types.h"
 102 #include "dlt_protocol.h"
 103
 104 #if !defined (PACKED)
 105 #define PACKED __attribute__((aligned(1),packed))
 106 #endif
 107
 108 #if defined (__MSDOS__) || defined (_MSC_VER)
 109 /* set instead /Zp8 flag in Visual C++ configuration */
 110 #undef PACKED
 111 #define PACKED
 112 #endif
 113
 114 /*
 115  * Macros to swap the byte order.
 116  */
 117 #define DLT_SWAP_64(value) ((((uint64_t)DLT_SWAP_32((value)&0xffffffffull))<<32) | (DLT_SWAP_32((value)>>32)))
 118
 119 #define DLT_SWAP_16(value) ((((value) >> 8)&0xff) | (((value) << 8)&0xff00))
 120 #define DLT_SWAP_32(value) ((((value) >> 24)&0xff) | (((value) << 8)&0xff0000) | (((value) >> 8)&0xff00) | (((value) << 24)&0xff000000))
 121
 122 /* Set Big Endian and Little Endian to a initial value, if not defined */
 123 #ifndef LITTLE_ENDIAN
 124 #define LITTLE_ENDIAN 1234
 125 #endif
 126
 127 #ifndef BIG_ENDIAN
 128 #define BIG_ENDIAN    4321
 129 #endif
 130
 131 /* If byte order is not defined, default to little endian */
 132 #ifndef BYTE_ORDER
 133 #define BYTE_ORDER LITTLE_ENDIAN
 134 #endif
 135
 136 /* Check for byte-order */
 137 #if (BYTE_ORDER==BIG_ENDIAN)
 138 /* #warning "Big Endian Architecture!" */
 139 #define DLT_HTOBE_16(x) ((x))
 140 #define DLT_HTOLE_16(x) DLT_SWAP_16((x))
 141 #define DLT_BETOH_16(x) ((x))
 142 #define DLT_LETOH_16(x) DLT_SWAP_16((x))
 143
 144 #define DLT_HTOBE_32(x) ((x))
 145 #define DLT_HTOLE_32(x) DLT_SWAP_32((x))
 146 #define DLT_BETOH_32(x) ((x))
 147 #define DLT_LETOH_32(x) DLT_SWAP_32((x))
 148
 149 #define DLT_HTOBE_64(x) ((x))
 150 #define DLT_HTOLE_64(x) DLT_SWAP_64((x))
 151 #define DLT_BETOH_64(x) ((x))
 152 #define DLT_LETOH_64(x) DLT_SWAP_64((x))
 153 #else
 154 /* #warning "Litte Endian Architecture!" */
 155 #define DLT_HTOBE_16(x) DLT_SWAP_16((x))
 156 #define DLT_HTOLE_16(x) ((x))
 157 #define DLT_BETOH_16(x) DLT_SWAP_16((x))
 158 #define DLT_LETOH_16(x) ((x))
 159
 160 #define DLT_HTOBE_32(x) DLT_SWAP_32((x))
 161 #define DLT_HTOLE_32(x) ((x))
 162 #define DLT_BETOH_32(x) DLT_SWAP_32((x))
 163 #define DLT_LETOH_32(x) ((x))
 164
 165 #define DLT_HTOBE_64(x) DLT_SWAP_64((x))
 166 #define DLT_HTOLE_64(x) ((x))
 167 #define DLT_BETOH_64(x) DLT_SWAP_64((x))
 168 #define DLT_LETOH_64(x) ((x))
 169 #endif
 170
 171 #define DLT_ENDIAN_GET_16(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_16(x):DLT_LETOH_16(x))
 172 #define DLT_ENDIAN_GET_32(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_32(x):DLT_LETOH_32(x))
 173 #define DLT_ENDIAN_GET_64(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_64(x):DLT_LETOH_64(x))
 174
 175 #if defined (__WIN32__) || defined (_MSC_VER)
 176 #define LOG_EMERG       0
 177 #define LOG_ALERT       1
 178 #define LOG_CRIT        2
 179 #define LOG_ERR         3
 180 #define LOG_WARNING     4
 181 #define LOG_NOTICE      5
 182 #define LOG_INFO        6
 183 #define LOG_DEBUG       7
 184
 185 #define LOG_PID         0x01
 186 #define LOG_DAEMON      (3<<3)
 187 #endif
 188
 189 /**
 190  * The standard TCP Port used for DLT daemon
 191  */
 192 #define DLT_DAEMON_TCP_PORT 3490
 193
 194 /**
 195  * The size of a DLT ID
 196  */
 197 #define DLT_ID_SIZE 4
 198
 199 #define DLT_SIZE_WEID DLT_ID_SIZE
 200 #define DLT_SIZE_WSID (sizeof(uint32_t))
 201 #define DLT_SIZE_WTMS (sizeof(uint32_t))
 202
 203 /**
 204  * Get the size of extra header parameters, depends on htyp.
 205  */
 206 #define DLT_STANDARD_HEADER_EXTRA_SIZE(htyp) ( (DLT_IS_HTYP_WEID(htyp) ? DLT_SIZE_WEID : 0) + (DLT_IS_HTYP_WSID(htyp) ? DLT_SIZE_WSID : 0) + (DLT_IS_HTYP_WTMS(htyp) ? DLT_SIZE_WTMS : 0) )
 207
 208
 209 #if defined (__MSDOS__) || defined (_MSC_VER)
 210 #define __func__ __FUNCTION__
 211 #endif
 212
 213 #define PRINT_FUNCTION_VERBOSE(_verbose)  \
 214 { \
 215         static char _strbuf[255]; \
 216     \
 217     if(_verbose) \
 218     { \
 219                 sprintf(_strbuf, "%s()\n",__func__); \
 220                 dlt_log(LOG_INFO, _strbuf); \
 221     } \
 222 }
 223
 224 #ifndef NULL
 225 #define NULL (char*)0
 226 #endif
 227
 228 #define DLT_MSG_IS_CONTROL(MSG)          ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 229                                           (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL))
 230
 231 #define DLT_MSG_IS_CONTROL_REQUEST(MSG)  ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 232                                           (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
 233                                           (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_REQUEST))
 234
 235 #define DLT_MSG_IS_CONTROL_RESPONSE(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 236                                           (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
 237                                           (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_RESPONSE))
 238
 239 #define DLT_MSG_IS_CONTROL_TIME(MSG)     ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 240                                           (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
 241                                           (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_TIME))
 242
 243 #define DLT_MSG_IS_NW_TRACE(MSG)         ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 244                                                                               (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_NW_TRACE))
 245
 246 #define DLT_MSG_IS_TRACE_MOST(MSG)       ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
 247                                                                               (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_NW_TRACE) && \
 248                                                                               (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_NW_TRACE_MOST))
 249
 250 #define DLT_MSG_IS_NONVERBOSE(MSG)       (!(DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) || \
 251                                           ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && (!(DLT_IS_MSIN_VERB((MSG)->extendedheader->msin)))))
 252
 253 /*
 254
 255  * Definitions of DLT message buffer overflow
 256  */
 257 #define DLT_MESSAGE_BUFFER_NO_OVERFLOW     0x00 /**< Buffer overflow has not occured */
 258 #define DLT_MESSAGE_BUFFER_OVERFLOW        0x01 /**< Buffer overflow has occured */
 259
 260 /*
 261  * Definition of DLT output variants
 262  */
 263 #define DLT_OUTPUT_HEX              1
 264 #define DLT_OUTPUT_ASCII            2
 265 #define DLT_OUTPUT_MIXED_FOR_PLAIN  3
 266 #define DLT_OUTPUT_MIXED_FOR_HTML   4
 267 #define DLT_OUTPUT_ASCII_LIMITED    5
 268
 269 #define DLT_FILTER_MAX 30 /**< Maximum number of filters */
 270
 271 #define DLT_MSG_READ_VALUE(dst,src,length,type) \
 272     { \
 273     if((length<0) || ((length)<((int32_t)sizeof(type)))) \
 274         { length = -1; } \
 275     else \
 276         { dst = *((type*)src);src+=sizeof(type);length-=sizeof(type); } \
 277     }
 278
 279 #define DLT_MSG_READ_ID(dst,src,length) \
 280     { \
 281     if((length<0) || ((length)<DLT_ID_SIZE)) \
 282         { length = -1; } \
 283     else \
 284         { memcpy(dst,src,DLT_ID_SIZE);src+=DLT_ID_SIZE;length-=DLT_ID_SIZE; } \
 285     }
 286
 287 #define DLT_MSG_READ_STRING(dst,src,maxlength,length) \
 288     { \
 289     if(((maxlength)<0) || ((length)<0) || ((maxlength)<(length))) \
 290         { maxlength = -1; } \
 291     else \
 292         { memcpy(dst,src,length);dlt_clean_string(dst,length);dst[length]=0; \
 293           src+=length;maxlength-=length; } \
 294     }
 295
 296 #define DLT_MSG_READ_NULL(src,maxlength,length) \
 297     { \
 298     if(((maxlength)<0) || ((length)<0) || ((maxlength)<(length))) \
 299         { length = -1; } \
 300     else \
 301         { src+=length;maxlength-=length; } \
 302     }
 303
 304 #define DLT_HEADER_SHOW_NONE       0x0000
 305 #define DLT_HEADER_SHOW_TIME       0x0001
 306 #define DLT_HEADER_SHOW_TMSTP      0x0002
 307 #define DLT_HEADER_SHOW_MSGCNT     0x0004
 308 #define DLT_HEADER_SHOW_ECUID      0x0008
 309 #define DLT_HEADER_SHOW_APID       0x0010
 310 #define DLT_HEADER_SHOW_CTID       0x0020
 311 #define DLT_HEADER_SHOW_MSGTYPE    0x0040
 312 #define DLT_HEADER_SHOW_MSGSUBTYPE 0x0080
 313 #define DLT_HEADER_SHOW_VNVSTATUS  0x0100
 314 #define DLT_HEADER_SHOW_NOARG      0x0200
 315 #define DLT_HEADER_SHOW_ALL        0xFFFF
 316
 317 /**
 318  * The definition of the serial header containing the characters "DLS" + 0x01.
 319  */
 320 extern const char dltSerialHeader[DLT_ID_SIZE];
 321
 322 /**
 323  * The definition of the serial header containing the characters "DLS" + 0x01 as char.
 324  */
 325 extern char dltSerialHeaderChar[DLT_ID_SIZE];
 326
 327 /**
 328
 329  * The type of a DLT ID (context id, application id, etc.)
 330  */
 331 typedef char ID4[DLT_ID_SIZE];
 332
 333 /**
 334  * The structure of the DLT file storage header. This header is used before each stored DLT message.
 335  */
 336 typedef struct
 337 {
 338     char pattern[DLT_ID_SIZE];          /**< This pattern should be DLT0x01 */
 339     time_t seconds;                                 /**< seconds since 1.1.1970 */
 340     int32_t microseconds;                       /**< Microseconds */
 341     char ecu[DLT_ID_SIZE];                      /**< The ECU id is added, if it is not already in the DLT message itself */
 342 } PACKED DltStorageHeader;
 343
 344 /**
 345  * The structure of the DLT standard header. This header is used in each DLT message.
 346  */
 347 typedef struct
 348 {
 349     uint8_t htyp;           /**< This parameter contains several informations, see definitions below */
 350     uint8_t mcnt;           /**< The message counter is increased with each sent DLT message */
 351     uint16_t len;           /**< Length of the complete message, without storage header */
 352 } PACKED DltStandardHeader;
 353
 354 /**
 355  * The structure of the DLT extra header parameters. Each parameter is sent only if enabled in htyp.
 356  */
 357 typedef struct
 358 {
 359     char ecu[DLT_ID_SIZE];       /**< ECU id */
 360     uint32_t seid;     /**< Session number */
 361     uint32_t tmsp;     /**< Timestamp since system start in 0.1 milliseconds */
 362 } PACKED DltStandardHeaderExtra;
 363
 364 /**
 365  * The structure of the DLT extended header. This header is only sent if enabled in htyp parameter.
 366  */
 367 typedef struct
 368 {
 369     uint8_t msin;          /**< messsage info */
 370     uint8_t noar;          /**< number of arguments */
 371     char apid[DLT_ID_SIZE];          /**< application id */
 372     char ctid[DLT_ID_SIZE];          /**< context id */
 373 } PACKED DltExtendedHeader;
 374
 375 /**
 376  * The structure to organise the DLT messages.
 377  * This structure is used by the corresponding functions.
 378  */
 379 typedef struct sDltMessage
 380 {
 381     /* flags */
 382     int8_t found_serialheader;
 383
 384     /* offsets */
 385     int32_t resync_offset;
 386
 387     /* size parameters */
 388     int32_t headersize;    /**< size of complete header including storage header */
 389     int32_t datasize;      /**< size of complete payload */
 390
 391     /* buffer for current loaded message */
 392     uint8_t headerbuffer[sizeof(DltStorageHeader)+
 393                          sizeof(DltStandardHeader)+sizeof(DltStandardHeaderExtra)+sizeof(DltExtendedHeader)]; /**< buffer for loading complete header */
 394     uint8_t *databuffer;         /**< buffer for loading payload */
 395
 396     /* header values of current loaded message */
 397     DltStorageHeader       *storageheader;  /**< pointer to storage header of current loaded header */
 398     DltStandardHeader      *standardheader; /**< pointer to standard header of current loaded header */
 399     DltStandardHeaderExtra headerextra;     /**< extra parameters of current loaded header */
 400     DltExtendedHeader      *extendedheader; /**< pointer to extended of current loaded header */
 401 } DltMessage;
 402
 403 /**
 404  * The structure of the DLT Service Get Log Info.
 405  */
 406 typedef struct
 407 {
 408     uint32_t service_id;            /**< service ID */
 409     uint8_t options;                /**< type of request */
 410     char apid[DLT_ID_SIZE];                   /**< application id */
 411     char ctid[DLT_ID_SIZE];                   /**< context id */
 412     char com[DLT_ID_SIZE];                    /**< communication interface */
 413 } PACKED DltServiceGetLogInfoRequest;
 414
 415 /**
 416  * The structure of the DLT Service Set Log Level.
 417  */
 418 typedef struct
 419 {
 420     uint32_t service_id;            /**< service ID */
 421     char apid[DLT_ID_SIZE];                   /**< application id */
 422     char ctid[DLT_ID_SIZE];                   /**< context id */
 423     uint8_t log_level;              /**< log level to be set */
 424     char com[DLT_ID_SIZE];                    /**< communication interface */
 425 } PACKED DltServiceSetLogLevel;
 426
 427 /**
 428  * The structure of the DLT Service Set Default Log Level.
 429  */
 430 typedef struct
 431 {
 432     uint32_t service_id;            /**< service ID */
 433     uint8_t log_level;              /**< default log level to be set */
 434     char com[DLT_ID_SIZE];                    /**< communication interface */
 435 } PACKED DltServiceSetDefaultLogLevel;
 436
 437 /**
 438  * The structure of the DLT Service Set Verbose Mode
 439  */
 440 typedef struct
 441 {
 442     uint32_t service_id;            /**< service ID */
 443     uint8_t new_status;             /**< new status to be set */
 444 } PACKED DltServiceSetVerboseMode;
 445
 446 /**
 447  * The structure of the DLT Service Set Communication Interface Status
 448  */
 449 typedef struct
 450 {
 451     uint32_t service_id;            /**< service ID */
 452     char com[DLT_ID_SIZE];                    /**< communication interface */
 453     uint8_t new_status;             /**< new status to be set */
 454 } PACKED DltServiceSetCommunicationInterfaceStatus;
 455
 456 /**
 457  * The structure of the DLT Service Set Communication Maximum Bandwidth
 458  */
 459 typedef struct
 460 {
 461     uint32_t service_id;            /**< service ID */
 462     char com[DLT_ID_SIZE];                    /**< communication interface */
 463     uint32_t max_bandwidth;         /**< maximum bandwith */
 464 } PACKED DltServiceSetCommunicationMaximumBandwidth;
 465
 466 typedef struct
 467 {
 468     uint32_t service_id;            /**< service ID */
 469     uint8_t status;                 /**< reponse status */
 470 } PACKED DltServiceResponse;
 471
 472 typedef struct
 473 {
 474     uint32_t service_id;            /**< service ID */
 475     uint8_t status;                 /**< reponse status */
 476     uint8_t log_level;              /**< log level */
 477 } PACKED DltServiceGetDefaultLogLevelResponse;
 478
 479 typedef struct
 480 {
 481     uint32_t service_id;            /**< service ID */
 482     uint8_t status;                 /**< reponse status */
 483     uint8_t overflow;               /**< overflow status */
 484 } PACKED DltServiceMessageBufferOverflowResponse;
 485
 486 typedef struct
 487 {
 488     uint32_t service_id;            /**< service ID */
 489     uint8_t  status;                /**< reponse status */
 490     uint32_t length;                /**< length of following payload */
 491     /* char [] payload */
 492 } PACKED DltServiceGetSoftwareVersionResponse;
 493
 494 /**
 495  * Structure to store filter parameters.
 496  * ID are maximal four characters. Unused values are filled with zeros.
 497  * If every value as filter is valid, the id should be empty by having only zero values.
 498  */
 499 typedef struct
 500 {
 501     char apid[DLT_FILTER_MAX][DLT_ID_SIZE]; /**< application id */
 502     char ctid[DLT_FILTER_MAX][DLT_ID_SIZE]; /**< context id */
 503     int  counter;                           /**< number of filters */
 504 } DltFilter;
 505
 506 /**
 507  * The structure to organise the access to DLT files.
 508  * This structure is used by the corresponding functions.
 509  */
 510 typedef struct sDltFile
 511 {
 512     /* file handle and index for fast access */
 513     FILE *handle;      /**< file handle of opened DLT file */
 514     long *index;       /**< file positions of all DLT messages for fast access to file, only filtered messages */
 515
 516     /* size parameters */
 517     int32_t counter;       /**< number of messages in DLT file with filter */
 518     int32_t counter_total; /**< number of messages in DLT file without filter */
 519     int32_t position;      /**< current index to message parsed in DLT file starting at 0 */
 520     long file_length;  /**< length of the file */
 521     long file_position; /**< current position in the file */
 522
 523     /* error counters */
 524     int32_t error_messages; /**< number of incomplete DLT messages found during file parsing */
 525
 526     /* filter parameters */
 527     DltFilter *filter;  /**< pointer to filter list. Zero if no filter is set. */
 528     int32_t filter_counter; /**< number of filter set */
 529
 530     /* current loaded message */
 531     DltMessage msg;     /**< pointer to message */
 532
 533 } DltFile;
 534
 535 /**
 536  * The structure is used to organise the receiving of data
 537  * including buffer handling.
 538  * This structure is used by the corresponding functions.
 539  */
 540 typedef struct
 541 {
 542     int32_t lastBytesRcvd;    /**< bytes received in last receive call */
 543     int32_t bytesRcvd;        /**< received bytes */
 544     int32_t totalBytesRcvd;   /**< total number of received bytes */
 545     char *buffer;         /**< pointer to receiver buffer */
 546     char *buf;            /**< pointer to position within receiver buffer */
 547     int fd;               /**< connection handle */
 548     int32_t buffersize;       /**< size of receiver buffer */
 549 } DltReceiver;
 550
 551 typedef struct
 552 {
 553     char*   buffer;         /**< Ptr. to buffer */
 554     uint32_t    size;       /**< Maximum size of buffer */
 555     uint32_t    pos_write;  /**< current writing position in bytes*/
 556     uint32_t    pos_read;   /**< current reading position in bytes*/
 557     uint32_t    count;      /**< nr. of entries */
 558 } DltRingBuffer;
 559
 560 #ifdef __cplusplus
 561 extern "C"
 562 {
 563 #endif
 564
 565     /**
 566      * Helper function to print a byte array in hex.
 567      * @param ptr pointer to the byte array.
 568      * @param size number of bytes to be printed.
 569      */
 570     void dlt_print_hex(uint8_t *ptr,int size);
 571     /**
 572      * Helper function to print a byte array in hex into a string.
 573      * @param text pointer to a ASCII string, in which the text is written
 574      * @param textlength maximal size of text buffer
 575      * @param ptr pointer to the byte array.
 576      * @param size number of bytes to be printed.
 577      * @return negative value if there was an error
 578      */
 579     int dlt_print_hex_string(char *text,int textlength,uint8_t *ptr,int size);
 580     /**
 581      * Helper function to print a byte array in hex and ascii into a string.
 582      * @param text pointer to a ASCII string, in which the text is written
 583      * @param textlength maximal size of text buffer
 584      * @param ptr pointer to the byte array.
 585      * @param size number of bytes to be printed.
 586      * @param html output is html? 0 - false, 1 - true
 587      * @return negative value if there was an error
 588      */
 589     int dlt_print_mixed_string(char *text,int textlength,uint8_t *ptr,int size,int html);
 590     /**
 591      * Helper function to print a byte array in ascii into a string.
 592      * @param text pointer to a ASCII string, in which the text is written
 593      * @param textlength maximal size of text buffer
 594      * @param ptr pointer to the byte array.
 595      * @param size number of bytes to be printed.
 596      * @return negative value if there was an error
 597      */
 598     int dlt_print_char_string(char **text,int textlength,uint8_t *ptr,int size);
 599
 600     /**
 601      * Helper function to print an id.
 602      * @param text pointer to ASCII string where to write the id
 603      * @param id four byte char array as used in DLT mesages as IDs.
 604      */
 605     void dlt_print_id(char *text,const char *id);
 606
 607     /**
 608      * Helper function to set an ID parameter.
 609      * @param id four byte char array as used in DLT mesages as IDs.
 610      * @param text string to be copied into char array.
 611      */
 612     void dlt_set_id(char *id,const char *text);
 613
 614     /**
 615      * Helper function to remove not nice to print characters, e.g. NULL or carage return.
 616      * @param text pointer to string to be cleaned.
 617      * @param length length of string excluding terminating zero.
 618      */
 619     void dlt_clean_string(char *text,int length);
 620
 621     /**
 622      * Initialise the filter list.
 623      * This function must be called before using further dlt filter.
 624      * @param filter pointer to structure of organising DLT filter
 625      * @param verbose if set to true verbose information is printed out.
 626      * @return negative value if there was an error
 627      */
 628     int dlt_filter_init(DltFilter *filter,int verbose);
 629     /**
 630      * Free the used memory by the organising structure of filter.
 631      * @param filter pointer to structure of organising DLT filter
 632      * @param verbose if set to true verbose information is printed out.
 633      * @return negative value if there was an error
 634      */
 635     int dlt_filter_free(DltFilter *filter,int verbose);
 636     /**
 637      * Load filter list from file.
 638      * @param filter pointer to structure of organising DLT filter
 639      * @param filename filename to load filters from
 640      * @param verbose if set to true verbose information is printed out.
 641      * @return negative value if there was an error
 642      */
 643     int dlt_filter_load(DltFilter *filter,const char *filename,int verbose);
 644     /**
 645      * Save filter list to file.
 646      * @param filter pointer to structure of organising DLT filter
 647      * @param filename filename to load filters from
 648      * @param verbose if set to true verbose information is printed out.
 649      * @return negative value if there was an error
 650      */
 651     int dlt_filter_save(DltFilter *filter,const char *filename,int verbose);
 652     /**
 653      * Find index of filter in filter list
 654      * @param filter pointer to structure of organising DLT filter
 655      * @param apid application id to be found in filter list
 656      * @param ctid context id to be found in filter list
 657      * @param verbose if set to true verbose information is printed out.
 658      * @return negative value if there was an error (or not found), else return index of filter
 659      */
 660     int dlt_filter_find(DltFilter *filter,const char *apid,const char *ctid, int verbose);
 661     /**
 662      * Add new filter to filter list.
 663      * @param filter pointer to structure of organising DLT filter
 664      * @param apid application id to be added to filter list (must always be set).
 665      * @param ctid context id to be added to filter list. empty equals don't care.
 666      * @param verbose if set to true verbose information is printed out.
 667      * @return negative value if there was an error
 668      */
 669     int dlt_filter_add(DltFilter *filter,const char *apid,const char *ctid,int verbose);
 670     /**
 671      * Delete filter from filter list
 672      * @param filter pointer to structure of organising DLT filter
 673      * @param apid application id to be deleted from filter list
 674      * @param ctid context id to be deleted from filter list
 675      * @param verbose if set to true verbose information is printed out.
 676      * @return negative value if there was an error
 677      */
 678     int dlt_filter_delete(DltFilter *filter,const char *apid,const char *ctid,int verbose);
 679
 680     /**
 681      * Initialise the structure used to access a DLT message.
 682      * This function must be called before using further dlt_message functions.
 683      * @param msg pointer to structure of organising access to DLT messages
 684      * @param verbose if set to true verbose information is printed out.
 685      * @return negative value if there was an error
 686      */
 687     int dlt_message_init(DltMessage *msg,int verbose);
 688     /**
 689      * Free the used memory by the organising structure of file.
 690      * @param msg pointer to structure of organising access to DLT messages
 691      * @param verbose if set to true verbose information is printed out.
 692      * @return negative value if there was an error
 693      */
 694     int dlt_message_free(DltMessage *msg,int verbose);
 695     /**
 696      * Print Header into an ASCII string.
 697      * This function calls dlt_message_header_flags() with flags=DLT_HEADER_SHOW_ALL
 698      * @param msg pointer to structure of organising access to DLT messages
 699      * @param text pointer to a ASCII string, in which the header is written
 700      * @param textlength maximal size of text buffer
 701      * @param verbose if set to true verbose information is printed out.
 702      * @return negative value if there was an error
 703      */
 704     int dlt_message_header(DltMessage *msg,char *text,int textlength,int verbose);
 705     /**
 706      * Print Header into an ASCII string, selective.
 707      * @param msg pointer to structure of organising access to DLT messages
 708      * @param text pointer to a ASCII string, in which the header is written
 709      * @param textlength maximal size of text buffer
 710      * @param flags select, bit-field to select, what should be printed (DLT_HEADER_SHOW_...)
 711      * @param verbose if set to true verbose information is printed out.
 712      * @return negative value if there was an error
 713      */
 714     int dlt_message_header_flags(DltMessage *msg,char *text,int textlength,int flags, int verbose);
 715     /**
 716      * Print Payload into an ASCII string.
 717      * @param msg pointer to structure of organising access to DLT messages
 718      * @param text pointer to a ASCII string, in which the header is written
 719      * @param textlength maximal size of text buffer
 720      * @param type 1 = payload as hex, 2 = payload as ASCII.
 721      * @param verbose if set to true verbose information is printed out.
 722      * @return negative value if there was an error
 723      */
 724     int dlt_message_payload(DltMessage *msg,char *text,int textlength,int type,int verbose);
 725     /**
 726      * Check if message is filtered or not. All filters are applied (logical OR).
 727      * @param msg pointer to structure of organising access to DLT messages
 728      * @param filter pointer to filter
 729      * @param verbose if set to true verbose information is printed out.
 730      * @return 1 = filter matches, 0 = filter does not match, negative value if there was an error
 731      */
 732     int dlt_message_filter_check(DltMessage *msg,DltFilter *filter,int verbose);
 733
 734     /**
 735      * Read message from memory buffer.
 736      * Message in buffer has no storage header.
 737      * @param msg pointer to structure of organising access to DLT messages
 738      * @param buffer pointer to memory buffer
 739      * @param length length of message in buffer
 740      * @param resync if set to true resync to serial header is enforced
 741      * @param verbose if set to true verbose information is printed out.
 742      * @return negative value if there was an error
 743      */
 744     int dlt_message_read(DltMessage *msg,uint8_t *buffer,unsigned int length,int resync,int verbose);
 745
 746     /**
 747      * Get standard header extra parameters
 748      * @param msg pointer to structure of organising access to DLT messages
 749      * @param verbose if set to true verbose information is printed out.
 750      * @return negative value if there was an error
 751      */
 752     int dlt_message_get_extraparameters(DltMessage *msg,int verbose);
 753
 754     /**
 755      * Set standard header extra parameters
 756      * @param msg pointer to structure of organising access to DLT messages
 757      * @param verbose if set to true verbose information is printed out.
 758      * @return negative value if there was an error
 759      */
 760     int dlt_message_set_extraparameters(DltMessage *msg,int verbose);
 761
 762     /**
 763      * Initialise the structure used to access a DLT file.
 764      * This function must be called before using further dlt_file functions.
 765      * @param file pointer to structure of organising access to DLT file
 766      * @param verbose if set to true verbose information is printed out.
 767      * @return negative value if there was an error
 768      */
 769     int dlt_file_init(DltFile *file,int verbose);
 770     /**
 771      * Set a list to filters.
 772      * This function should be called before loading a DLT file, if filters should be used.
 773      * A filter list is an array of filters. Several filters are combined logically by or operation.
 774      * The filter list is not copied, so take care to keep list in memory.
 775      * @param file pointer to structure of organising access to DLT file
 776      * @param filter pointer to filter list array
 777      * @param verbose if set to true verbose information is printed out.
 778      * @return negative value if there was an error
 779      */
 780     int dlt_file_set_filter(DltFile *file,DltFilter *filter,int verbose);
 781     /**
 782      * Initialising loading a DLT file.
 783      * @param file pointer to structure of organising access to DLT file
 784      * @param filename filename of DLT file
 785      * @param verbose if set to true verbose information is printed out.
 786      * @return negative value if there was an error
 787      */
 788     int dlt_file_open(DltFile *file,const char *filename,int verbose);
 789     /**
 790      * Find next message in the DLT file and parse them.
 791      * This function finds the next message in the DLT file.
 792      * If a filter is set, the filter list is used.
 793      * @param file pointer to structure of organising access to DLT file
 794      * @param verbose if set to true verbose information is printed out.
 795      * @return 0 = message does not match filter, 1 = message was read, negative value if there was an error
 796      */
 797     int dlt_file_read(DltFile *file,int verbose);
 798     /**
 799      * Find next message in the DLT file in RAW format (without storage header) and parse them.
 800      * This function finds the next message in the DLT file.
 801      * If a filter is set, the filter list is used.
 802      * @param file pointer to structure of organising access to DLT file
 803      * @param resync Resync to serial header when set to true
 804      * @param verbose if set to true verbose information is printed out.
 805      * @return 0 = message does not match filter, 1 = message was read, negative value if there was an error
 806      */
 807     int dlt_file_read_raw(DltFile *file,int resync,int verbose);
 808     /**
 809      * Closing loading a DLT file.
 810      * @param file pointer to structure of organising access to DLT file
 811      * @param verbose if set to true verbose information is printed out.
 812      * @return negative value if there was an error
 813      */
 814     int dlt_file_close(DltFile *file,int verbose);
 815     /**
 816      * Load standard header of a message from file
 817      * @param file pointer to structure of organising access to DLT file
 818      * @param verbose if set to true verbose information is printed out.
 819      * @return negative value if there was an error
 820      */
 821     int dlt_file_read_header(DltFile *file,int verbose);
 822     /**
 823      * Load standard header of a message from file in RAW format (without storage header)
 824      * @param file pointer to structure of organising access to DLT file
 825      * @param resync Resync to serial header when set to true
 826      * @param verbose if set to true verbose information is printed out.
 827      * @return negative value if there was an error
 828      */
 829     int dlt_file_read_header_raw(DltFile *file,int resync,int verbose);
 830     /**
 831      * Load, if available in message, extra standard header fields and
 832      * extended header of a message from file
 833      * (dlt_file_read_header() must have been called before this call!)
 834      * @param file pointer to structure of organising access to DLT file
 835      * @param verbose if set to true verbose information is printed out.
 836      * @return negative value if there was an error
 837      */
 838     int dlt_file_read_header_extended(DltFile *file, int verbose);
 839     /**
 840      * Load payload of a message from file
 841      * (dlt_file_read_header() must have been called before this call!)
 842      * @param file pointer to structure of organising access to DLT file
 843      * @param verbose if set to true verbose information is printed out.
 844      * @return negative value if there was an error
 845      */
 846     int dlt_file_read_data(DltFile *file, int verbose);
 847     /**
 848      * Load headers and payload of a message selected by the index.
 849      * If filters are set, index is based on the filtered list.
 850      * @param file pointer to structure of organising access to DLT file
 851      * @param index position of message in the files beginning from zero
 852      * @param verbose if set to true verbose information is printed out.
 853      * @return number of messages loaded, negative value if there was an error
 854      */
 855     int dlt_file_message(DltFile *file,int index,int verbose);
 856     /**
 857      * Free the used memory by the organising structure of file.
 858      * @param file pointer to structure of organising access to DLT file
 859      * @param verbose if set to true verbose information is printed out.
 860      * @return negative value if there was an error
 861      */
 862     int dlt_file_free(DltFile *file,int verbose);
 863
 864     /**
 865      * Initialize (external) logging facility
 866      * @param mode positive, if syslog should be used; zero for console output
 867      */
 868     void dlt_log_init(int mode);
 869     /**
 870      * Log ASCII string with null-termination to (external) logging facility
 871      * @param prio priority (see syslog() call)
 872      * @param s Pointer to ASCII string with null-termination
 873      * @return negative value if there was an error
 874      */
 875     int dlt_log(int prio, char *s);
 876     /**
 877      * De-Initialize (external) logging facility
 878      */
 879     void dlt_log_free(void);
 880
 881     /**
 882      * Initialising a dlt receiver structure
 883      * @param receiver pointer to dlt receiver structure
 884      * @param _fd handle to file/socket/fifo, fram which the data should be received
 885      * @param _buffersize size of data buffer for storing the received data
 886      * @return negative value if there was an error
 887      */
 888     int dlt_receiver_init(DltReceiver *receiver,int _fd, int _buffersize);
 889     /**
 890      * De-Initialize a dlt receiver structure
 891      * @param receiver pointer to dlt receiver structure
 892      * @return negative value if there was an error
 893      */
 894     int dlt_receiver_free(DltReceiver *receiver);
 895     /**
 896      * Receive data from socket using the dlt receiver structure
 897      * @param receiver pointer to dlt receiver structure
 898      * @return negative value if there was an error
 899      */
 900     int dlt_receiver_receive_socket(DltReceiver *receiver);
 901     /**
 902      * Receive data from file/fifo using the dlt receiver structure
 903      * @param receiver pointer to dlt receiver structure
 904      * @return negative value if there was an error
 905      */
 906     int dlt_receiver_receive_fd(DltReceiver *receiver);
 907     /**
 908      * Remove a specific size of bytes from the received data
 909      * @param receiver pointer to dlt receiver structure
 910      * @param size amount of bytes to be removed
 911      * @return negative value if there was an error
 912      */
 913     int dlt_receiver_remove(DltReceiver *receiver,int size);
 914     /**
 915      * Move data from last receive call to front of receive buffer
 916      * @param receiver pointer to dlt receiver structure
 917      * @return negative value if there was an error
 918      */
 919     int dlt_receiver_move_to_begin(DltReceiver *receiver);
 920
 921     /**
 922      * Fill out storage header of a dlt message
 923      * @param storageheader pointer to storage header of a dlt message
 924      * @param ecu name of ecu to be set in storage header
 925      * @return negative value if there was an error
 926      */
 927     int dlt_set_storageheader(DltStorageHeader *storageheader, const char *ecu);
 928     /**
 929      * Check if a storage header contains its marker
 930      * @param storageheader pointer to storage header of a dlt message
 931      * @return 0 no, 1 yes, negative value if there was an error
 932      */
 933     int dlt_check_storageheader(DltStorageHeader *storageheader);
 934
 935     /**
 936      * Initialize ringbuffer of with a maximum size of size
 937      * @param dltbuf Pointer to ringbuffer structure
 938      * @param size Maximum size of buffer in bytes
 939      * @return negative value if there was an error
 940      */
 941     int dlt_ringbuffer_init(DltRingBuffer *dltbuf, uint32_t size);
 942
 943     /**
 944      * Release and free memory used by ringbuffer
 945      * @param dltbuf Pointer to ringbuffer structure
 946      * @return negative value if there was an error
 947      */
 948     int dlt_ringbuffer_free(DltRingBuffer *dltbuf);
 949
 950     /**
 951      * Write one entry to ringbuffer
 952      * @param dltbuf Pointer to ringbuffer structure
 953      * @param data Pointer to data to be written to ringbuffer
 954      * @param size Size of data in bytes to be written to ringbuffer
 955      * @return negative value if there was an error
 956      */
 957     int dlt_ringbuffer_put(DltRingBuffer *dltbuf, void *data, uint32_t size);
 958
 959     /**
 960      * Write one entry given as 3 chunks to ringbuffer
 961      * @param dltbuf Pointer to ringbuffer structure
 962      * @param data1 Pointer to data1 to be written to ringbuffer
 963      * @param size1 Size of data1 in bytes to be written to ringbuffer
 964      * @param data2 Pointer to data2 to be written to ringbuffer
 965      * @param size2 Size of data2 in bytes to be written to ringbuffer
 966      * @param data3 Pointer to data3 to be written to ringbuffer
 967      * @param size3 Size of data3 in bytes to be written to ringbuffer
 968      * @return negative value if there was an error
 969      */
 970     int dlt_ringbuffer_put3(DltRingBuffer *dltbuf, void *data1, uint32_t size1, void *data2, uint32_t size2, void *data3, uint32_t size3);
 971
 972     /**
 973      * Read one entry from ringbuffer
 974      * @param dltbuf Pointer to ringbuffer structure
 975      * @param data Pointer to data read from ringbuffer
 976      * @param size Size of read data in bytes from ringbuffer
 977      * @return negative value if there was an error
 978      */
 979     int dlt_ringbuffer_get(DltRingBuffer *dltbuf, void *data, size_t *size);
 980
 981     /**
 982      * Helper function: Skip one readable entry in ringbuffer
 983      * @param dltbuf Pointer to ringbuffer structure
 984      * @return negative value if there was an error
 985      */
 986     int dlt_ringbuffer_get_skip(DltRingBuffer *dltbuf);
 987
 988     /**
 989      * Helper function: Get free space in bytes for writting between write and read position
 990      * @param dltbuf Pointer to ringbuffer structure
 991      * @param freespace Free Space in bytes for writting is returned
 992      * @return negative value if there was an error
 993      */
 994     int dlt_ringbuffer_freespacewrite(DltRingBuffer *dltbuf, uint32_t *freespace);
 995
 996     /**
 997      * Helper function: Check free space and if necessary discard entries, so that at least
 998      * reqspace bytes are available for writting
 999      * @param dltbuf Pointer to ringbuffer structure
1000      * @param reqspace Requested space for writting in bytes
1001      * @return negative value if there was an error
1002      */
1003     int dlt_ringbuffer_checkandfreespace(DltRingBuffer *dltbuf, uint32_t reqspace);
1004
1005 #if !defined (__WIN32__)
1006
1007     /**
1008      * Helper function: Setup serial connection
1009      * @param fd File descriptor of serial tty device
1010      * @param speed Serial line speed, as defined in termios.h
1011      * @return negative value if there was an error
1012      */
1013     int dlt_setup_serial(int fd, speed_t speed);
1014
1015     /**
1016      * Helper function: Convert serial line baudrate (as number) to line speed (as defined in termios.h)
1017      * @param baudrate Serial line baudrate (as number)
1018      * @return Serial line speed, as defined in termios.h
1019      */
1020     speed_t dlt_convert_serial_speed(int baudrate);
1021
1022     /**
1023      * Print dlt version and dlt svn version to buffer
1024      * @param buf Pointer to buffer
1025      */
1026     void dlt_get_version(char *buf);
1027
1028 #endif
1029
1030     /* Function prototypes which should be used only internally */
1031     /*                                                          */
1032
1033     /**
1034      * Common part of initialisation
1035      * @return negative value if there was an error
1036      */
1037     int dlt_init_common(void);
1038
1039     /**
1040      * Return the uptime of the system in 0.1 ms resolution
1041      * @return 0 if there was an error
1042      */
1043     uint32_t dlt_uptime(void);
1044
1045     /**
1046      * Print header of a DLT message
1047      * @param message pointer to structure of organising access to DLT messages
1048      * @param text pointer to a ASCII string, in which the header is written
1049      * @param size maximal size of text buffer
1050      * @param verbose if set to true verbose information is printed out.
1051      * @return negative value if there was an error
1052      */
1053     int dlt_message_print_header(DltMessage *message, char *text, uint32_t size, int verbose);
1054
1055     /**
1056      * Print payload of a DLT message as Hex-Output
1057      * @param message pointer to structure of organising access to DLT messages
1058      * @param text pointer to a ASCII string, in which the output is written
1059      * @param size maximal size of text buffer
1060      * @param verbose if set to true verbose information is printed out.
1061      * @return negative value if there was an error
1062      */
1063     int dlt_message_print_hex(DltMessage *message, char *text, uint32_t size, int verbose);
1064
1065     /**
1066      * Print payload of a DLT message as ASCII-Output
1067      * @param message pointer to structure of organising access to DLT messages
1068      * @param text pointer to a ASCII string, in which the output is written
1069      * @param size maximal size of text buffer
1070      * @param verbose if set to true verbose information is printed out.
1071      * @return negative value if there was an error
1072      */
1073     int dlt_message_print_ascii(DltMessage *message, char *text, uint32_t size, int verbose);
1074
1075     /**
1076      * Print payload of a DLT message as Mixed-Ouput (Hex and ASCII), for plain text output
1077      * @param message pointer to structure of organising access to DLT messages
1078      * @param text pointer to a ASCII string, in which the output is written
1079      * @param size maximal size of text buffer
1080      * @param verbose if set to true verbose information is printed out.
1081      * @return negative value if there was an error
1082      */
1083     int dlt_message_print_mixed_plain(DltMessage *message, char *text, uint32_t size, int verbose);
1084
1085     /**
1086      * Print payload of a DLT message as Mixed-Ouput (Hex and ASCII), for HTML text output
1087      * @param message pointer to structure of organising access to DLT messages
1088      * @param text pointer to a ASCII string, in which the output is written
1089      * @param size maximal size of text buffer
1090      * @param verbose if set to true verbose information is printed out.
1091      * @return negative value if there was an error
1092      */
1093     int dlt_message_print_mixed_html(DltMessage *message, char *text, uint32_t size, int verbose);
1094
1095     /**
1096      * Decode and print a argument of a DLT message
1097      * @param msg pointer to structure of organising access to DLT messages
1098      * @param type_info Type of argument
1099      * @param ptr pointer to pointer to data (pointer to data is changed within this function)
1100      * @param datalength pointer to datalength (datalength is changed within this function)
1101      * @param text pointer to a ASCII string, in which the output is written
1102      * @param textlength maximal size of text buffer
1103      * @param byteLength If argument is a string, and this value is 0 or greater, this value will be taken as string length
1104      * @param verbose if set to true verbose information is printed out.
1105      * @return negative value if there was an error
1106      */
1107     int dlt_message_argument_print(DltMessage *msg,uint32_t type_info,uint8_t **ptr,int32_t *datalength,char *text,int textlength,int byteLength,int verbose);
1108
1109 #ifdef __cplusplus
1110 }
1111 #endif
1112
1113 /**
1114   \}
1115 */
1116
1117 #endif /* DLT_COMMON_H */