From c85b5311cd13961e707f401179675c7ce479141a Mon Sep 17 00:00:00 2001
From: dehanj <jobson@tillitis.se>
Date: Thu, 21 Mar 2024 14:31:12 +0100
Subject: [PATCH] Change filename personalize.py to patch_uds_udi.py

Also adding a more detailed explaination of what the script intends to
do
---
 hw/application_fpga/Makefile                  |  2 +-
 .../{personalize.py => patch_uds_udi.py}      | 25 ++++++++++++++++---
 2 files changed, 22 insertions(+), 5 deletions(-)
 rename hw/application_fpga/tools/{personalize.py => patch_uds_udi.py} (71%)

diff --git a/hw/application_fpga/Makefile b/hw/application_fpga/Makefile
index 2596039..a50eb94 100644
--- a/hw/application_fpga/Makefile
+++ b/hw/application_fpga/Makefile
@@ -248,7 +248,7 @@ application_fpga_par.json: synth.json $(P)/data/$(PIN_FILE)
 		--pcf $(P)/data/$(PIN_FILE) --write $@
 
 application_fpga.asc: application_fpga_par.json $(P)/data/uds.hex $(P)/data/udi.hex
-	UDS_HEX="$(P)/data/uds.hex" UDI_HEX="$(P)/data/udi.hex" OUT_ASC=$@ $(NEXTPNR_PATH)nextpnr-ice40 --up5k --package sg48 --ignore-loops --json $< --run tools/personalize.py
+	UDS_HEX="$(P)/data/uds.hex" UDI_HEX="$(P)/data/udi.hex" OUT_ASC=$@ $(NEXTPNR_PATH)nextpnr-ice40 --up5k --package sg48 --ignore-loops --json $< --run tools/patch_uds_udi.py
 
 application_fpga.bin: application_fpga.asc bram_fw.hex firmware.hex
 	$(ICESTORM_PATH)icebram -v bram_fw.hex firmware.hex < $< > $<.tmp
diff --git a/hw/application_fpga/tools/personalize.py b/hw/application_fpga/tools/patch_uds_udi.py
similarity index 71%
rename from hw/application_fpga/tools/personalize.py
rename to hw/application_fpga/tools/patch_uds_udi.py
index 2e5d86f..e1226ed 100644
--- a/hw/application_fpga/tools/personalize.py
+++ b/hw/application_fpga/tools/patch_uds_udi.py
@@ -1,17 +1,34 @@
 # -*- coding: utf-8 -*-
 #=======================================================================
 #
-# personalize.py
+# Copyright (C) 2023 Tillitis AB
+# Written by Myrtle Shah <gatecat@ds0.me>
+# SPDX-License-Identifier: GPL-2.0-only
+#
+# patch_uds_udi.py
 # --------------
 # Python program that patches the UDS and UDI implemented using
 # named LUT4 instances to have unique initial values, not the generic
 # values used during synthesis, p&r and mapping. This allows us to
 # generate device unique bitstreams without running the complete flow.
 #
+# Both the UDI and UDS are using bit indexing from 32 LUTs for each
+# word, i.e., the first word consists of bit 0 from each 32 LUTs and
+# so on.
+#
+# The size requirements for the UDI and UDS are specified as 1 bit (8
+# bytes of data) and 3 bits (32 bytes of data), respectively. The UDI
+# does not occupy the entire LUT4 instance, and to conserve resources,
+# the pattern of the UDI is repeated over the unused portion of the
+# LUT4 instance. This eliminates the need to drive the three MSB pins
+# while still achieving the correct output.
+#
+# In the case of UDS, a read-enable signal is present, and the most
+# significant bit serves as the read-enable input. This requires the
+# lower half of initialization bits to be forced to zero, ensuring
+# that the memory outputs zero when the read-enable signal is
+# inactive.
 #
-# Copyright (C) 2023 Tillitis AB
-# Written by Myrtle Shah <gatecat@ds0.me>
-# SPDX-License-Identifier: GPL-2.0-only
 #
 #=======================================================================