Tool: mp_mpt2elf
Overview
MicroprobeTest (mpt) to ELF loop tool provides a command-line interface (CLI) to convert code snippets to assembly and ELF format. Using a test definition format (Microprobe test (mpt) format), the user can specify the initial state (initialization of the registers), the variables that have to be declared and the code snippet, which might contain references to those variables, branch labels, fixed addresses, etc. Check the Microprobe test (mpt) format for further details.
Note
The microbenchmark generation policy implemented in this tool reproduces exactly the code provided. It resolves any symbolic references (references to data, or branch targets), and only if specified by the user, it also modifies memory accesses to avoid segmentation fault issues. The tool wraps the code provided within an endless loop.
Basic usage
> mp_mpt2elf -T TARGET -t MPT_DEFINITION_FILE -O ASM_FILE --compiler COMPILER_PATH
where:
Flag/Argument |
Description |
|---|---|
|
Target definition string. Check: Command line target definition scheme. |
|
Microprobe test definition file. Check: Microprobe test (mpt) format. |
|
Output file name. |
|
Compiled binary. If provided the tools compiles the generated assembly file. |
Full usage
mp_mpt2elf.py: INFO: Processing input arguments...
usage: mp_mpt2elf.py [-h] [-P SEARCH_PATH [SEARCH_PATH ...]] [-V] [-v] [-d]
[-c CONFIG_FILE [CONFIG_FILE ...]] [-C FORCE_CONFIG_FILE]
[--dump-configuration-file OUTPUT_CONFIG_FILE]
[--dump-full-configuration-file OUTPUT_CONFIG_FILE]
[-A ARCHITECTURE_PATHS] [-M MICROARCHITECTURE_PATHS]
[-E ENVIRONMENT_PATHS] -T TARGET [--list-architectures]
[--list-microarchitectures] [--list-environments]
[--traceback] [--profile PROFILE_OUTPUT] -t
MPT_DEFINITION_FILE -O ELF_OUTPUT_FILE
[--compiler COMPILER] [--compiler-flags COMPILER_FLAGS]
[--fix-indirect-branches] [--fix-branch-next]
[--fix-memory-references] [--fix-memory-registers]
[--fix-flatten-code] [--safe-bin] [--raw-bin]
[--fix-long-jump] [-S FIX_START_ADDRESS]
[-X FIX_32BIT_ADDRESS] [--no-wrap-test] [--wrap-endless]
[--wrap-endless-threshold WRAP_ENDLESS_THRESHOLD]
[--reset]
MicroprobeTest (mpt) to ELF tool
optional arguments:
-h, --help show this help message and exit
-P SEARCH_PATH [SEARCH_PATH ...], --default_paths SEARCH_PATH [SEARCH_PATH ...]
Default search paths for microprobe target definitions
-V, --version Show Microprobe version and exit
-v, --verbosity Verbosity level (Values: [0,1,2,3,4]). Each time this
argument is specified the verbosity level is
increased. By default, no logging messages are shown.
These are the four levels available:
-v (1): critical messages
-v -v (2): critical and error messages
-v -v -v (3): critical, error and warning messages
-v -v -v -v (4): critical, error, warning and info messages
Specifying more than four verbosity flags, will
default to the maximum of four. If you need extra
information, enable the debug mode (--debug or -d
flags).
-d, --debug Enable debug mode in Microprobe framework. Lots of
output messages will be generated
Configuration arguments:
Command arguments related to configuration file handling
-c CONFIG_FILE [CONFIG_FILE ...], --configuration CONFIG_FILE [CONFIG_FILE ...]
Configuration file. The configuration files will be
readed in order of appearance. Values are reset by the
last configuration file in case of non-list values.
List values will be appended (not reset)
-C FORCE_CONFIG_FILE, --force-configuration FORCE_CONFIG_FILE
Force configuration file. Use this configuration file
as the default start configuration. This disables any
system-wide, or user-provided configuration.
--dump-configuration-file OUTPUT_CONFIG_FILE
Dump a configuration file with the actual
configuration used
--dump-full-configuration-file OUTPUT_CONFIG_FILE
Dump a configuration file with the actual
configuration used plus all the configuration options
not set
Target path arguments:
Command arguments related to target paths
-A ARCHITECTURE_PATHS, --architecture-paths ARCHITECTURE_PATHS
Search path for architecture definitions. Microprobe
will search in these paths for architecture
definitions
-M MICROARCHITECTURE_PATHS, --microarchitecture-paths MICROARCHITECTURE_PATHS
Search path for microarchitecture definitions.
Microprobe will search in these paths for
microarchitecture definitions
-E ENVIRONMENT_PATHS, --environment-paths ENVIRONMENT_PATHS
Search path for environment definitions. Microprobe
will search in these paths for environment definitions
Target arguments:
Command arguments related to target specification and queries
-T TARGET, --target TARGET
Target tuple. Microprobe follows a GCC-like target
definition scheme, where a target is defined by a
tuple as following:
<arch-name>-<uarch-name>-<env-name>
where:
<arch-name>: is the name of the architecture
<uarch-name>: is the name of the microarchitecture
<env-name>: is the name of the environment
One can use --list-* options to get the list of
definitions available in the default search paths or
the paths specified by the different --*-paths options
--list-architectures Generate a list of architectures available in the
defined search paths and exit
--list-microarchitectures
Generate a list of microarchitectures available in the
defined search paths and exit
--list-environments Generate a list of environments available in the
defined search paths and exit
Debug arguments:
Command arguments related to debugging facilities
--traceback show a traceback and starts a python debugger (pdb)
when an error occurs. 'pdb' is an interactive python
shell that facilitates the debugging of errors
--profile PROFILE_OUTPUT
dump profiling information into given file (see
'pstats' module)
Microprobe Test arguments:
Command arguments related to Microprobe Test (mpt) generation
-t MPT_DEFINITION_FILE, --mpt-definition-file MPT_DEFINITION_FILE
Microprobe test (mpt) definition file
MPT to ELF arguments:
Command arguments related to MPT to ELF tool
-O ELF_OUTPUT_FILE, --elf-output-file ELF_OUTPUT_FILE
ELF output file name
--compiler COMPILER Path to the compiler
--compiler-flags COMPILER_FLAGS
Compiler flags to use, if compiler is provided
Fixing options:
Command arguments related to fixing options
--fix-indirect-branches
Fix branches without known target
--fix-branch-next Force target of branches to be the next sequential
instruction
--fix-memory-references
Ensure that registers used by instructions accessing
storage are initialized to valid locations
--fix-memory-registers
Fix non-storage instructions touching registers used
for storage address computations (implies --fix-
memory-references flag)
--fix-flatten-code All code is flatten using consecutive addresses
--safe-bin Ignore unrecognized binary codifications (do notfail).
Useful when MPTs are generated by dumping directly
code pages, which contain padding zeros and other non-
code stuff)
--raw-bin Process all instruction entries together. They all
shoud be binary entries. Implies --safe-bin flag.
Useful when MPTs are generated by dumping directly
code pages, which contain padding zeros and other non-
code stuff)
--fix-long-jump Sometimes the generated code is unable compile due a
long jump displacement required to jump to the start
insturction.
-S FIX_START_ADDRESS, --fix-start-address FIX_START_ADDRESS
Sometimes the user requires the main start point to be
on specific address to avoid compilation issues or
comply with the execution environment requirements.
This flag forces the main entry point of execution to
be at the specified address. It is up to the user to
define a proper entry point that does not clash with
existing code.
-X FIX_32BIT_ADDRESS, --fix-32bit-address FIX_32BIT_ADDRESS
Sometimes the user requires the addresses of the
content to be within a 32bit address space. However, a
test may incorporate content outside of that address
space. This flag forces the variables to be shifted to
fit within this limit, starting at the specified
address. It is up to the user to define a proper
starting address that does not clash with the existing
code.
Wrapping options:
Command arguments related to wrapping options
--no-wrap-test By default the code is wrapped like it was a function
call, use this flag to disable the wrapping
--wrap-endless Use this flag to wrap the code in an endless loop
assuming it is a function. If needed (--reset option),
additional instructions are added to reset the the
initial state between loop iterations.
--wrap-endless-threshold WRAP_ENDLESS_THRESHOLD
Maximum percentage of instructions allowed in the
reset code if --wrap-endless and --reset is used. I.e.
if 10 is set, the tool will fail if the reset code
required is more than 10% of the actual code of the
test case. Default is 1%.
--reset Use this flag to enable the generation of reset code
if wrap-endless is enabled.
Environment variables:
MICROPROBETEMPLATES Default path for microprobe templates
MICROPROBEDEBUG If set, enable debug
MICROPROBEDEBUGPASSES If set, enable debug during passes
MICROPROBEASMHEXFMT Assembly hexadecimal format. Options:
'all' -> All immediates in hex format
'address' -> Address immediates in hex format (default)
'none' -> All immediate in integer format
Fix flags
As stated above, this tool does not ensure that the memory address accessed by the assembly code access valid storage regions. For that, one has to declare the appropriate variables and initialize valid register contents. Also, it might be the case that the code still is not correct and extra modifications are required.
Going through the assembly to understand it and manually modify it to make sure it runs correctly can be a tedious task. This tool provide a set of flags that perform predefined modifications on that code with the aim to make sure that at least it will run correctly. One has to take into account that the modifications might change the performance profile of the code. So, we strongly suggest you to validate the code generated to make sure it is still valid for your needs.
In the table below, we summarize the flags that enable extra modification to the code:
Flag |
Description |
|---|---|
|
Fix registers that are used to compute addresses in instruction accessing that access storage locations. |
|
Fix instructions touching registers used for storage address computations. If an instruction modifies a register that is used for storage address computation, the instruction is modified to not modify such register. Instead, a register that minimizes the dependency between instructions is used. Also, load and update or store and update instructions are replaced by their very same implementation without the update. Implies –fix-memory-references flag. |
|
Fix branches without known target. Any branch with unknown target is replaced by an unconditional branch to the next instruction. |
|
Force target of branches to be the next sequential instruction. |
Linker script
The assembly file generated provides the linker script required for compilation in comments. To extract it you should execute the following command:
> grep "MICROPROBE LD" assembly_file | cut -d '@' -f 2 > custom.ld.script
Compiling
In order to maintain the memory layout in the generated binary, should provide the linker scripts during the program compilation:
> gcc -o output input.s -static -T custom.ld.script -T default.system.ld.script
To obtain the default system ld script one can execute:
> ld --verbose > default.system.ld.script
and then remove the comments in the file (header and footer).