dlt_user.h

Go to the documentation of this file.

/*
 * @licence app begin@
 * SPDX license identifier: MPL-2.0
 *
 * Copyright (C) 2011-2015, BMW AG
 *
 * This file is part of GENIVI Project DLT - Diagnostic Log and Trace.
 *
 * This Source Code Form is subject to the terms of the
 * Mozilla Public License (MPL), v. 2.0.
 * If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * For further information see http://www.genivi.org/.
 * @licence end@
 */

/*******************************************************************************
**                                                                            **
**  SRC-MODULE: dlt_user.h                                                    **
**                                                                            **
**  TARGET    : linux                                                         **
**                                                                            **
**  PROJECT   : DLT                                                           **
**                                                                            **
**  AUTHOR    : Alexander Wenzel Alexander.AW.Wenzel@bmw.de                   **
**              Markus Klein                                                  **
**                                                                            **
**  PURPOSE   :                                                               **
**                                                                            **
**  REMARKS   :                                                               **
**                                                                            **
**  PLATFORM DEPENDANT [yes/no]: yes                                          **
**                                                                            **
**  TO BE CHANGED BY USER [yes/no]: no                                        **
**                                                                            **
*******************************************************************************/

/*******************************************************************************
**                      Author Identity                                       **
********************************************************************************
**                                                                            **
** Initials     Name                       Company                            **
** --------     -------------------------  ---------------------------------- **
**  aw          Alexander Wenzel           BMW                                **
**  mk          Markus Klein               Fraunhofer ESK                     **
*******************************************************************************/

/*******************************************************************************
**                      Revision Control History                              **
*******************************************************************************/

/*
 * $LastChangedRevision: 1670 $
 * $LastChangedDate: 2011-04-08 15:12:06 +0200 (Fr, 08. Apr 2011) $
 * $LastChangedBy$
 Initials    Date         Comment
 aw          13.01.2010   initial
 */

#ifndef DLT_USER_H
#define DLT_USER_H

#include <mqueue.h>

#if !defined (__WIN32__)
#include <semaphore.h>
#endif

#include "dlt_types.h"
#include "dlt_user_macros.h"
#include "dlt_shm.h"

#ifdef __cplusplus
extern "C" {
#endif

#define DLT_USER_BUF_MAX_SIZE 1390               
#define DLT_USER_RESENDBUF_MAX_SIZE (DLT_USER_BUF_MAX_SIZE + 100)       
/* Use a semaphore or mutex from your OS to prevent concurrent access to the DLT buffer. */
#define DLT_SEM_LOCK() { sem_wait(&dlt_mutex); }
#define DLT_SEM_FREE() { sem_post(&dlt_mutex); }

typedef struct
{
    char contextID[DLT_ID_SIZE];                  
    int32_t log_level_pos;                        
    int8_t *log_level_ptr;                        
    int8_t *trace_status_ptr;                     
    uint8_t mcnt;                                 
} DltContext;

typedef struct
{
    DltContext *handle;                           
    unsigned char buffer[DLT_USER_BUF_MAX_SIZE];  
    int32_t size;                                 
    int32_t log_level;                            
    int32_t trace_status;                         
    int32_t args_num;                             
    char* context_description;                    
} DltContextData;

typedef struct
{
    uint32_t service_id;
    int (*injection_callback)(uint32_t service_id, void *data, uint32_t length);
} DltUserInjectionCallback;

typedef struct
{
    char contextID[DLT_ID_SIZE];      
    int8_t log_level;                 
    int8_t trace_status;              
    void (*log_level_changed_callback) (char context_id[DLT_ID_SIZE],uint8_t log_level,uint8_t trace_status);
} DltUserLogLevelChangedCallback;

typedef struct
{
    char contextID[DLT_ID_SIZE];      
    int8_t log_level;                 
    int8_t *log_level_ptr;             
    int8_t trace_status;              
    int8_t *trace_status_ptr;             
    char *context_description;        
    DltUserInjectionCallback *injection_table; 
    uint32_t nrcallbacks;

    /* Log Level changed callback */
    void (*log_level_changed_callback) (char context_id[DLT_ID_SIZE],uint8_t log_level,uint8_t trace_status);

} dlt_ll_ts_type;

typedef struct
{
    char appId[DLT_ID_SIZE];
    char ctxId[DLT_ID_SIZE];
    int8_t ll;
} dlt_env_ll_item;


typedef struct
{
    dlt_env_ll_item * item;
    size_t array_size;
    size_t num_elem;
} dlt_env_ll_set;


typedef struct
{
    char ecuID[DLT_ID_SIZE];                   
    char appID[DLT_ID_SIZE];                   
    int dlt_log_handle;                        
    int dlt_user_handle;                       
    mqd_t dlt_segmented_queue_read_handle;     
    mqd_t dlt_segmented_queue_write_handle;    
    pthread_t dlt_segmented_nwt_handle;        
    int8_t dlt_is_file;                        
    dlt_ll_ts_type *dlt_ll_ts;                 
    uint32_t dlt_ll_ts_max_num_entries;        
    uint32_t dlt_ll_ts_num_entries;            
    int8_t overflow;                           
    uint32_t overflow_counter;                 
    char *application_description;             
    DltReceiver receiver;                      
    int8_t verbose_mode;                       
    int8_t use_extende_header_for_non_verbose; 
    int8_t with_session_id;                    
    int8_t with_timestamp;                     
    int8_t with_ecu_id;                        
    int8_t enable_local_print;                 
    int8_t local_print_mode;                   
    int8_t log_state;                          
    DltBuffer startup_buffer; 
    /* Buffer used for resending, locked by DLT semaphore */
    uint8_t resend_buffer[DLT_USER_RESENDBUF_MAX_SIZE];

    uint32_t timeout_at_exit_handler; 
    dlt_env_ll_set initial_ll_set;

#ifdef DLT_SHM_ENABLE
    DltShm dlt_shm;
#endif
#ifdef DLT_TEST_ENABLE
    int corrupt_user_header;
    int corrupt_message_size;
    int16_t corrupt_message_size_size;
#endif
} DltUser;

/**************************************************************************************************
* The following API functions define a low level function interface for DLT
**************************************************************************************************/

DltReturnValue dlt_user_log_write_start(DltContext *handle, DltContextData *log, DltLogLevelType loglevel);

DltReturnValue dlt_user_log_write_start_id(DltContext *handle, DltContextData *log, DltLogLevelType loglevel, uint32_t messageid);

DltReturnValue dlt_user_log_write_finish(DltContextData *log);

DltReturnValue dlt_user_log_write_bool(DltContextData *log, uint8_t data);

DltReturnValue dlt_user_log_write_float32(DltContextData *log, float32_t data);

DltReturnValue dlt_user_log_write_float64(DltContextData *log, double data);

DltReturnValue dlt_user_log_write_uint(DltContextData *log, unsigned int data);
DltReturnValue dlt_user_log_write_uint8(DltContextData *log, uint8_t data);
DltReturnValue dlt_user_log_write_uint16(DltContextData *log, uint16_t data);
DltReturnValue dlt_user_log_write_uint32(DltContextData *log, uint32_t data);
DltReturnValue dlt_user_log_write_uint64(DltContextData *log, uint64_t data);

DltReturnValue dlt_user_log_write_uint8_formatted(DltContextData *log, uint8_t data, DltFormatType type);
DltReturnValue dlt_user_log_write_uint16_formatted(DltContextData *log, uint16_t data, DltFormatType type);
DltReturnValue dlt_user_log_write_uint32_formatted(DltContextData *log, uint32_t data, DltFormatType type);
DltReturnValue dlt_user_log_write_uint64_formatted(DltContextData *log, uint64_t data, DltFormatType type);

DltReturnValue dlt_user_log_write_ptr(DltContextData *log, void *data);

DltReturnValue dlt_user_log_write_int(DltContextData *log, int data);
DltReturnValue dlt_user_log_write_int8(DltContextData *log, int8_t data);
DltReturnValue dlt_user_log_write_int16(DltContextData *log, int16_t data);
DltReturnValue dlt_user_log_write_int32(DltContextData *log, int32_t data);
DltReturnValue dlt_user_log_write_int64(DltContextData *log, int64_t data);
DltReturnValue dlt_user_log_write_string( DltContextData *log, const char *text);

DltReturnValue dlt_user_log_write_constant_string( DltContextData *log, const char *text);

DltReturnValue dlt_user_log_write_utf8_string(DltContextData *log, const char *text);

DltReturnValue dlt_user_log_write_raw(DltContextData *log,void *data,uint16_t length);

DltReturnValue dlt_user_log_write_raw_formatted(DltContextData *log,void *data,uint16_t length,DltFormatType type);

DltReturnValue dlt_user_trace_network(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload);

DltReturnValue dlt_user_trace_network_truncated(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload, int allow_truncate);

DltReturnValue dlt_user_trace_network_segmented(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload);

/**************************************************************************************************
 * The following API functions define a high level function interface for DLT
 **************************************************************************************************/

DltReturnValue dlt_init();

DltReturnValue dlt_init_file(const char *name);

DltReturnValue dlt_free();

DltReturnValue dlt_check_library_version(const char * user_major_version, const char * user_minor_version);

DltReturnValue dlt_register_app(const char *appid, const char * description);

DltReturnValue dlt_unregister_app(void);

DltReturnValue dlt_register_context(DltContext *handle, const char *contextid, const char * description);

DltReturnValue dlt_register_context_ll_ts(DltContext *handle, const char *contextid, const char * description, int loglevel, int tracestatus);

DltReturnValue dlt_unregister_context(DltContext *handle);


int dlt_set_resend_timeout_atexit(uint32_t timeout_in_milliseconds);

DltReturnValue dlt_set_log_mode(DltUserLogMode mode);

int dlt_get_log_state();

DltReturnValue dlt_register_injection_callback(DltContext *handle, uint32_t service_id,
        int (*dlt_injection_callback)(uint32_t service_id, void *data, uint32_t length));

DltReturnValue dlt_register_log_level_changed_callback(DltContext *handle,
        void (*dlt_log_level_changed_callback)(char context_id[DLT_ID_SIZE],uint8_t log_level, uint8_t trace_status));

DltReturnValue dlt_verbose_mode(void);

DltReturnValue dlt_user_check_library_version(const char *user_major_version,const char *user_minor_version);

DltReturnValue dlt_nonverbose_mode(void);

DltReturnValue dlt_use_extended_header_for_non_verbose(int8_t use_extende_header_for_non_verbose);

DltReturnValue dlt_with_session_id(int8_t with_session_id);

DltReturnValue dlt_with_timestamp(int8_t with_timestamp);

DltReturnValue dlt_with_ecu_id(int8_t with_ecu_id);

DltReturnValue dlt_set_application_ll_ts_limit(DltLogLevelType loglevel, DltTraceStatusType tracestatus);


int dlt_env_adjust_ll_from_env(dlt_env_ll_set const * const ll_set, char const * const apid, char const * const ctid, int const ll);

int dlt_env_extract_ll_set(char ** const env, dlt_env_ll_set * const ll_set);

void dlt_env_free_ll_set(dlt_env_ll_set * const ll_set);

DltReturnValue dlt_enable_local_print(void);

DltReturnValue dlt_disable_local_print(void);

DltReturnValue dlt_log_string(DltContext *handle,DltLogLevelType loglevel, const char *text);

DltReturnValue dlt_log_string_int(DltContext *handle,DltLogLevelType loglevel, const char *text, int data);

DltReturnValue dlt_log_string_uint(DltContext *handle,DltLogLevelType loglevel, const char *text, unsigned int data);

DltReturnValue dlt_log_int(DltContext *handle,DltLogLevelType loglevel, int data);

DltReturnValue dlt_log_uint(DltContext *handle,DltLogLevelType loglevel, unsigned int data);

DltReturnValue dlt_log_raw(DltContext *handle,DltLogLevelType loglevel, void *data,uint16_t length);

DltReturnValue dlt_log_marker();

DltReturnValue dlt_forward_msg(void *msgdata,size_t size);

DltReturnValue dlt_user_check_buffer(int *total_size, int *used_size);

int dlt_user_atexit_blow_out_user_buffer(void);

DltReturnValue dlt_user_log_resend_buffer(void);

static inline DltReturnValue dlt_user_is_logLevel_enabled(DltContext *handle,DltLogLevelType loglevel)
{
    if (handle == NULL || handle->log_level_ptr == NULL)
    {
        return DLT_RETURN_WRONG_PARAMETER;
    }

    if (loglevel <= (DltLogLevelType)(*(handle->log_level_ptr)) && loglevel != DLT_LOG_OFF)
    {
        return DLT_RETURN_TRUE;
    }

    return DLT_RETURN_LOGGING_DISABLED;
}

#ifdef DLT_TEST_ENABLE
    void dlt_user_test_corrupt_user_header(int enable);
    void dlt_user_test_corrupt_message_size(int enable,int16_t size);
#endif /* DLT_TEST_ENABLE */

#ifdef __cplusplus
}
#endif

#endif /* DLT_USER_H */