Harald Welte 4d2ff9a173 assert: Use printf_sync() to ensure printing of assert / panic
Change-Id: Icc202e60445d9be1cdcd61176db5ed1704d583e7
2021-04-06 02:17:39 +02:00
apps card_emu: Use USART timeout for waiting time 2021-04-06 02:17:39 +02:00
atmel_softpack_libraries dfu: let the device reset itself 2021-01-29 11:02:27 +00:00
libboard make sim switch board specific 2021-04-06 02:17:39 +02:00
libcommon assert: Use printf_sync() to ensure printing of assert / panic 2021-04-06 02:17:39 +02:00
libosmocore assert: Use printf_sync() to ensure printing of assert / panic 2021-04-06 02:17:39 +02:00
openocd Renamed main folder to firmware 2015-04-07 18:24:06 +02:00
test usb_buf: count number of elements in queue 2019-12-14 21:50:59 +01:00
usbstring add missing usbstring.c 2017-03-07 15:51:49 +01:00
Makefile firmware: allow verbose builds 2021-04-04 16:16:24 +00:00
README.txt add new board and app for gpio testing on octsimtest board 2019-07-30 10:56:51 +02:00
TODO.txt Add firmware/TODO.txt that was not committed so far 2018-05-11 15:49:31 +02:00


This is the source code for SIMtrace 2 firmwares.

= Hardware

== Micro-Controller

The firmware is for Microchip (formerly Atmel) ATSAM3S4B micro-controllers (MCU).
Product page:

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
* `octsimtest`: A sysmocom-proprietary production testing board, not publicly available

= Firmware

== Library

The firmware uses the manufacturer provided Software Package (SoftPack) micro-controller library.
The original library is available at .
Version 2.1 from 2001 is used:
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): .
The SAM3S ASF documentation is available at .

== 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.
* `gpio_test`: internal test code

== 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)
* ram: Run from within the RAM of the chip, downloaded via JTAG/SWD

== Building

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.:

* 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)

The qmod specific option `ALLOW_PEER_ERASE` controls if the UART debug command to assert the peer SAM3S ERASE line is present in the code.
Per default this is set to 0 to prevent accidentally erasing all firmware, including the DFU bootloader, which would then need to be flashed using SAM-BA or JTAG/SWD.
Setting `ALLOW_PEER_ERASE` to 1 enables back the debug command and should be used only for debugging or development purposes.

= Flashing

To flash a firmware image follow the instructions provided in the [wiki](