From f4f8c9e6c609cfc504a0b5e632fa61a03462d55b Mon Sep 17 00:00:00 2001
From: Michael Cardell Widerkrantz <mc@tillitis.se>
Date: Fri, 30 May 2025 18:07:29 +0200
Subject: [PATCH] doc: Update Building & flashing docs

- Point out where to find tools.

- Add some description that we assume a Linux dist.

- Move the make targets around: make flash builds and flashes the
  entire thing so someone who just want to exactly that can use it
  right away.

- Explain what kind of hardware the USB controller is.

- Add a description on how to be able to use chprog without being
  root when running chprog.
---
 README.md | 59 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 35 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index e92df02..11dc8fa 100644
--- a/README.md
+++ b/README.md
@@ -87,35 +87,30 @@ but keep our own copy of it in the repo. See below.
 
 ## Building & flashing
 
+These instructions assume you're using a Linux distribution. Most of
+them also assume you're using our OCI image
+[tkey-builder](https://ghcr.io/tillitis/tkey-builder). If you want to
+run native tools, look in `contrib/Dockerfile` and
+`contrib/buildtools.sh` for the tools and versions to use.
+
 ### FPGA
 
 You need a [TKey
-Unlocked](https://shop.tillitis.se/products/tkey-not-provisioned) and
-a [TKey Programmer
-Board](https://shop.tillitis.se/products/tkey-dev-kit) to use this on
-real hardware.
+Unlocked](https://shop.tillitis.se/products/tkey-not-provisioned), a
+[the TP1 TKey Programmer
+board](https://shop.tillitis.se/products/tkey-dev-kit), and probably a
+[Blinkinlabs CH55x Reset
+Controller](https://shop-nl.blinkinlabs.com/products/ch55x-reset-controller)
+to use this on real hardware.
 
-Building is probably easiest using make and Podman. Do this to see all
-targets:
+Building is probably easiest using make and Podman.
+
+To build everything and then flash the resulting bitstream with the
+testloadapp in app slot 0 and the partition table copies in one go,
+place the TKey Unlocked in the TP1, then do:
 
 ```
 cd contrib
-make
-```
-
-Build the entire FPGA bitstream, which includes the firmware, using
-Podman:
-
-```
-cd contrib
-make run-make
-```
-
-To flash the bitstream, the testloadapp in app slot 0 and the
-partition table copies in one go, place the TKey Unlocked in the TP1,
-then do:
-
-```
 make flash
 ```
 
@@ -123,11 +118,21 @@ This uses the make target `prog_flash` in
 `hw/application_fpga/Makefile` behind the scenes, but mounts your TP1
 device into the container.
 
+To see all targets:
+
+```
+cd contrib
+make
+```
+
 See the [Tillitis Developer Handbook](https://dev.tillitis.se) for
 more.
 
 ### USB Controller
 
+The TKey uses a WCH CH552 chip as a USB controller. It has its own
+firmware.
+
 Build:
 
 ```
@@ -137,8 +142,8 @@ cd hw/usb_interface/ch552_fw
 make
 ```
 
-To flash the controller you need hardware like the [Blinkinlabs CH55x
-Reset
+To flash the controller with new firmware you need hardware like the
+[Blinkinlabs CH55x Reset
 Controller](https://shop-nl.blinkinlabs.com/products/ch55x-reset-controller)
 and a USB-A to USB-C converter.
 
@@ -146,6 +151,12 @@ and a USB-A to USB-C converter.
 
 You also need [chprog](https://github.com/ole00/chprog).
 
+The bootloader identifies itself as USB VID 4348, PID 55e0. To be able
+to access it and run `chprog` without root you need to allow your user
+to access it. Place `contrib/99-tillitis.rules` in `/etc/udev/rules.d`
+and run `udevadm control --reload`. Now you can add your user to the
+`dialout` group and access it.
+
 1. Connect the Reset Controller to your computer through "DUT\_IN"/"PC".
 2. Connect the TKey to "DUT\_OUT"/"DUT".
 3. Press the "Bootloader" button.