xref: /aosp_15_r20/external/emboss/doc/text-format.md (revision 99e0aae7469b87d12f0ad23e61142c2d74c1ef70) 
1<!-- TODO(bolms): this file could use a review to make sure it is still correct
2(as of 2017 December).  -->
3
4# Text Format
5
6[TOC]
7
8## Background
9
10Emboss messages may be automatically converted between a human-readable text
11format and machine-readable bytes.  For example, if you have the following
12`.emb` file:
13
14```
15struct Foo:
16  0 [+1]  UInt  a
17  1 [+1]  UInt  b
18
19struct Bar:
20  0 [+2]  Foo  c
21  2 [+2]  Foo  d
22```
23
24You may decode a Bar like so:
25
26```c++
27uint8_t buffer[4];
28auto bar_writer = BarWriter(buffer, sizeof buffer);
29bar_writer.UpdateFromText(R"(
30    {
31      c: {
32        a: 12
33        b: 0x20  # Hex numbers are supported.
34      }
35      d: {
36        a: 33
37        b: 0b10110011  # ... as are binary.
38      }
39    }
40)");
41assert(bar_writer.c().a().Read() == 12);
42assert(bar_writer.c().b().Read() == 32);
43assert(bar_writer.d().a().Read() == 33);
44assert(bar_writer.d().b().Read() == 0xb3);
45```
46
47Note that you can use `#`-style comments inside of the text format.
48
49It is also acceptable to omit fields, in which case they will not be updated:
50
51```c++
52bar_writer.UpdateFromText("d { a: 123 }");
53assert(bar_writer.c().a().Read() == 12);
54assert(bar_writer.d().a().Read() == 123);
55```
56
57Because Emboss does not enforce dependencies or duplicate field sets in
58`UpdateFromText`, it is currently possible to do something like this:
59
60```
61# memory_selector.emb
62struct MemorySelector:
63  0    [+1]  UInt    addr
64  addr [+1]  UInt:8  byte
65```
66
67```c++
68// memory_select_writer.cc
69uint8_t buffer[4];
70auto memory_writer = MemoryWriter(buffer, sizeof buffer);
71memory_writer.UpdateFromText(R"(
72    {
73      addr: 1
74      byte: 10
75      addr: 2
76      byte: 20
77      addr: 3
78      byte: 30
79      addr: 0
80    }
81)");
82assert(buffer[1] == 10);
83assert(buffer[2] == 20);
84assert(buffer[3] == 30);
85assert(buffer[0] == 0);
86```
87
88*Do not rely on this behavior.*  A future version of Emboss may add tracking to
89ensure that this example is an error.
90
91
92## Text Format Details
93
94The exact text format accepted by an Emboss view depends on the view type.
95Extra whitespace is ignored between tokens.  Any place where whitespace is
96allowed, the `#` character denotes a comment which extends to the end of the
97line.
98
99
100### `struct` and `bits`
101
102The text format of a `struct` or `bits` is a sequence of name/value pairs
103surrounded by braces, where field names are separated from field values by
104colons:
105
106    {
107      field_name: FIELD_VALUE
108      field_name_2: FIELD_VALUE_2
109      substructure: {
110        subfield: 123
111      }
112    }
113
114Only fields which are actually listed in the text will be set.
115
116If a field's address depends on another field's value, then the order in which
117they are listed in the text format becomes important.  When setting both,
118always make sure to set the dependee field before the dependent field.
119
120It is currently possible to specify a field more than once, but this may not be
121supported in the future.
122
123
124### `UInt` and `Int`
125
126`UInt`s and `Int`s accept numeric values in the same formats that are allowed
127in Emboss source files:
128
129    123456
130    123_456
131    0x1234cdef
132    0x1234_cdef
133    0b10100101
134    0b1010_0101
135    -123
136    -0b111
137
138
139### `Flag`
140
141`Flag`s expect either `true` or `false`.
142
143
144### `enum`
145
146An `enum`'s value may be either a name listed in the enum definition, or a
147numeric value:
148
149    FOO
150    2
151    100
152
153
154### Arrays
155
156An array is a list of values (in the appropriate format for the type of the
157array), separated by commas and surrounded by braces.  Values may be optionally
158prefixed with index markers of the form `[0]:`, where `0` may be any unsigned
159integer.  An extra comma at the end of the list is allowed, but not required:
160
161    { 0, 1, 2, 3, 4, 5, 6, 7 }
162    { 0, 1, 2, 3, 4, 5, 6, 7, }
163    { 0, 1, 2, 3, 4, [7]: 7, [6]: 6, [5]: 5 }
164
165When no index marker is specified, values are written to the index which is one
166greater than the previous value's index:
167
168    { [4]: 4, 5, 6, 7, [0]: 0, 1, 2, 3 }
169
170It is currently possible to specify multiple values for a single index, but
171this may not be supported in the future.
172
173*TODO(bolms): In the future section about creating new `external` types, make
174sure to note that the `external`'s text format should not start with `[` or
175`}`.*
176
177
178
179