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