doc/aarch64/topics/state-trace.md - platform/external/vixl - Git at Google

 AArch64 Simulator state trace
 =============================

 The AArch64 Simulator can be configured to produce traces of instruction
 execution, register contents, and memory accesses. The trace is designed to be
 intuitive for human readers, but this document describes the format of the
 trace, so that post-processing tools can confidently parse the output.

 In VIXL's own test runner, the trace is controlled by the `--trace*` options.
 Run `test-runner --help` for details.

 Basic structure
 ---------------

 Executed instructions show the address, the encoding of the instruction and the
 disassembly (as produced by VIXL's Disassembler). For example:

     0x00007fbe2a6a9044  d299d200		mov x0, #0xce90

 The first field is the address of the instruction, with exactly 16 hexadecimal
 characters and a leading 0x, and is followed by two spaces. The second field is
 the instruction encoding, with exactly eight hexadecimal characters (and no
 leading 0x). This is followed by two _tab_ characters, and the instruction
 disassembly. The following regular expression can be used to capture each field:

     (0x[0-9a-f]{16})  ([0-9a-f]{8})\t\t(.*)

 Following each instruction are zero or more lines of state update. Most notably,
 these represent the register state updates and memory accesses that occurred
 during simulation of the instruction. All of these lines begin with a '#'
 character, so that they can be easily identified, and filtered if necessary. For
 example:

     0x00007fd2221c907c  8b82200e		add x14, x0, x2, asr #8
     #            x14: 0xfffedcba98765432
     0x00007fd2221c9080  0b81200f		add w15, w0, w1, asr #8
     #            w15:         0xff89abcd

 Note that the Simulator uses these state update lines to describe its initial
 state. As a result, there will be state trace output before the first simulated
 instruction, and parsers need to be tolerant of this.

 Note that padding white space is used liberally to keep values vertically
 aligned throughout the trace (as shown with the write to `w15` in the example
 above). Similarly, some compound values are split into parts using the C++14
 literal separator (`'`) character. Refer to the "Memory accesses" section
 (below) for examples.

 Ordering
 --------

 VIXL guarantees that each instruction is printed before its associated state
 trace.

 State trace must be interpreted sequentially, line by line. VIXL avoids updating
 the same register more than once (because it makes the trace hard for humans to
 read), but this can occur in some situations, and should be supported by
 parsers.

 The state is intended to be consistent with architectural execution at the start
 of each instruction and at the end of the whole trace, but no such guarantees
 are made about the traced state _between_ instructions. VIXL prioritises
 human-readability when choosing the ordering of state updates.

 If simulated registers are modified externally, for example using
 `WriteRegister` from C++ code, their state will (by default) be logged
 immediately. In the full trace, it will appear as though the (runtime) call or
 return instruction modified the state. This is consistent with the guarantees
 above, but it can result in single instructions appearing to generate a large
 number of state updates.

 There is no upper limit on the number of state update lines that any one
 instruction can generate.

 Whole register trace
 --------------------

 The simplest form of state trace has the form "`REG: VALUE`", meaning that
 the register `REG` has the specified value, and any high-order bits in aliased
 registers are set to zero.

     0x00007fd2221c907c  8b82200e		add x14, x0, x2, asr #8
     #            x14: 0xfffedcba98765432

 Note that to correctly track state, parsers need to be aware of architectural
 register aliasing rules. Also, VIXL uses some standard register aliases, such as
 `lr` (`x30`). To avoid misinterpreting a register alias (and thereby potentially
 missing an aliased register update), some tools may need to treat an
 unrecognised register name as an error.

 This trace format attempts to represent _architectural_ register writes.
 However, this is not strictly checked or enforced.

 `VALUE` is always shown in hexadecimal (raw bits) form, with a leading `0x` and
 enough digits to exactly fill `REG`. `VALUE` may also include annotations (for
 example to show FP arithmetic values) in parentheses. These annotations are for
 the benefit of human readers, and parsers may ignore them.

 Note that SVE registers _always_ use the partial register trace format,
 described below, so a plain `z` or `p` register will never be used in a whole
 register trace. This is true even if the vector length is configured to 16
 bytes.

 Partial register trace
 ----------------------

 Sometimes, VIXL needs to show _part_ of a register without implying that the
 rest of the register is zeroed. A partial register value is indicated by a bit
 range in angled brackets after the register name: "`REG<MSB:LSB>: VALUE`".
 This format is used for stores, for example.

 SVE register updates are split across multiple lines, and therefore always use
 the partial register trace format. For example (with a 384-bit VL):

     0x00007fb1978da044  04214000		index z0.b, #0, #1
     #   z0<383:256>: 0x2f2e2d2c2b2a29282726252423222120
     #   z0<255:128>: 0x1f1e1d1c1b1a19181716151413121110
     #     z0<127:0>: 0x0f0e0d0c0b0a09080706050403020100

 Note that VIXL will omit whole lines where they are unnecessary, for example if
 they have no active (predicated) lanes. Parsers should not assume that every
 part of a register will appear in such cases.

 The `VALUE` has the same format as in the whole register trace, except in the
 case of SVE `p` registers (as described below).

 SVE `p` registers
 -----------------

 For `p` registers, we try to keep the lanes vertically aligned with the
 corresponding parts of the `z` registers that they affect. To do this, we use a
 binary format, with a leading `0b`, and spaces between each digit. For example:

     0x00007f66e539b0b8  04f54607		index z7.d, x16, #-11
     #     z7<127:0>: 0x00000000000000150000000000000020
     0x00007f66e539b0bc  25d8e3a7		ptrue p7.d, all
     #      p7<15:0>: 0b 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 1

 Memory accesses
 ---------------

 The pattern for a memory access is "`VALUE OP ADDRESS`", where:

 - `VALUE` is a hexadecimal value, with visual separators (') between
   structure components,
 - `OP` is `"->"` for a store, or `"<-"` for a load,
 - `ADDRESS` is the (hexadecimal) address of the access.

 Accesses shown in this style are always contiguous, and with little-endian
 semantics. However, a given instruction might have multiple lines of memory
 access trace, particularly if the instruction performs non-contiguous accesses.

 In the case of simple accesses, the `VALUE` is shared with register value trace:

     0x00007f3835372058  e400e401		st1b { z1.b }, p1, [x0]
     #      z1<127:0>: 0xd4d7dadde0e3e6e9eceff2f5f8fbfe01 -> 0x000055d170298e90

 Sign-extending loads show the whole resulting register value, with the (smaller)
 access represented on a separate line. This makes the (differing) values in the
 register and in memory unambiguous, without parsers needing to understand the
 instruction set:

     0x00007f47922d0068  79800306		ldrsh x6, [x24]
     #             x6: 0xffffffffffff8080
     #                                  ╙─ 0x8080 <- 0x00007fffbc197708

 Some instructions access several different memory locations. In these cases,
 each access is given its own line, with the highest lane index first so that
 (for contiguous accesses) the lowest address ends up at the bottom:

     0x00007fa6001e9060  e4217c0a		st2b { z10.b, z11.b }, p7, [x0, x1]
     #     z10<127:0>: 0x0f0e0d0c0b0a09080706050403020100
     #     z11<127:0>: 0x1f1e1d1c1b1a19181716151413121110
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─ 0x10'00 -> 0x00007ffe485d2f90
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─── 0x11'01 -> 0x00007ffe485d2f92
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───── 0x12'02 -> 0x00007ffe485d2f94
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─────── 0x13'03 -> 0x00007ffe485d2f96
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───────── 0x14'04 -> 0x00007ffe485d2f98
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─────────── 0x15'05 -> 0x00007ffe485d2f9a
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───────────── 0x16'06 -> 0x00007ffe485d2f9c
     #                    ║ ║ ║ ║ ║ ║ ║ ║ ╙─────────────── 0x17'07 -> 0x00007ffe485d2f9e
     #                    ║ ║ ║ ║ ║ ║ ║ ╙───────────────── 0x18'08 -> 0x00007ffe485d2fa0
     #                    ║ ║ ║ ║ ║ ║ ╙─────────────────── 0x19'09 -> 0x00007ffe485d2fa2
     #                    ║ ║ ║ ║ ║ ╙───────────────────── 0x1a'0a -> 0x00007ffe485d2fa4
     #                    ║ ║ ║ ║ ╙─────────────────────── 0x1b'0b -> 0x00007ffe485d2fa6
     #                    ║ ║ ║ ╙───────────────────────── 0x1c'0c -> 0x00007ffe485d2fa8
     #                    ║ ║ ╙─────────────────────────── 0x1d'0d -> 0x00007ffe485d2faa
     #                    ║ ╙───────────────────────────── 0x1e'0e -> 0x00007ffe485d2fac
     #                    ╙─────────────────────────────── 0x1f'0f -> 0x00007ffe485d2fae

 The line-drawing characters are encoded as UTF-8 (as is this document). There is
 currently no locale handling in VIXL, so this is not configurable. However,
 since these annotations are for the benefit of human readers, parsers can safely
 ignore them, and treat the whole trace as an ASCII byte stream (ignoring 8-bit
 characters). This is useful in situations where UTF-8 handling carries an
 unacceptable performance cost.

 In the future, VIXL may offer an option to avoid printing these annotations, so
 that the trace is restricted to single-byte characters.

 Floating-point value annotations
 --------------------------------

 Some floating-point operations produce register trace that annotates the raw
 values with the corresponding FP arithmetic values. This is for the benefit of
 human readers (and has limited precision). Such annotations follow the `VALUE`
 in parentheses.

 Scalar form:

     #             s1:                         0x3f800000 (1.000) <- 0x00007ffdc64d2314

 Vector form, updating all S lanes using a load:

     #            v16: 0x1211100f0e0d0c0b0a09080706050403 (4.577e-28, 1.739e-30, 6.598e-33, 2.502e-35)
     #                          ║       ║       ║       ╙─ 0x06050403 <- 0x00007ffe56fd7863
     #                          ║       ║       ╙───────── 0x0a090807 <- 0x00007ffe56fd7867
     #                          ║       ╙───────────────── 0x0e0d0c0b <- 0x00007ffe56fd786b
     #                          ╙───────────────────────── 0x1211100f <- 0x00007ffe56fd786f

 Vector form, updating a single S lane using a load:

     #             v2: 0x03020100040302017ff0f0027f80f000 (..., 1.540e-36, ...)
     #                                  ╙───────────────── 0x04030201 <- 0x00007ffc7b2e3ca1

 Vector form, replicating a single struct load to all S lanes:

     #            v15: 0x100f0e0d100f0e0d100f0e0d100f0e0d (2.821e-29, 2.821e-29, 2.821e-29, 2.821e-29)
     #            v16: 0x14131211141312111413121114131211 (7.425e-27, 7.425e-27, 7.425e-27, 7.425e-27)
     #            v17: 0x18171615181716151817161518171615 (1.953e-24, 1.953e-24, 1.953e-24, 1.953e-24)
     #                          ╙───────╨───────╨───────╨─ 0x18171615'14131211'100f0e0d <- 0x00007ffdd64d847d
	AArch64 Simulator state trace
	=============================

	The AArch64 Simulator can be configured to produce traces of instruction
	execution, register contents, and memory accesses. The trace is designed to be
	intuitive for human readers, but this document describes the format of the
	trace, so that post-processing tools can confidently parse the output.

	In VIXL's own test runner, the trace is controlled by the `--trace*` options.
	Run `test-runner --help` for details.

	Basic structure
	---------------

	Executed instructions show the address, the encoding of the instruction and the
	disassembly (as produced by VIXL's Disassembler). For example:

	0x00007fbe2a6a9044 d299d200 mov x0, #0xce90

	The first field is the address of the instruction, with exactly 16 hexadecimal
	characters and a leading 0x, and is followed by two spaces. The second field is
	the instruction encoding, with exactly eight hexadecimal characters (and no
	leading 0x). This is followed by two _tab_ characters, and the instruction
	disassembly. The following regular expression can be used to capture each field:

	(0x[0-9a-f]{16}) ([0-9a-f]{8})\t\t(.*)

	Following each instruction are zero or more lines of state update. Most notably,
	these represent the register state updates and memory accesses that occurred
	during simulation of the instruction. All of these lines begin with a '#'
	character, so that they can be easily identified, and filtered if necessary. For
	example:

	0x00007fd2221c907c 8b82200e add x14, x0, x2, asr #8
	# x14: 0xfffedcba98765432
	0x00007fd2221c9080 0b81200f add w15, w0, w1, asr #8
	# w15: 0xff89abcd

	Note that the Simulator uses these state update lines to describe its initial
	state. As a result, there will be state trace output before the first simulated
	instruction, and parsers need to be tolerant of this.

	Note that padding white space is used liberally to keep values vertically
	aligned throughout the trace (as shown with the write to `w15` in the example
	above). Similarly, some compound values are split into parts using the C++14
	literal separator (`'`) character. Refer to the "Memory accesses" section
	(below) for examples.

	Ordering
	--------

	VIXL guarantees that each instruction is printed before its associated state
	trace.

	State trace must be interpreted sequentially, line by line. VIXL avoids updating
	the same register more than once (because it makes the trace hard for humans to
	read), but this can occur in some situations, and should be supported by
	parsers.

	The state is intended to be consistent with architectural execution at the start
	of each instruction and at the end of the whole trace, but no such guarantees
	are made about the traced state _between_ instructions. VIXL prioritises
	human-readability when choosing the ordering of state updates.

	If simulated registers are modified externally, for example using
	`WriteRegister` from C++ code, their state will (by default) be logged
	immediately. In the full trace, it will appear as though the (runtime) call or
	return instruction modified the state. This is consistent with the guarantees
	above, but it can result in single instructions appearing to generate a large
	number of state updates.

	There is no upper limit on the number of state update lines that any one
	instruction can generate.

	Whole register trace
	--------------------

	The simplest form of state trace has the form "`REG: VALUE`", meaning that
	the register `REG` has the specified value, and any high-order bits in aliased
	registers are set to zero.

	0x00007fd2221c907c 8b82200e add x14, x0, x2, asr #8
	# x14: 0xfffedcba98765432

	Note that to correctly track state, parsers need to be aware of architectural
	register aliasing rules. Also, VIXL uses some standard register aliases, such as
	`lr` (`x30`). To avoid misinterpreting a register alias (and thereby potentially
	missing an aliased register update), some tools may need to treat an
	unrecognised register name as an error.

	This trace format attempts to represent _architectural_ register writes.
	However, this is not strictly checked or enforced.

	`VALUE` is always shown in hexadecimal (raw bits) form, with a leading `0x` and
	enough digits to exactly fill `REG`. `VALUE` may also include annotations (for
	example to show FP arithmetic values) in parentheses. These annotations are for
	the benefit of human readers, and parsers may ignore them.

	Note that SVE registers _always_ use the partial register trace format,
	described below, so a plain `z` or `p` register will never be used in a whole
	register trace. This is true even if the vector length is configured to 16
	bytes.

	Partial register trace
	----------------------

	Sometimes, VIXL needs to show _part_ of a register without implying that the
	rest of the register is zeroed. A partial register value is indicated by a bit
	range in angled brackets after the register name: "`REG<MSB:LSB>: VALUE`".
	This format is used for stores, for example.

	SVE register updates are split across multiple lines, and therefore always use
	the partial register trace format. For example (with a 384-bit VL):

	0x00007fb1978da044 04214000 index z0.b, #0, #1
	# z0<383:256>: 0x2f2e2d2c2b2a29282726252423222120
	# z0<255:128>: 0x1f1e1d1c1b1a19181716151413121110
	# z0<127:0>: 0x0f0e0d0c0b0a09080706050403020100

	Note that VIXL will omit whole lines where they are unnecessary, for example if
	they have no active (predicated) lanes. Parsers should not assume that every
	part of a register will appear in such cases.

	The `VALUE` has the same format as in the whole register trace, except in the
	case of SVE `p` registers (as described below).

	SVE `p` registers
	-----------------

	For `p` registers, we try to keep the lanes vertically aligned with the
	corresponding parts of the `z` registers that they affect. To do this, we use a
	binary format, with a leading `0b`, and spaces between each digit. For example:

	0x00007f66e539b0b8 04f54607 index z7.d, x16, #-11
	# z7<127:0>: 0x00000000000000150000000000000020
	0x00007f66e539b0bc 25d8e3a7 ptrue p7.d, all
	# p7<15:0>: 0b 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 1

	Memory accesses
	---------------

	The pattern for a memory access is "`VALUE OP ADDRESS`", where:

	- `VALUE` is a hexadecimal value, with visual separators (') between
	structure components,
	- `OP` is `"->"` for a store, or `"<-"` for a load,
	- `ADDRESS` is the (hexadecimal) address of the access.

	Accesses shown in this style are always contiguous, and with little-endian
	semantics. However, a given instruction might have multiple lines of memory
	access trace, particularly if the instruction performs non-contiguous accesses.

	In the case of simple accesses, the `VALUE` is shared with register value trace:

	0x00007f3835372058 e400e401 st1b { z1.b }, p1, [x0]
	# z1<127:0>: 0xd4d7dadde0e3e6e9eceff2f5f8fbfe01 -> 0x000055d170298e90

	Sign-extending loads show the whole resulting register value, with the (smaller)
	access represented on a separate line. This makes the (differing) values in the
	register and in memory unambiguous, without parsers needing to understand the
	instruction set:

	0x00007f47922d0068 79800306 ldrsh x6, [x24]
	# x6: 0xffffffffffff8080
	# ╙─ 0x8080 <- 0x00007fffbc197708

	Some instructions access several different memory locations. In these cases,
	each access is given its own line, with the highest lane index first so that
	(for contiguous accesses) the lowest address ends up at the bottom:

	0x00007fa6001e9060 e4217c0a st2b { z10.b, z11.b }, p7, [x0, x1]
	# z10<127:0>: 0x0f0e0d0c0b0a09080706050403020100
	# z11<127:0>: 0x1f1e1d1c1b1a19181716151413121110
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─ 0x10'00 -> 0x00007ffe485d2f90
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─── 0x11'01 -> 0x00007ffe485d2f92
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───── 0x12'02 -> 0x00007ffe485d2f94
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─────── 0x13'03 -> 0x00007ffe485d2f96
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───────── 0x14'04 -> 0x00007ffe485d2f98
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙─────────── 0x15'05 -> 0x00007ffe485d2f9a
	# ║ ║ ║ ║ ║ ║ ║ ║ ║ ╙───────────── 0x16'06 -> 0x00007ffe485d2f9c
	# ║ ║ ║ ║ ║ ║ ║ ║ ╙─────────────── 0x17'07 -> 0x00007ffe485d2f9e
	# ║ ║ ║ ║ ║ ║ ║ ╙───────────────── 0x18'08 -> 0x00007ffe485d2fa0
	# ║ ║ ║ ║ ║ ║ ╙─────────────────── 0x19'09 -> 0x00007ffe485d2fa2
	# ║ ║ ║ ║ ║ ╙───────────────────── 0x1a'0a -> 0x00007ffe485d2fa4
	# ║ ║ ║ ║ ╙─────────────────────── 0x1b'0b -> 0x00007ffe485d2fa6
	# ║ ║ ║ ╙───────────────────────── 0x1c'0c -> 0x00007ffe485d2fa8
	# ║ ║ ╙─────────────────────────── 0x1d'0d -> 0x00007ffe485d2faa
	# ║ ╙───────────────────────────── 0x1e'0e -> 0x00007ffe485d2fac
	# ╙─────────────────────────────── 0x1f'0f -> 0x00007ffe485d2fae

	The line-drawing characters are encoded as UTF-8 (as is this document). There is
	currently no locale handling in VIXL, so this is not configurable. However,
	since these annotations are for the benefit of human readers, parsers can safely
	ignore them, and treat the whole trace as an ASCII byte stream (ignoring 8-bit
	characters). This is useful in situations where UTF-8 handling carries an
	unacceptable performance cost.

	In the future, VIXL may offer an option to avoid printing these annotations, so
	that the trace is restricted to single-byte characters.

	Floating-point value annotations
	--------------------------------

	Some floating-point operations produce register trace that annotates the raw
	values with the corresponding FP arithmetic values. This is for the benefit of
	human readers (and has limited precision). Such annotations follow the `VALUE`
	in parentheses.

	Scalar form:

	# s1: 0x3f800000 (1.000) <- 0x00007ffdc64d2314

	Vector form, updating all S lanes using a load:

	# v16: 0x1211100f0e0d0c0b0a09080706050403 (4.577e-28, 1.739e-30, 6.598e-33, 2.502e-35)
	# ║ ║ ║ ╙─ 0x06050403 <- 0x00007ffe56fd7863
	# ║ ║ ╙───────── 0x0a090807 <- 0x00007ffe56fd7867
	# ║ ╙───────────────── 0x0e0d0c0b <- 0x00007ffe56fd786b
	# ╙───────────────────────── 0x1211100f <- 0x00007ffe56fd786f

	Vector form, updating a single S lane using a load:

	# v2: 0x03020100040302017ff0f0027f80f000 (..., 1.540e-36, ...)
	# ╙───────────────── 0x04030201 <- 0x00007ffc7b2e3ca1

	Vector form, replicating a single struct load to all S lanes:

	# v15: 0x100f0e0d100f0e0d100f0e0d100f0e0d (2.821e-29, 2.821e-29, 2.821e-29, 2.821e-29)
	# v16: 0x14131211141312111413121114131211 (7.425e-27, 7.425e-27, 7.425e-27, 7.425e-27)
	# v17: 0x18171615181716151817161518171615 (1.953e-24, 1.953e-24, 1.953e-24, 1.953e-24)
	# ╙───────╨───────╨───────╨─ 0x18171615'14131211'100f0e0d <- 0x00007ffdd64d847d