3 * Copyright (C) 2012 BMW AG
5 * This file is part of GENIVI Project Dlt - Diagnostic Log and Trace console apps.
7 * Contributions are licensed to the GENIVI Alliance under one or more
8 * Contribution License Agreements.
11 * This Source Code Form is subject to the terms of the
12 * Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
13 * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
16 * \author Alexander Wenzel <alexander.aw.wenzel@bmw.de> BMW 2011-2012
19 * For further information see http://www.genivi.org/.
23 /*******************************************************************************
25 ** SRC-MODULE: dlt_common.h **
31 ** AUTHOR : Alexander Wenzel Alexander.AW.Wenzel@bmw.de **
38 ** PLATFORM DEPENDANT [yes/no]: yes **
40 ** TO BE CHANGED BY USER [yes/no]: no **
42 *******************************************************************************/
44 /*******************************************************************************
46 ********************************************************************************
48 ** Initials Name Company **
49 ** -------- ------------------------- ---------------------------------- **
50 ** aw Alexander Wenzel BMW **
51 ** mk Markus Klein Fraunhofer ESK **
52 *******************************************************************************/
54 /*******************************************************************************
55 ** Revision Control History **
56 *******************************************************************************/
59 * $LastChangedRevision: 1670 $
60 * $LastChangedDate: 2011-04-08 15:12:06 +0200 (Fr, 08. Apr 2011) $
69 \defgroup commonapi DLT Common API
76 #if !defined(_MSC_VER)
81 #if !defined (__WIN32__) && !defined(_MSC_VER)
85 #include "dlt_types.h"
86 #include "dlt_protocol.h"
89 #define PACKED __attribute__((aligned(1),packed))
92 #if defined (__MSDOS__) || defined (_MSC_VER)
93 /* set instead /Zp8 flag in Visual C++ configuration */
99 * Macros to swap the byte order.
101 #define DLT_SWAP_64(value) ((((uint64_t)DLT_SWAP_32((value)&0xffffffffull))<<32) | (DLT_SWAP_32((value)>>32)))
103 #define DLT_SWAP_16(value) ((((value) >> 8)&0xff) | (((value) << 8)&0xff00))
104 #define DLT_SWAP_32(value) ((((value) >> 24)&0xff) | (((value) << 8)&0xff0000) | (((value) >> 8)&0xff00) | (((value) << 24)&0xff000000))
106 /* Set Big Endian and Little Endian to a initial value, if not defined */
107 #if !defined __USE_BSD
108 #ifndef LITTLE_ENDIAN
109 #define LITTLE_ENDIAN 1234
113 #define BIG_ENDIAN 4321
115 #endif /* __USE_BSD */
117 /* If byte order is not defined, default to little endian */
118 #if !defined __USE_BSD
120 #define BYTE_ORDER LITTLE_ENDIAN
122 #endif /* __USE_BSD */
124 /* Check for byte-order */
125 #if (BYTE_ORDER==BIG_ENDIAN)
126 /* #warning "Big Endian Architecture!" */
127 #define DLT_HTOBE_16(x) ((x))
128 #define DLT_HTOLE_16(x) DLT_SWAP_16((x))
129 #define DLT_BETOH_16(x) ((x))
130 #define DLT_LETOH_16(x) DLT_SWAP_16((x))
132 #define DLT_HTOBE_32(x) ((x))
133 #define DLT_HTOLE_32(x) DLT_SWAP_32((x))
134 #define DLT_BETOH_32(x) ((x))
135 #define DLT_LETOH_32(x) DLT_SWAP_32((x))
137 #define DLT_HTOBE_64(x) ((x))
138 #define DLT_HTOLE_64(x) DLT_SWAP_64((x))
139 #define DLT_BETOH_64(x) ((x))
140 #define DLT_LETOH_64(x) DLT_SWAP_64((x))
142 /* #warning "Litte Endian Architecture!" */
143 #define DLT_HTOBE_16(x) DLT_SWAP_16((x))
144 #define DLT_HTOLE_16(x) ((x))
145 #define DLT_BETOH_16(x) DLT_SWAP_16((x))
146 #define DLT_LETOH_16(x) ((x))
148 #define DLT_HTOBE_32(x) DLT_SWAP_32((x))
149 #define DLT_HTOLE_32(x) ((x))
150 #define DLT_BETOH_32(x) DLT_SWAP_32((x))
151 #define DLT_LETOH_32(x) ((x))
153 #define DLT_HTOBE_64(x) DLT_SWAP_64((x))
154 #define DLT_HTOLE_64(x) ((x))
155 #define DLT_BETOH_64(x) DLT_SWAP_64((x))
156 #define DLT_LETOH_64(x) ((x))
159 #define DLT_ENDIAN_GET_16(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_16(x):DLT_LETOH_16(x))
160 #define DLT_ENDIAN_GET_32(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_32(x):DLT_LETOH_32(x))
161 #define DLT_ENDIAN_GET_64(htyp,x) ((((htyp) & DLT_HTYP_MSBF)>0)?DLT_BETOH_64(x):DLT_LETOH_64(x))
163 #if defined (__WIN32__) || defined (_MSC_VER)
168 #define LOG_WARNING 4
174 #define LOG_DAEMON (3<<3)
178 DLT_LOG_TO_CONSOLE=0,
185 * The standard TCP Port used for DLT daemon
187 #define DLT_DAEMON_TCP_PORT 3490
190 /* Initi value for file descritpor */
191 #define DLT_FD_INIT -1
193 /* Minimum value for a file descriptor except the POSIX Standards: stdin=0, stdout=1, stderr=2 */
194 #define DLT_FD_MINIMUM 3
197 * The size of a DLT ID
199 #define DLT_ID_SIZE 4
201 #define DLT_SIZE_WEID DLT_ID_SIZE
202 #define DLT_SIZE_WSID (sizeof(uint32_t))
203 #define DLT_SIZE_WTMS (sizeof(uint32_t))
206 * Get the size of extra header parameters, depends on htyp.
208 #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) )
211 #if defined (__MSDOS__) || defined (_MSC_VER)
212 #define __func__ __FUNCTION__
215 #define PRINT_FUNCTION_VERBOSE(_verbose) \
217 static char _strbuf[255]; \
221 snprintf(_strbuf, 255, "%s()\n",__func__); \
222 dlt_log(LOG_INFO, _strbuf); \
227 #define NULL (char*)0
230 #define DLT_MSG_IS_CONTROL(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
231 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL))
233 #define DLT_MSG_IS_CONTROL_REQUEST(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
234 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
235 (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_REQUEST))
237 #define DLT_MSG_IS_CONTROL_RESPONSE(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
238 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
239 (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_RESPONSE))
241 #define DLT_MSG_IS_CONTROL_TIME(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
242 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_CONTROL) && \
243 (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_CONTROL_TIME))
245 #define DLT_MSG_IS_NW_TRACE(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
246 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_NW_TRACE))
248 #define DLT_MSG_IS_TRACE_MOST(MSG) ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && \
249 (DLT_GET_MSIN_MSTP((MSG)->extendedheader->msin)==DLT_TYPE_NW_TRACE) && \
250 (DLT_GET_MSIN_MTIN((MSG)->extendedheader->msin)==DLT_NW_TRACE_MOST))
252 #define DLT_MSG_IS_NONVERBOSE(MSG) (!(DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) || \
253 ((DLT_IS_HTYP_UEH((MSG)->standardheader->htyp)) && (!(DLT_IS_MSIN_VERB((MSG)->extendedheader->msin)))))
257 * Definitions of DLT message buffer overflow
259 #define DLT_MESSAGE_BUFFER_NO_OVERFLOW 0x00 /**< Buffer overflow has not occured */
260 #define DLT_MESSAGE_BUFFER_OVERFLOW 0x01 /**< Buffer overflow has occured */
263 * Definition of DLT output variants
265 #define DLT_OUTPUT_HEX 1
266 #define DLT_OUTPUT_ASCII 2
267 #define DLT_OUTPUT_MIXED_FOR_PLAIN 3
268 #define DLT_OUTPUT_MIXED_FOR_HTML 4
269 #define DLT_OUTPUT_ASCII_LIMITED 5
271 #define DLT_FILTER_MAX 30 /**< Maximum number of filters */
273 #define DLT_MSG_READ_VALUE(dst,src,length,type) \
275 if((length<0) || ((length)<((int32_t)sizeof(type)))) \
278 { dst = *((type*)src);src+=sizeof(type);length-=sizeof(type); } \
281 #define DLT_MSG_READ_ID(dst,src,length) \
283 if((length<0) || ((length)<DLT_ID_SIZE)) \
286 { memcpy(dst,src,DLT_ID_SIZE);src+=DLT_ID_SIZE;length-=DLT_ID_SIZE; } \
289 #define DLT_MSG_READ_STRING(dst,src,maxlength,length) \
291 if(((maxlength)<0) || ((length)<0) || ((maxlength)<(length))) \
292 { maxlength = -1; } \
294 { memcpy(dst,src,length);dlt_clean_string(dst,length);dst[length]=0; \
295 src+=length;maxlength-=length; } \
298 #define DLT_MSG_READ_NULL(src,maxlength,length) \
300 if(((maxlength)<0) || ((length)<0) || ((maxlength)<(length))) \
303 { src+=length;maxlength-=length; } \
306 #define DLT_HEADER_SHOW_NONE 0x0000
307 #define DLT_HEADER_SHOW_TIME 0x0001
308 #define DLT_HEADER_SHOW_TMSTP 0x0002
309 #define DLT_HEADER_SHOW_MSGCNT 0x0004
310 #define DLT_HEADER_SHOW_ECUID 0x0008
311 #define DLT_HEADER_SHOW_APID 0x0010
312 #define DLT_HEADER_SHOW_CTID 0x0020
313 #define DLT_HEADER_SHOW_MSGTYPE 0x0040
314 #define DLT_HEADER_SHOW_MSGSUBTYPE 0x0080
315 #define DLT_HEADER_SHOW_VNVSTATUS 0x0100
316 #define DLT_HEADER_SHOW_NOARG 0x0200
317 #define DLT_HEADER_SHOW_ALL 0xFFFF
320 * The definition of the serial header containing the characters "DLS" + 0x01.
322 extern const char dltSerialHeader[DLT_ID_SIZE];
325 * The definition of the serial header containing the characters "DLS" + 0x01 as char.
327 extern char dltSerialHeaderChar[DLT_ID_SIZE];
331 * The type of a DLT ID (context id, application id, etc.)
333 typedef char ID4[DLT_ID_SIZE];
336 * The structure of the DLT file storage header. This header is used before each stored DLT message.
340 char pattern[DLT_ID_SIZE]; /**< This pattern should be DLT0x01 */
341 uint32_t seconds; /**< seconds since 1.1.1970 */
342 int32_t microseconds; /**< Microseconds */
343 char ecu[DLT_ID_SIZE]; /**< The ECU id is added, if it is not already in the DLT message itself */
344 } PACKED DltStorageHeader;
347 * The structure of the DLT standard header. This header is used in each DLT message.
351 uint8_t htyp; /**< This parameter contains several informations, see definitions below */
352 uint8_t mcnt; /**< The message counter is increased with each sent DLT message */
353 uint16_t len; /**< Length of the complete message, without storage header */
354 } PACKED DltStandardHeader;
357 * The structure of the DLT extra header parameters. Each parameter is sent only if enabled in htyp.
361 char ecu[DLT_ID_SIZE]; /**< ECU id */
362 uint32_t seid; /**< Session number */
363 uint32_t tmsp; /**< Timestamp since system start in 0.1 milliseconds */
364 } PACKED DltStandardHeaderExtra;
367 * The structure of the DLT extended header. This header is only sent if enabled in htyp parameter.
371 uint8_t msin; /**< messsage info */
372 uint8_t noar; /**< number of arguments */
373 char apid[DLT_ID_SIZE]; /**< application id */
374 char ctid[DLT_ID_SIZE]; /**< context id */
375 } PACKED DltExtendedHeader;
378 * The structure to organise the DLT messages.
379 * This structure is used by the corresponding functions.
381 typedef struct sDltMessage
384 int8_t found_serialheader;
387 int32_t resync_offset;
389 /* size parameters */
390 int32_t headersize; /**< size of complete header including storage header */
391 int32_t datasize; /**< size of complete payload */
393 /* buffer for current loaded message */
394 uint8_t headerbuffer[sizeof(DltStorageHeader)+
395 sizeof(DltStandardHeader)+sizeof(DltStandardHeaderExtra)+sizeof(DltExtendedHeader)]; /**< buffer for loading complete header */
396 uint8_t *databuffer; /**< buffer for loading payload */
397 int32_t databuffersize;
399 /* header values of current loaded message */
400 DltStorageHeader *storageheader; /**< pointer to storage header of current loaded header */
401 DltStandardHeader *standardheader; /**< pointer to standard header of current loaded header */
402 DltStandardHeaderExtra headerextra; /**< extra parameters of current loaded header */
403 DltExtendedHeader *extendedheader; /**< pointer to extended of current loaded header */
407 * The structure of the DLT Service Get Log Info.
411 uint32_t service_id; /**< service ID */
412 uint8_t options; /**< type of request */
413 char apid[DLT_ID_SIZE]; /**< application id */
414 char ctid[DLT_ID_SIZE]; /**< context id */
415 char com[DLT_ID_SIZE]; /**< communication interface */
416 } PACKED DltServiceGetLogInfoRequest;
419 * The structure of the DLT Service Set Log Level.
424 uint32_t service_id; /**< service ID */
425 char apid[DLT_ID_SIZE]; /**< application id */
426 char ctid[DLT_ID_SIZE]; /**< context id */
427 uint8_t log_level; /**< log level to be set */
428 char com[DLT_ID_SIZE]; /**< communication interface */
429 } PACKED DltServiceSetLogLevel;
432 * The structure of the DLT Service Set Default Log Level.
436 uint32_t service_id; /**< service ID */
437 uint8_t log_level; /**< default log level to be set */
438 char com[DLT_ID_SIZE]; /**< communication interface */
439 } PACKED DltServiceSetDefaultLogLevel;
442 * The structure of the DLT Service Set Verbose Mode
446 uint32_t service_id; /**< service ID */
447 uint8_t new_status; /**< new status to be set */
448 } PACKED DltServiceSetVerboseMode;
451 * The structure of the DLT Service Set Communication Interface Status
455 uint32_t service_id; /**< service ID */
456 char com[DLT_ID_SIZE]; /**< communication interface */
457 uint8_t new_status; /**< new status to be set */
458 } PACKED DltServiceSetCommunicationInterfaceStatus;
461 * The structure of the DLT Service Set Communication Maximum Bandwidth
465 uint32_t service_id; /**< service ID */
466 char com[DLT_ID_SIZE]; /**< communication interface */
467 uint32_t max_bandwidth; /**< maximum bandwith */
468 } PACKED DltServiceSetCommunicationMaximumBandwidth;
472 uint32_t service_id; /**< service ID */
473 uint8_t status; /**< reponse status */
474 } PACKED DltServiceResponse;
478 uint32_t service_id; /**< service ID */
479 uint8_t status; /**< reponse status */
480 uint8_t log_level; /**< log level */
481 } PACKED DltServiceGetDefaultLogLevelResponse;
485 uint32_t service_id; /**< service ID */
486 uint8_t status; /**< reponse status */
487 uint8_t overflow; /**< overflow status */
488 uint32_t overflow_counter; /**< overflow counter */
489 } PACKED DltServiceMessageBufferOverflowResponse;
493 uint32_t service_id; /**< service ID */
494 uint8_t status; /**< reponse status */
495 uint32_t length; /**< length of following payload */
496 /*char []Â payload;*/
497 } PACKED DltServiceGetSoftwareVersionResponse;
500 * The structure of the DLT Service Unregister Context.
504 uint32_t service_id; /**< service ID */
505 uint8_t status; /**< reponse status */
506 char apid[DLT_ID_SIZE]; /**< application id */
507 char ctid[DLT_ID_SIZE]; /**< context id */
508 char comid[DLT_ID_SIZE]; /**< communication interface */
509 } PACKED DltServiceUnregisterContext;
512 * The structure of the DLT Service Connection Info
516 uint32_t service_id; /**< service ID */
517 uint8_t status; /**< reponse status */
518 uint8_t state; /**< new state */
519 char comid[DLT_ID_SIZE]; /**< communication interface */
520 } PACKED DltServiceConnectionInfo;
523 * The structure of the DLT Service Timezone
527 uint32_t service_id; /**< service ID */
528 uint8_t status; /**< reponse status */
529 int32_t timezone; /**< Timezone in seconds */
530 uint8_t isdst; /**< Is daylight saving time */
531 } PACKED DltServiceTimezone;
534 * Structure to store filter parameters.
535 * ID are maximal four characters. Unused values are filled with zeros.
536 * If every value as filter is valid, the id should be empty by having only zero values.
540 char apid[DLT_FILTER_MAX][DLT_ID_SIZE]; /**< application id */
541 char ctid[DLT_FILTER_MAX][DLT_ID_SIZE]; /**< context id */
542 int counter; /**< number of filters */
546 * The structure to organise the access to DLT files.
547 * This structure is used by the corresponding functions.
549 typedef struct sDltFile
551 /* file handle and index for fast access */
552 FILE *handle; /**< file handle of opened DLT file */
553 long *index; /**< file positions of all DLT messages for fast access to file, only filtered messages */
555 /* size parameters */
556 int32_t counter; /**< number of messages in DLT file with filter */
557 int32_t counter_total; /**< number of messages in DLT file without filter */
558 int32_t position; /**< current index to message parsed in DLT file starting at 0 */
559 long file_length; /**< length of the file */
560 long file_position; /**< current position in the file */
563 int32_t error_messages; /**< number of incomplete DLT messages found during file parsing */
565 /* filter parameters */
566 DltFilter *filter; /**< pointer to filter list. Zero if no filter is set. */
567 int32_t filter_counter; /**< number of filter set */
569 /* current loaded message */
570 DltMessage msg; /**< pointer to message */
575 * The structure is used to organise the receiving of data
576 * including buffer handling.
577 * This structure is used by the corresponding functions.
581 int32_t lastBytesRcvd; /**< bytes received in last receive call */
582 int32_t bytesRcvd; /**< received bytes */
583 int32_t totalBytesRcvd; /**< total number of received bytes */
584 char *buffer; /**< pointer to receiver buffer */
585 char *buf; /**< pointer to position within receiver buffer */
586 int fd; /**< connection handle */
587 int32_t buffersize; /**< size of receiver buffer */
592 unsigned char* shm; /* pointer to beginning of shared memory */
593 int size; /* size of data area in shared memory */
594 unsigned char* mem; /* pointer to data area in shared memory */
596 uint32_t min_size; /**< Minimum size of buffer */
597 uint32_t max_size; /**< Maximum size of buffer */
598 uint32_t step_size; /**< Step size of buffer */
608 #define DLT_BUFFER_HEAD "SHM"
613 unsigned char status;
615 } DltBufferBlockHead;
617 #define DLT_MESSAGE_ERROR_OK 0
618 #define DLT_MESSAGE_ERROR_UNKNOWN -1
619 #define DLT_MESSAGE_ERROR_SIZE -2
620 #define DLT_MESSAGE_ERROR_CONTENT -3
628 * Helper function to print a byte array in hex.
629 * @param ptr pointer to the byte array.
630 * @param size number of bytes to be printed.
632 void dlt_print_hex(uint8_t *ptr,int size);
634 * Helper function to print a byte array in hex into a string.
635 * @param text pointer to a ASCII string, in which the text is written
636 * @param textlength maximal size of text buffer
637 * @param ptr pointer to the byte array.
638 * @param size number of bytes to be printed.
639 * @return negative value if there was an error
641 int dlt_print_hex_string(char *text,int textlength,uint8_t *ptr,int size);
643 * Helper function to print a byte array in hex and ascii into a string.
644 * @param text pointer to a ASCII string, in which the text is written
645 * @param textlength maximal size of text buffer
646 * @param ptr pointer to the byte array.
647 * @param size number of bytes to be printed.
648 * @param html output is html? 0 - false, 1 - true
649 * @return negative value if there was an error
651 int dlt_print_mixed_string(char *text,int textlength,uint8_t *ptr,int size,int html);
653 * Helper function to print a byte array in ascii into a string.
654 * @param text pointer to a ASCII string, in which the text is written
655 * @param textlength maximal size of text buffer
656 * @param ptr pointer to the byte array.
657 * @param size number of bytes to be printed.
658 * @return negative value if there was an error
660 int dlt_print_char_string(char **text,int textlength,uint8_t *ptr,int size);
663 * Helper function to print an id.
664 * @param text pointer to ASCII string where to write the id
665 * @param id four byte char array as used in DLT mesages as IDs.
667 void dlt_print_id(char *text,const char *id);
670 * Helper function to set an ID parameter.
671 * @param id four byte char array as used in DLT mesages as IDs.
672 * @param text string to be copied into char array.
674 void dlt_set_id(char *id,const char *text);
677 * Helper function to remove not nice to print characters, e.g. NULL or carage return.
678 * @param text pointer to string to be cleaned.
679 * @param length length of string excluding terminating zero.
681 void dlt_clean_string(char *text,int length);
684 * Initialise the filter list.
685 * This function must be called before using further dlt filter.
686 * @param filter pointer to structure of organising DLT filter
687 * @param verbose if set to true verbose information is printed out.
688 * @return negative value if there was an error
690 int dlt_filter_init(DltFilter *filter,int verbose);
692 * Free the used memory by the organising structure of filter.
693 * @param filter pointer to structure of organising DLT filter
694 * @param verbose if set to true verbose information is printed out.
695 * @return negative value if there was an error
697 int dlt_filter_free(DltFilter *filter,int verbose);
699 * Load filter list from file.
700 * @param filter pointer to structure of organising DLT filter
701 * @param filename filename to load filters from
702 * @param verbose if set to true verbose information is printed out.
703 * @return negative value if there was an error
705 int dlt_filter_load(DltFilter *filter,const char *filename,int verbose);
707 * Save filter list to file.
708 * @param filter pointer to structure of organising DLT filter
709 * @param filename filename to load filters from
710 * @param verbose if set to true verbose information is printed out.
711 * @return negative value if there was an error
713 int dlt_filter_save(DltFilter *filter,const char *filename,int verbose);
715 * Find index of filter in filter list
716 * @param filter pointer to structure of organising DLT filter
717 * @param apid application id to be found in filter list
718 * @param ctid context id to be found in filter list
719 * @param verbose if set to true verbose information is printed out.
720 * @return negative value if there was an error (or not found), else return index of filter
722 int dlt_filter_find(DltFilter *filter,const char *apid,const char *ctid, int verbose);
724 * Add new filter to filter list.
725 * @param filter pointer to structure of organising DLT filter
726 * @param apid application id to be added to filter list (must always be set).
727 * @param ctid context id to be added to filter list. empty equals don't care.
728 * @param verbose if set to true verbose information is printed out.
729 * @return negative value if there was an error
731 int dlt_filter_add(DltFilter *filter,const char *apid,const char *ctid,int verbose);
733 * Delete filter from filter list
734 * @param filter pointer to structure of organising DLT filter
735 * @param apid application id to be deleted from filter list
736 * @param ctid context id to be deleted from filter list
737 * @param verbose if set to true verbose information is printed out.
738 * @return negative value if there was an error
740 int dlt_filter_delete(DltFilter *filter,const char *apid,const char *ctid,int verbose);
743 * Initialise the structure used to access a DLT message.
744 * This function must be called before using further dlt_message functions.
745 * @param msg pointer to structure of organising access to DLT messages
746 * @param verbose if set to true verbose information is printed out.
747 * @return negative value if there was an error
749 int dlt_message_init(DltMessage *msg,int verbose);
751 * Free the used memory by the organising structure of file.
752 * @param msg pointer to structure of organising access to DLT messages
753 * @param verbose if set to true verbose information is printed out.
754 * @return negative value if there was an error
756 int dlt_message_free(DltMessage *msg,int verbose);
758 * Print Header into an ASCII string.
759 * This function calls dlt_message_header_flags() with flags=DLT_HEADER_SHOW_ALL
760 * @param msg pointer to structure of organising access to DLT messages
761 * @param text pointer to a ASCII string, in which the header is written
762 * @param textlength maximal size of text buffer
763 * @param verbose if set to true verbose information is printed out.
764 * @return negative value if there was an error
766 int dlt_message_header(DltMessage *msg,char *text,int textlength,int verbose);
768 * Print Header into an ASCII string, selective.
769 * @param msg pointer to structure of organising access to DLT messages
770 * @param text pointer to a ASCII string, in which the header is written
771 * @param textlength maximal size of text buffer
772 * @param flags select, bit-field to select, what should be printed (DLT_HEADER_SHOW_...)
773 * @param verbose if set to true verbose information is printed out.
774 * @return negative value if there was an error
776 int dlt_message_header_flags(DltMessage *msg,char *text,int textlength,int flags, int verbose);
778 * Print Payload into an ASCII string.
779 * @param msg pointer to structure of organising access to DLT messages
780 * @param text pointer to a ASCII string, in which the header is written
781 * @param textlength maximal size of text buffer
782 * @param type 1 = payload as hex, 2 = payload as ASCII.
783 * @param verbose if set to true verbose information is printed out.
784 * @return negative value if there was an error
786 int dlt_message_payload(DltMessage *msg,char *text,int textlength,int type,int verbose);
788 * Check if message is filtered or not. All filters are applied (logical OR).
789 * @param msg pointer to structure of organising access to DLT messages
790 * @param filter pointer to filter
791 * @param verbose if set to true verbose information is printed out.
792 * @return 1 = filter matches, 0 = filter does not match, negative value if there was an error
794 int dlt_message_filter_check(DltMessage *msg,DltFilter *filter,int verbose);
797 * Read message from memory buffer.
798 * Message in buffer has no storage header.
799 * @param msg pointer to structure of organising access to DLT messages
800 * @param buffer pointer to memory buffer
801 * @param length length of message in buffer
802 * @param resync if set to true resync to serial header is enforced
803 * @param verbose if set to true verbose information is printed out.
804 * @return negative value if there was an error
806 int dlt_message_read(DltMessage *msg,uint8_t *buffer,unsigned int length,int resync,int verbose);
809 * Get standard header extra parameters
810 * @param msg pointer to structure of organising access to DLT messages
811 * @param verbose if set to true verbose information is printed out.
812 * @return negative value if there was an error
814 int dlt_message_get_extraparameters(DltMessage *msg,int verbose);
817 * Set standard header extra parameters
818 * @param msg pointer to structure of organising access to DLT messages
819 * @param verbose if set to true verbose information is printed out.
820 * @return negative value if there was an error
822 int dlt_message_set_extraparameters(DltMessage *msg,int verbose);
825 * Initialise the structure used to access a DLT file.
826 * This function must be called before using further dlt_file functions.
827 * @param file pointer to structure of organising access to DLT file
828 * @param verbose if set to true verbose information is printed out.
829 * @return negative value if there was an error
831 int dlt_file_init(DltFile *file,int verbose);
833 * Set a list to filters.
834 * This function should be called before loading a DLT file, if filters should be used.
835 * A filter list is an array of filters. Several filters are combined logically by or operation.
836 * The filter list is not copied, so take care to keep list in memory.
837 * @param file pointer to structure of organising access to DLT file
838 * @param filter pointer to filter list array
839 * @param verbose if set to true verbose information is printed out.
840 * @return negative value if there was an error
842 int dlt_file_set_filter(DltFile *file,DltFilter *filter,int verbose);
844 * Initialising loading a DLT file.
845 * @param file pointer to structure of organising access to DLT file
846 * @param filename filename of DLT file
847 * @param verbose if set to true verbose information is printed out.
848 * @return negative value if there was an error
850 int dlt_file_open(DltFile *file,const char *filename,int verbose);
852 * Find next message in the DLT file and parse them.
853 * This function finds the next message in the DLT file.
854 * If a filter is set, the filter list is used.
855 * @param file pointer to structure of organising access to DLT file
856 * @param verbose if set to true verbose information is printed out.
857 * @return 0 = message does not match filter, 1 = message was read, negative value if there was an error
859 int dlt_file_read(DltFile *file,int verbose);
861 * Find next message in the DLT file in RAW format (without storage header) and parse them.
862 * This function finds the next message in the DLT file.
863 * If a filter is set, the filter list is used.
864 * @param file pointer to structure of organising access to DLT file
865 * @param resync Resync to serial header when set to true
866 * @param verbose if set to true verbose information is printed out.
867 * @return 0 = message does not match filter, 1 = message was read, negative value if there was an error
869 int dlt_file_read_raw(DltFile *file,int resync,int verbose);
871 * Closing loading a DLT file.
872 * @param file pointer to structure of organising access to DLT file
873 * @param verbose if set to true verbose information is printed out.
874 * @return negative value if there was an error
876 int dlt_file_close(DltFile *file,int verbose);
878 * Load standard header of a message from file
879 * @param file pointer to structure of organising access to DLT file
880 * @param verbose if set to true verbose information is printed out.
881 * @return negative value if there was an error
883 int dlt_file_read_header(DltFile *file,int verbose);
885 * Load standard header of a message from file in RAW format (without storage header)
886 * @param file pointer to structure of organising access to DLT file
887 * @param resync Resync to serial header when set to true
888 * @param verbose if set to true verbose information is printed out.
889 * @return negative value if there was an error
891 int dlt_file_read_header_raw(DltFile *file,int resync,int verbose);
893 * Load, if available in message, extra standard header fields and
894 * extended header of a message from file
895 * (dlt_file_read_header() must have been called before this call!)
896 * @param file pointer to structure of organising access to DLT file
897 * @param verbose if set to true verbose information is printed out.
898 * @return negative value if there was an error
900 int dlt_file_read_header_extended(DltFile *file, int verbose);
902 * Load payload of a message from file
903 * (dlt_file_read_header() must have been called before this call!)
904 * @param file pointer to structure of organising access to DLT file
905 * @param verbose if set to true verbose information is printed out.
906 * @return negative value if there was an error
908 int dlt_file_read_data(DltFile *file, int verbose);
910 * Load headers and payload of a message selected by the index.
911 * If filters are set, index is based on the filtered list.
912 * @param file pointer to structure of organising access to DLT file
913 * @param index position of message in the files beginning from zero
914 * @param verbose if set to true verbose information is printed out.
915 * @return number of messages loaded, negative value if there was an error
917 int dlt_file_message(DltFile *file,int index,int verbose);
919 * Free the used memory by the organising structure of file.
920 * @param file pointer to structure of organising access to DLT file
921 * @param verbose if set to true verbose information is printed out.
922 * @return negative value if there was an error
924 int dlt_file_free(DltFile *file,int verbose);
927 * Set internal logging filename if mode 2
928 * @param filename the filename
930 void dlt_log_set_filename(const char *filename);
932 * Set internal logging level
933 * @param level the level
935 void dlt_log_set_level(int level);
937 * Initialize (external) logging facility
938 * @param mode positive, 0 = log to stdout, 1 = log to syslog, 2 = log to file
940 void dlt_log_init(int mode);
942 * Log ASCII string with null-termination to (external) logging facility
943 * @param prio priority (see syslog() call)
944 * @param s Pointer to ASCII string with null-termination
945 * @return negative value if there was an error
947 int dlt_log(int prio, char *s);
949 * De-Initialize (external) logging facility
951 void dlt_log_free(void);
954 * Initialising a dlt receiver structure
955 * @param receiver pointer to dlt receiver structure
956 * @param _fd handle to file/socket/fifo, fram which the data should be received
957 * @param _buffersize size of data buffer for storing the received data
958 * @return negative value if there was an error
960 int dlt_receiver_init(DltReceiver *receiver,int _fd, int _buffersize);
962 * De-Initialize a dlt receiver structure
963 * @param receiver pointer to dlt receiver structure
964 * @return negative value if there was an error
966 int dlt_receiver_free(DltReceiver *receiver);
968 * Receive data from socket using the dlt receiver structure
969 * @param receiver pointer to dlt receiver structure
970 * @return negative value if there was an error
972 int dlt_receiver_receive_socket(DltReceiver *receiver);
974 * Receive data from file/fifo using the dlt receiver structure
975 * @param receiver pointer to dlt receiver structure
976 * @return negative value if there was an error
978 int dlt_receiver_receive_fd(DltReceiver *receiver);
980 * Remove a specific size of bytes from the received data
981 * @param receiver pointer to dlt receiver structure
982 * @param size amount of bytes to be removed
983 * @return negative value if there was an error
985 int dlt_receiver_remove(DltReceiver *receiver,int size);
987 * Move data from last receive call to front of receive buffer
988 * @param receiver pointer to dlt receiver structure
989 * @return negative value if there was an error
991 int dlt_receiver_move_to_begin(DltReceiver *receiver);
994 * Fill out storage header of a dlt message
995 * @param storageheader pointer to storage header of a dlt message
996 * @param ecu name of ecu to be set in storage header
997 * @return negative value if there was an error
999 int dlt_set_storageheader(DltStorageHeader *storageheader, const char *ecu);
1001 * Check if a storage header contains its marker
1002 * @param storageheader pointer to storage header of a dlt message
1003 * @return 0 no, 1 yes, negative value if there was an error
1005 int dlt_check_storageheader(DltStorageHeader *storageheader);
1009 * Initialise static ringbuffer with a size of size.
1010 * Initialise as server. Init counters.
1011 * Memory is already allocated.
1012 * @param buf Pointer to ringbuffer structure
1013 * @param ptr Ptr to ringbuffer memory
1014 * @param size Maximum size of buffer in bytes
1015 * @return negative value if there was an error
1017 int dlt_buffer_init_static_server(DltBuffer *buf, const unsigned char *ptr, uint32_t size);
1020 * Initialize static ringbuffer with a size of size.
1021 * Initialise as a client. Do not change counters.
1022 * Memory is already allocated.
1023 * @param buf Pointer to ringbuffer structure
1024 * @param ptr Ptr to ringbuffer memory
1025 * @param size Maximum size of buffer in bytes
1026 * @return negative value if there was an error
1028 int dlt_buffer_init_static_client(DltBuffer *buf, const unsigned char *ptr, uint32_t size);
1031 * Initialize dynamic ringbuffer with a size of size.
1032 * Initialise as a client. Do not change counters.
1033 * Memory will be allocated starting with min_size.
1034 * If more memory is needed size is increased wit step_size.
1035 * The maximum size is max_size.
1036 * @param buf Pointer to ringbuffer structure
1037 * @param min_size Minimum size of buffer in bytes
1038 * @param max_size Maximum size of buffer in bytes
1039 * @param step_size size of which ringbuffer is increased
1040 * @return negative value if there was an error
1042 int dlt_buffer_init_dynamic(DltBuffer *buf, uint32_t min_size, uint32_t max_size,uint32_t step_size);
1045 * Deinitilaise usage of static ringbuffer
1046 * @param buf Pointer to ringbuffer structure
1047 * @return negative value if there was an error
1049 int dlt_buffer_free_static(DltBuffer *buf);
1052 * Release and free memory used by dynamic ringbuffer
1053 * @param buf Pointer to ringbuffer structure
1054 * @return negative value if there was an error
1056 int dlt_buffer_free_dynamic(DltBuffer *buf);
1059 * Write one entry to ringbuffer
1060 * @param buf Pointer to ringbuffer structure
1061 * @param data Pointer to data to be written to ringbuffer
1062 * @param size Size of data in bytes to be written to ringbuffer
1063 * @return negative value if there was an error
1065 int dlt_buffer_push(DltBuffer *buf,const unsigned char *data,unsigned int size);
1068 * Write up to three entries to ringbuffer.
1069 * Entries are joined to one block.
1070 * @param dlt Pointer to ringbuffer structure
1071 * @param data1 Pointer to data to be written to ringbuffer
1072 * @param size1 Size of data in bytes to be written to ringbuffer
1073 * @param data2 Pointer to data to be written to ringbuffer
1074 * @param size2 Size of data in bytes to be written to ringbuffer
1075 * @param data3 Pointer to data to be written to ringbuffer
1076 * @param size3 Size of data in bytes to be written to ringbuffer
1077 * @return negative value if there was an error
1079 int dlt_buffer_push3(DltBuffer *buf,const unsigned char *data1,unsigned int size1,const unsigned char *data2,unsigned int size2,const unsigned char *data3,unsigned int size3);
1082 * Read one entry from ringbuffer.
1083 * Remove it from ringbuffer.
1084 * @param buf Pointer to ringbuffer structure
1085 * @param data Pointer to data read from ringbuffer
1086 * @param max_size Max size of read data in bytes from ringbuffer
1087 * @return size of read data, zero if no data available, negative value if there was an error
1089 int dlt_buffer_pull(DltBuffer *buf,unsigned char *data, int max_size);
1092 * Read one entry from ringbuffer.
1093 * Do not remove it from ringbuffer.
1094 * @param buf Pointer to ringbuffer structure
1095 * @param data Pointer to data read from ringbuffer
1096 * @param max_size Max size of read data in bytes from ringbuffer
1097 * @return size of read data, zero if no data available, negative value if there was an error
1099 int dlt_buffer_copy(DltBuffer *buf,unsigned char *data, int max_size);
1102 * Remove entry from ringbuffer.
1103 * @param buf Pointer to ringbuffer structure
1104 * @return size of read data, zero if no data available, negative value if there was an error
1106 int dlt_buffer_remove(DltBuffer *buf);
1109 * Print information about buffer and log to internal DLT log.
1110 * @param buf Pointer to ringbuffer structure
1112 void dlt_buffer_info(DltBuffer *buf);
1115 * Print status of buffer and log to internal DLT log.
1116 * @param buf Pointer to ringbuffer structure
1118 void dlt_buffer_status(DltBuffer *buf);
1121 * Get total size in bytes of ringbuffer.
1122 * If buffer is dynamic, max size is returned.
1123 * @param buf Pointer to ringbuffer structure
1124 * @return total size of buffer
1126 int dlt_buffer_get_total_size(DltBuffer *buf);
1129 * Get used size in bytes of ringbuffer.
1130 * @param buf Pointer to ringbuffer structure
1131 * @return used size of buffer
1133 int dlt_buffer_get_used_size(DltBuffer *buf);
1136 * Get number of entries in ringbuffer.
1137 * @param buf Pointer to ringbuffer structure
1138 * @return number of entries
1140 int dlt_buffer_get_message_count(DltBuffer *buf);
1142 #if !defined (__WIN32__)
1145 * Helper function: Setup serial connection
1146 * @param fd File descriptor of serial tty device
1147 * @param speed Serial line speed, as defined in termios.h
1148 * @return negative value if there was an error
1150 int dlt_setup_serial(int fd, speed_t speed);
1153 * Helper function: Convert serial line baudrate (as number) to line speed (as defined in termios.h)
1154 * @param baudrate Serial line baudrate (as number)
1155 * @return Serial line speed, as defined in termios.h
1157 speed_t dlt_convert_serial_speed(int baudrate);
1160 * Print dlt version and dlt svn version to buffer
1161 * @param buf Pointer to buffer
1162 * @param size size of buffer
1164 void dlt_get_version(char *buf, size_t size);
1167 * Print dlt major version to buffer
1168 * @param buf Pointer to buffer
1169 * @param size size of buffer
1171 void dlt_get_major_version(char *buf, size_t size);
1174 * Print dlt minor version to buffer
1175 * @param buf Pointer to buffer
1176 * @param size size of buffer
1178 void dlt_get_minor_version(char *buf, size_t size);
1182 /* Function prototypes which should be used only internally */
1186 * Common part of initialisation
1187 * @return negative value if there was an error
1189 int dlt_init_common(void);
1192 * Return the uptime of the system in 0.1 ms resolution
1193 * @return 0 if there was an error
1195 uint32_t dlt_uptime(void);
1198 * Print header of a DLT message
1199 * @param message pointer to structure of organising access to DLT messages
1200 * @param text pointer to a ASCII string, in which the header is written
1201 * @param size maximal size of text buffer
1202 * @param verbose if set to true verbose information is printed out.
1203 * @return negative value if there was an error
1205 int dlt_message_print_header(DltMessage *message, char *text, uint32_t size, int verbose);
1208 * Print payload of a DLT message as Hex-Output
1209 * @param message pointer to structure of organising access to DLT messages
1210 * @param text pointer to a ASCII string, in which the output is written
1211 * @param size maximal size of text buffer
1212 * @param verbose if set to true verbose information is printed out.
1213 * @return negative value if there was an error
1215 int dlt_message_print_hex(DltMessage *message, char *text, uint32_t size, int verbose);
1218 * Print payload of a DLT message as ASCII-Output
1219 * @param message pointer to structure of organising access to DLT messages
1220 * @param text pointer to a ASCII string, in which the output is written
1221 * @param size maximal size of text buffer
1222 * @param verbose if set to true verbose information is printed out.
1223 * @return negative value if there was an error
1225 int dlt_message_print_ascii(DltMessage *message, char *text, uint32_t size, int verbose);
1228 * Print payload of a DLT message as Mixed-Ouput (Hex and ASCII), for plain text output
1229 * @param message pointer to structure of organising access to DLT messages
1230 * @param text pointer to a ASCII string, in which the output is written
1231 * @param size maximal size of text buffer
1232 * @param verbose if set to true verbose information is printed out.
1233 * @return negative value if there was an error
1235 int dlt_message_print_mixed_plain(DltMessage *message, char *text, uint32_t size, int verbose);
1238 * Print payload of a DLT message as Mixed-Ouput (Hex and ASCII), for HTML text output
1239 * @param message pointer to structure of organising access to DLT messages
1240 * @param text pointer to a ASCII string, in which the output is written
1241 * @param size maximal size of text buffer
1242 * @param verbose if set to true verbose information is printed out.
1243 * @return negative value if there was an error
1245 int dlt_message_print_mixed_html(DltMessage *message, char *text, uint32_t size, int verbose);
1248 * Decode and print a argument of a DLT message
1249 * @param msg pointer to structure of organising access to DLT messages
1250 * @param type_info Type of argument
1251 * @param ptr pointer to pointer to data (pointer to data is changed within this function)
1252 * @param datalength pointer to datalength (datalength is changed within this function)
1253 * @param text pointer to a ASCII string, in which the output is written
1254 * @param textlength maximal size of text buffer
1255 * @param byteLength If argument is a string, and this value is 0 or greater, this value will be taken as string length
1256 * @param verbose if set to true verbose information is printed out.
1257 * @return negative value if there was an error
1259 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);
1262 * Check environment variables.
1264 void dlt_check_envvar();
1274 #endif /* DLT_COMMON_H */