README: rewrite to better explain environment variables and point to the wiki for flashing
diff --git a/firmware/README.txt b/firmware/README.txt
index 9e82557..dcbafb2 100644
--- a/firmware/README.txt
+++ b/firmware/README.txt
@@ -1,70 +1,81 @@
+This is the source code for SIMtrace 2 firmwares.
-== BOARDS
+= Hardware
-A board defines a given circuit board, i.e. SIMtrace, OWHW, QMOD
+== Micro-Controller
-It defines the given hardware model for which the program is to be
-compiled.
+The firmware is for Microchip (formerly Atmel) ATSAM3S4B micro-controllers (MCU).
+Product page: https://www.microchip.com/wwwproducts/en/ATSAM3S4B
+Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6500-32-bit-Cortex-M3-Microcontroller-SAM3S4-SAM3S2-SAM3S1_Datasheet.pdf
+
+Note: The SAM3S is now not recommended for new designs.
+It can be replaced by the pin-compatible SAM4S.
+The MCU can be specified using the environment variable `CHIP` (set to `sam3s4` per default) for future MCU support.
+
+== Boards
+
+The SIMtrace 2 firmware supports multiple boards.
+A board defines a given circuit board.
+While compiling the firmware, set the target board using the `BOARD` environment variable (set to `qmod` per default).
+The supported boards correspond to sub-folders under `libboard`.
Current boards supported are:
-* simtrace: The good old Osmocom SIMtrace PCB with SAM3 instead of
- SAM7, open hardware.
-* qmod: A sysmocom-proprietary quad mPCIe carrier board, publicly available
-* owhw: An undisclosed sysmocom-internal board, not publicly available
-== APPLICATIONS
+* `simtrace`: The good old Osmocom SIMtrace PCB with SAM3 instead of SAM7, open hardware.
+* `qmod`: A sysmocom-proprietary quad mPCIe carrier board, publicly available
+* `owhw`: An undisclosed sysmocom-internal board, not publicly available
-An application is a specific piece of software with given
-functionality.
+= Firmware
-== ENVIRONMENTS
+== Library
-An environment is a runtime environment, typically defined by a linker
-script. The current runtime environments include
+The firmware uses the manufacturer provided Software Package (SoftPack) micro-controller library.
+The original library is available at https://www.microchip.com/design-centers/32-bit/softpacks/legacy-softpacks .
+Version 2.1 from 2001 is used: http://ww1.microchip.com/downloads/en/DeviceDoc/SAM3S_softpack_2.1_for_CodeSourcery_2010q1.zip
+The SIMtrace 2 project uses the `libboard_sam3s-ek`, `libchip_sam3s`, and `usb` sub-libraries, saved in `atmel_softpack_libraries` (with local modifications).
+
+Note: SoftPack is the legacy micro-controller library.
+This library is now replaced by the Advanced Software Framework (ASF): https://www.microchip.com/avr-support/advanced-software-framework-(asf) .
+The SAM3S ASF documentation is available at http://asf.atmel.com/docs/latest/sam3s/html/index.html .
+
+== Applications
+
+An application is a specific piece of software with given functionality.
+While compiling the firmware, set the target application using the `APP` environment variable (set to `dfu` per default).
+The supported applications correspond to sub-folder under `apps`.
+
+Current applications supported are:
+
+* `dfu`: The USB DFU bootloader to flash further main appliction firmwares.
+* `ccid`: To use SIMtrace 2 as USB CCID smartcard reader.
+* `cardem`: To provide remote SIM operation capabilities.
+* `trace`: To monitor the communication between a SIM card and a phone (corresponds to the functionality provide by the first SIMtrace)
+* `triple_play`: To support the three previous functionalities, using USB configurations.
+
+== Memories
+
+Firmwares can be run from several memory locations:
+
* flash: Run natively from start of flash memory
-* dfu: Run after a DFU bootloader from an offset after the first 16k
- of flash (the first 16k are reserved for the bootloader)
+* dfu: Run after a DFU bootloader from an offset after the first 16k of flash (the first 16k are reserved for the bootloader)
* ram: Run from within the RAM of the chip, downloaded via JTAG/SWD
-
== Building
-A given software build is made for a specific combination of an APP
-running in a certain ENVIRONMENT on a given BOARD.
+A given firmware build is made for a specific combination of an application `APP` running in a certain memory `MEM` on a given board `BOARD`.
+When building using `make`, set the target application using the `APP` environment variable and target board using the `BOARD` environment variable, e.g.:
-A Makefile is provided. It will create output files in the format
-bin/$(BOARD)-$(APP)-$(ENV).{elf,bin}
-
-You can specify the APP and BOARD to build when calling make, like
-e.g.
* make APP=cardem BOARD=qmod
* make APP=dfu BOARD=qmod
+The Makefile will create output files in the format: `bin/$(BOARD)-$(APP)-$(MEM).{elf,bin}`
+
The level of debug messages can be altered at compile time:
```
$ make TRACE_LEVEL=4
```
Accepted values: 0 (NO_TRACE) to 5 (DEBUG)
-== Flashing
+= Flashing
-For flashing the firmware, there are at least two options.
-
-=== Using JTAG + OpenOCD to flash the DFU bootloader
-
-The first one is using openocd and a JTAG key.
-For this option, a JTAG connector has to be soldered onto the board, which is not attached per default.
-
-```
-$ openocd -f openocd/openocd.cfg -c "init" -c "halt" -c "flash write_bank 0 ./bin/$(BOARD)-dfu-flash.bin 0" -c "reset" -c "shutdown"
-```
-
-=== Using bossac to flash the DFU bootloader
-
-The second option is using rumba for flashing. No further hardware has to be provided for this option.
-
-FIXME
-
-=== Using DFU to flash application
-
-FIXME
+To flash a firmware image follow the instructions provided in the [wiki](https://projects.osmocom.org/projects/simtrace2/wiki/).