sync: WIN-BOWEI 2026-08-10 fpga_flash 增 Zynq BOOT.bin/QSPI 脚本，rtl-ip-replace 与 sim-rtl-flow 更新

- fpga_flash: 新增 build_zynq_boot.py / program_zynq_qspi.py（bootgen + program_flash，
  含备份、SHA-256/容量/marker 守卫）；vivado_env.py 增 resolve_sdk_dir（SDK_ROOT/SDK_PATH）；
  SKILL.md 补 Zynq 烧写流程，示例去掉写死的 D:\Xilinx\SDK\2018.1，改由 skills_env.md 解析。
- rtl-ip-replace: gen_ip.tcl / namespace_ip.py 更新。
- sim-rtl-flow: SKILL.md 与 run_sim_rtl_flow.py 更新。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

rtl-ip-replace/scripts/gen_ip.tcl

@@ -32,22 +32,58 @@ foreach ip $ips {
     }
     switch -- $c(type) {
         dist_mem_gen {
+            # mode {rom} (default) -- constant lookup table, asynchronous read.
+            # mode {dual_port_ram} -- LUTRAM, port A = write + async read (spo),
+            #   port B = async read (dpo), NO output registers.  Use this (not
+            #   blk_mem_gen) whenever the generated RAM needs a DEFINED read of
+            #   the pre-write word while the other port writes the same address:
+            #   a block-RAM primitive leaves the opposite port's read data
+            #   undefined on such a collision (PG058), distributed RAM does not.
+            #   The output registers / write-first read-back stay in the RTL
+            #   wrapper so latency and enb gating remain cycle-identical.
+            set dmode [opt c mode {rom}]
             create_ip -name dist_mem_gen -vendor xilinx.com -library ip -version 8.0 \
                 -module_name $name -dir $ipdir
-            set_property -dict [list \
-                CONFIG.memory_type        {rom} \
-                CONFIG.data_width         $c(width) \
-                CONFIG.depth              $c(depth) \
-                CONFIG.coefficient_file   $c(coe) \
-            ] [get_ips $name]
+            if {$dmode eq "dual_port_ram"} {
+                set_property -dict [list \
+                    CONFIG.memory_type        {dual_port_ram} \
+                    CONFIG.data_width         $c(width) \
+                    CONFIG.depth              $c(depth) \
+                    CONFIG.input_options      {non_registered} \
+                    CONFIG.output_options     {non_registered} \
+                    CONFIG.dual_port_address  {non_registered} \
+                    CONFIG.input_clock_enable {false} \
+                    CONFIG.default_data       {0} \
+                ] [get_ips $name]
+            } else {
+                set_property -dict [list \
+                    CONFIG.memory_type        {rom} \
+                    CONFIG.data_width         $c(width) \
+                    CONFIG.depth              $c(depth) \
+                    CONFIG.coefficient_file   $c(coe) \
+                ] [get_ips $name]
+            }
         }
         blk_mem_gen {
-            # SDP, common clock, READ_FIRST on the write port, no output register,
-            # ENA/ENB pins -- matches SimpleDualPortRAM_generic semantics exactly.
+            # mode {sdp_readfirst_commonclk} (default): SDP, common clock,
+            #   READ_FIRST on the write port, no output register, ENA/ENB pins --
+            #   matches SimpleDualPortRAM_generic semantics exactly.
+            # mode {tdp_writefirst_commonclk}: TRUE dual port, port A
+            #   WRITE_FIRST (write with read-back), port B READ_FIRST.
+            #   CAUTION: a BRAM primitive does NOT define the port-B read data
+            #   when port A writes the same address in the same cycle; only use
+            #   this when the design provably never collides.
+            set bmode [opt c mode {sdp_readfirst_commonclk}]
+            set mtype {Simple_Dual_Port_RAM}
+            set opa   {READ_FIRST}
+            if {$bmode eq "tdp_writefirst_commonclk"} {
+                set mtype {True_Dual_Port_RAM}
+                set opa   {WRITE_FIRST}
+            }
             create_ip -name blk_mem_gen -vendor xilinx.com -library ip -version 8.4 \
                 -module_name $name -dir $ipdir
             set_property -dict [list \
-                CONFIG.Memory_Type                {Simple_Dual_Port_RAM} \
+                CONFIG.Memory_Type                $mtype \
                 CONFIG.Assume_Synchronous_Clk     {true} \
                 CONFIG.Use_Byte_Write_Enable      {false} \
                 CONFIG.Write_Width_A              $c(width) \
@@ -55,12 +91,19 @@ foreach ip $ips {
                 CONFIG.Read_Width_A               $c(width) \
                 CONFIG.Write_Width_B              $c(width) \
                 CONFIG.Read_Width_B               $c(width) \
-                CONFIG.Operating_Mode_A           {READ_FIRST} \
+                CONFIG.Operating_Mode_A           $opa \
                 CONFIG.Enable_A                   {Use_ENA_Pin} \
                 CONFIG.Enable_B                   {Use_ENB_Pin} \
                 CONFIG.Register_PortB_Output_of_Memory_Primitives {false} \
                 CONFIG.Register_PortB_Output_of_Memory_Core       {false} \
             ] [get_ips $name]
+            if {$bmode eq "tdp_writefirst_commonclk"} {
+                set_property -dict [list \
+                    CONFIG.Operating_Mode_B {READ_FIRST} \
+                    CONFIG.Register_PortA_Output_of_Memory_Primitives {false} \
+                    CONFIG.Register_PortA_Output_of_Memory_Core       {false} \
+                ] [get_ips $name]
+            }
         }
         fifo_generator {
             # guided: mode field carries standard|fwft; depth/width from manifest

rtl-ip-replace/scripts/namespace_ip.py

@@ -8,7 +8,27 @@ coexist in one xsim `work` library for the dual-DUT cycle-true comparison.
   left untouched -- they are not declared here.
 
 Run LAST, after rom_to_ip.py / ram_to_ip.py / any hand edits (CORDIC, FIFO).
-Idempotent: modules already ending in _IP are skipped.
+Idempotent: a name already ending in _IP is never suffixed twice.
+
+INCREMENTAL RUNS -- THE BUG THIS DOCSTRING USED TO DESCRIBE AS A FEATURE.
+The rename set used to be "modules declared here whose name does NOT already end
+in _IP", i.e. it treated an already-suffixed declaration as nothing left to do.
+That is wrong the moment incr_plan.py restores previously-rewritten files and
+drops ONE freshly regenerated file beside them, which is the normal incremental
+case:
+
+    EncAddr.v    restored from the last run  ->  declares EncAddr_IP
+    DpdTrain.v   freshly generated           ->  declares DpdTrain, instantiates EncAddr
+
+`EncAddr` was no longer in the rename set, so the new DpdTrain.v kept its bare
+`EncAddr u_EncAddr (...)` while the file that defines it had been renamed away.
+The delivery then elaborated only because the dual-DUT bench compiled the GOLDEN
+tree into the same work library, where a bare `EncAddr` still exists; synthesis,
+which sees the delivery alone, failed with "module 'EncAddr' not found".
+
+The rename set is therefore built from the BASE NAME of every declaration --
+X_IP counts as X -- so a regenerated file is namespaced against the whole
+delivery, not just against the part of it that has not been namespaced yet.
 """
 import argparse, os, re
 
@@ -19,13 +39,20 @@ def main():
     d = os.path.abspath(a.rtl_ip_dir)
     files = [os.path.join(d, f) for f in os.listdir(d) if f.endswith('.v')]
 
-    mods = []
+    mods, already = [], []
     for p in files:
         for m in re.finditer(r'^\s*module\s+(\w+)', open(p, encoding='utf-8', errors='replace').read(), re.M):
-            if not m.group(1).endswith('_IP'):
-                mods.append(m.group(1))
+            n = m.group(1)
+            if n.endswith('_IP'):
+                already.append(n[:-3])
+                mods.append(n[:-3])      # base name: a restored file still OWNS this name
+            else:
+                mods.append(n)
     mods = sorted(set(mods), key=len, reverse=True)
     print('modules:', mods)
+    if already:
+        print('already namespaced (kept in the rename set as base names):',
+              sorted(set(already)))
 
     for p in files:
         txt = open(p, encoding='utf-8', errors='replace').read()