Gitiles
Code Review Sign In
gerrit.osmocom.org / simtrace2 / d5f583da60ab9b589b3ec2c73c28642c27d58130 / . / firmware / README.txt
blob: dcbafb29ac2a57f69d575f1f709deab3f5ca8018 [file] [log] [blame]
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]1This is the source code for SIMtrace 2 firmwares.
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]2
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]3= Hardware
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]4
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]5== Micro-Controller
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]6
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]7The firmware is for Microchip (formerly Atmel) ATSAM3S4B micro-controllers (MCU).
8Product page: https://www.microchip.com/wwwproducts/en/ATSAM3S4B
9Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6500-32-bit-Cortex-M3-Microcontroller-SAM3S4-SAM3S2-SAM3S1_Datasheet.pdf
10
11Note: The SAM3S is now not recommended for new designs.
12It can be replaced by the pin-compatible SAM4S.
13The MCU can be specified using the environment variable `CHIP` (set to `sam3s4` per default) for future MCU support.
14
15== Boards
16
17The SIMtrace 2 firmware supports multiple boards.
18A board defines a given circuit board.
19While compiling the firmware, set the target board using the `BOARD` environment variable (set to `qmod` per default).
20The supported boards correspond to sub-folders under `libboard`.
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]21
22Current boards supported are:
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]23
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]24* `simtrace`: The good old Osmocom SIMtrace PCB with SAM3 instead of SAM7, open hardware.
25* `qmod`: A sysmocom-proprietary quad mPCIe carrier board, publicly available
26* `owhw`: An undisclosed sysmocom-internal board, not publicly available
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]27
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]28= Firmware
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]29
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]30== Library
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]31
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]32The firmware uses the manufacturer provided Software Package (SoftPack) micro-controller library.
33The original library is available at https://www.microchip.com/design-centers/32-bit/softpacks/legacy-softpacks .
34Version 2.1 from 2001 is used: http://ww1.microchip.com/downloads/en/DeviceDoc/SAM3S_softpack_2.1_for_CodeSourcery_2010q1.zip
35The SIMtrace 2 project uses the `libboard_sam3s-ek`, `libchip_sam3s`, and `usb` sub-libraries, saved in `atmel_softpack_libraries` (with local modifications).
36
37Note: SoftPack is the legacy micro-controller library.
38This library is now replaced by the Advanced Software Framework (ASF): https://www.microchip.com/avr-support/advanced-software-framework-(asf) .
39The SAM3S ASF documentation is available at http://asf.atmel.com/docs/latest/sam3s/html/index.html .
40
41== Applications
42
43An application is a specific piece of software with given functionality.
44While compiling the firmware, set the target application using the `APP` environment variable (set to `dfu` per default).
45The supported applications correspond to sub-folder under `apps`.
46
47Current applications supported are:
48
49* `dfu`: The USB DFU bootloader to flash further main appliction firmwares.
50* `ccid`: To use SIMtrace 2 as USB CCID smartcard reader.
51* `cardem`: To provide remote SIM operation capabilities.
52* `trace`: To monitor the communication between a SIM card and a phone (corresponds to the functionality provide by the first SIMtrace)
53* `triple_play`: To support the three previous functionalities, using USB configurations.
54
55== Memories
56
57Firmwares can be run from several memory locations:
58
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]59* flash: Run natively from start of flash memory
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]60* dfu: Run after a DFU bootloader from an offset after the first 16k of flash (the first 16k are reserved for the bootloader)
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]61* ram: Run from within the RAM of the chip, downloaded via JTAG/SWD
62
Harald Welted8a003d2017-02-27 20:31:09 +0100[diff] [blame]63== Building
64
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]65A given firmware build is made for a specific combination of an application `APP` running in a certain memory `MEM` on a given board `BOARD`.
66When building using `make`, set the target application using the `APP` environment variable and target board using the `BOARD` environment variable, e.g.:
Harald Welte601e0d32017-03-08 15:33:33 +0100[diff] [blame]67
Harald Welte601e0d32017-03-08 15:33:33 +0100[diff] [blame]68* make APP=cardem BOARD=qmod
69* make APP=dfu BOARD=qmod
70
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]71The Makefile will create output files in the format: `bin/$(BOARD)-$(APP)-$(MEM).{elf,bin}`
72
Harald Welte601e0d32017-03-08 15:33:33 +0100[diff] [blame]73The level of debug messages can be altered at compile time:
74```
75$ make TRACE_LEVEL=4
76```
77Accepted values: 0 (NO_TRACE) to 5 (DEBUG)
78
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]79= Flashing
Harald Welte601e0d32017-03-08 15:33:33 +0100[diff] [blame]80
Kévin Redon0828b912018-05-21 19:35:56 +0200[diff] [blame]81To flash a firmware image follow the instructions provided in the [wiki](https://projects.osmocom.org/projects/simtrace2/wiki/).