Tomas Susanka
5 years ago
@ -0,0 +1 @@
|
||||
book
|
||||
@ -0,0 +1,18 @@
|
||||
# Summary
|
||||
|
||||
- [Introduction](intro.md)
|
||||
- [Build](build/index.md)
|
||||
- [Embedded](build/embedded.md)
|
||||
- [Emulator](build/emulator.md)
|
||||
- [Emulator](emulator/index.md)
|
||||
- [Hardware](hardware/index.md)
|
||||
- [Hardware](hardware/hardware.md)
|
||||
- [Boot stages](hardware/boot.md)
|
||||
- [Memory layout](hardware/memory.md)
|
||||
- [Trezor Core](src/index.md)
|
||||
- [Communication](src/communication.md)
|
||||
- [Apps](src/apps.md)
|
||||
- [Tests](tests/index.md)
|
||||
- [Miscellaneous](misc/index.md)
|
||||
- [Coins' BIP-44 Paths](misc/coins-bip44-paths.md)
|
||||
- [TOIF Image Format](misc/toif.md)
|
||||
@ -0,0 +1,8 @@
|
||||
[book]
|
||||
title = "Trezor Core"
|
||||
description = "Documentation of Trezor Core firmware."
|
||||
src = "."
|
||||
|
||||
[build]
|
||||
build-dir = "../build/docs"
|
||||
create-missing = false
|
||||
@ -1,120 +0,0 @@
|
||||
# Build instructions
|
||||
|
||||
## Build instructions for Emulator (Unix port)
|
||||
|
||||
Run the following to checkout the project:
|
||||
|
||||
```sh
|
||||
git clone --recursive https://github.com/trezor/trezor-firmware.git
|
||||
cd trezor-firmware/core
|
||||
```
|
||||
|
||||
If you are building from an existing checkout, don't forget to use the following to refresh the submodules:
|
||||
|
||||
```sh
|
||||
make vendor
|
||||
```
|
||||
|
||||
Install the required packages, depending on your operating system.
|
||||
|
||||
* __Debian/Ubuntu__:
|
||||
|
||||
```sh
|
||||
sudo apt-get install scons libsdl2-dev libsdl2-image-dev
|
||||
```
|
||||
|
||||
* __Fedora__:
|
||||
|
||||
```sh
|
||||
sudo yum install scons SDL2-devel SDL2_image-devel
|
||||
```
|
||||
|
||||
* __OpenSUSE__:
|
||||
|
||||
```sh
|
||||
sudo zypper install scons libSDL2-devel libSDL2_image-devel
|
||||
```
|
||||
|
||||
* __Arch__:
|
||||
|
||||
```sh
|
||||
sudo pacman -S scons sdl2 sdl2_image
|
||||
```
|
||||
|
||||
* __NixOS__:
|
||||
|
||||
There is a `shell.nix` file in the root of the project. Just run the following **before** entering the `core` directory:
|
||||
|
||||
```sh
|
||||
nix-shell
|
||||
```
|
||||
|
||||
* __Mac OS X__:
|
||||
|
||||
```sh
|
||||
brew install scons sdl2 sdl2_image pkg-config
|
||||
```
|
||||
|
||||
* __Windows__: not supported yet, sorry.
|
||||
|
||||
Run the build with:
|
||||
|
||||
```sh
|
||||
make build_unix
|
||||
```
|
||||
|
||||
Now you can start the emulator:
|
||||
|
||||
```sh
|
||||
./emu.sh
|
||||
```
|
||||
|
||||
## Build instructions for Embedded (ARM port)
|
||||
|
||||
### 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.
|
||||
|
||||
#### Debian/Ubuntu
|
||||
|
||||
```sh
|
||||
sudo apt-get install scons gcc-arm-none-eabi libnewlib-arm-none-eabi
|
||||
```
|
||||
|
||||
#### OS X
|
||||
|
||||
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`
|
||||
|
||||
### Building
|
||||
|
||||
```sh
|
||||
sudo pip3 install pipenv
|
||||
pipenv install
|
||||
pipenv run make vendor build_boardloader build_bootloader build_firmware
|
||||
```
|
||||
|
||||
### Uploading
|
||||
|
||||
Use `make upload` to upload the firmware to a production device (with a bootloader).
|
||||
|
||||
### Flashing
|
||||
|
||||
For flashing firmware to blank device (without bootloader) use `make flash`,
|
||||
or `make flash STLINK_VER=v2-1` if using a ST-LINK/V2.1 interface.
|
||||
You need to have OpenOCD installed.
|
||||
|
||||
|
||||
## Building for debugging and hacking in Emulator (Unix port)
|
||||
|
||||
Build the debuggable unix binary so you can attach the gdb or lldb.
|
||||
This removes optimizations and reduces address space randomizaiton.
|
||||
Beware that this will significantly bloat the final binary
|
||||
and the firmware runtime memory limit HEAPSIZE may have to be increased.
|
||||
|
||||
```sh
|
||||
DEBUG_BUILD=1 make build_unix
|
||||
```
|
||||
@ -1,27 +0,0 @@
|
||||
# Emulator
|
||||
|
||||
|
||||
|
||||
1. [build](build.md) the emulator
|
||||
2. run `emu.sh`
|
||||
3. to use [bridge](https://github.com/trezor/trezord-go) with the emulator support, start it with `trezord -e 21324`
|
||||
|
||||
## Profiles
|
||||
|
||||
To run emulator with different flash and sdcard files set the environment
|
||||
variable **TREZOR_PROFILE** like so:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=foobar ./emu.sh
|
||||
```
|
||||
|
||||
This will create a profile directory in your home ``` ~/.trezoremu/foobar```
|
||||
containing emulator run files.
|
||||
|
||||
Alternatively you can set a full path like so:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=/var/tmp/foobar ./emu.sh
|
||||
```
|
||||
|
||||
When the **TREZOR_PROFILE** is not set the default is ```/var/tmp``` .
|
||||
|
After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 59 KiB |
@ -0,0 +1,77 @@
|
||||
# Emulator
|
||||
|
||||
Emulator is a unix version of Core firmware that runs on your computer.
|
||||
|
||||
|
||||
|
||||
There is neither boardloader nor bootloader and no firmware uploads. Emulator runs the current code as is it is and if you want to run some specific firmware version you need to use git for that (simply checkout the right branch/tag). Actually, maybe we should call it _simulator_ to be precise, because it does not emulate the device in its completeness, it just runs the firmware on your host.
|
||||
|
||||
Emulator significantly speeds up development and has several features to help you along the way.
|
||||
|
||||
## How to run
|
||||
|
||||
1. [build](../build/emulator.md) the emulator
|
||||
2. run `emu.sh`
|
||||
3. to use [bridge](https://github.com/trezor/trezord-go) with the emulator support, start it with `trezord -e 21324`
|
||||
|
||||
Now you can use the emulator the same way as you use the device, for example you can visit our Wallet (https://wallet.trezor.io), use our Python CLI tool (`trezorctl`) etc. Simply click to emulate screen touches.
|
||||
|
||||
## Features
|
||||
|
||||
### Debug mode
|
||||
|
||||
To allow debug link (to run tests), see exceptions and log output, run emulator with `PYOPT=0 ./emu.sh`. To properly distinguish the debug mode from production there is a tiny red square in the top right corner. The debug mode is obviously disabled on production firmwares.
|
||||
|
||||
|
||||
|
||||
### Initialize with mnemonic words
|
||||
|
||||
If the debug mode is enabled, you can load the device with any recovery seed directly from the console. This feature is otherwise disabled. To enter seed use `trezorctl`:
|
||||
|
||||
```sh
|
||||
trezorctl -m "your mnemonic words"
|
||||
```
|
||||
|
||||
or to use the "all all all" seed defined in [SLIP-14](https://github.com/satoshilabs/slips/blob/master/slip-0014.md):
|
||||
|
||||
```sh
|
||||
trezorctl -s
|
||||
```
|
||||
|
||||
Shamir Backup is also supported:
|
||||
|
||||
```sh
|
||||
trezorctl -m "share 1 words" -m "share 2 words"
|
||||
```
|
||||
|
||||
### Storage and Profiles
|
||||
|
||||
Internal Trezor's storage is emulated and stored in the `/var/tmp/trezor.flash` file on default. Deleting this file is similar to calling _wipe device_. You can also find `/var/tmp/trezor.sdcard` for SD card and `/var/tmp/trezor.log`, which contains the communication log, the same as is in the emulator's stdout.
|
||||
|
||||
To run emulator with different files set the environment variable **TREZOR_PROFILE** like so:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=foobar ./emu.sh
|
||||
```
|
||||
|
||||
This will create a profile directory in your home ``` ~/.trezoremu/foobar``` containing emulator run files. Alternatively you can set a full path like so:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=/var/tmp/foobar ./emu.sh
|
||||
```
|
||||
|
||||
### Run in gdb
|
||||
|
||||
Running `emu.sh` with `-d` runs emulator inside gdb/lldb.
|
||||
|
||||
### Watch for file changes
|
||||
|
||||
Running `emu.sh` with `-r` watches for file changes and reloads the emulator if any occur. Note that this does not do rebuild, i.e. this works for MicroPython code (which is interpreted) but if you make C changes, you need to rebuild your self.
|
||||
|
||||
### Print screen
|
||||
|
||||
Press `p` on your keyboard to capture emulator's screen. You will find a png screenshot in the `src` directory.
|
||||
|
||||
### Auto print screen
|
||||
|
||||
If ``` TREZOR_SAVE_SCREEN=1 ``` is set, the emulator makes print screen on every screen change.
|
||||
|
Before Width: | Height: | Size: 139 KiB After Width: | Height: | Size: 139 KiB |
|
Before Width: | Height: | Size: 135 KiB After Width: | Height: | Size: 135 KiB |
|
Before Width: | Height: | Size: 119 KiB After Width: | Height: | Size: 119 KiB |
|
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 54 KiB |
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 15 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 99 KiB After Width: | Height: | Size: 99 KiB |
|
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 61 KiB |
|
Before Width: | Height: | Size: 518 KiB After Width: | Height: | Size: 518 KiB |
@ -1,7 +1,6 @@
|
||||
# Trezor Core Bootloader
|
||||
# Trezor Core Boot Stages
|
||||
|
||||
Trezor initialization is split into two stages.
|
||||
See [Memory Layout](memory.md) for info about in which sectors each stage is stored.
|
||||
Trezor T initialization is split into two stages. See [Memory Layout](memory.md) for info about in which sectors each stage is stored.
|
||||
|
||||
First stage (boardloader) is stored in write-protected area, which means it is non-upgradable.
|
||||
Only second stage (bootloader) update is allowed.
|
||||
@ -0,0 +1,7 @@
|
||||
# Hardware
|
||||
|
||||
Currently, only Trezor T runs Trezor Core. However, we plan to port Core to Trezor One as well ([#24](https://github.com/trezor/trezor-firmware/issues/24)).
|
||||
|
||||
That being said, Core and Model T are tightly coupled together. That means, Core contains many T-only codebase and documentation.
|
||||
|
||||
This section is not concern with Model One whatsoever. Please see the Legacy documentation for that.
|
||||
@ -1,4 +1,4 @@
|
||||
# Memory Layout
|
||||
# Trezor T Memory Layout
|
||||
|
||||
## Flash
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
# Introduction
|
||||
|
||||
Trezor Core is the second-gen firmware running on Trezor devices. It currently runs on Trezor T only, but it will probably be used on Trezor One in future as well (see issue [#24](https://github.com/trezor/trezor-firmware/issues/24)).
|
||||
|
||||
Trezor Core is part of the trezor-firmware monorepo to be found on [GitHub](https://github.com/trezor/trezor-firmware), in the `core` subdirectory. You can read more on the monorepo structure in the root `docs` folder.
|
||||
@ -0,0 +1 @@
|
||||
# Miscellaneous
|
||||
@ -0,0 +1,16 @@
|
||||
# Apps
|
||||
|
||||
The folder `src/apps/` is the place where all the user-facing features are implemented.
|
||||
|
||||
Each app has a `boot()` function in the module's \_\_init\_\_ file. This functions assigns what function should be called if some specific message was received. In other words, it is a link between the MicroPython functions and the Protobuf messages.
|
||||
|
||||
## Example
|
||||
|
||||
This binds the message GetAddress to function `get_address` inside the `apps.wallet` module.
|
||||
|
||||
```python
|
||||
from trezor import wire
|
||||
from trezor.messages import MessageType
|
||||
|
||||
wire.add(MessageType.GetAddress, apps.wallet, "get_address")
|
||||
```
|
||||
@ -0,0 +1,8 @@
|
||||
# Communication
|
||||
|
||||
We use [Protobuf v2](https://developers.google.com/protocol-buffers/) for host-device communication. The communication cycle is very simple, Trezor receives a message, acts on it and responds with another message. Trezor on its own is incapable of initiating the communication.
|
||||
|
||||
|
||||
## Definitions
|
||||
|
||||
Protobuf messages are defined in the [Common](http://github.com/trezor/trezor-firmware/blob/master/common) project, which is part of this monorepo. This repository is also exported to [trezor/trezor-common](https://github.com/trezor/trezor-common) to be used by third parties, which prefer not to include the whole monorepo. This copy is read-only and all changes are happening in this monorepo.
|
||||
@ -0,0 +1,9 @@
|
||||
# Trezor Core
|
||||
|
||||
Trezor Core uses [MicroPython](https://github.com/micropython/micropython), it is a Python implementation for embedded systems, which allows us to have an application layer in Python, which makes the code significantly more readable and sustainable. This is what you find in the `src` folder.
|
||||
|
||||
Not everything is in Python though, we need to use C occasionally, usually for performance reasons. That is what `embed/extmod` is for. It extends MicroPython's modules with a number of our owns and serves as a bridge between C and Python codebase. Related to that, `mocks` contain Python mocks of those functions to improve readability and IDE functioning.
|
||||
|
||||
## Boot
|
||||
|
||||
Module `src/main.py` is the first one to be invoked in MicroPython. It starts the USB, initializes the wire codec and boots applications (see [Apps](apps.md)).
|
||||