Oliver Smith e6e77399d6 firmware/Makefile: don't use distribution's CFLAGS
Set CFLAGS on top of the Makefile, to avoid using the distribution's
default CFLAGS. In debian testing and unstable, -fcf-protection was
recently added to the default CFLAGS, but it cannot be used with the
cross compiler:

  [COMPILING libosmocore/source/backtrace.c]
  cc1: error: '-fcf-protection=full' is not supported for this target
  make[2]: *** [Makefile:270: obj/simtrace/flash_backtrace.o] Error 1

Change-Id: I5f7cd0402f9bb85dd600204fdf8855773ddbeb70
2023-09-13 15:33:48 +00:00
apps main: rotor: erase immediately after send 2022-11-13 22:07:48 -05:00
atmel_softpack_libraries Cosmetic: fix CI errors 2023-04-25 17:53:11 +02:00
libboard cardem: set more reasonable interrupt priorities 2022-02-21 23:24:20 +01:00
libcommon Cosmetic: fix CI errors 2023-04-25 17:53:11 +02:00
libosmocore treewide: remove FSF address 2021-12-14 11:47:21 +01:00
misc firmware: add crc stub to all dfu apps to ensure reliable loading 2021-12-15 14:04:20 +00:00
openocd Renamed main folder to firmware 2015-04-07 18:24:06 +02:00
test assert: Use printf_sync() to ensure printing of assert / panic 2021-06-02 09:12:35 +02:00
usbstring treewide: remove FSF address 2021-12-14 11:47:21 +01:00
Makefile firmware/Makefile: don't use distribution's CFLAGS 2023-09-13 15:33:48 +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](