documentation update

Merge branch 'master' of git.soton.ac.uk:dwf1m12/soclabs-cortexm0-mcu

GetStarted.md

 # Example soclabs Arm-Cortex-M0-based microcontroller project
 
 
-Recommended directory structure
+## Recommended directory structure
 
 A good starting point for a template for building a Cortex-M based microntroller is to use the AAA components:
 
 Create a directory of (Read-only) Arm IP bundles from Product Download Hub, logged in with AAA credentials:
 
-Download Corstone-101:
+Download Corstone-101 system, Cortex-M0 CPU and PL230 Micro-DMA IP:
+
+```
   https://developer.arm.com/downloads/view/BP306-GRP
-Download Cortex-M0 CPU:
   https://developer.arm.com/downloads/view/AT510-GRP
-Download Micro-DMA PL230:
   https://developer.arm.com/downloads/view/PL230-GRP
+```
 
-and in each case
+and in each case decompress and unpack the IP deleivery trees:
+
+```
   gunzip the <bundle>.tar.gz
   gtar xfv <bundle>.tar
+```
 
 The project is structured to work alongside IP provided under the Arm Acacdemic Access enttilements.
 
@@ -34,21 +38,28 @@ soclabs-cortexm0-mcu
 
 The Arm documentation can be referenced from the download trees:
 
-Cortex-M0 release note, and reference manuals:
-'''
+Cortex-M0 release note and reference manuals:
+
+```
    arm-AAA-ip/Cortex-M0/*.pdf
    arm-AAA-ip/Cortex-M0/AT510-BU-00000-r0p0-03rel3/doc/*.pdf
-'''   
-Corstone-101 release notes, and reference manuals:
-'''
+```
+
+
+Corstone-101 release notes and reference manuals:
+
+```
    arm-AAA-ip/Corstone-101_Foundation_IP/*.pdf
    arm-AAA-ip/Corstone-101_Foundation_IP/BP210-BU-00000-r1p1-00rel0/documentation/*.pdf
-'''   
-PL230 MicroDMA release notes, and reference manuals:
-'''
+```
+
+ 
+PL230 MicroDMA release notes and reference manuals:
+
+```
    arm-AAA-ip/DMA-230_MicroDMA_Controller/*.pdf
    arm-AAA-ip/DMA-230_MicroDMA_Controller/PL230-BU-00000-r0p0-02rel1/*.pdf
-'''   
+```
 
 The microcontroller simulation hierarchy is delivered in the '**soclabs-cortexm0-mcu**' directory:
 
@@ -112,12 +123,45 @@ soclabs-cortexm0-mcu
 |   |   |   |-- verilog
 ```
 
-simulation setup (of the form):
+## The simulation environment is run in the **rtl_sim** directory:
+
+`    soclabs-cortexm0-mcu/Cortex-M0/soclabs_demo/systems/cortex_m0_mcu/rtl_sim`
+
+A quick out-of-box test of the installation is:
+
+1. build a test program image to run as a memory image (see .`./tools/setup_ds5_tools.scr` for example of setting up the environment variables to run the Arm DS tools available through AAA)
+2. compile the rtl simulation target using the appropriate makefile target for the isntalled simulator (mti_sim in this example)
+3. run the simulator with the pre-built test code
+
+ ```
+   make code TESTNAME=hello     (or another test from the `../testcodes/` directory)
+   make compile_mti
+   make run_mti TESTNAME=hello
+```
+As well as the simulation transcript the following log files are produced:
+
+```
+   uart2.log   -- ASCII character strings output from 'stdout' on UART2
+   tarmac0.log -- Instruction trace for the Cortex-M0 CPU executing the test code
+   tarmac1.log -- (instruction trace for a Cortex-M0 running the debug tester)
+```
+The directory can be cleaned up after running tests using:
+
+```
+   make clean 
+
 ```
-  export ARM_PRODUCT_PATH=/apps/arm/developmentstudio-2021.0/sw/mappings
-  export ARM_TOOL_VARIANT=gold
-  export PATH=$PATH:/apps/arm/developmentstudio-2021.0/sw/ARMCompiler5.06u7/bin/
+## Getting to understand the microcontroller design:
+
+The design has been documented using a _verilog-to-HTML_ tool; if the `../v2html_doc.tgz` file is decompressed and unpacked an HTML directory is built (`../v2html_doc`) which can then be inspected with a web browser:
+
 ```
+   firefox ../v2html_doc/hierarchy.html &
+   
+```
+This allows the exploration of design hierarchy from the testbench inwards, and cross referencing of design modules and signals.
+
+