Package: pypiemma
EmmaEmma Memory and Mapfile Analyser (Emma)Conduct static (i.e. worst case) memory consumption analyses based on arbitrary linker map files. It produces extensive.csvfiles which are easy to filter and post-process. Optionally.htmland markdown reports as well as neat figures help you visualising your results.Given amap file input(Green Hills map files are the default but others - like GCC - are supported via configuration options; examples are enclosed) Emmamaps 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 ofvirtual memoryobjects and sections lying within virtual address spaces (VASes) gettranslated back into physical memory. This is depicted in the figure above (lower part).Categorisationcan 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 afiner 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.As a result you will getoutputfiles in form of a.csvfilewhich sets you up to do later processing on this data easily. In this fileadditional information is addedlike:Overlaps (of sections/objects)Containments (e.g. sections containing objects)DuplicatesAll meta data about the origin of each section/object (mapfile, addess space, ...)...Holding the aforementionedaugmented datamakes it easy todetect issues in linker scriptsand get anin-depth understanding ofyour program'smemory consumption. Including a lot of additional and "corrected" data can cause confusion. Thus all original (unmodified) data is preserved in the output files simultaneously.The Emma visualiser helps you to create nice plots and reports in a.pngand.htmland markdown file format.The whole Emma tool suite contains command line options making it convenient to berun on a build serverlike--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).Installationpip3installpypiemmaDependencies: Python 3.6 or higher;pip3 install Pygments Markdown matplotlib pandas pypiscoutOptional: CythonFor bigger projects escpecially the number of objects will grow. We provide an optional Cython implementation which can speed-up your analysis (you will gain typically about **30 % speed-up**).For now we do not provide the binaries with Emma, hence you have to compile (make sure a suitable compiler is installed) it yourself (don't worry it is quick and easy):Install theCythonpackage (pip install Cython) and (in the Emma top level folder) execute (MSVC is recommended on Windows):python setup.py build_ext --inplace --compiler=msvcGeneral WorkflowThe following figure shows a possible workflow using Emma:Emma- as the core component - produces an intermediate.csvfile. Inputs are mapfiles and JSON files (for configuration (memory layout, sizes, ...)). From this point you are very flexible to choose your own pipeline. You coulduse the Emma tools (Emma Visualiser,Emma Deltas, ...) forfurther processing (data aggregation and analysis),simply your favourite spreadsheet software (like Microsoft Excel or LibreOffice Calc) oruse your own tool for the data analysis.Quick Start GuideAt 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)and use our example projects in./doc/test_project*.if the Emmaproject 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 presentoryoustartyour analysisfrom scratchand need to do configure Emma before you use it then go to-> Project files have to be created.Example projects (including Emma* outputs/results) can be found in./doc/test_project*.Since version 3.1Emma can be called in two ways (if you want to run it from the installation folder) where the following variant is recommended:pythonEmma.pya--projectdoc/test_project--mapfilesdoc/test_project/mapfiles--nopromptThe following table provides an overview how you call Emma:Emma moduleEntry point + <options> (if installed viapip)Top level sub-command (tlsc) (python Emma.py<tlsc>)Module (python -m+ <module> <options>)AnalyseremmaaEmma.emmaVisualiseremma_visvEmma.emma_visDeltasemma_deltasdEmma.emma_deltasProject files are already presentTrypython Emma.py a --helpto see all possible options or refer to the documentation (./doc/*).Create intermediate.csvfrom mapfiles with Emma:pythonEmma.pya-p.\MyProjectFolder--map.\MyProjectFolder\mapfiles--dir.\MyProjectFolder\analysis--subdirAnalysis_1Generate reports and graphs with Emma Visualiser:pythonEmma.pyv-p.\MyProjectFolder--dir.\MyProjectFolder\analysis--subdirAnalysis_1-qProject files that have to be createdTo create a new project, the following files must be created:globalConfig.jsonbudgets.jsoncategories.jsoncategoriesKeywords.jsoncategoriesSections.jsoncategoriesSectionsKeywords.jsonYou will find example projects in./doc/test_project*. In-depth documentation can be found in the full documentation (see./doc/).A 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.One main concept includes theglobalConfig.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.AglobalConfig.jsoncould look like this:{"configID1":{"addressSpacesPath":"addressSpaces.json","sectionsPath":"sections.json","patternsPath":"patterns.json"}}Full documentationFor the full documentation please refer to the./doc/directory.ContributeWe are glad if you want to participate. In./doc/dev-guide.mdyou will find a guide telling you everything you need to know including coding conventions and more.Mailing Listemma-dev (. at) googlegroups.comDependencies & LicencesLibrary (version)pip package nameLicenceURLMarkdown (v3.0.1+)MarkdownBSD-3-Clausehttps://github.com/Python-Markdown/markdown;https://python-markdown.github.io/Pandas (v0.23.4+)pandasBSD-3-Clausehttps://github.com/pandas-dev/pandas/;http://pandas.pydata.org/getpandas.htmlPygments (v2.3.1+)PygmentsBSD-2-Clausehttps://bitbucket.org/birkenfeld/pygments-main/src/default/;http://pygments.org/download/Matplotlib (v3.0.0+)matplotlibMatplotlib License (BSD compatible)https://matplotlib.org/users/installing.html;https://github.com/matplotlib/matplotlibSCout (v2.0+)pypiscoutMIThttps://github.com/holzkohlengrill/SCoutsvgwrite (v1.4+)svgwriteMIT License (MIT License)https://github.com/mozman/svgwrite;https://svgwrite.readthedocs.io/en/latest/Optional dependencies:Utility scripts in./doc/need additional dependencies. As a normal user you can ignore this.Library (version)pip package nameLicenceURLgprof2dot (v2017.9.19+)gprof2dotLGPL-3.0https://github.com/jrfonseca/gprof2dotpylint (v2.3.1+)pylintGPL-2.0https://github.com/PyCQA/pylintCython (v0.29.13+)CythonApache-2.0https://cython.org/Please refer to thegprof2dot project siteand installits dependencies (this has to be done even if you install Emma via pip).Note that those modules are invoked via subprocess calls within the ./genDoc/ scripts.Dependencies used to generate documentation for GitHub pages (separate, independent branchgh-pages):Utility scripts used to build GitHub pages documentation. As a normal user you can ignore this.Library (version)pip package nameLicenceURLMkDocs (v1.0.4+)mkdocsBSD-3Clausehttps://github.com/mkdocs/mkdocsMaterial for MkDocs (v4.4.1+)mkdocs-materialMIThttps://github.com/squidfunk/mkdocs-materialCode snippets etc.:Name (version)KindModified?LicenceURLpygmentize (v2.2.0+)Auto-generated .css fileYesBSD-2-Clausehttp://pygments.org/download/;https://bitbucket.org/birkenfeld/pygments-main/issues/1496/question-licence-of-auto-generated-csstoHumanReadable (--)Code snippetNoMIThttps://github.com/TeamFlowerPower/kb/wiki/humanReadableFor the full documentation please refer to the./doc/directory.