Tool: mp_mpt2bin
Overview
MicroprobeTest (mpt) to BIN loop tool provides a command-line interface (CLI) to convert code snippets to BINARY 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_mpt2bin -T TARGET -t MPT_DEFINITION_FILE -O MPT_OUTPUT_FILE
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. |
Full usage
mp_mpt2bin.py: INFO: Processing input arguments...
usage: mp_mpt2bin.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 BIN_OUTPUT_FILE [--big-endian]
[--fix-indirect-branches] [--fix-branch-next]
[--fix-memory-references] [--fix-memory-registers]
[--fix-flatten-code] [--safe-bin] [--no-wrap-test]
[--wrap-endless]
[--wrap-endless-threshold WRAP_ENDLESS_THRESHOLD]
[--endless]
MicroprobeTest (mpt) to BIN 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 BIN arguments:
Command arguments related to MPT to BIN tool
-O BIN_OUTPUT_FILE, --bin-output-file BIN_OUTPUT_FILE
BIN output file name
--big-endian Test case in big endian (default is little endian)
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)
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, 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 loop 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%.
--endless Use this flag to wrap the code in an endless loop.
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. |