MPT v0.5
Section |
Type |
Description |
|---|---|---|
|
Mandatory |
MPT header |
|
Mandatory |
Code snippet specification |
|
Optional |
Register initialization |
|
Optional |
Variable initialization |
|
Optional |
RAW statements |
|
Optional |
State specification |
|
Optional |
Tracing information |
|
Optional |
DAT specification |
[REGISTERS] Section
[REGISTERS] ; Section to specify the initial register values
; Format: register = value. E.g.:
; Set GR0, GR1 and GR2 register to 0, 1, 2 values respectively
GR0 = 0x0
GR1 = 0x1
GR2 = 0x2
[DATA] Section
[DATA] ; Section to specify the variables
; Data section default address. Variables will be placed from this address
; if their address is not specified
default_address = 0x00200000
; Variable Declaration
; Format: var_name = [ "type", nelems, address, alignment, init_values ]
; where:
; - "type": is a string specifying the type of elements in the variable
; - nelems: is the number of elements in the variable
; - address : is the address of the variable, if set the address will be
; fixed, otherwise, it will be computer by microprobe
; - alignment : alignment requirements of the variable. It should not
; conflict with address if specified. It can be set to None
; - init_values : if it is a single value, all the elements will be
; initialized to that value, if it is an array, elements
; will be initialized to the values specified in a round-
; robin fashion. Two special keywords can be specified:
; RNDFP and RNDINT to initialize the elements to random FP
; and random INT values
;
; Note that variable names ARE NOT case sensitive. I.e. VAR = Var = var
;
; Some examples:
; Integer initialized to 1 without address or alignment requirements
var_sngl_int_1 = [ "int", 1, None, None, 1]
; Array of 2 double elements initialized to 1.0 placed at address 0x00210000
var_array_fp_1 = [ "double", 2, 0x00210000, None, 1.0 ]
; Array of 40 double elements initialized to random FP values placed in
; an address aligned to 16 bytes
var_array_fp_rnd = [ "double", 40, None, 16, RNDFP ]
; Array of 10 short elements placed at address 0x00220000 and initialized to
; 2,4,2 ... 4,2,4 values
var_array_int24 = [ "short", 10, 0x00220000, 4, [2,4]]
[CODE] Section
Note
Notice that the contents of the ‘instructions =’ entry are indented. That is, all the instructions, labels or addresses should be specified in an indented line. Otherwise, the parser believes that each line is a different entry.
[CODE] ; Section to specify the code
; Code section default address. Code will be placed from this address
; if the instruction address is not specified
default_address = 0x00100000
; The code specified after 'instructions' entry (below) is the code that will be
; processed by microprobe. The instruction format is similar to GNU assembler
; format, it also allows the specification of labels (NOT case sensitive) and
; references to the declared variables. It is also possible to specify instruction
; addresses and to do code expansion by referencing other user
; defined entries. Check the example below to see examples of these features.
;
; *****************************************************************************
; ****** Although Microprobe performs some sanity checks, it is the ********
; ****** responsibility of the user to define correct code. ********
; ****** ********
; *****************************************************************************
instructions =
larl r2, var_array_fp_rnd ; reference to variable var_array_fp_rnd
larl r5, var_array_fp_1 ; reference to variable var_array_fp_1
brcl_v3 15, myalign ; branch relative to myalign, in some
; situations the instruction variant
; (BRCL_V3) has to be specified
0x00000010 <myalign> : ; declaration of label 'myalign' plus
; specification of the address for
; the following instruction
vl v2, 0(r0, r5) ;
lghi r1, 20 ;
<loop1> : ; declaration of label 'loop1'
%(myloop)s ; expansion, 'myloop' will be replaced by
; the value of myloop entry (below) .
; Useful when the same code snippet has
; to be replicated several times
brctg r1, loop1 ; reference to label 'loop1'
brcl_v3 15, label1 ;
<label1> 0x000100300: bcr 0, 0 ; labels/address can be also specified
0x000100302 <label2>: bcr 0, 0 ; in the same line as assembly in
<label3>: bcr 0, 0 ; different order
0x000100306: bcr 0, 0 ;
;
svc 0 ; Add your favorite end test sequences
brc 15, 0 ; svc or branch-to-self
;
;
myloop = ; declaration of myloop entry used
vl v0, 0(r0, r2) ; expanded within 'instructions' entry
vfa v0, v0, v2, 3, 0 ;
vst v0, 0(r0, r2) ;
aghi r2, 16 ;
Note
Notice that the contents of the ‘instructions =’ entry are indented. That is, all the instructions, labels or addresses should be specified in an indented line. Otherwise, the parser believes that each line is a different entry.
[RAW] Section
[RAW] ; Section to specify raw string to be generated in the output file
; Currently, the user can embed 'raw' statements at four different locations
file_header = * ------------------------ FILE HEADER -----------------------
* This is going to be embedded 'as is' at the beginning of the
* the generated file.
* ------------------------ FILE HEADER -----------------------
file_footer = * ------------------------ FILE FOOTER -----------------------
* This is going to be embedded 'as is' at the end of the
* the generated file.
* ------------------------ FILE FOOTER -----------------------
code_header = * ------------------------ CODE HEADER -----------------------
* This is going to be embedded 'as is' just before the code
* ------------------------ CODE HEADER -----------------------
code_footer = * ------------------------ CODE FOOTER -----------------------
* This is going to be embedded 'as is' just after the code
* ------------------------ CODE FOOTER -----------------------
[DAT] Section
In general, microbenchmarks generated do not need to be aware of the Dynamic Address Translation (DAT) as they typically are targeted to generate addresses within their own logical address space. However, some backends support the generation of Dynamic Address Translation aware microbenchmarks. In such backends, the user can specify the address translation mappings. Check the example below:
[DAT] ; Dynamic address translation
# Translation mappings. One can specify manually the translation mappings, and the
# instruction addresses will be generated accordingly. Whenever the instruction
# address matches one of the mappings, it is translated accordingly.
# Format is: address, mapping_address, mask
# e.g.: trans_map = [ (0x0123456700123000, 0x00000DFA76590000, 0xfffffffffffff000 ),
# (0x0123456700124000, 0x00000DFA765A0000, 0xfffffffffffff000 ),
# ... ]
dat_map = [ (0x0123456700123000, 0x00000DFA76590000, 0xfffffffffffff000 ) ]
#
# This entry will be automatically appended to the generated testcase. It is treated
# like the code_footer entry in the [RAW] section
#
dat_raw =
* -------- DAT RAW ENTRY ----------------
any code/set up required to generated the
expected DAT mappings
* -------- DAT RAW ENTRY ----------------
Example code using DAT-related decorations to control when the dynamic address translation mechanisms is used or not:
[CODE] ; Section to specify the code
default_address = 0x123456700123000
instructions =
@ DAT=On ; Enable DAT
brc 0, 0x0 ; At address: 0x123456700123000 --> 0x00000DFA76590000
lpswe 0x0(2) ; At address: 0x123456700123004 --> 0x00000DFA76590004
@ DAT=Off ; Disable DAT
0x000000000123000: ; New address
ptlb ; At address: 0x0000000000123000 (no translation)
lpswe 0x0(1) ; At address: 0x0000000000123004 (no translation)
@ DAT=On ; Enable DAT
0x123456700123008: ; New address
brc 0, 0x0 ; At address: 0x123456700123008 --> 0x00000DFA76590008
brc 0, 0x0 ; At address: 0x12345670012300C --> 0x00000DFA7659000C
brc 0, 0x0 ; At address: 0x123456700123010 --> 0x00000DFA76590010
brc 15, 0x0 ; At address: 0x123456700123014 --> 0x00000DFA76590014
[STATE] Section
The state section is used to define the initial state of the microbenchmark. Currently, it only has one entry:
[STATE]
contents = <path_to_state_file>
State files are text files where each line follows the following format:
a line starting by M, then an address and its contents separated by a single space (to specify memory contents)
a line starting by ‘R’, then the register name and then the value (to specify the reg. contents)
Example:
M 0x012345677 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
M 0x012345677 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
...
M 0x012345677 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
M 0x012345677 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
...
R GR0 0x0123456789ABC
R GR1 0x0123456789ABC
R GR2 0x0123456789ABC
...
R GR31 0x0123456789ABC
Clarifications on the format:
Register entries can appear at any point.
Register entries do not need to be sorted.
Register entries can have duplicates. The last value of seen for a register will be used. A warning will be generated.
Register values provided in
[REGISTERS]section will take preference over registers values specified in the state file.Memory entries can appear at any point but they should be sorted by memory access order (the actual access order generated by the program). This information about order might be eventually used by Microprobe to implement different data warm-up schemes.
Size of memory contents is automatically inferred from the content string length.
For readability, it is preferred to dump first the registers and then the memory entries in program access order.
[TRACE] Section
MPTs can be generated from simulation/execution traces. Also, traces can be generated from a given MPT. The trace section is used to define trace related information such as the number of instructions/cycles executed/simulated or the information (start/end) in cycles or instructions of the region of interest (ROI) to be traced. Currently, this section supports the following entries:
[TRACE]
roi_start_instruction = <integer> ; Start dynamic instruction of the region of interest
roi_end_instruction = <integer> ; End dynamic instruction of the region of interest
roi_start_cycle = <integer> ; Start cycle of the region of interest
roi_end_cycle = <integer> ; End cycle of the region of interest
instruction_count = <integer> ; Number of dynamic instructions readed/to_generate
cycle_count = <integer> ; Number of cycles processed in the source trace
roi_memory_access_trace = <path_to_trace_file> ; Path to trace file containing the memory
; access trace of the test cases.
Memory access trace files are text files where each line describes a memory access in progrem execution order. Each line contains the following four fields separated by a space:
Type of data: data (D) or code (I)
Type of access: read/load (R) or write/store (W)
Address in hexadecimal format (0x ….)
Length in bytes in decimal format
Lines can also include comments after the ‘;’ character. Example:
I R 0x0000000100001000 4 ; Code read of 4 bytes at address 0x100001000
I R 0x0000000100001004 4 ; Code read of 4 bytes at address 0x100001004
I R 0x0000000100001008 4 ; Code read of 4 bytes at address 0x100001008
D R 0x0000000101000000 8 ; Data read of 8 bytes at address 0x101000000
D W 0x0000000101000008 8 ; Data write of 8 bytes at address 0x101000008
Complete example
1; Microprobe Test Definition File
2[MPT]
3mpt_version = 0.5 ; Format version of this MPT file.
4
5[REGISTERS] ; Section to specify the initial register values
6
7; Format: register = value. E.g.:
8
9; Set GR0, GR1 and GR2 register to 0, 1, 2 values respectively
10GR0 = 0x0
11GR1 = 0x1
12GR2 = 0x2
13
14[DATA] ; Section to specify the variables
15
16; Data section default address. Variables will be placed from this address
17; if their address is not specified
18
19default_address = 0x00200000
20
21; Variable Declaration
22; Format: var_name = [ "type", nelems, address, alignment, init_values ]
23; where:
24; - "type": is a string specifying the type of elements in the variable
25; - nelems: is the number of elements in the variable
26; - address : is the address of the variable, if set the address will be
27; fixed, otherwise, it will be computer by microprobe
28; - alignment : alignment requirements of the variable. It should not
29; conflict with address if specified. It can be set to None
30; - init_values : if it is a single value, all the elements will be
31; initialized to that value, if it is an array, elements
32; will be initialized to the values specified in a round-
33; robin fashion. Two special keywords can be specified:
34; RNDFP and RNDINT to initialize the elements to random FP
35; and random INT values
36;
37; Note that variable names ARE NOT case sensitive. I.e. VAR = Var = var
38;
39; Some examples:
40
41; Integer initialized to 1 without address or alignment requirements
42var_sngl_int_1 = [ "int", 1, None, None, 1]
43
44; Array of 2 double elements initialized to 1.0 placed at address 0x00210000
45var_array_fp_1 = [ "double", 2, 0x00210000, None, 1.0 ]
46
47; Array of 40 double elements initialized to random FP values placed in
48; an address aligned to 16 bytes
49var_array_fp_rnd = [ "double", 40, None, 16, RNDFP ]
50
51; Array of 10 short elements placed at address 0x00220000 and initialized to
52; 2,4,2 ... 4,2,4 values
53var_array_int24 = [ "short", 10, 0x00220000, 4, [2,4]]
54
55[CODE] ; Section to specify the code
56
57; Code section default address. Code will be placed from this address
58; if the instruction address is not specified
59
60default_address = 0x00100000
61
62; The code specified after 'instructions' entry (below) is the code that will be
63; processed by microprobe. The instruction format is similar to GNU assembler
64; format, it also allows the specification of labels (NOT case sensitive) and
65; references to the declared variables. It is also possible to specify instruction
66; addresses and to do code expansion by referencing other user
67; defined entries. Check the example below to see examples of these features.
68;
69; *****************************************************************************
70; ****** Although Microprobe performs some sanity checks, it is the ********
71; ****** responsibility of the user to define correct code. ********
72; ****** ********
73; *****************************************************************************
74
75instructions =
76 larl r2, var_array_fp_rnd ; reference to variable var_array_fp_rnd
77 larl r5, var_array_fp_1 ; reference to variable var_array_fp_1
78 brcl_v3 15, myalign ; branch relative to myalign, in some
79 ; situations the instruction variant
80 ; (BRCL_V3) has to be specified
81 0x00000010 <myalign> : ; declaration of label 'myalign' plus
82 ; specification of the address for
83 ; the following instruction
84 vl v2, 0(r0, r5) ;
85 lghi r1, 20 ;
86 <loop1> : ; declaration of label 'loop1'
87 %(myloop)s ; expansion, 'myloop' will be replaced by
88 ; the value of myloop entry (below) .
89 ; Useful when the same code snippet has
90 ; to be replicated several times
91 brctg r1, loop1 ; reference to label 'loop1'
92 brcl_v3 15, label1 ;
93 <label1> 0x000100300: bcr 0, 0 ; labels/address can be also specified
94 0x000100302 <label2>: bcr 0, 0 ; in the same line as assembly in
95 <label3>: bcr 0, 0 ; different order
96 0x000100306: bcr 0, 0 ;
97 ;
98 svc 0 ; Add your favorite end test sequences
99 brc 15, 0 ; svc or branch-to-self
100 ;
101 ;
102myloop = ; declaration of myloop entry used
103 vl v0, 0(r0, r2) ; expanded within 'instructions' entry
104 vfa v0, v0, v2, 3, 0 ;
105 vst v0, 0(r0, r2) ;
106 aghi r2, 16 ;
107
108
109[RAW] ; Section to specify raw string to be generated in the output file
110
111; Currently, the user can embed 'raw' statements at four different locations
112
113file_header = * ------------------------ FILE HEADER -----------------------
114 * This is going to be embedded 'as is' at the beginning of the
115 * the generated file.
116 * ------------------------ FILE HEADER -----------------------
117
118file_footer = * ------------------------ FILE FOOTER -----------------------
119 * This is going to be embedded 'as is' at the end of the
120 * the generated file.
121 * ------------------------ FILE FOOTER -----------------------
122
123code_header = * ------------------------ CODE HEADER -----------------------
124 * This is going to be embedded 'as is' just before the code
125 * ------------------------ CODE HEADER -----------------------
126
127code_footer = * ------------------------ CODE FOOTER -----------------------
128 * This is going to be embedded 'as is' just after the code
129 * ------------------------ CODE FOOTER -----------------------
130
131[TRACE]
132
133roi_start_instruction = 4323 ; Start dynamic instruction of the region of interest
134roi_end_instruction = 5744 ; End dynamic instruction of the region of interest
135roi_start_cycle = 30000 ; Start cycle of the region of interest
136roi_end_cycle = 39982 ; End cycle of the region of interest
137instruction_count = 5744 ; Number of dynamic instructions readed/to_generate
138cycle_count = 39982 ; Number of cycles processed in the source trace
139