added README.adoc

README.adoc

+= About
+
+The following guide describes the steps to build and run the mbed applications
+targeting the XMC 4500 Relax Kit board from Infineon.
+
+The `mbed-os` folder contains the MBED platform with various drivers for the
+XMC platform. At the moment this is kept in a separate repository from the
+main mbed project hosted on github at https://github.com/mbed-Infineon-XMC/mbed-os[https://github.com/mbed-Infineon-XMC/mbed-os].
+
+The example applications are obtained from https://github.com/mbed-Infineon-XMC?tab=repositories[https://github.com/mbed-Infineon-XMC?tab=repositories] and are 
+structured in folders named like `APP_XXX`.
+
+== Import the project
+
+[source%nowrap, bash]
+----
+$ git clone https://es.technikum-wien.at/bel/bel4_ezb_public.git
+$ cd XMC_MBED/
+----
+
+= Step-by-Step Building/Flashing/Debugging
+
+== Compile a project
+
+Navigate into the project folder and build it using:
+
+[source%nowrap, bash]
+----
+cd APP_BB_BLINKY/
+mbed compile -m XMC_4500_RELAX_KIT -t GCC_ARM -N main
+----
+
+mbed creates a BUILD directory where you can find the executable (`*.bin`, `*.elf`, `*.hex` ...).
+
+[NOTE]
+When using MS-Windows delete the existing Unix symbolic-link `mbed-os` and 
+replace it with a Windows symbolic link using `mklink /D mbed-os ..\mbed-os`.
+
+== Flash the application to the Relax-Kit
+
+Use the JLink tools to flash the application hexfile to the Relax-Kit.
+
+[source%nowrap, bash]
+----
+$ JLinkExe -device XMC4500-1024 -if SWD -speed 4000 -autoconnect 1
+J-LINK> h
+J-Link> loadfile BUILD/XMC_4500_RELAX_KIT/GCC_ARM/main.hex
+J-Link> r
+J-Link> g
+----
+
+== Debugging
+
+To the debug the application 4 steps in sequence are necessary.
+
+(1) You will need to create the executable with DEBUg symbols. To that end add 
+`--profile mbed-os/tools/profiles/debug.json` to the build command.
+
+[source%nowrap, bash]
+----
+mbed compile -m XMC_4500_RELAX_KIT -t GCC_ARM -N main --profile mbed-os/tools/profiles/debug.json
+----
+
+(2) Start the `JLinkGDEBServer`, e.g.:
+
+[source%nowrap, bash]
+----
+JLinkGDBServer -Device XMC4500-1024 -if SWD
+----
+
+(3) In order to log messages printed to `stdout` we connect to port 2333 via
+telnet.
+
+[source%nowrap, bash]
+----
+telnet 127.0.0.1 2333
+----
+
+(4) We launch the debugger and control the debug session:
+
+[source%nowrap, bash]
+----
+arm-none-eabi-gdb -q BUILD/XMC_4500_RELAX_KIT/GCC_ARM/main.elf
+(gdb) target remote :2331
+(gdb) monitor reset
+(gdb) load
+(gdb) monitor reset
+(gdb) b main
+(gdb) c
+[...]
+----
+
+= Makefile Building/Flashing/Debugging
+
+Using the prepared `Makefile` one can invoke trhe following actions in a more 
+convenient way:
+
+[source%nowrap, bash]
+----
+make          # build the application with debug symbols
+make debug    # -"-
+make release  # debug a release version of the project
+make flash    # flash the application
+make debug    # debug the application
+make erase    # erase the program memory
+make doc      # invoke doxygen
+make clean    # clean the project
+----
+
+