diff --git a/doc/trace_notes.md b/doc/trace_notes.md index a126a238f..1cdf8dead 100644 --- a/doc/trace_notes.md +++ b/doc/trace_notes.md @@ -1,10 +1,18 @@ -# Trace command notes +# Notes about the tracelog. + +## Table of Contents + * [Command](#trace-command) + * [File format](#tracelog-format) + * [Wireshark dissector interoperability](#trace-and-wireshark) + + +## Trace command The `trace` command lists the data exchange by the proxmark3 and a tag or a reader in human readable form. With `trace list` a table is shown which gives timing information, the src of the data bytes, the transmitted/received bytes itself, a check if the CRC was correct and some decoding of the command. -## Timing +### Timing The Start and the End coloumn lists timestamps when the transmission of the shown data started (time of first bit) and when it ended (end of last modulation). @@ -20,26 +28,55 @@ The unit for this time information depends on the protocol in use: By specifing the option ```f``` (e.g. ```trace list 14a f```) the frame delay times are shown. (So you don't have to do the math by your own). -## Sources +### Sources If the data is marked as a response the source is shown as Tag. Otherwise it is marked as Reader (Rdr). -## Data +### Data This coloumn show the raw bytes trasmitted over the air. With option ```c``` CRC bytes are marked in square brackets. -## CRC +### CRC Marks if the transmitted CRC matches with the calculated CRC. -## Annotation +### Annotation Annotations provide a rough decoding of the transmitted data. For ISO14443A a more detailed decoding is available with Wireshark (s. next chapter) +-- +## Tracelog format +The binary format for the dynamic tracelog is as following. + +``` + /* + Traceformat: + 32 bits timestamp (little endian) + 16 bits duration (little endian) + 15 bits data length (little endian) (0x7FFF) + 1 bit isResponse (used as readerToTag flag) + y Bytes data + x Bytes parity, where x == ceil(data_len/8) +*/ + +typedef struct { + uint32_t timestamp; + uint16_t duration; + uint16_t data_len : 15; + bool isResponse : 1; + uint8_t frame[]; + // data_len bytes of data + // ceil(data_len/8) bytes of parity +} PACKED tracelog_hdr_t; + +#define TRACELOG_HDR_LEN sizeof(tracelog_hdr_t) +#define TRACELOG_PARITY_LEN(x) (((x)->data_len - 1) / 8 + 1) +``` + -- -# Trace and Wireshark +## Trace and Wireshark To get a more detailed explanation of the transmitted data for ISO14443A traces the output can be converted to a pcapng file to read it with [Wireshark](https://www.wireshark.org/).