diff --git a/README.md b/README.md
index 8a13f31d988eaf2d269547e969ed157ebc29b81f..72aaf0331af17244138b80f5c315e7721f56bebb 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,87 @@
 # Cortex-M0-baseline
+# Example soclabs Arm-Cortex-M0-based microcontroller project
+
+The project is structured to work alongside IP provided under the Arm Acacdemic Access enttilements.
+
+Provide a soft-link to the downloaded and configured IP in a directory '**arm-ip-configured**':
+
+```
+arm-ip-configured --> link to Arm directory trees
+|-- AT514-BU-98000-r0p1-00rel0
+|-- AT555-BU-98000-r1p1-00eac0
+```
+
+The microcontroller simulation hierarchy is delivered in the '**soclabs-cortexm0-mcu**' directory:
+
+```
+soclabs-cortexm0-mcu
+|-- Cortex-M0
+|   |-- soclabs_demo
+|   |   software
+|   |   |   cmsis
+|   |   |   |-- CMSIS
+|   |   |   |   |-- Include
+|   |   |   |-- Device
+|   |   |   |   |-- ARM
+|   |   |   |   |   |-- CMSDK_CM0
+|   |   |   |   |   |   |-- Include
+|   |   |   |   |   |   |   |-- Source
+|   |   |   |   |   |   |   |--  ARM
+|   |   |   |   |   |   |   |--  GCC
+|   |   |   common
+|   |   |   |-- bootloader
+|   |   |   |-- debug_tests
+|   |   |   |-- demos
+|   |   |   |-- dhry
+|   |   |   |-- retarget
+|   |   |   |-- romtable_tests
+|   |   |   |-- scripts
+|   |   |   |-- validation
+|   |   |   debug_tester
+|   |   systems
+|   |   |-- cortx_m0_cpu
+|   |   |   |-- rtl_sim
+|   |   |   |   testcodes
+|   |   |   |   |-- apb_mux_tests
+|   |   |   |   |-- bitband_tests
+|   |   |   |   |-- bootloader
+|   |   |   |   |-- debug_tests
+|   |   |   |   |-- default_slaves_tests
+|   |   |   |   |-- dhry
+|   |   |   |   |-- dma_tests
+|   |   |   |   |-- dualtimer_demo
+|   |   |   |   |-- generic
+|   |   |   |   |-- gpio_driver_tests
+|   |   |   |   |-- gpo_tests
+|   |   |   |   |-- hello
+|   |   |   |   |-- interrupt_demo
+|   |   |   |   |-- memory_tests
+|   |   |   |   |-- mpu_tests
+|   |   |   |   |-- mtb_tests
+|   |   |   |   |-- romtable_tests
+|   |   |   |   |-- rtx_demo
+|   |   |   |   |-- self_reset_demo
+|   |   |   |   |-- sleep_demo
+|   |   |   |   |-- timer_driver_tests
+|   |   |   |   |-- timer_tests
+|   |   |   |   |-- uart_driver_tests
+|   |   |   |   |-- uart_tests
+|   |   |   |   |-- user_tests
+|   |   |   |   |-- vtor_tests
+|   |   |   |-- tools
+|   |   |   |-- v2html_doc
+|   |   |   |-- verilog
+```
+
+simulation setup (of the form):
+```
+  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/
+```
+
+
+