mirror of
https://gitea.osmocom.org/sim-card/simtrace2.git
synced 2026-03-20 07:18:33 +03:00
README: rewrite to better explain environment variables and point to the wiki for flashing
This commit is contained in:
Kévin Redon
@@ -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
|
The firmware is for Microchip (formerly Atmel) ATSAM3S4B micro-controllers (MCU).
|
||||||
compiled.
|
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:
|
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
|
= Firmware
|
||||||
functionality.
|
|
||||||
|
|
||||||
== ENVIRONMENTS
|
== 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.
|
||||||
|
|
||||||
|
== Memories
|
||||||
|
|
||||||
|
Firmwares can be run from several memory locations:
|
||||||
|
|
||||||
An environment is a runtime environment, typically defined by a linker
|
|
||||||
script. The current runtime environments include
|
|
||||||
* flash: Run natively from start of flash memory
|
* flash: Run natively from start of flash memory
|
||||||
* dfu: Run after a DFU bootloader from an offset after the first 16k
|
* dfu: Run after a DFU bootloader from an offset after the first 16k of flash (the first 16k are reserved for the bootloader)
|
||||||
of flash (the first 16k are reserved for the bootloader)
|
|
||||||
* ram: Run from within the RAM of the chip, downloaded via JTAG/SWD
|
* ram: Run from within the RAM of the chip, downloaded via JTAG/SWD
|
||||||
|
|
||||||
|
|
||||||
== Building
|
== Building
|
||||||
|
|
||||||
A given software build is made for a specific combination of an APP
|
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`.
|
||||||
running in a certain ENVIRONMENT on a given 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=cardem BOARD=qmod
|
||||||
* make APP=dfu 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:
|
The level of debug messages can be altered at compile time:
|
||||||
```
|
```
|
||||||
$ make TRACE_LEVEL=4
|
$ make TRACE_LEVEL=4
|
||||||
```
|
```
|
||||||
Accepted values: 0 (NO_TRACE) to 5 (DEBUG)
|
Accepted values: 0 (NO_TRACE) to 5 (DEBUG)
|
||||||
|
|
||||||
== Flashing
|
= Flashing
|
||||||
|
|
||||||
For flashing the firmware, there are at least two options.
|
To flash a firmware image follow the instructions provided in the [wiki](https://projects.osmocom.org/projects/simtrace2/wiki/).
|
||||||
|
|
||||||
=== 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user