ASMAT manual

Name

asmat - Assembly Analysis and Testing

Description

ASMAT is a testing and analysis tool made for checking assembly code efficency. This tool offers three main actions: generation, validation and analysis. The generation phase generates reference assembly code. This code is stored in a reference folder. The validation phase compares assembly code generated by the current library version with assembly code in the reference folder. The analysis of a program gives information about assembly code that a compiler generates. Analysis is only available for x86 instruction set.

Installation

pip install asmat

Command line - Options

-a, --analysis
Analysis mode. Generates a detailed report of the assembly code generated by a compiler using a specific cpu extension. This mode can't be selected with validation or generation at the same time.

--build
Build default files and directories settings.json, ref/.

-c compiler, --compiler compiler
The code is only generated and tested for the given compiler.

-d Deep generation. When generating assembly this option will replace existing files even though they already contain assembly code. Enable this option when you want to update reference files outdated (otherwise reference files are not changed if they already exist).

-D tool, --disassembler tool
Defines the disassembling tool. Available disassembling tools are standard (-S option of compilers) or objdump. Assembly code generated by one of this tool can't be validated by the other. Default value is objdump. The standard option is only available for gcc and clang compilers.

-f , --fatal
Raises exception. This option interrupts the testing process if there is an assembly mismatch error. Useless for generation.

--flags flags
Flags used for compilation. Flags musn't contain dashes. It has the highest priority for the compilation process. It means that if flags are given, -m options is ignored even though it's also given. If there are no flags, default flags are used.

-g Generation mode. Generates assembly code and stores it in ref. Without this option, the default mode is validation.

-H headers, --header headers
Defines headers for compilation. headers are paths that will be add in C++ file as follows #include <header>. If this option is not given, headers are extracted from settings.json.

-i Instruction comparison. Compares only instructions and ignores their parameters.

--input files | group
Defines your own input file or group. Without this option all config files are used. The given file must exist in folder config. If a group is given it mist exist in settings.json. The priority is config file, group, all. When generating, it only generates those files. When validating, it only compares those files.

-j nbprocess
Defines the number of parallel compilations. The default number of parallel processes is equal to the number of processors cores.

-l Log. Generates a log file giving details about errors that occured during the validation. Two types of errors are described: comparison errors that occured when assembly code doesn't correspond and missing reference that occured when a function doesn't have a reference file.

--output path
The path of the output. If this option is not defined, it takes the default path which is the directory ref.

--ref reference_path
Defines a custom path for the reference folder. When generating it changes the location of the stored files. When validating it changes the place we get the reference files.

--reset
Clears the ref directory.

-s setup, --setup setup
The code is only generated and validated for the given simd extension. The given extension name must exist in settings.json.

-S limit, --functionsperfile limit
Limit the number of functions in cpp files. If the number of functions is greater than the limit it creates several cpp files that are compiled seperately.

--settings path
Defines the path to access the settings file. If not given it takes settings.json in the src directory. If given, it first searches the path in the src directory. If not found it searches path.

-t Keeps temporary files after the process. Temporary files are files used to produce assembly code:

• tmp.cpp : Contains generated cpp functions
• tmp.o : Compiled file
• tmp.txt : Contains assembly code extracts from tmp.o.

-v Verbose. Displays information in the command line. At the end of the process it gives the time elapsed since the beginning of the process.

API - Examples

import asmat

# Generates requiered files if they do not exist
asmat.build_dependencies()

# Creates user query
s = asmat.setup()
s.verbose = True
s.keep_tmp = True

# Generation of references
asmat.generate(s)

# Validation of references
asmat.validate(s)

# Analysis of assembly code
asmat.analyze(s, "gcc", "sse")

Settings

Settings are stored in settings.json. This file can be generated by calling build_dependencies() or by using --build option in console.