From e079bc2bafec3ea8483e44f07387735b0ae00f0f Mon Sep 17 00:00:00 2001 From: Lassi Marttala Date: Fri, 12 Oct 2012 13:38:15 +0200 Subject: Converted extended network trace document to asciidoc. Signed-off-by: Alexander Wenzel --- doc/CMakeLists.txt | 9 +-- doc/dlt_extended_network_trace.txt | 83 ++++++++++++++++++++++ doc/extended_network_trace_mainpage.h | 129 ---------------------------------- 3 files changed, 85 insertions(+), 136 deletions(-) create mode 100644 doc/dlt_extended_network_trace.txt delete mode 100755 doc/extended_network_trace_mainpage.h (limited to 'doc') diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 49939ec..b1b068d 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -17,18 +17,12 @@ if(WITH_DOC) find_package(Doxygen) configure_file(${CMAKE_SOURCE_DIR}/doc/doxygen.cfg.cmake ${CMAKE_BINARY_DIR}/doc/doxygen.cfg @ONLY) - configure_file(${CMAKE_SOURCE_DIR}/doc/extended_network_trace_doxygen.cfg.cmake ${CMAKE_BINARY_DIR}/doc/extended_network_trace_doxygen.cfg @ONLY) add_custom_target (doc ALL COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/doc/doxygen.cfg WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc ) - add_custom_target (doc-extended-network-trace ALL - COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/doc/extended_network_trace_doxygen.cfg - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc - ) - add_custom_target (doc-manuals ALL COMMAND mkdir -p ${CMAKE_BINARY_DIR}/doc/manuals COMMAND mkdir -p ${CMAKE_BINARY_DIR}/doc/manuals/images @@ -46,7 +40,8 @@ if(WITH_DOC) COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt-convert.1.html ${CMAKE_SOURCE_DIR}/doc/dlt-convert.1.txt COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt.conf.5.html ${CMAKE_SOURCE_DIR}/doc/dlt.conf.5.txt COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt-system.conf.5.html ${CMAKE_SOURCE_DIR}/doc/dlt-system.conf.5.txt - COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_book.html ${CMAKE_SOURCE_DIR}/doc/dlt_book.txt + COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_book.html ${CMAKE_SOURCE_DIR}/doc/dlt_book.txt + COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_extended_network_trace.html ${CMAKE_SOURCE_DIR}/doc/dlt_extended_network_trace.txt WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc ) diff --git a/doc/dlt_extended_network_trace.txt b/doc/dlt_extended_network_trace.txt new file mode 100644 index 0000000..9b07dcd --- /dev/null +++ b/doc/dlt_extended_network_trace.txt @@ -0,0 +1,83 @@ +Extended Network Trace +===================== +Lassi Marttala +0.0.1, 2012/10/11: Initial version + +image::images/genivi_chrome_1_transparent.png[width=128] + +== Introduction + +The extended network trace allows the user to send or truncate network trace messages +that are larger than the normal maximum size of a DLT message. + +== Protocol + +When truncation of messages is allowed, the truncated messages will be wrapped into a special message which indicates +that a network trace message was truncated and what was the original size of the message. + +Segmented messages are sent in multiple packages. The package stream is prepended with a a start message indicating +which contain a unique handle for this stream, size of data to follow, count of segments to follow and segment size. +Each segment contains the stream handle, segment sequence number, the data and data length. +Finally after sending all the data segments, one more packet is sent to indicate the end of the stream. + +== Truncated package + +Truncated message can be sent using the following function: +[source,c] +---- +int 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) +---- + +This will send a packet in the following format: + +|================================================================== +| NWTR | Package identifier. STRING +| header | nw_trace header and it's length. RAW +| size | Original size of the message. UINT +| payload | The truncated nw_trace payload. RAW +|================================================================== + +== Segmented messages +User can send a segmented network trace message asynchronously using: +[source,c] +---- +void dlt_user_trace_network_segmented(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload) +---- +This will start a background thread and return immediately. + +User can also send all the required packages one by one using: + +[source,c] +---- +int dlt_user_trace_network_segmented_start(unsigned int *id, DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len) +int dlt_user_trace_network_segmented_segment(int id, DltContext *handle, DltNetworkTraceType nw_trace_type, int sequence, uint16_t payload_len, void *payload) +int dlt_user_trace_network_segmented_end(int id, DltContext *handle, DltNetworkTraceType nw_trace_type) +---- +It is not recommended to use these functions unless you really have to. + +== Segmented start packet +The first packet in the stream is the header: +|================================================================== +| NWST | Package identifier. STRING +| streamhandle | Unique identifier for all packages in the stream. UINT +| header | nw_trace header and it's length. RAW +| payloadsize | Size of the complete payload in this stream. UINT +| segmentcount | Number of segments to follow. +| segmentlen | Size of one segment +|================================================================== + +== Data segment +After the header, follows a stream of data segments. +|================================================================== +| NWCH | Package identifier. STRING +| streamhandle | Unique identifier for all packages in the stream. UINT +| sequence | Sequence number of this segment. UINT +| data | One segment of the original nw_trace. RAW +|================================================================== + +== End packet +After all the segments have been sent, an End identifier is sent. +|================================================================== +| NWEN | Package identifier. STRING +| streamhandle | Unique identifier for all packages in the stream. UINT +|================================================================== diff --git a/doc/extended_network_trace_mainpage.h b/doc/extended_network_trace_mainpage.h deleted file mode 100755 index f525d12..0000000 --- a/doc/extended_network_trace_mainpage.h +++ /dev/null @@ -1,129 +0,0 @@ -/** - * @licence app begin@ - * Copyright (C) 2012 BMW AG - * - * This file is part of GENIVI Project Dlt - Diagnostic Log and Trace console apps. - * - * Contributions are licensed to the GENIVI Alliance under one or more - * Contribution License Agreements. - * - * \copyright - * This Source Code Form is subject to the terms of the - * Mozilla Public License, 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/. - * - * - * \author Lassi Marttala BMW 2012 - * - * For further information see http://www.genivi.org/. - * @licence end@ - */ - -/** \mainpage - -\image html genivilogo.png - -\par More information -can be found at https://collab.genivi.org/wiki/display/genivi/GENIVI+Home \n - -\par About DLT -The DLT is a Deamon that enables diagnostic log and trace in a GENIVI headunit and is based on AUTOSAR 4.0. - -DLT Extended Network Trace Main Page - -\section Introduction Introduction -The extended network trace functionality allows now for large network messages to be sent or truncated. - -\section Protocol Protocol -When truncation of messages is allowed, the truncated messages will be wrapped into a special message which indicates -that a network trace message was truncated and what was the original size of the message. - -Segmented messages are sent in multiple packages. The package stream is prepended with a a start message indicating -which contain a unique handle for this stream, size of data to follow, count of segments to follow and segment size. -Each segment contains the stream handle, segment sequence number, the data and data length. -Finally after sending all the data segments, one more packet is sent to indicate the end of the stream. - -\subsection Truncated Truncated package -Truncated message can be sent using the following function: -\code -int 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) -\endcode -This will send a packet in the following format: -\code -,----------------------------------------------------. -| NWTR | Package identifier. STRING -|----------------------------------------------------| -| header | nw_trace header and it's length. RAW -|----------------------------------------------------| -| size | Original size of the message. UINT -|----------------------------------------------------| -| payload | The truncated nw_trace payload. RAW -`----------------------------------------------------' -\endcode - -\subsection Segmented Segmented messages -User can send a segmented network trace message asynchronously using: -\code -void dlt_user_trace_network_segmented(DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len, void *payload) -\endcode -This will start a background thread and return immediately. User can also send all the required packages one by one using: -\code -int dlt_user_trace_network_segmented_start(unsigned int *id, DltContext *handle, DltNetworkTraceType nw_trace_type, uint16_t header_len, void *header, uint16_t payload_len) -int dlt_user_trace_network_segmented_segment(int id, DltContext *handle, DltNetworkTraceType nw_trace_type, int sequence, uint16_t payload_len, void *payload) -int dlt_user_trace_network_segmented_end(int id, DltContext *handle, DltNetworkTraceType nw_trace_type) -\endcode -It is not recommended to use these functions unless you really have to. - -\subsection Start Segmented start packet -The first packet in the stream is the header: -\code -,----------------------------------------------------. -| NWST | Package identifier. STRING -|----------------------------------------------------| -| streamhandle | Unique identifier for all packages in the stream. UINT -|----------------------------------------------------| -| header | nw_trace header and it's length. RAW -|----------------------------------------------------| -| payloadsize | Size of the complete payload in this stream. UINT -|----------------------------------------------------| -| segmentcount | Number of segments to follow. -|----------------------------------------------------| -| segmentlen | Size of one segment -`----------------------------------------------------' -\endcode - -\subsection Data Data segment -After the header, follows a stream of data segments. -\code -,----------------------------------------------------. -| NWCH | Package identifier. STRING -|----------------------------------------------------| -| streamhandle | Unique identifier for all packages in the stream. UINT -|----------------------------------------------------| -| sequence | Sequence number of this segment. UINT -|----------------------------------------------------| -| data | One segment of the original nw_trace. RAW -`----------------------------------------------------' -\endcode - -\subsection End End packet -After all the segments have been sent, an End identifier is sent. -\code -,----------------------------------------------------. -| NWEN | Package identifier. STRING -|----------------------------------------------------| -| streamhandle | Unique identifier for all packages in the stream. UINT -`----------------------------------------------------' -\endcode - - -\section Requirements Requirements - \code - automotive-dlt - \endcode -
- -\section Licence Licence -Copyright 2012 - BMW AG, Lassi Marttala - -* */ -- cgit v1.2.1