tools: Prune and document tools

Add a tools/README.md.

Remove:

- create_flash_image.py: role now overtaken by tkeyimage which does
  more.
- reset-tk1: Leftover from when production_test was removed.

Rename:

- makehex.py: Moved up one level.

LICENSES/spdx-ensure

@@ -41,7 +41,7 @@ hw/application_fpga/firmware.bin.sha512
 hw/application_fpga/fw/.clang-format
 hw/application_fpga/fw/testfw/Makefile
 hw/application_fpga/fw/tk1/Makefile
-hw/application_fpga/tools/makehex/makehex.py
+hw/application_fpga/tools/makehex.py
 hw/application_fpga/tools/reset-tk1
 hw/application_fpga/tools/tpt/README.md
 )

hw/application_fpga/Makefile

@@ -255,11 +255,11 @@ bram_fw.hex:
 	$(ICESTORM_PATH)icebram -v -g 32 $(BRAM_FW_SIZE) > $@
 
 firmware.hex: firmware.bin firmware_size_mismatch
-	python3 $(P)/tools/makehex/makehex.py $< $(BRAM_FW_SIZE) > $@
+	python3 $(P)/tools/makehex.py $< $(BRAM_FW_SIZE) > $@
 simfirmware.hex: simfirmware.bin simfirmware_size_mismatch
-	python3 $(P)/tools/makehex/makehex.py $< $(BRAM_FW_SIZE) > $@
+	python3 $(P)/tools/makehex.py $< $(BRAM_FW_SIZE) > $@
 testfw.hex: testfw.bin testfw_size_mismatch
-	python3 $(P)/tools/makehex/makehex.py $< $(BRAM_FW_SIZE) > $@
+	python3 $(P)/tools/makehex.py $< $(BRAM_FW_SIZE) > $@
 
 .PHONY: check-binary-hashes
 check-binary-hashes:

hw/application_fpga/tools/README.md

@@ -0,0 +1,33 @@
+# Tools
+
+We have developed some tools necessary for the build.
+
+- `app_bin_to_spram_hex.py`: Script used to include a device app in a
+  testbench simulation.
+
+- `b2s`: Compute and print a BLAKE2s digest over a file. Used for the
+  digest of the app in app slot 0 included in the firmware.
+
+- `default_partition.bin`: Default partition table for the flash.
+
+- `load_preloaded_app.sh`: Script to load two copies of the partition
+  table to flash and a pre-loaded to app slot 0 or 1. Needs
+  `default_partition.bin`, generated with `tkeyimage` and the binary
+  of the device app to load. Call like: `./load_preloaded_app 0
+  path/to/binary`.
+
+- `makehex.py`: Used to build hex version of firmware ROM for FPGA
+  bitstream build.
+
+- `patch_uds_udi.py`: Script used to patch in the Unique Device Secret
+  in `data/uds.hex` and the Unique Device Identifier in `data/udi.hex`
+  into the bitstream without having to rebuild the entire bitstream.
+
+- `run_pnr.sh`: Script to run place and route with `nextpnr` in order
+  to find a routing seed that will meet desired timing.
+
+- `tkeyimage`: Utility to create and parse flash images with a TKey
+  filesystem or the partition table
+
+- `tpt/tpt.py`: Utility to create the Unique Device Secret (UDS) and
+  Unique Device Identity (UDI) interactively.

hw/application_fpga/tools/create_flash_image.py

@@ -1,28 +0,0 @@
-#!/usr/bin/env python3
-
-import argparse
-
-FLASH_SIZE_BYTES = 1 * 1024 * 1024
-PRELOADED_APP_0_START = 0x30000
-
-
-def run(output_path, preloaded_app_0_path):
-    with (
-        open(output_path, "wb") as output_file,
-        open(preloaded_app_0_path, "rb") as preloaded_app_0_file,
-    ):
-        content = bytearray(b"\xFF") * FLASH_SIZE_BYTES
-        preloaded_app = preloaded_app_0_file.read()
-        content[
-            PRELOADED_APP_0_START : PRELOADED_APP_0_START + len(preloaded_app)
-        ] = preloaded_app
-        output_file.write(content)
-
-
-if __name__ == "__main__":
-    arg_parser = argparse.ArgumentParser()
-    arg_parser.add_argument("OUTPUT_PATH")
-    arg_parser.add_argument("PRELOADED_APP_0_PATH")
-    args = arg_parser.parse_args()
-
-    run(args.OUTPUT_PATH, args.PRELOADED_APP_0_PATH)

hw/application_fpga/tools/reset-tk1

@@ -1,15 +0,0 @@
-#!/bin/sh
-set -eu
-
-cd "${0%/*}"
-cd ../../production_test
-
-if [ ! -e venv ]; then
-  python3 -m venv venv
-  . ./venv/bin/activate
-  pip3 install -r requirements.txt
-else
-  . ./venv/bin/activate
-fi
-
-./reset.py