docs(core) Update embedded build instraction, add DISC2 and TrustZone section

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)

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.
 
-### Debian/Ubuntu
+To install nix-shell, follow the instructions [here](https://nix.dev/manual/nix/2.18/installation/installing-binary).
 
-```sh
-sudo apt-get install scons gcc-arm-none-eabi libnewlib-arm-none-eabi llvm-dev libclang-dev clang
-```
-
-### NixOS
-
-There is a `shell.nix` file in the root of the project. Just run the following
-**before** entering the `core` directory:
+Once nix-shell is installed, go to the **repository root** and run:
 
 ```sh
 nix-shell
 ```
 
-### OS X
+### Working with Developer Tools
 
-_Consider using [Nix](https://nixos.org/download.html). With Nix all you need to do is `nix-shell`._
+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:
 
-For other users:
+```sh
+nix-shell --arg devTools true
+```
 
-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`
+### Manual Requirements Installation
+
+If you prefer to install the requirements manually, look into the shell.nix file where you can find a list of requirements with versions.
+
+## 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
+```
+
+**Note: The recommended way of initializing your environment is to first run nix-shell and then initialize the Poetry shell within it.**
 
 ## Protobuf Compiler
 

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.

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.