# 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
``` shell
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
``` python
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/erwanlem/atp",
"name": "asmat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "ASSEMBLER, TEST, ANALYSIS",
"author": "Erwan LEMATTRE",
"author_email": "erwanlem4@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4c/05/22d76ccc2800f58132c27ff4bffd09a7767f6f3c772d58d3b539ad0e51af/asmat-1.1.3.tar.gz",
"platform": null,
"description": "# ASMAT manual\n\n## Name\n\nasmat - Assembly Analysis and Testing\n\n## Description\n\n**ASMAT** is a testing and analysis tool made for checking assembly code efficency. This tool offers three main actions: **generation**, **validation** and **analysis**.\nThe generation phase generates reference assembly code. This code is stored in a reference folder.\nThe validation phase compares assembly code generated by the current library version with assembly code in the reference folder.\nThe analysis of a program gives information about assembly code that a compiler generates. Analysis is **only available for x86 instruction set**.\n\n\n\n## Installation\n\n``` shell\npip install asmat\n```\n\n\n## Command line - Options\n\n**-a**, **--analysis** \nAnalysis 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.\n\n**--build** \nBuild default files and directories `settings.json`, `ref/`. \n\n**-c** *compiler*, **--compiler** *compiler* \nThe code is only generated and tested for the given compiler.\n\n**-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).\n\n**-D** *tool*, **--disassembler** *tool* \nDefines 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.\n\n**-f** , **--fatal** \nRaises exception. This option interrupts the testing process if there is an assembly mismatch error. Useless for generation.\n\n**--flags** *flags* \nFlags 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.\n\n**-g** Generation mode. Generates assembly code and stores it in `ref`. Without this option, the default mode is validation.\n\n**-H** *headers*, **--header** *headers* \nDefines 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`.\n\n**-i** Instruction comparison. Compares only instructions and ignores their parameters.\n\n**--input** *files* | *group* \nDefines 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.\n\n**-j** *nbprocess* \nDefines the number of parallel compilations. The default number of parallel processes is equal to the number of processors cores.\n\n**-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.\n\n**--output** *path* \nThe path of the output. If this option is not defined, it takes the default path which is the directory *ref*.\n\n**--ref** *reference_path* \nDefines 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.\n\n**--reset** \nClears the `ref` directory.\n\n**-s** *setup*, **--setup** *setup* \nThe code is only generated and validated for the given simd extension. The given extension name **must** exist in `settings.json`.\n\n**-S** *limit*, **--functionsperfile** *limit* \nLimit 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.\n\n**--settings** *path* \nDefines 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*.\n\n**-t** Keeps temporary files after the process. Temporary files are files used to produce assembly code:\n- tmp.cpp : Contains generated cpp functions\n- tmp.o : Compiled file\n- tmp.txt : Contains assembly code extracts from tmp.o.\n\n**-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.\n\n\n## API - Examples\n\n``` python\nimport asmat\n\n# Generates requiered files if they do not exist\nasmat.build_dependencies()\n\n# Creates user query\ns = asmat.setup()\ns.verbose = True\ns.keep_tmp = True\n\n# Generation of references\nasmat.generate(s)\n\n# Validation of references\nasmat.validate(s)\n\n# Analysis of assembly code\nasmat.analyze(s, \"gcc\", \"sse\")\n```\n\n\n\n\n### Settings\nSettings are stored in `settings.json`. This file can be generated by calling `build_dependencies()` or by using `--build` option in console.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Assembly Testing and Analysis",
"version": "1.1.3",
"project_urls": {
"Download": "https://github.com/erwanlem/atp/archive/refs/tags/v1.0.tar.gz",
"Homepage": "https://github.com/erwanlem/atp"
},
"split_keywords": [
"assembler",
" test",
" analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "649a452cb251b8e2fe40d8e7cbe746f0c5954ad2a76469dad661a7dfe6867bc0",
"md5": "4770c03d1ba935b1fc88d37a576f1dad",
"sha256": "81eedf2e37dcda62897e3e452e5787e0bb2af2e0e55fca9bffc30985d287299f"
},
"downloads": -1,
"filename": "asmat-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4770c03d1ba935b1fc88d37a576f1dad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 134040,
"upload_time": "2024-06-28T14:05:32",
"upload_time_iso_8601": "2024-06-28T14:05:32.391222Z",
"url": "https://files.pythonhosted.org/packages/64/9a/452cb251b8e2fe40d8e7cbe746f0c5954ad2a76469dad661a7dfe6867bc0/asmat-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4c0522d76ccc2800f58132c27ff4bffd09a7767f6f3c772d58d3b539ad0e51af",
"md5": "e7281547bac667014fa44ecaa9fac360",
"sha256": "e7c34d6271ca2522d494042a3052ca1e4f1a34fda8bac9ad1ffa3635d7296649"
},
"downloads": -1,
"filename": "asmat-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "e7281547bac667014fa44ecaa9fac360",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 134929,
"upload_time": "2024-06-28T14:05:34",
"upload_time_iso_8601": "2024-06-28T14:05:34.021553Z",
"url": "https://files.pythonhosted.org/packages/4c/05/22d76ccc2800f58132c27ff4bffd09a7767f6f3c772d58d3b539ad0e51af/asmat-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-28 14:05:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "erwanlem",
"github_project": "atp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asmat"
}
JSON
