Added memap documentation

Author: screamerbg

docs/memap.md

@@ -0,0 +1,119 @@
+## Introduction
+
+*memap* is a simple command line utility useful to display static memory information required by [mbed-OS](https://github.com/ARMmbed/mbed-os) applications. This information is produced by analysing the memory map file previously generated by your toolchain.
+
+Note: this tool is only showing static RAM usage and the total size of allocated heap and stack space, not the actual heap and stack usage.
+
+## Table of Contents
+
+1. [Installation](#installation)
+1. [Using memap](#using-memap)
+1. [Running pytest](#running-pytest)
+1. [Current support](#current-support)
+1. [Known problems](#known-problems)
+
+## Installation
+
+*memap* lives in https://github.com/ARMmbed/memap.
+
+To get the latest version of *memap*, clone the repository and installed it:
+
+```
+git clone https://github.com/ARMmbed/memap
+cd memap
+python setup.py install
+```
+
+## Using memap
+
+*memap* is a simple utility. These are the command line options:
+
+```
+$> memap
+usage: memap-script.py [-h] -t TOOLCHAIN [-o OUTPUT] [-j] [-v] file
+
+Memory Map File Analyser for ARM mbed OS version 0.3.2
+
+positional arguments:
+  file                  memory map file
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -t TOOLCHAIN, --toolchain TOOLCHAIN
+                        select a toolchain that corresponds to the memory map
+                        file (ARM, GCC_ARM, IAR)
+  -o OUTPUT, --output OUTPUT
+                        output file name
+  -j, --json            output in JSON formatted list
+  -v, --version         show program's version number and exit
+```
+
+Example:
+
+```
+$> memap GCC_ARM\myprog3.map -t GCC_ARM
+
++-----------------------------------+-------+-------+------+
+| Module                            | .text | .data | .bss |
++-----------------------------------+-------+-------+------+
+| Misc                              |  248  |   12  |  28  |
+| core/mbed-rtos                    |  5638 |   24  | 2494 |
+| core/util                         |  323  |   0   |  8   |
+| core/uvisor-mbed-lib              |   4   |   0   |  0   |
+| frameworks/greentea-client        |  416  |   28  |  0   |
+| frameworks/utest                  |  3055 |   32  | 688  |
+| hal/common                        |  2453 |   4   | 272  |
+| hal/targets                       |  9796 |   0   | 672  |
+| net/LWIPInterface                 |  172  |   4   | 272  |
+| net/atmel-rf-driver               |  332  |   8   | 212  |
+| net/mbed-client                   |   64  |   4   |  12  |
+| net/nanostack-hal-mbed-cmsis-rtos |  100  |   4   |  56  |
+| net/nanostack-interface           |   40  |   4   |  16  |
+| Subtotals                         | 22641 |  124  | 4730 |
++-----------------------------------+-------+-------+------+
+Static RAM memory (data + bss): 4854
+Heap: 131072
+Stack: 3072
+Total RAM memory (data + bss + heap + stack): 138998
+Total Flash memory (text + data): 22765
+Elapsed time: 55mS
+```
+
+Information on memory sections:
+
+- text: is where the code application and constants are located in Flash
+- data: initialized variables, allocated in both RAM and Flash memory
+- bss: uninitialized data allocated in RAM
+- heap: dynamic allocated memory, usually used by malloc, etc, in RAM
+- stack: used to store local data, temporary data when branching to a subroutine and context switch info; considered dynamic allocated memory region in RAM.
+
+
+## Running pytest
+
+- Run automated tests, for example:
+
+```
+$> py.test
+============================= test session starts =============================
+platform win32 -- Python 2.7.11, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+rootdir: ...\memap, inifile:
+collected 3 items
+
+test\test_memap.py ...
+
+========================== 3 passed in 0.11 seconds ===========================
+
+```
+
+## Current support
+
+*memap* has been tested on Windows 7.
+
+Supported map files generated by the following toolchains: gcc, ARM Compiler 5 and IAR.
+
+## Known problems & New features
+
+This utility is considered 'Alpha' quality at the moment.
+The report generated may not be accurate and may vary from one toolchain to another.
+
+If you are seeing problems or would like new features to be added then please raise a ticket on [GitHub](https://github.com/ARMmbed/memap/issues).