Skip to content

Commit 09c5728

Browse files
committed
Docs add trace overview to README.
1 parent cd45969 commit 09c5728

File tree

1 file changed

+37
-0
lines changed

1 file changed

+37
-0
lines changed

README.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,40 @@ cd build
2121
../configure --enable-plugins --target-list=<target>
2222
make
2323
```
24+
25+
## Trace format
26+
27+
The generated trace consists of three parts: the header,
28+
a table of contents (TOC) holding the frame entries, and an index into the TOC.
29+
30+
Each frame entry starts with the size of the frame, followed by the actual frame data.
31+
A fixed number of frame entries are considered one _entry_ in the TOC.
32+
33+
The TOC index is stored at the end.
34+
35+
For specifics about the frame contents, please refer
36+
to the [definitions](https://github.com/BinaryAnalysisPlatform/bap-frames/tree/master/piqi) in
37+
the BAP-frames repository.
38+
39+
**Format**
40+
41+
| Offset | Type | Field | Trace section |
42+
|--------|------|-------|------|
43+
| 0x0 | uint64_t | magic number (7456879624156307493LL) | Header begin |
44+
| 0x8 | uint64_t | trace version number | |
45+
| 0x10 | uint64_t | frame_architecture | |
46+
| 0x18 | uint64_t | frame_machine, 0 for unspecified. | |
47+
| 0x20 | uint64_t | n = number of frames per TOC entry. | |
48+
| 0x28 | uint64_t | T = offset to TOC index. | |
49+
| 0x30 | uint64_t | sizeof(frame_0) | TOC begin |
50+
| 0x38 | meta_frame | frame_0 | |
51+
| 0x40 | uint64_t | sizeof(frame_1) | |
52+
| 0x48 | type(frame_1) | frame_1 | |
53+
| ... | ... | ... | |
54+
| T-0x10 | uint64_t | sizeof(frame_n-1) | |
55+
| T-0x8 | type(frame_n-1) | frame_n-1 | |
56+
| T+0 | uint64_t | m = number of TOC entries | TOC index begin |
57+
| T+0x8 | uint64_t | offset toc_entry(0) | |
58+
| T+0x10 | uint64_t | offset toc_entry(1) | |
59+
| ... | ... | ... | |
60+
| T+0x8+(0x8*m) | uint64_t | offset toc_entry(m-1) | |

0 commit comments

Comments
 (0)