diff options
Diffstat (limited to 'doc/dlt_extended_network_trace.txt')
| -rw-r--r-- | doc/dlt_extended_network_trace.txt | 83 |
1 files changed, 83 insertions, 0 deletions
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 <Lassi.LM.Marttala@partner.bmw.de> +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 +|================================================================== |