MPT v0.5

Section

Type

Description

[MPT]

Mandatory

MPT header

[CODE]

Mandatory

Code snippet specification

[REGISTERS]

Optional

Register initialization

[DATA]

Optional

Variable initialization

[RAW]

Optional

RAW statements

[STATE]

Optional

State specification

[TRACE]

Optional

Tracing information

[DAT]

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
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
; Microprobe Test Definition File
[MPT]
mpt_version = 0.5 ;  Format version of this MPT file.

[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 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 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                   ;
 
    
[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 ----------------------- 

[TRACE]

roi_start_instruction = 4323      ; Start dynamic instruction of the region of interest
roi_end_instruction = 5744        ; End dynamic instruction of the region of interest
roi_start_cycle = 30000           ; Start cycle of the region of interest
roi_end_cycle = 39982             ; End cycle of the region of interest
instruction_count = 5744          ; Number of dynamic instructions readed/to_generate
cycle_count = 39982               ; Number of cycles processed in the source trace