simtrace2

History

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

README.txt

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: 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
* `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 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.
* `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](https://projects.osmocom.org/projects/simtrace2/wiki/).