tilegrid fuzzer: document better

Signed-off-by: John McMaster <johndmcmaster@gmail.com>

fuzzers/005-tilegrid/README.txt

@@ -0,0 +1,32 @@
+This fuzzer creates the tilegrid.json bitstream database
+This database contains segment definitions including base frame address and frame offsets
+
+Example workflow for CLB:
+generate.tcl LOCs one LUT per segment column towards generating frame base addresses
+A reference bitstream is generated and then a series of bitstreams are generated each with one LUT bit toggled
+These are compared to find a toggled bit in the CLB segment column
+The resulting address is truncated to get the base frame address
+Finally, generate.py calculates the segment word offsets based on known segment column structure
+
+
+Environment variables
+
+XRAY_ROI
+This environment variable must be set with a valid ROI
+See database for example values
+
+XRAY_ROI_FRAMES
+This can be set to a specific value to speed up processing and reduce disk space
+If you don't know where your ROI is, just set to to include all values (0x00000000:0xfffffff)
+
+XRAY_ROI_GRID_*
+Optionally these as a small performance optimization:
+-XRAY_ROI_GRID_X1
+-XRAY_ROI_GRID_X2
+-XRAY_ROI_GRID_Y1
+-XRAY_ROI_GRID_Y2
+Which should, if unused, be set to -1, with this caveat:
+WARNING: CLB test generates this based on CLBs but implicitly includes INT
+Therefore, if you don't set an explicit XRAY_ROI_GRID_* it may fail
+if you don't have a CLB*_L at left and a CLB*_R at right
+

fuzzers/005-tilegrid/generate.tcl

@@ -34,6 +34,9 @@ if 0 {
 	set grid_max_y $::env(XRAY_ROI_GRID_Y2)
 }
 
+# LOC one LUT (a "selected_lut") into each CLB segment configuration column (ie 50 per column)
+# Also, if GRID_MIN/MAX is not defined, automatically create it based on used CLBs
+# See caveat in README on automatic creation
 foreach lut $luts {
 	set tile [get_tile -of_objects $lut]
 	set grid_x [get_property GRID_POINT_X $tile]
@@ -45,6 +48,7 @@ foreach lut $luts {
 	if [expr $grid_min_y < 0 || $grid_y < $grid_min_y] {set grid_min_y $grid_y}
 	if [expr $grid_max_y < 0 || $grid_y > $grid_max_y] {set grid_max_y $grid_y}
 
+	# 50 per column => 50, 100, 150, etc
 	if [regexp "Y(0|[0-9]*[05]0)/" $lut] {
 		set cell [get_cells roi/is[$lut_index].lut]
 		set_property LOC [get_sites -of_objects $lut] $cell
@@ -59,8 +63,10 @@ route_design
 write_checkpoint -force design.dcp
 write_bitstream -force design.bit
 
+# Get all tiles in ROI, ie not just the selected LUTs
 set tiles [get_tiles -filter "GRID_POINT_X >= $grid_min_x && GRID_POINT_X <= $grid_max_x && GRID_POINT_Y >= $grid_min_y && GRID_POINT_Y <= $grid_max_y"]
 
+# Write tiles.txt with site metadata
 set fp [open "tiles.txt" w]
 foreach tile $tiles {
 	set type [get_property TYPE $tile]
@@ -80,9 +86,11 @@ foreach tile $tiles {
 }
 close $fp
 
+# Toggle one bit in each selected LUT to generate base addresses
 for {set i 0} {$i < $lut_index} {incr i} {
 	set cell [get_cells roi/is[$i].lut]
 	set orig_init [get_property INIT $cell]
+	# Flip a bit by changing MSB 0 => 1
 	set new_init [regsub "h8" $orig_init "h0"]
 	set_property INIT $new_init $cell
 	write_bitstream -force design_[get_sites -of_objects [lindex $selected_luts $i]].bit

fuzzers/005-tilegrid/top.v

@@ -1,3 +1,4 @@
+//Need at least one LUT per frame base address we want
 `define N 100
 
 module top(input clk, stb, di, output do);