arno/trezor-firmware
1
0
Fork 0
mirror of https://github.com/trezor/trezor-firmware.git synced 2024-11-26 09:28:13 +00:00
Code Issues Releases Wiki Activity

markdown: follow commonmark spec

Browse Source
This commit is contained in:
Pavol Rusnak 2017-03-20 15:49:11 +01:00
parent b141e6b1e3
commit cc525e97ce
No known key found for this signature in database
GPG Key ID: 91F3B339B9A02A3D
6 changed files with 46 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -1,46 +1,45 @@
# TREZOR Core
![TREZOR Core](docs/trezor_core.png) ![TREZOR Core](docs/trezor_core.png)
[![Build Status](https://travis-ci.org/trezor/trezor-core.svg?branch=master)](https://travis-ci.org/trezor/trezor-core) [![gitter](https://badges.gitter.im/trezor/community.svg)](https://gitter.im/trezor/community) [![Build Status](https://travis-ci.org/trezor/trezor-core.svg?branch=master)](https://travis-ci.org/trezor/trezor-core) [![gitter](https://badges.gitter.im/trezor/community.svg)](https://gitter.im/trezor/community)
This is the core of the upcoming TREZOR v2. It consists of several parts: This is the core of the upcoming TREZOR v2.
* patched version of [MicroPython](https://github.com/micropython/micropython) - in `vendor/micropython` ## Documentation
* application logic - in `src`
##Documentation
* [Documentation](docs/) * [Documentation](docs/)
##Build instructions for emulator ## Build instructions for emulator
###Linux ### Linux
####Debian/Ubuntu #### Debian/Ubuntu
``` ```sh
sudo dpkg --add-architecture i386 sudo dpkg --add-architecture i386
sudo apt-get update sudo apt-get update
sudo apt-get install libsdl2-dev:i386 libsdl2-image-dev:i386 sudo apt-get install libsdl2-dev:i386 libsdl2-image-dev:i386
make build_unix make build_unix
``` ```
####Fedora #### Fedora
``` ```sh
sudo yum install SDL2-devel.i686 SDL2_image-devel.i686 sudo yum install SDL2-devel.i686 SDL2_image-devel.i686
make build_unix make build_unix
``` ```
####openSUSE #### openSUSE
``` ```sh
sudo zypper install libSDL2-devel-32bit libSDL2_image-devel-32bit sudo zypper install libSDL2-devel-32bit libSDL2_image-devel-32bit
make build_unix make build_unix
``` ```
###OS X ### OS X
``` ```sh
brew install --universal sdl2 sdl2_image brew install --universal sdl2 sdl2_image
make build_unix make build_unix
``` ```
@ -49,20 +48,21 @@ make build_unix
Not supported yet ... Not supported yet ...
##Build instructions for ARM ## Build instructions for ARM
###Linux ### Linux
For flashing firmware to blank device (without bootloader) by `make flash`, please install [stlink](https://github.com/texane/stlink) For flashing firmware to blank device (without bootloader) by `make flash`,
please install [stlink](https://github.com/texane/stlink).
####Debian/Ubuntu #### Debian/Ubuntu
``` ```sh
sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
make build_trezorhal make build_trezorhal
``` ```
###OS X ### OS X
1. Download [gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/5.0/5-2016-q3-update/) 1. Download [gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/5.0/5-2016-q3-update/)
2. Follow the [install instructions](https://launchpadlibrarian.net/287100883/readme.txt) 2. Follow the [install instructions](https://launchpadlibrarian.net/287100883/readme.txt)

2
docs/README.md
View File

@ -1,4 +1,4 @@
#TREZOR Core documentation # TREZOR Core documentation
* [TREZOR Core API](api.md) * [TREZOR Core API](api.md)
* [TREZOR Core Bootloader](bootloader.md) * [TREZOR Core Bootloader](bootloader.md)

5
docs/api.md
View File

@ -1,3 +1,4 @@
#TREZOR Core API # TREZOR Core API
Syntax used below is a valid Python function declaration with type hints defined in [PEP 0484](https://www.python.org/dev/peps/pep-0484/). Syntax used below is a valid Python function declaration with type hints
defined in [PEP 0484](https://www.python.org/dev/peps/pep-0484/).

21
docs/bootloader.md
View File

@ -1,38 +1,37 @@
#TREZOR Core Bootloader # TREZOR Core Bootloader
Bootloader is split into two stages. See [Memory Layout](memory.md) for info about in which sectors each stage is stored. Bootloader is split into two stages. See [Memory Layout](memory.md) for info about in which sectors each stage is stored.
First stage is stored in write-protected area, which means it is non-upgradable. Only second stage bootloader update is allowed. First stage is stored in write-protected area, which means it is non-upgradable. Only second stage bootloader update is allowed.
##First Stage Bootloader ## First Stage Bootloader
First stage checks the integrity and signatures of the second stage and runs it if everything is OK. First stage checks the integrity and signatures of the second stage and runs it if everything is OK.
If first stage bootloader finds a valid second stage bootloader image on the SD card (in raw format, no filesystem), If first stage bootloader finds a valid second stage bootloader image on the SD card (in raw format, no filesystem),
it will replace the internal second stage, allowing a second stage update via SD card. it will replace the internal second stage, allowing a second stage update via SD card.
##Second Stage Bootloader ## Second Stage Bootloader
Second stage checks the integrity and signatures of the firmware and runs it if everything is OK. Second stage checks the integrity and signatures of the firmware and runs it if everything is OK.
If second stage bootloader detects a pressed finger on the display or there is no firmware loaded in the device, If second stage bootloader detects a pressed finger on the display or there is no firmware loaded in the device,
it will start in a firmware update mode, allowing a firmware update via USB. it will start in a firmware update mode, allowing a firmware update via USB.
##Common notes ## Common notes
* Hash function used below is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one). * Hash function used below is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one).
* All multibyte integer values are little endian. * All multibyte integer values are little endian.
* There is a tool called [firmwarectl](../tools/firmwarectl) which checks validity of the bootloader/firmware images including their headers. * There is a tool called [firmwarectl](../tools/firmwarectl) which checks validity of the bootloader/firmware images including their headers.
##Bootloader Format ## Bootloader Format
TREZOR Core (second stage) bootloader consists of 2 parts: TREZOR Core (second stage) bootloader consists of 2 parts:
1. bootloader header 1. bootloader header
2. bootloader code 2. bootloader code
### Bootloader Header
###Bootloader Header
Total length of bootloader header is always 256 bytes. Total length of bootloader header is always 256 bytes.
@ -50,7 +49,7 @@ Total length of bootloader header is always 256 bytes.
| 0x00BF | 1 | sigidx | SatoshiLabs signature indexes (bitmap) | | 0x00BF | 1 | sigidx | SatoshiLabs signature indexes (bitmap) |
| 0x00C0 | 64 | sig | SatoshiLabs signature | | 0x00C0 | 64 | sig | SatoshiLabs signature |
##Firmware Format ## Firmware Format
TREZOR Core firmware consists of 3 parts: TREZOR Core firmware consists of 3 parts:
@ -58,7 +57,7 @@ TREZOR Core firmware consists of 3 parts:
2. firmware header 2. firmware header
3. firmware code 3. firmware code
###Vendor Header ### Vendor Header
Total length of vendor header is 84 + 32 * (number of pubkeys) + (length of vendor string) + (length of vendor image) bytes rounded up to the closest multiply of 256 bytes. Total length of vendor header is 84 + 32 * (number of pubkeys) + (length of vendor string) + (length of vendor image) bytes rounded up to the closest multiply of 256 bytes.
@ -81,7 +80,7 @@ Total length of vendor header is 84 + 32 * (number of pubkeys) + (length of vend
| ? | 1 | sigidx | SatoshiLabs signature indexes (bitmap) | | ? | 1 | sigidx | SatoshiLabs signature indexes (bitmap) |
| ? | 64 | sig | SatoshiLabs signature | | ? | 64 | sig | SatoshiLabs signature |
###Firmware Header ### Firmware Header
Total length of firmware header is always 256 bytes. Total length of firmware header is always 256 bytes.
@ -99,7 +98,7 @@ Total length of firmware header is always 256 bytes.
| 0x00BF | 1 | sigidx | vendor signature indexes (bitmap) | | 0x00BF | 1 | sigidx | vendor signature indexes (bitmap) |
| 0x00C0 | 64 | sig | vendor signature | | 0x00C0 | 64 | sig | vendor signature |
##Various ideas ## Various ideas
* Bootloader should be able to read vendor+firmware header and send info about FW to client in features message. * Bootloader should be able to read vendor+firmware header and send info about FW to client in features message.
* Bootloader should not try to run firmware if there is not any. * Bootloader should not try to run firmware if there is not any.

6
docs/memory.md
View File

@ -1,6 +1,6 @@
#Memory Layout # Memory Layout
##Flash ## Flash
| sector | range | size | function | sector | range | size | function
|-----------|-------------------------|--------:|---------------------- |-----------|-------------------------|--------:|----------------------
@ -17,7 +17,7 @@
| Sector 10 | 0x080C0000 - 0x080DFFFF | 128 KiB | firmware | Sector 10 | 0x080C0000 - 0x080DFFFF | 128 KiB | firmware
| Sector 11 | 0x080E0000 - 0x080FFFFF | 128 KiB | firmware | Sector 11 | 0x080E0000 - 0x080FFFFF | 128 KiB | firmware
##RAM ## RAM
| region | range | size | function | region | range | size | function
|---------|-------------------------|--------:|---------------------- |---------|-------------------------|--------:|----------------------

16
docs/toif.md
View File

@ -1,8 +1,8 @@
#TREZOR Optimized Image Format # TREZOR Optimized Image Format
All multibyte integer values are little endian! All multibyte integer values are little endian!
##Header ## Header
| offset | length | name | description | | offset | length | name | description |
|-------:|-------:|------|-------------| |-------:|-------:|------|-------------|
@ -13,14 +13,14 @@ All multibyte integer values are little endian!
| 0x0008 | 4 | datasize | length of the compressed data | | 0x0008 | 4 | datasize | length of the compressed data |
| 0x000A | ? | data | compressed data (see below) | | 0x000A | ? | data | compressed data (see below) |
##Format ## Format
TOI currently supports 2 variants: TOI currently supports 2 variants:
* `f`: full-color, file extension `.toif` * `f`: full-color, file extension `.toif`
* `g`: gray-scale, file extension `.toig` * `g`: gray-scale, file extension `.toig`
###Full-color ### Full-color
For each pixel a 16-bit value is used. First 5 bits are used for red component, next 6 bits are green, final 5 bits are blue, so it looks like this: For each pixel a 16-bit value is used. First 5 bits are used for red component, next 6 bits are green, final 5 bits are blue, so it looks like this:
@ -28,7 +28,7 @@ For each pixel a 16-bit value is used. First 5 bits are used for red component,
|----|----|----|----|----|----|---|---|---|---|---|---|---|---|---|---| |----|----|----|----|----|----|---|---|---|---|---|---|---|---|---|---|
| R | R | R | R | R | G | G | G | G | G | G | B | B | B | B | B | | R | R | R | R | R | G | G | G | G | G | G | B | B | B | B | B |
###Gray-scale ### Gray-scale
Each pixel is encoded using a 4-bit value. Each byte contains color of two pixels, so it looks like this: Each pixel is encoded using a 4-bit value. Each byte contains color of two pixels, so it looks like this:
@ -38,17 +38,17 @@ Each pixel is encoded using a 4-bit value. Each byte contains color of two pixel
Where Po is odd pixel and Pe is even pixel. Where Po is odd pixel and Pe is even pixel.
##Compression ## Compression
Pixel data is compressed using DEFLATE algorithm with 10-bit sliding window and no header. This can be achieved with ZLIB library by using the following: Pixel data is compressed using DEFLATE algorithm with 10-bit sliding window and no header. This can be achieved with ZLIB library by using the following:
``` python ```python
import zlib import zlib
z = zlib.compressobj(level=9, wbits=10) z = zlib.compressobj(level=9, wbits=10)
zdata = z.compress(pixeldata) + z.flush() zdata = z.compress(pixeldata) + z.flush()
zdata = zdata[2:-4] # strip header and checksum zdata = zdata[2:-4] # strip header and checksum
``` ```
##Tools ## Tools
* [png2toi](../tools/png2toi) - tool for converting PNG into TOI format * [png2toi](../tools/png2toi) - tool for converting PNG into TOI format