{ "info": { "author": "", "author_email": "", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Environment :: Console", "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Topic :: Scientific/Engineering :: Visualization", "Topic :: Software Development", "Topic :: Software Development :: Embedded Systems", "Topic :: Software Development :: Quality Assurance" ], "description": "# Emma\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/8c6208f6f0bf4d429b13e2fa701aa780)](https://www.codacy.com/app/holzkohlengrill/Emma?utm_source=github.com&utm_medium=referral&utm_content=bmwcarit/Emma&utm_campaign=Badge_Grade)\n[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/8c6208f6f0bf4d429b13e2fa701aa780)](https://www.codacy.com/app/holzkohlengrill/Emma?utm_source=github.com&utm_medium=referral&utm_content=bmwcarit/Emma&utm_campaign=Badge_Coverage)\n[![Build Status](https://travis-ci.org/bmwcarit/Emma.svg?branch=master)](https://travis-ci.org/bmwcarit/Emma)\n[![PyPi](https://img.shields.io/pypi/v/pypiemma)](https://pypi.org/project/pypiemma/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![GitHub pages](https://img.shields.io/badge/doc-GitHub%20pages-blue)](https://bmwcarit.github.io/Emma)\n\n**Emma Memory and Mapfile Analyser (Emma)**\n\n> Conduct static (i.e. worst case) memory consumption analyses based on arbitrary linker map files. It produces extensive `.csv` files which are easy to filter and post-process. Optionally `.html` and markdown reports as well as neat figures help you visualising your results.\n\n\n
\n\nGiven a **map file input** (Green Hills map files are the default but others - like GCC - are supported via configuration options; examples are enclosed) Emma **map**s the addresses of sections (aka images) and/or objects (aka modules) **to memory regions** (all addresses given via map files must be known during compile time). Those memory regions are classified into two levels of granularity respectively. The first level defines arbitrary groups based on your personal taste (however using names similar to those defined by your microcontroller vendor makes most sense). Later each of those regions (second level) are assigned to one of four generalised predefined memory regions (those are: `INT_RAM`, `INT_FLASH`, `EXT_RAM`, `EXT_FLASH`). In case of **virtual memory** objects and sections lying within virtual address spaces (VASes) get **translated back into physical memory**. This is depicted in the figure above (lower part).\n\n**Categorisation** can be used to assign consumers (a consumer would usually represent a software component) to each object or section. This is useful for subsequent steps in order to display memory consumption per consumer type. See the upper part of the figure shown above. Mechanisms are provided to batch categorise object and section names. \"Objects in sections\" provides ways to obtain a **finer granularity of the categorisation result**. Therefore categorised sections containing (smaller) objects of a different category got split up and result into a more accurate categorisation.\n\nAs a result you will get **output** files in form of a **`.csv` file** which sets you up to do later processing on this data easily. In this file **additional information is added** like:\n\n* Overlaps (of sections/objects)\n* Containments (e.g. sections containing objects)\n* Duplicates\n* All meta data about the origin of each section/object (mapfile, addess space, ...)\n* ...\n\nHolding the aforementioned **augmented data** makes it easy to **detect issues in linker scripts** and get an **in-depth understanding of** your program's **memory consumption**. Including a lot of additional and \"corrected\" data can cause confusion. Thus all original (unmodified) data is preserved in the output files simultaneously.\n\nThe Emma visualiser helps you to create nice plots and reports in a `.png` and `.html` and markdown file format.\n\nThe whole Emma tool suite contains command line options making it convenient to be **run on a build server** like `--Werror` (treat all warnings as errors) or `--no-prompt` (exit and fail on user prompts; user prompts can happen when ambiguous configurations appear such as multiple matches for one configured map files).\n\n------------------------\n\n\n## Installation\n\n```bash\npip3 install pypiemma\n```\n\nDependencies: Python 3.6 or higher; `pip3 install Pygments Markdown matplotlib pandas pypiscout`\n\n\n## General Workflow\nThe following figure shows a possible workflow using Emma:\n\n\n
\n\n**Emma** - as the core component - produces an intermediate `.csv` file. Inputs are mapfiles and JSON files (for configuration (memory layout, sizes, ...)). From this point you are very flexible to choose your own pipeline. You could\n\n* use the Emma tools (**Emma Visualiser**, **Emma Deltas**, ...) for **further processing (data aggregation and analysis)**,\n* simply your favourite spreadsheet software (like Microsoft Excel or LibreOffice Calc) or\n* use your own tool for the data analysis.\n\n\n## Quick Start Guide\nAt this point we want to give you a brief overview what to do in the below two scenarios. If you want to play around go to [(project files are already present)](#Project-files-are-already-present) and use our example projects in `./doc/test_project*`.\n\n* if the Emma *project is already set-up* (JSON files were created) and you want to analyse your software with newly generated mapfiles proceed to [-> Project files are already present](#Project-files-are-already-present) or\n* you *start* your analysis *from scratch* and need to do configure Emma before you use it then go to [-> Project files have to be created](#project-files-that-have-to-be-created).\n\nExample projects (including Emma* outputs/results) can be found in `./doc/test_project*`.\n\n*Since version 3.1* Emma can be called in two ways (if you want to run it from the installation folder) where the following variant is recommended:\n\n```bash\npython Emma.py a --project doc/test_project --mapfiles doc/test_project/mapfiles --noprompt\n```\n\nThe following table provides an overview how you call Emma:\n\n| Emma module | Entry point + \\) (if installed via `pip`) | Top level sub-command (tlsc) (`python Emma.py` \\) | Module (`python -m` + \\ \\) |\n| ----------- | --------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------- |\n| Analyser | `emma` | `a` | `Emma.emma` |\n| Visualiser | `emma_vis` | `v` | `Emma.emma_vis` |\n| Deltas | `emma_deltas` | `d` | `Emma.emma_deltas` |\n\n\n------------------------\n\n\n### Project files are already present\nTry `python Emma.py a --help` to see all possible options or refer to the documentation (`./doc/*`).\n\n1. Create intermediate `.csv` from mapfiles with Emma:\n\n```bash\npython Emma.py a -p .\\MyProjectFolder --map .\\MyProjectFolder\\mapfiles --dir .\\MyProjectFolder\\analysis --subdir Analysis_1\n```\n\n2. Generate reports and graphs with Emma Visualiser:\n\n```bash\npython Emma.py v -p .\\MyProjectFolder --dir .\\MyProjectFolder\\analysis --subdir Analysis_1 -q \n```\n\n### Project files that have to be created\nTo create a new project, the following files must be created:\n\n* `globalConfig.json`\n* `budgets.json`\n* `categories.json`\n* `categoriesKeywords.json`\n* `categoriesSections.json`\n* `categoriesSectionsKeywords.json`\n\nYou will find example projects in `./doc/test_project*`. In-depth documentation can be found in the full documentation (see `./doc/`).\n\nA basic configuration can be short per file. For complex systems you can choose from many optional keywords/options that will provide you means to adjust your analysis as fine grained as you wish.\n\nOne main concept includes the `globalConfig.json`. You can see this as meta-config. Each configuration ID (configID) is a separately conducted analysis. Per configID you state individually the configuration files you want to use for this exact analysis. Herewith you can mix and match any combination of subconfigs you prefer.\n\n\n
\n\nA `globalConfig.json` could look like this:\n\n```json\n{\n \"configID1\": {\n \"addressSpacesPath\": \"addressSpaces.json\",\n \"sectionsPath\": \"sections.json\",\n \"patternsPath\": \"patterns.json\"\n }\n}\n```\n\n\n## Full documentation\nFor the full documentation please refer to the `./doc/` directory.\n\n\n## Contribute\nWe are glad if you want to participate. In `./doc/dev-guide.md` you will find a guide telling you everything you need to know including coding conventions and more.\n\n## [Mailing List](https://groups.google.com/forum/#!forum/emma-dev)\n\n```text\nemma-dev (. at) googlegroups.com\n```\n\n\n## Dependencies & Licences\n\n| Library (version) | pip package name | Licence | URL |\n|----------------------|-----------------------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Markdown (v3.0.1+) | [Markdown](https://pypi.org/project/Markdown/) | BSD-3-Clause | [https://github.com/Python-Markdown/markdown](https://github.com/Python-Markdown/markdown); [https://python-markdown.github.io/](https://python-markdown.github.io/) |\n| Pandas (v0.23.4+) | [pandas](https://pypi.org/project/pandas/) | BSD-3-Clause | [https://github.com/pandas-dev/pandas/](https://github.com/pandas-dev/pandas/); [http://pandas.pydata.org/getpandas.html](http://pandas.pydata.org/getpandas.html) |\n| Pygments (v2.3.1+) | [Pygments](https://pypi.org/project/Pygments/) | BSD-2-Clause | [https://bitbucket.org/birkenfeld/pygments-main/src/default/](https://bitbucket.org/birkenfeld/pygments-main/src/default/); [http://pygments.org/download/](http://pygments.org/download/) |\n| Matplotlib (v3.0.0+) | [matplotlib](https://pypi.org/project/matplotlib/) | Matplotlib License (BSD compatible) | [https://matplotlib.org/users/installing.html](https://matplotlib.org/users/installing.html); [https://github.com/matplotlib/matplotlib](https://github.com/matplotlib/matplotlib) |\n| SCout (v1.8+) | [pypiscout](https://pypi.org/project/pypiscout/) | MIT | [https://github.com/holzkohlengrill/SCout](https://github.com/holzkohlengrill/SCout) |\n\n\n**Dependencies needed to generate documentation:**\n\nUtility scripts in `./doc/` need additional dependencies. As a normal user you can ignore this.\n\n| Library (version) | pip package name | Licence | URL |\n|--------------------------|-----------------------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|\n| gprof2dot (v2017.9.19+) | [gprof2dot](https://pypi.org/project/gprof2dot/) | LGPL-3.0 | [https://github.com/jrfonseca/gprof2dot](https://github.com/jrfonseca/gprof2dot) |\n| pylint (v2.3.1+) | [pylint](https://pypi.org/project/pylint/) | GPL-2.0 | [https://github.com/PyCQA/pylint](https://github.com/PyCQA/pylint) |\n\nPlease refer to the [gprof2dot project site](https://github.com/jrfonseca/gprof2dot) and install **its dependencies (this has to be done even if you install Emma via pip)**.\n\nNote that those modules are invoked via subprocess calls within the ./genDoc/ scripts.\n\n**Dependencies used for documentation on GitHub pages (separate, independent branch `gh-pages`):**\n\nUtility scripts used to build GitHub pages documentation. As a normal user you can ignore this.\n\n| Library (version) | pip package name | Licence | URL |\n|-------------------------------|-------------------------------------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|\n| MkDocs (v1.0.4+) | [mkdocs](https://pypi.org/project/mkdocs/) | BSD-3Clause | [https://github.com/mkdocs/mkdocs](https://github.com/mkdocs/mkdocs) |\n| Material for MkDocs (v4.4.1+) | [mkdocs-material](https://pypi.org/project/mkdocs-material/) | MIT | [https://github.com/squidfunk/mkdocs-material](https://github.com/squidfunk/mkdocs-material) |\n\n\n\n**Code snippets etc.:**\n\n| Name (version) | Kind | Modified? | Licence | URL |\n|-------------------------------------|---------------------------------------------------------------|---------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| pygmentize (v2.2.0+) | Auto-generated .css file | Yes | BSD-2-Clause | [http://pygments.org/download/](http://pygments.org/download/); [https://bitbucket.org/birkenfeld/pygments-main/issues/1496/question-licence-of-auto-generated-css](https://bitbucket.org/birkenfeld/pygments-main/issues/1496/question-licence-of-auto-generated-css) |\n| toHumanReadable (--) | Code snippet | No | MIT | [https://github.com/TeamFlowerPower/kb/wiki/humanReadable](https://github.com/TeamFlowerPower/kb/wiki/humanReadable) |\n\nFor the full documentation please refer to the `./doc/` directory.\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/bmwcarit/Emma", "keywords": "memory-analysis,mapfile,memory-analyzer,embedded,ghs,gcc,mcu,linker,visualization,reports,csv,python,categorisation,memory-consumption,mapfile-analyser", "license": "GPLv3+", "maintainer": "The Emma Authors", "maintainer_email": "emma-dev@googlegroups.com", "name": "pypiemma", "package_url": "https://pypi.org/project/pypiemma/", "platform": "", "project_url": "https://pypi.org/project/pypiemma/", "project_urls": { "Homepage": "https://github.com/bmwcarit/Emma" }, "release_url": "https://pypi.org/project/pypiemma/3.1.1/", "requires_dist": [ "Pygments", "Markdown", "matplotlib", "pandas", "pypiscout (>=2.0)", "graphviz", "gprof2dot ; extra == 'dev'", "pylint ; extra == 'dev'", "mkdocs ; extra == 'dev'", "mkdocs-material ; extra == 'dev'" ], "requires_python": ">=3.6", "summary": "Emma Memory and Mapfile Analyser (Emma) | Conduct static (i.e. worst case) memory consumption analyses based on arbitrary linker map files. It produces extensive .csv files which are easy to filter and post-process. Optionally .html and markdown reports as well as neat figures help you visualising your results.", "version": "3.1.1" }, "last_serial": 5855324, "releases": { "3.1": [ { "comment_text": "", "digests": { "md5": "5f5540f3fff88fed2bf311a51e242960", "sha256": "a35cab67443b55c7116a028aa022a1920c456f2bf981d1fd71ff44352f7aeccc" }, "downloads": -1, "filename": "pypiemma-3.1-py3-none-any.whl", "has_sig": false, "md5_digest": "5f5540f3fff88fed2bf311a51e242960", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 126666, "upload_time": "2019-09-18T16:33:32", "url": "https://files.pythonhosted.org/packages/06/a4/72e9d97577b0e3fdd21e6f24c5b4c3f5733701811cc8cf073a71ef09cede/pypiemma-3.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "24eefe1016370bbda383892c433ca497", "sha256": "6c0f8f1257991029387ca101c8fc68d6d25ec6eba395945c07aa70e5bdb825f9" }, "downloads": -1, "filename": "pypiemma-3.1.tar.gz", "has_sig": false, "md5_digest": "24eefe1016370bbda383892c433ca497", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 78978, "upload_time": "2019-09-18T16:33:34", "url": "https://files.pythonhosted.org/packages/c1/5e/3660e241e36b2760921a131536c54042c472c01f8fefd9549384141eefd3/pypiemma-3.1.tar.gz" } ], "3.1.1": [ { "comment_text": "", "digests": { "md5": "41b3722b730637e3ba393ab64f503c9c", "sha256": "75da4afe66fbc4c19a8f2ebe1faefc44fabe1238f408fd78e97ec22c325309d1" }, "downloads": -1, "filename": "pypiemma-3.1.1-py3-none-any.whl", "has_sig": false, "md5_digest": "41b3722b730637e3ba393ab64f503c9c", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 127200, "upload_time": "2019-09-19T10:03:38", "url": "https://files.pythonhosted.org/packages/1d/c7/140c2d4a347fdc1328f480534b5736650b6754840cf2c84709bf0765f059/pypiemma-3.1.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "6640bc8f6dde8c1b4b3da9b037364d9c", "sha256": "3cc5e5d46f1b4aba3b628203f64520b044f555f3e49b304475922e66bdd1ed7e" }, "downloads": -1, "filename": "pypiemma-3.1.1.tar.gz", "has_sig": false, "md5_digest": "6640bc8f6dde8c1b4b3da9b037364d9c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 78984, "upload_time": "2019-09-19T10:03:40", "url": "https://files.pythonhosted.org/packages/10/17/a94d2d5266614914499b6f5fb29c9636e002b86673ab57dfc22c62c7eff3/pypiemma-3.1.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "41b3722b730637e3ba393ab64f503c9c", "sha256": "75da4afe66fbc4c19a8f2ebe1faefc44fabe1238f408fd78e97ec22c325309d1" }, "downloads": -1, "filename": "pypiemma-3.1.1-py3-none-any.whl", "has_sig": false, "md5_digest": "41b3722b730637e3ba393ab64f503c9c", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.6", "size": 127200, "upload_time": "2019-09-19T10:03:38", "url": "https://files.pythonhosted.org/packages/1d/c7/140c2d4a347fdc1328f480534b5736650b6754840cf2c84709bf0765f059/pypiemma-3.1.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "6640bc8f6dde8c1b4b3da9b037364d9c", "sha256": "3cc5e5d46f1b4aba3b628203f64520b044f555f3e49b304475922e66bdd1ed7e" }, "downloads": -1, "filename": "pypiemma-3.1.1.tar.gz", "has_sig": false, "md5_digest": "6640bc8f6dde8c1b4b3da9b037364d9c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.6", "size": 78984, "upload_time": "2019-09-19T10:03:40", "url": "https://files.pythonhosted.org/packages/10/17/a94d2d5266614914499b6f5fb29c9636e002b86673ab57dfc22c62c7eff3/pypiemma-3.1.1.tar.gz" } ] }