From 6050412ed43fb846a81926cbe7f65502e889fa3a Mon Sep 17 00:00:00 2001
From: Martin Milata <martin@martinmilata.cz>
Date: Fri, 5 Feb 2021 17:36:25 +0100
Subject: [PATCH] docs: hardware CI test jobs

---
 ci/hardware_tests/README.md |  9 +--------
 ci/test-hw.yml              |  6 ++++++
 docs/ci/jobs.md             | 26 +++++++++++++++++++++++++-
 3 files changed, 32 insertions(+), 9 deletions(-)
 mode change 100644 => 120000 ci/hardware_tests/README.md

diff --git a/ci/hardware_tests/README.md b/ci/hardware_tests/README.md
deleted file mode 100644
index bdc890067..000000000
--- a/ci/hardware_tests/README.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Hardware tests
-
-Hardware tests are device tests that run against an actual device instead of an emulator.
-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. Currently T1 is supported
-but TT might follow.
-
-See `ci/test.yml` "hardware legacy device test" what exactly is run.
diff --git a/ci/hardware_tests/README.md b/ci/hardware_tests/README.md
new file mode 120000
index 000000000..a1f938592
--- /dev/null
+++ b/ci/hardware_tests/README.md
@@ -0,0 +1 @@
+../../docs/ci/jobs.md
\ No newline at end of file
diff --git a/ci/test-hw.yml b/ci/test-hw.yml
index c930f54b5..ef010efac 100644
--- a/ci/test-hw.yml
+++ b/ci/test-hw.yml
@@ -2,6 +2,12 @@ image: registry.gitlab.com/satoshilabs/trezor/trezor-firmware/trezor-firmware-en
 
 # Hardware
 
+# Currently it's not possible to run all regular TT tests without getting into
+# a state where the micropython heap is too fragmented and allocations fail
+# (often manifesting as a stuck test case). For that reason some tests are
+# skipped and the rest is divided into several groups with device reboots in
+# between them.
+# See also: https://github.com/trezor/trezor-firmware/issues/1371
 hardware core regular device test:
   stage: test
   only:
diff --git a/docs/ci/jobs.md b/docs/ci/jobs.md
index 8cb290a9b..38a1505f6 100644
--- a/docs/ci/jobs.md
+++ b/docs/ci/jobs.md
@@ -2,7 +2,7 @@
 
 ## Environment
 
-### Environment
+### environment
 
 Environment job builds the `ci/Dockerfile` and pushes the built docker image
 into our GitLab registry. Since modifications of this Dockerfile are very rare
@@ -89,3 +89,27 @@ build? This is most likely it.**
 
 UI tests for Core. See artifacts for a comprehensive report of UI. See [tests/ui-tests](../tests/ui-tests.html#reports)
 for more info.
+
+### hardware core regular device test
+
+[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.
+
+All hardware tests are run nightly on the `master` branch, as well as on push to branches
+with whitelisted prefix. If you want hardware tests ran on your branch, make sure its
+name starts with `hw/`.
+
+### hardware core btconly device test
+
+Also device tests on physical Trezor T but with Bitcoin-only firmware.
+
+### hardware legacy regular device test
+
+[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 btconly device test
+
+Also device tests on physical Trezor 1 but with Bitcoin-only firmware.