blob: 730cf5db0870b19635c77e63ee8617d8fb3922ca [file] [log] [blame] [view]
Greg Chadwick18a09cb2020-11-06 18:15:18 +00001# OTBN Tracer
2
3The tracer consists of a module (`otbn_tracer.sv`) and an interface
Rupert Swarbrickccb53f82020-12-16 16:55:43 +00004(`otbn_trace_if.sv`). The interface is responsible for directly probing the
Greg Chadwick18a09cb2020-11-06 18:15:18 +00005design and implementing any basic tracking logic that is required. The module
6takes an instance of this interface and uses it to produce trace data.
7
8Trace output is provided to the simulation environment by calling the
9`accept_otbn_trace_string` function which is imported via DPI (the simulator
10environment provides its implementation). Each call to
11`accept_otbn_trace_string` provides a trace record and a cycle count. There is
12at most one call per cycle. Further details are below.
13
Rupert Swarbrickccb53f82020-12-16 16:55:43 +000014A typical setup would bind an instantiation of `otbn_trace_if` and
15`otbn_tracer` into `otbn_core` passing the `otbn_trace_if` instance into the
Greg Chadwick18a09cb2020-11-06 18:15:18 +000016`otbn_tracer` instance. However this is no need for `otbn_tracer` to be bound
Rupert Swarbrickccb53f82020-12-16 16:55:43 +000017into `otbn_core` provided it is given a `otbn_trace_if` instance.
Greg Chadwick18a09cb2020-11-06 18:15:18 +000018
19## Trace Format
20
Rupert Swarbrick7245a182022-01-25 13:44:27 +000021Trace output is generated as a series of records. Every record has zero or more
22*header lines*, followed by zero or more *body lines*. There is no fixed
23ordering within the header lines or the body lines.
Greg Chadwick18a09cb2020-11-06 18:15:18 +000024
Rupert Swarbrick7245a182022-01-25 13:44:27 +000025The type of any line can be identified by its first character. The possible
26types for header lines are as follows:
Greg Chadwick18a09cb2020-11-06 18:15:18 +000027
Rupert Swarbrick7245a182022-01-25 13:44:27 +000028- `S`: **Instruction stall**. An instruction is stalled.
29- `E`: **Instruction execute**. An instruction completed its execution.
30- `U`: **Wipe in progress**. OTBN is in the middle of an internal wipe.
31- `V`: **Wipe complete**. An internal wipe has completed.
32
33The possible types for body lines are:
34
35- `<`: **Register read**: A register has been read.
36- `>`: **Register write**: A register has been written.
37- `R`: **Memory load**: A value has been loaded from memory.
38- `W`: **Memory store**: A value has been stored to memory.
39
40See the [sections below](#line-formats) for details of what information is in
41the different lines.
42
43A well-formed record has exactly one header line, but it's possible for the
44tracer to generate other records if something goes wrong in the design. It is
45not the tracer's responsibility to detect bugs; the simulation environment
46should flag these as errors in a suitable way.
47
48An instruction execution will be represented by zero or more `S` records,
49followed by one `E` record that represents the retirement of the instruction.
50The secure wipe phase at the end of OTBN's operation will be represented by
51zero or more `U` records, followed by a final `V` record.
52
53Whilst the tracer does not aim to detect bugs, there may be instances where the
54signals it traces do something unexpected that requires special behaviour.
55Where this happens, the string `"ERR"` will be placed somewhere in the line
56that contains information about the unexpected signals. See information on
57Memory Write (`W`) lines below for an example. `ERR` will not be present in
58trace output for any other reason.
Greg Chadwick18a09cb2020-11-06 18:15:18 +000059
60### Record examples
61(The first line of each example illustrates the instruction being traced to aid the example and
62is not part of the record)
63
64Executing `BN.SID x26++, 0(x25)` at PC 0x00000158:
65```
66E PC: 0x00000158, insn: 0x01acd08b
67< w20: 0x78fccc06_2228e9d6_89c9b54f_887cf14e_c79af825_69be57d4_fecd21a1_b9dd0141
68< x25: 0x00000020
69< x26: 0x00000014
70> x26: 0x00000015
71W [0x00000020]: 0x78fccc06_2228e9d6_89c9b54f_887cf14e_c79af825_69be57d4_fecd21a1_b9dd0141
72```
73
74Executing `BN.ADD w3, w1, w2` at PC 0x000000e8:
75```
76E PC: 0x000000e8, insn: 0x002081ab
77< w01: 0x78fccc06_2228e9d6_89c9b54f_887cf14e_c79af825_69be586e_9866bb3b_53769ada
78< w02: 0x99999999_99999999_99999999_99999999_99999999_99999999_99999999_99999999
79> w03: 0x1296659f_bbc28370_23634ee9_22168ae8_613491bf_0357f208_320054d4_ed103473
80> FLAGS0: {C: 1, M: 0, L: 1, Z: 0}
81```
82
83## Line formats
84
85### Instruction Execute (`E`) and Stall (`S`) lines
86
Rupert Swarbrick7245a182022-01-25 13:44:27 +000087These indicate that an instruction is executing or stalling. An 'E' line
88indicates the instruction completed in the trace record's cycle. An instruction
89that is stalled will first produce a record containing an 'S' line and will
90produce a matching 'E' line in a future record on the cycle it unstalls and
91finishes. The line provides the PC and raw instruction bits.
Greg Chadwick18a09cb2020-11-06 18:15:18 +000092
93Instruction at 0x0000014c is 0x01800d13 and stalling (a future record will
94contain a matching 'E' line):
95```
96S PC: 0x0000014c, insn: 0x01800d13
97```
98
99Instruction at 0x00000150 is 0x01acc10b is executing and will complete:
100```
101E PC: 0x00000150, insn: 0x01acc10b
102```
103
Rupert Swarbrick7245a182022-01-25 13:44:27 +0000104### Secure wipe (`U` and `V`) lines
105
106These indicate that a secure wipe operation is in progress. There is no other
107information, so the line consists of a bare `U` or `V` character.
108
Greg Chadwick18a09cb2020-11-06 18:15:18 +0000109### Register Read (`<`) and Write (`>`) lines
110
Rupert Swarbrick7245a182022-01-25 13:44:27 +0000111These show data that has been read or written to either register files or
112special purpose registers (such as ACC or the bignum side flags). The line
113provides the register name and the data read/written
Greg Chadwick18a09cb2020-11-06 18:15:18 +0000114
115Register x26 was read and contained value 0x00000018:
116```
117< x26: 0x00000018
118```
119
120Register w24 had value
121`0xcccccccc_bbbbbbbb_aaaaaaaa_facefeed_deadbeef_cafed00d_d0beb533_1234abcd`
122written to it:
123```
124> w24: 0xcccccccc_bbbbbbbb_aaaaaaaa_facefeed_deadbeef_cafed00d_d0beb533_1234abcd
125```
126
127Accumulator had value
128`0x00000000_00000000_00311bcb_5e157313_a2fd5453_c7eb58ce_1a1d070d_673963ce`
129written to it:
130```
131> ACC: 0x00000000_00000000_00311bcb_5e157313_a2fd5453_c7eb58ce_1a1d070d_673963ce
132```
133
134Flag group 0 had value `{C: 1, M: 1, L: 1, Z: 0}` written to it:
135```
136> FLAGS0: {C: 1, M: 1, L: 1, Z: 0}
137```
138
139### Memory Read (`R`) and Write (`W`) lines
140
Rupert Swarbrick7245a182022-01-25 13:44:27 +0000141These indicate activity on the Dmem bus. The line provides the address and data
Greg Chadwick18a09cb2020-11-06 18:15:18 +0000142written/read. For a read the data is always WLEN bits and the address is WLEN
143aligned (for an execution of LW only a 32-bit chunk of that data is required).
144For a write the write mask is examined. Where the mask indicates a bignum side
145write (BN.SID) full WLEN bit data is provided and the address is WLEN aligned.
146Where the mask indicates a base side write (SW) only 32-bit data is provided and
147the address is 32-bit aligned (giving the full address of the written chunk).
148
149Address `0x00000040` was read and contained value
150`0xcccccccc_bbbbbbbb_aaaaaaaa_facefeed_deadbeef_cafed00d_baadf00d_1234abcd`:
151```
152R [0x00000040]: 0xcccccccc_bbbbbbbb_aaaaaaaa_facefeed_deadbeef_cafed00d_baadf00d_1234abcd
153```
154
155Address `0x00000004` had value `0xd0beb533` written to it:
156```
157W [0x00000004]: 0xd0beb533
158```
159
160In the event of an OTBN bug that produces bad memory masks on writes (where the
161write is neither to a full 256 bits nor a aligned 32-bit chunk), an error line
162is produced giving the full mask and data
163```
164W [0x00000080]: Mask ERR Mask: 0xfffff800_0000ffff_ffffffff_00000000_00000000_00000000_00000000_00000000 Data: 0xcccccccc_bbbbbbbb_aaaaaaaa_facefeed_deadbeef_cafed00d_baadf00d_1234abcd
165```
Rupert Swarbrick660baa92020-12-15 17:00:55 +0000166
167## Using with dvsim
168
169To use this code, depend on the core file. If you're using dvsim,
170you'll also need to include `otbn_tracer_sim_opts.hjson` in your
171simulator configuration and add `"{tool}_otbn_tracer_build_opts"` to
172the `en_build_modes` variable.