1# Annotated Flatbuffer Binary
2
3This directory demonstrates the ability of flatc to annotate binary flatbuffers
4with helpful annotations. The resulting annotated flatbuffer binary (afb)
5contains all the binary data with line-by-line annotations.
6
7## Usage
8
9Given a `schema` in either plain-text (.fbs) or already compiled to a binary
10schema (.bfbs) and `binary` file(s) that was created by the `schema`.
11
12```sh
13flatc --annotate {schema_file} -- {binary_file}...
14```
15
16### Example
17
18The following command should produce `annotated_binary.afb` in this directory:
19
20```sh
21cd tests\annotated_binary
22..\..\flatc --annotate annotated_binary.fbs -- annotated_binary.bin
23```
24
25The `annotated_binary.bin` is the flatbufer binary of the data contained within
26 `annotated_binary.json`, which was made by the following command:
27
28```sh
29..\..\flatc -b annotated_binary.fbs annotated_binary.json
30```
31
32## Text Format
33
34Currently there is a built-in text-based format for outputting the annotations.
35The `annotated_binary.afb` is an example of the text format of a binary
36`annotated_binary.bin` and the `annotated_binary.fbs` (or
37`annotated_binary.bfbs`) schema.
38
39The file is ordered in increasing the offsets from the beginning of the binary.
40The offset is the 1st column, expressed in hexadecimal format (e.g. `+0x003c`).
41
42### Binary Sections
43
44Binary sections are comprised of contigious [binary regions](#binary-regions)
45that are logically grouped together. For example, a binary section may be a
46single instance of a flatbuffer `Table` or its `vtable`. The sections may be
47labelled with the name of the associated type, as defined in the input schema.
48
49Example of a `vtable` Binary Section that is associated with the user-defined
50`AnnotateBinary.Bar` table.
51
52```
53vtable (AnnotatedBinary.Bar):
54 +0x00A0 | 08 00 | uint16_t | 0x0008 (8) | size of this vtable
55 +0x00A2 | 13 00 | uint16_t | 0x0013 (19) | size of referring table
56 +0x00A4 | 08 00 | VOffset16 | 0x0008 (8) | offset to field `a` (id: 0)
57 +0x00A6 | 04 00 | VOffset16 | 0x0004 (4) | offset to field `b` (id: 1)
58```
59
60### Binary Regions
61
62Binary regions are contigious bytes regions that are grouped together to form
63some sort of value, e.g. a `scalar` or an array of scalars. A binary region may
64be split up over multiple text lines, if the size of the region is large.
65
66Looking at an example binary region:
67
68```
69vtable (AnnotatedBinary.Bar):
70 +0x00A0 | 08 00 | uint16_t | 0x0008 (8) | size of this vtable
71```
72
73The first column (`+0x00A0`) is the offset to this region from the beginning of
74the buffer.
75
76The second column are the raw bytes (hexadecimal) that make up this
77region. These are expressed in the little-endian format that flatbuffers uses
78for the wire format.
79
80The third column is the type to interpret the bytes as. Some types are special
81to flatbuffer internals (e.g. `SOffet32`, `Offset32`, and `VOffset16`) which are
82used by flatbuffers to point to various offsetes. The other types are specified
83as C++-like types which are the standard fix-width scalars. For the above
84example, the type is `uint16_t` which is a 16-bit unsigned integer type.
85
86The fourth column shows the raw bytes as a compacted, big-endian value. The raw
87bytes are duplicated in this fashion since it is more intutive to read the data
88in the big-endian format (e.g., `0x0008`). This value is followed by the decimal
89representation of the value (e.g., `(8)`). (For strings, the raw string value
90is shown instead).
91
92The fifth column is a textual comment on what the value is. As much metadata as
93known is provided.
94
95#### Offsets
96
97If the type in the 3rd column is of an absolute offset (`SOffet32` or
98`Offset32`), the fourth column also shows an `Loc: +0x025A` value which shows
99where in the binary this region is pointing to. These values are absolute from
100the beginning of the file, their calculation from the raw value in the 4th
101column depends on the context.
View as plain text