mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-24 23:38:09 +00:00
chore(docs): Clean up dead links [no changelog]
This commit is contained in:
Simon Males
marnova
parent
8668eba936
commit
393bbb2bf1
@ -9,7 +9,7 @@ image: registry.gitlab.com/satoshilabs/trezor/trezor-firmware/trezor-firmware-en
|
||||
|
||||
# Hardware
|
||||
|
||||
# [Device tests](../docs/tests/device-tests.md) that run against an actual physical Trezor T.
|
||||
# [Device tests](../tests/device-tests.md) that run against an actual physical Trezor T.
|
||||
# The device needs to have special bootloader, found in `core/embed/bootloader_ci`, that
|
||||
# makes it possible to flash firmware without confirmation on the touchscreen.
|
||||
#
|
||||
@ -107,7 +107,7 @@ hardware core monero test:
|
||||
expire_in: 2 days
|
||||
when: always
|
||||
|
||||
# [Device tests](../docs/tests/device-tests.md) executed on physical Trezor 1.
|
||||
# [Device tests](../tests/device-tests.md) executed on physical Trezor 1.
|
||||
# This works thanks to [tpmb](https://github.com/mmahut/tpmb), which is a small arduino
|
||||
# device capable of pushing an actual buttons on the device.
|
||||
hardware legacy regular device test:
|
||||
|
||||
@ -60,7 +60,7 @@ core unit t1 test:
|
||||
# Device tests for Core. Running device tests and also comparing screens
|
||||
# with the expected UI result.
|
||||
# See artifacts for a comprehensive report of UI.
|
||||
# See [docs/tests/ui-tests](../docs/tests/ui-tests.md) for more info.
|
||||
# See [docs/tests/ui-tests](../tests/ui-tests.md) for more info.
|
||||
core device test:
|
||||
stage: test
|
||||
<<: *gitlab_caching
|
||||
@ -304,7 +304,7 @@ core fido2 asan test:
|
||||
when: always
|
||||
|
||||
# Click tests.
|
||||
# See [docs/tests/click-tests](../docs/tests/click-tests.md) for more info.
|
||||
# See [docs/tests/click-tests](../tests/click-tests.md) for more info.
|
||||
core click test:
|
||||
stage: test
|
||||
<<: *gitlab_caching
|
||||
@ -342,7 +342,7 @@ core click asan test:
|
||||
when: always
|
||||
|
||||
# Upgrade tests.
|
||||
# See [docs/tests/upgrade-tests](../docs/tests/upgrade-tests.md) for more info.
|
||||
# See [docs/tests/upgrade-tests](../tests/upgrade-tests.md) for more info.
|
||||
core upgrade test:
|
||||
stage: test
|
||||
<<: *gitlab_caching
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
It consists of multiple stages below, each having one or more jobs
|
||||
Latest CI pipeline of master branch can be seen at [https://gitlab.com/satoshilabs/trezor/trezor-firmware/-/pipelines/master/latest](https://gitlab.com/satoshilabs/trezor/trezor-firmware/-/pipelines/master/latest)
|
||||
|
||||
## ENVIRONMENT stage - [environment.yml](../../ci/environment.yml)
|
||||
## ENVIRONMENT stage - [environment.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/environment.yml)
|
||||
Connected with creating the testing image for CI.
|
||||
|
||||
Consists of **3 jobs** below:
|
||||
@ -20,7 +20,7 @@ Almost all CI jobs run inside this docker image.
|
||||
### [environment scheduled](https://github.com/trezor/trezor-firmware/blob/master/ci/environment.yml#L35)
|
||||
|
||||
---
|
||||
## PREBUILD stage - [prebuild.yml](../../ci/prebuild.yml)
|
||||
## PREBUILD stage - [prebuild.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/prebuild.yml)
|
||||
Static checks on the code.
|
||||
|
||||
Consists of **7 jobs** below:
|
||||
@ -51,7 +51,7 @@ Verifying that all commits changing some functionality have a changelog entry
|
||||
or contain `[no changelog]` in the commit message.
|
||||
|
||||
---
|
||||
## BUILD stage - [build.yml](../../ci/build.yml)
|
||||
## BUILD stage - [build.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/build.yml)
|
||||
All builds are published as artifacts so they can be downloaded and used.
|
||||
|
||||
Consists of **28 jobs** below:
|
||||
@ -138,7 +138,7 @@ Bitcoin-only version.
|
||||
### [legacy emu btconly debug asan build](https://github.com/trezor/trezor-firmware/blob/master/ci/build.yml#L526)
|
||||
|
||||
---
|
||||
## TEST stage - [test.yml](../../ci/test.yml)
|
||||
## TEST stage - [test.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml)
|
||||
All the tests run test cases on the freshly built emulators from the previous `BUILD` stage.
|
||||
|
||||
Consists of **35 jobs** below:
|
||||
@ -156,7 +156,7 @@ Python and rust unit tests, checking TT functionality.
|
||||
Device tests for Core. Running device tests and also comparing screens
|
||||
with the expected UI result.
|
||||
See artifacts for a comprehensive report of UI.
|
||||
See [docs/tests/ui-tests](../docs/tests/ui-tests.md) for more info.
|
||||
See [docs/tests/ui-tests](../tests/ui-tests.md) for more info.
|
||||
|
||||
### [core device ui2 test](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L93)
|
||||
|
||||
@ -184,13 +184,13 @@ FIDO2 device tests.
|
||||
|
||||
### [core click test](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L308)
|
||||
Click tests.
|
||||
See [docs/tests/click-tests](../docs/tests/click-tests.md) for more info.
|
||||
See [docs/tests/click-tests](../tests/click-tests.md) for more info.
|
||||
|
||||
### [core click asan test](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L325)
|
||||
|
||||
### [core upgrade test](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L346)
|
||||
Upgrade tests.
|
||||
See [docs/tests/upgrade-tests](../docs/tests/upgrade-tests.md) for more info.
|
||||
See [docs/tests/upgrade-tests](../tests/upgrade-tests.md) for more info.
|
||||
|
||||
### [core upgrade asan test](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L365)
|
||||
|
||||
@ -228,12 +228,12 @@ Persistence tests.
|
||||
### [connect test core](https://github.com/trezor/trezor-firmware/blob/master/ci/test.yml#L687)
|
||||
|
||||
---
|
||||
## TEST-HW stage - [test-hw.yml](../../ci/test-hw.yml)
|
||||
## TEST-HW stage - [test-hw.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/test-hw.yml)
|
||||
|
||||
Consists of **5 jobs** below:
|
||||
|
||||
### [hardware core regular device test](https://github.com/trezor/trezor-firmware/blob/master/ci/test-hw.yml#L25)
|
||||
[Device tests](../docs/tests/device-tests.md) that run against an actual physical Trezor T.
|
||||
[Device tests](../tests/device-tests.md) that run against an actual physical Trezor T.
|
||||
The device needs to have special bootloader, found in `core/embed/bootloader_ci`, that
|
||||
makes it possible to flash firmware without confirmation on the touchscreen.
|
||||
|
||||
@ -253,7 +253,7 @@ Also device tests on physical Trezor T but with Bitcoin-only firmware.
|
||||
### [hardware core monero test](https://github.com/trezor/trezor-firmware/blob/master/ci/test-hw.yml#L83)
|
||||
|
||||
### [hardware legacy regular device test](https://github.com/trezor/trezor-firmware/blob/master/ci/test-hw.yml#L113)
|
||||
[Device tests](../docs/tests/device-tests.md) executed on physical Trezor 1.
|
||||
[Device tests](../tests/device-tests.md) executed on physical Trezor 1.
|
||||
This works thanks to [tpmb](https://github.com/mmahut/tpmb), which is a small arduino
|
||||
device capable of pushing an actual buttons on the device.
|
||||
|
||||
@ -261,7 +261,7 @@ device capable of pushing an actual buttons on the device.
|
||||
Also device tests on physical Trezor 1 but with Bitcoin-only firmware.
|
||||
|
||||
---
|
||||
## POSTTEST stage - [posttest.yml](../../ci/posttest.yml)
|
||||
## POSTTEST stage - [posttest.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/posttest.yml)
|
||||
|
||||
Consists of **2 jobs** below:
|
||||
|
||||
@ -270,7 +270,7 @@ Consists of **2 jobs** below:
|
||||
### [unix ui changes](https://github.com/trezor/trezor-firmware/blob/master/ci/posttest.yml#L31)
|
||||
|
||||
---
|
||||
## DEPLOY stage - [deploy.yml](../../ci/deploy.yml)
|
||||
## DEPLOY stage - [deploy.yml](https://github.com/trezor/trezor-firmware/blob/master/ci/deploy.yml)
|
||||
|
||||
Consists of **14 jobs** below:
|
||||
|
||||
|
||||
@ -9,21 +9,18 @@ Trezor device functionalities.
|
||||
|
||||
### Trezor Connect (Web)
|
||||
|
||||
For more information about Trezor Connect (JavaScript), see [Trezor
|
||||
Connect API](../developers/connect.md) and this GitHub [page][].
|
||||
<https://github.com/trezor/trezor-suite/tree/develop/packages/connect>
|
||||
|
||||
### Python-trezor
|
||||
|
||||
For more information about Python-trezor, please see [python-trezor][]
|
||||
or this GitHub [page][1]. It is possible to use python-trezor with
|
||||
[trezorctl][] commands from the command line.
|
||||
<https://github.com/trezor/trezor-firmware/tree/master/python>
|
||||
|
||||
<https://pypi.org/project/trezor/>
|
||||
|
||||
### Android
|
||||
|
||||
<https://github.com/trezor/trezor-android>
|
||||
|
||||
*See also: [Developers guide > Android](../developers/android.md)*
|
||||
|
||||
### Go
|
||||
|
||||
<https://github.com/trezor/trezord-go>
|
||||
@ -42,10 +39,7 @@ Trezor.Net supports Android, UWP, .NET Core and .NET Framework with
|
||||
Hid.Net. Support for other platforms can be added with the Hid.Net
|
||||
dependency injection. See this [page][4] or this GitHub [page][5].
|
||||
|
||||
[page]: https://github.com/trezor/trezor-suite/tree/develop/packages/connect
|
||||
[python-trezor]: https://pypi.org/project/trezor/
|
||||
[1]: https://github.com/trezor/trezor-firmware/tree/master/python
|
||||
[trezorctl]: ../python/trezorctl.md
|
||||
[trezor-android]: https://github.com/trezor/trezor-android
|
||||
[3]: https://github.com/gary-rowe/trezor-java
|
||||
[4]: https://www.nuget.org/packages/Trezor.Net/
|
||||
|
||||
@ -32,7 +32,7 @@ Total length of legacy header is always 256 bytes.
|
||||
Signature verification:
|
||||
|
||||
* Calculate SHA256 digest of firmware without this header.
|
||||
* Verify signature `sig1` of the digest against public key with index `sigindex1` in [`V1_BOOTLOADER_KEYS`](../../../python/src/trezorlib/firmware.py).
|
||||
* Verify signature `sig1` of the digest against public key with index `sigindex1` in [`V1_BOOTLOADER_KEYS`](https://github.com/trezor/trezor-firmware/blob/master/python/src/trezorlib/firmware.py).
|
||||
* Repeat for `sig2` and `sig3`. Indexes must be distinct.
|
||||
|
||||
## V2 Header
|
||||
@ -75,5 +75,5 @@ Signature verification:
|
||||
|
||||
* Calculate SHA256 digest of the entire header with `sig1`-`sig3` and `sigindex1`-`sigindex3` zeroed
|
||||
out.
|
||||
* Verify signature `sig1` of the digest against public key with index `sigindex1` in [`V1_BOOTLOADER_KEYS`](../../../python/src/trezorlib/firmware.py).
|
||||
* Verify signature `sig1` of the digest against public key with index `sigindex1` in [`V1_BOOTLOADER_KEYS`](https://github.com/trezor/trezor-firmware/blob/master/python/src/trezorlib/firmware.py).
|
||||
* Repeat for `sig2` and `sig3`. Indexes must be distinct.
|
||||
|
||||
@ -42,7 +42,7 @@ Make sure you have Python 3.6 or later and [Poetry](https://python-poetry.org/)
|
||||
installed.
|
||||
|
||||
If you want to build device firmware, also make sure that you have the [GNU ARM Embedded toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) installed.
|
||||
See [Dockerfile](../../ci/Dockerfile#L72-L76) for up-to-date version of the toolchain.
|
||||
See [Dockerfile](https://github.com/trezor/trezor-firmware/blob/master/ci/Dockerfile) for up-to-date version of the toolchain.
|
||||
|
||||
The build process is configured via environment variables:
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
## Overview
|
||||
This document shows the creation of a custom functionality (feature, application) on TT. It explains how to build both the Trezor (device, core) logic, as well as the client (computer, host, trezorlib) logic needed to speak with Trezor. For most new features, also the communication layer between Trezor and computer (protobuf) needs to be modified, to set up the messages they will exchange.
|
||||
|
||||
Intermediate knowledge of `python` and `linux` environment is assumed here to easily follow along. For steps how to set up the Trezor dev environment, refer to other docs - [build](core/build/index.md) or [emulator](core/emulator/index.md). The most important part is being in the `poetry shell` of this project, so all dependencies are installed.
|
||||
Intermediate knowledge of `python` and `linux` environment is assumed here to easily follow along. For steps how to set up the Trezor dev environment, refer to other docs - [build](../core/build/index.md) or [emulator](../core/emulator/index.md). The most important part is being in the `poetry shell` of this project, so all dependencies are installed.
|
||||
|
||||
## Feature description
|
||||
We will implement a simple hello-world feature where Trezor gets some information from the host, will do something with it (optionally shows something on the screen), and returns some information back to the host, where we want to display them. (Note that there are no cryptographic operations involved in this example, it focuses only on basic communication between Trezor and host.)
|
||||
@ -17,7 +17,7 @@ As already mentioned, to get something useful from Trezor, writing device logic
|
||||
### TLDR: [implementation in a single commit](https://github.com/trezor/trezor-firmware/commit/8a855b38e69bea64ba79ca704876cf4862a9ff79)
|
||||
|
||||
### 1. Communication part (protobuf)
|
||||
Communication between Trezor and the computer is handled by a protocol called `protobuf`. It allows for the creation of specific messages (containing clearly defined data) that will be exchanged. More details about this can be seen in [docs](common/communication/index.md).
|
||||
Communication between Trezor and the computer is handled by a protocol called `protobuf`. It allows for the creation of specific messages (containing clearly defined data) that will be exchanged. More details about this can be seen in [docs](../common/communication/index.md).
|
||||
|
||||
Trezor on its own cannot send data to the computer, it can only react to a "request" message it recognizes and send a "response" message.
|
||||
Both of these messages will need to be specified, and both parts of communication will need to understand them.
|
||||
@ -119,7 +119,7 @@ Even though the code in `core` is run by a `micropython` interpreter, almost all
|
||||
|
||||
As we want to also write unittests for this module, we define a helper function `_get_text_from_msg`, even though it could easily be inlined in this case.
|
||||
|
||||
To see the details about code style and conventions, refer to [codestyle.md](core/misc/codestyle.md).
|
||||
To see the details about code style and conventions, refer to [codestyle.md](../core/misc/codestyle.md).
|
||||
|
||||
We have defined all the logic, but it is not being called anywhere. We need to register the function to be called as a response to the appropriate message - in our case `HelloWorldRequest`. Registration is done in `core/src/apps/workflow_handlers.py` and the following two lines need to be added there (ideally under the `misc` section):
|
||||
|
||||
@ -228,7 +228,7 @@ The example command on its own will however not work without listening Trezor wh
|
||||
### 4. Putting it together
|
||||
Looks like all the code changes have been done, the final part is to build a Trezor image - `emulator` - so that we can actually run and test all the logic we created.
|
||||
|
||||
Detailed information about the emulator can be found in its [docs](core/emulator/index.md), but we only need two most important commands, that will build and spawn the emulator:
|
||||
Detailed information about the emulator can be found in its [docs](../core/emulator/index.md), but we only need two most important commands, that will build and spawn the emulator:
|
||||
|
||||
```sh
|
||||
cd core
|
||||
@ -246,13 +246,13 @@ Hello George!
|
||||
Hello George!
|
||||
```
|
||||
|
||||
For building the new feature into a physical Trezor, refer to [embedded](core/build/embedded.md).
|
||||
For building the new feature into a physical Trezor, refer to [embedded](../core/build/embedded.md).
|
||||
|
||||
## Testing
|
||||
It is always good to include some tests exercising the created functionality, so when we break it later, it will be noticed. Trezor model T supports both `unit tests` and `integration tests` (which are called `device tests`).
|
||||
|
||||
### Unit tests
|
||||
[docs](core/tests/index.md)
|
||||
[docs](../core/tests/index.md)
|
||||
|
||||
Unit tests can verify individual (mostly helper) functions that have clearly defined inputs and outputs.
|
||||
|
||||
@ -283,13 +283,13 @@ Code above is using the `unittest` testing framework, however not directly from
|
||||
Current code checks one usage of `_get_text_from_msg`, the only deterministic helper function we use in our feature. One could create many test vectors trying different inputs and expecting different outputs.
|
||||
|
||||
### Device tests
|
||||
[docs](tests/device-tests.md)
|
||||
[docs](../tests/device-tests.md)
|
||||
|
||||
Device tests (our name for integration tests) should test the whole workflow from sending the first request into Trezor to Trezor sending the final response.
|
||||
|
||||
`trezorlib` is used extensively in these tests as a way to request something from Trezor and then assert the expected response (it actually uses the code we created in Part 3).
|
||||
|
||||
They are closely connected with [ui tests](tests/ui-tests.md), which assert Trezor's screens have a known and expected content during the device tests.
|
||||
They are closely connected with [ui tests](../tests/ui-tests.md), which assert Trezor's screens have a known and expected content during the device tests.
|
||||
|
||||
Device tests are stored in `tests/device_tests` and they can be run by `make test_emu` in `core`. Running the specific file we will create can be done by `make test_emu TESTOPTS="-k test_hello_world.py"`.
|
||||
|
||||
|
||||
@ -29,7 +29,7 @@ We currently have two vendors:
|
||||
As the names suggest, the first one is the official SatoshiLabs vendor header and all
|
||||
public firmwares are signed with that. The second one is meant for generic audience; if
|
||||
you build firmware this vendor header is automatically applied and the firmware is signed
|
||||
with it (see `tools/headertool.py`).
|
||||
with it (see `core/tools/headertool.py`).
|
||||
|
||||
The device gets **wiped**:
|
||||
- If the firmware to be installed is from different vendor than the present firmware [2].
|
||||
|
||||
@ -92,7 +92,7 @@ trezorctl debug show-text "Line one. @@BR @@BR Line two. @@BR @@BR_HALF Line thr
|
||||
|
||||
### Text colors
|
||||
|
||||
To switch to one of the [available colors](../../core/src/trezor/ui/style.py#L14-L47),
|
||||
To switch to one of the [available colors](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L15-L44),
|
||||
use the color name prefixed with `%%`: e.g., `%%RED`, `%%LIGHT_BLUE`...
|
||||
|
||||
To switch back to the default color, you can use `%%FG`:
|
||||
@ -114,13 +114,13 @@ To change the text, use `-h` option:
|
||||
trezorctl debug show-text -h "Hello world" "My hovercraft is full."
|
||||
```
|
||||
|
||||
To change the icon, you can pick [an icon name from here](../../core/src/trezor/ui/style.py#L50-L70) and specify it with the `-i` option:
|
||||
To change the icon, you can pick [an icon name from here](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L51-L71) and specify it with the `-i` option:
|
||||
|
||||
```sh
|
||||
trezorctl debug show-text -i RECEIVE "My hovercraft is full."
|
||||
```
|
||||
|
||||
The icons are defined as shapes, and you can specify a custom color [from the list](../../core/src/trezor/ui/style.py#L14-L47) with the `-c` option:
|
||||
The icons are defined as shapes, and you can specify a custom color [from the list](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L15-L44) with the `-c` option:
|
||||
|
||||
```sh
|
||||
trezorctl debug show-text -c RED "My hovercraft is full."
|
||||
|
||||
@ -103,14 +103,13 @@ the following marker:
|
||||
@pytest.mark.newcoin
|
||||
```
|
||||
|
||||
This marker must be registered in [REGISTERED_MARKERS] file.
|
||||
This marker must be registered in `REGISTERED_MARKERS` file in `tests` folder.
|
||||
|
||||
If you wish to run a test only on TT, mark it with `@pytest.mark.skip_t1`.
|
||||
If the test should only run on T1, mark it with `@pytest.mark.skip_t2`.
|
||||
You must not use both on the same test.
|
||||
|
||||
[pytest-random-order]: https://pypi.org/project/pytest-random-order/
|
||||
[REGISTERED_MARKERS]: ../../tests/REGISTERED_MARKERS
|
||||
|
||||
## Extended testing and debugging
|
||||
|
||||
|
||||
@ -97,8 +97,9 @@ sources, so your changes are immediately effective.
|
||||
|
||||
The included `trezorctl` python script can perform various tasks such as
|
||||
changing setting in the Trezor, signing transactions, retrieving account
|
||||
info and addresses. See the [docs/](docs/) sub folder for detailed
|
||||
examples and options.
|
||||
info and addresses. See the
|
||||
[python/docs/](https://github.com/trezor/trezor-firmware/tree/master/python/docs)
|
||||
sub folder for detailed examples and options.
|
||||
|
||||
NOTE: An older version of the `trezorctl` command is [available for
|
||||
Debian Stretch](https://packages.debian.org/en/stretch/python-trezor)
|
||||
@ -107,7 +108,9 @@ Debian Stretch](https://packages.debian.org/en/stretch/python-trezor)
|
||||
## Python Library
|
||||
|
||||
You can use this python library to interact with a Trezor and use its capabilities in
|
||||
your application. See examples here in the [tools/](tools/) sub folder.
|
||||
your application. See examples here in the
|
||||
[tools/](https://github.com/trezor/trezor-firmware/tree/master/python/docs/tools)
|
||||
sub folder.
|
||||
|
||||
## PIN Entering
|
||||
|
||||
|
||||
@ -163,7 +163,7 @@ Latest CI pipeline of master branch can be seen at [${latest_master}](${latest_m
|
||||
header_3 = "###"
|
||||
%>
|
||||
% for file, file_info in all_jobs_items:
|
||||
${header_2} ${file.stem.upper()} stage - [${file.name}](../../${file})
|
||||
${header_2} ${file.stem.upper()} stage - [${file.name}](https://github.com/trezor/trezor-firmware/blob/master/${file})
|
||||
% if file_info["overall_description"]:
|
||||
% for stage_overall_description_line in file_info["overall_description"]:
|
||||
${stage_overall_description_line}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user