From 7eb0b4d689604ee943277b9b3531a8ac3b30ae60 Mon Sep 17 00:00:00 2001 From: kopecdav Date: Thu, 12 Dec 2024 14:21:05 +0100 Subject: [PATCH] docs(core) Update embedded build instraction, add DISC2 and TrustZone section --- docs/SUMMARY.md | 2 ++ docs/core/build/embedded.md | 40 +++++++++++++++++++++---------------- docs/core/misc/disc2.md | 29 +++++++++++++++++++++++++++ docs/core/misc/trustzone.md | 26 ++++++++++++++++++++++++ 4 files changed, 80 insertions(+), 17 deletions(-) create mode 100644 docs/core/misc/disc2.md create mode 100644 docs/core/misc/trustzone.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 9e2f77059c4..3912d480033 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -16,9 +16,11 @@ - [Boot stages](core/misc/boot.md) - [Code style](core/misc/codestyle.md) - [DISC1](core/misc/disc1.md) + - [DISC2](core/misc/disc2.md) - [Exceptions usage](core/misc/exceptions.md) - [Memory fragmentation management](core/misc/fragmentation.md) - [Memory layout](core/misc/memory.md) + - [TrustZone](core/misc/trustzone.md) - [SLIP-39](core/misc/slip0039.md) - [Translation data format](core/misc/translations.md) - [UI Layout lifecycle](core/misc/layout-lifecycle.md) diff --git a/docs/core/build/embedded.md b/docs/core/build/embedded.md index 5eb9a877fae..3003b1d30b9 100644 --- a/docs/core/build/embedded.md +++ b/docs/core/build/embedded.md @@ -1,38 +1,44 @@ # Build instructions for Embedded (ARM port) -First clone, initialize submodules and install Poetry as defined [here](index.md). -**Do not forget you need to be in a `poetry shell` environment!** + +First, clone the repository and initialize the submodules as defined [here](index.md). + +Then, you need to install all necessary requirements. ## Requirements -You will need the GCC ARM toolchain for building and OpenOCD for flashing to a device. -You will also need Python dependencies for signing. +The recommended way to control the requirements across all systems is to install **nix-shell**, which automatically installs all requirements in an isolated environment using the `shell.nix` configuration file located in the repository root. + +To install nix-shell, follow the instructions [here](https://nix.dev/manual/nix/2.18/installation/installing-binary). -### Debian/Ubuntu +Once nix-shell is installed, go to the **repository root** and run: ```sh -sudo apt-get install scons gcc-arm-none-eabi libnewlib-arm-none-eabi llvm-dev libclang-dev clang +nix-shell ``` -### NixOS +### Working with Developer Tools -There is a `shell.nix` file in the root of the project. Just run the following -**before** entering the `core` directory: +If you need to work with embedded development tools such as OpenOCD, gcc-arm-embedded, gdb, etc., you can run nix-shell with the following argument to enable additional development tools: ```sh -nix-shell +nix-shell --arg devTools true ``` -### OS X +### Manual Requirements Installation -_Consider using [Nix](https://nixos.org/download.html). With Nix all you need to do is `nix-shell`._ +If you prefer to install the requirements manually, look into the shell.nix file where you can find a list of requirements with versions. -For other users: +## Python Dependencies + +All Python dependencies and packages are handled with Poetry. If you work in nix-shell, Poetry will be installed automatically. Then, you can install the dependencies and run the Poetry shell in the repository root. + +```sh +poetry install +poetry shell +``` -1. Download [gcc-arm-none-eabi](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) -2. Follow the [install instructions](https://launchpadlibrarian.net/287100883/readme.txt) -3. To install OpenOCD, run `brew install open-ocd` -4. Run `make vendor build_boardloader build_bootloader build_firmware` +**Note: The recommended way of initializing your environment is to first run nix-shell and then initialize the Poetry shell within it.** ## Protobuf Compiler diff --git a/docs/core/misc/disc2.md b/docs/core/misc/disc2.md new file mode 100644 index 00000000000..b5684317bf3 --- /dev/null +++ b/docs/core/misc/disc2.md @@ -0,0 +1,29 @@ +DISC 2 + +DISC2 is an evaluation board STM32U5G9J used for firmware development of Trezor models with the STM32U5. + +The kit has accessible pins, a display, and an embedded ST-Link. + +To build and flash firmware to the DISC2 target, follow these instructions: + +1. Compile the firmware for the target with TREZOR_MODEL=DISC2 and BOOTLOADER_DEVEL=1 + +```sh +cd core +TREZOR_MODEL=DISC2 BOOTLOADER_DEVEL=1 make vendor build_boardloader build_bootloader build_firmware +``` + +2. Ensure that TrustZone is enabled on the DISC2 device, as explained here. + +3. Connect the DISC2 ST-Link to the PC using a micro-USB cable (connector CN5). + +4. Erase the DISC2 flash. +```sh +TREZOR_MODEL=DISC2 make flash_erase +``` +5. Flash the freshly compiled firmware from step 1. + +```sh +TREZOR_MODEL=DISC2 make flash +```` +6. Reset the device (you may need to do this a couple of times) until it boots up. diff --git a/docs/core/misc/trustzone.md b/docs/core/misc/trustzone.md new file mode 100644 index 00000000000..ccc662c7067 --- /dev/null +++ b/docs/core/misc/trustzone.md @@ -0,0 +1,26 @@ + + +# TrustZone + +New Trezor models are built on the STM32U5 series microcontrollers, which are based on the ARM Cortex-M33 and provide advanced security features, such as TrustZone. + +When building firmware for such a device (Blank Trezor device or DISC2 evaluation kit), you need to ensure that TrustZone is enabled in the STM32 microcontroller’s option bytes. + +## Enable TrustZone in STM32 Option Bytes + +1. Download and install [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html#st-get-software). + + +2. Connect the device via ST-Link (DISC2 has an embedded ST-Link; for Trezor devices, use an external one). + +3. Power on the device (connect via USB). + +4. Open STM32CubeProgrammer and connect to the device. + +5. Open the Option Bytes (OB) tab. + +6. In the User Configuration tab, enable TZEN, then press Apply. + +7. In the Boot Configuration tab, change the SECBOOTADD0 address to 0x0C004000, then press Apply. + +8. Disconnect the ST-Link and reset the device.