STEP 1 - INPUT ROM, RAW DATA  (MR-Transformer on FPGA, guide's architecture)
=====================================================================

What it is
----------
  I-ROM (1 x 128)  -->  I_out     per clock one output
  Q-ROM (1 x 128)  -->  Q_out     per clock one output
  128 clocks in total. Next block: S2P1 (takes I_out) and S2P2 (takes Q_out).

Folder
------
  S1_input_rom_raw_src\
     hls_config.cfg        part xc7s50csga324-1, clock 10 ns, top = input_rom
     src\input_rom.h       data type (ap_fixed<25,8>), top function
     src\input_rom.cpp     the two ROMs + read loop (PIPELINE II=1)
     tb\input_rom_tb.cpp   checks 128 + 128 outputs against the Python values
     data\i_rom.dat        128 I values  (ROM contents, comma separated)
     data\q_rom.dat        128 Q values
     rom_data\            folded ROM-W', ROM-P', token, raw input + fold_check.py

Ports in the generated RTL
--------------------------
  ap_clk, ap_rst, ap_start, ap_done, ap_idle, ap_ready
  i_out_din  (25 bit)  + i_out_write   (= 1 in each clock a new I value is sent)
  q_out_din  (25 bit)  + q_out_write
  i_out_full_n, q_out_full_n           (input from the next block: 1 = ready)

How to run (same as B1)
-----------------------
  1. Copy the folder S1_input_rom_raw_src to  C:\Users\<you>\Documents\MRT_Blocks\MRT_Blocks\
  2. Vitis: File -> New Component -> HLS
        Name: s1_input_rom_raw
        Configuration File: Existing -> browse to S1_input_rom_raw_src\hls_config.cfg
        Top function: input_rom      Part: xc7s50csga324-1   -> Finish
  3. Flow panel: C SIMULATION -> Run
        expect  "*** STEP 1 INPUT ROM TEST PASSED ***"
  4. C SYNTHESIS -> Run
        expect  loop ROM_READ: II = 1, about 128-130 cycles, BRAM_18K = 2 (the two ROMs)
  5. C/RTL COSIMULATION -> Run    expect  "C/RTL co-simulation finished: PASS"
  6. Waveform: open the .wdb with xsim --gui (see the B1 steps).
     Tcl console line for a clean view:
        set g [add_wave_group "S1_per_clock"]; set p /apatb_input_rom_top/AESL_inst_input_rom; add_wave -into $g $p/ap_clk; add_wave -into $g $p/ap_start; add_wave -into $g -radix dec $p/i_out_din; add_wave -into $g $p/i_out_write; add_wave -into $g -radix dec $p/q_out_din; add_wave -into $g $p/q_out_write; add_wave -into $g $p/ap_done
     You should see i_out_write = 1 and a new i_out_din / q_out_din value on every clock.

About the ROM data - RAW signal, no mean / std
-----------------------------------------------
  Model  : TransformerNoConv best_model.pt (RML2016.10a, 3 encoders, 92.59 % at +18 dB, 601,995 parameters)
  Signal : QPSK, 18 dB, dataset index 199018 (same as the v4 design)
  i_rom.dat / q_rom.dat hold the RAW I/Q samples (about +-0.01).
  The function (raw - channel_mean) / channel_std is REMOVED from the design.
  Its effect is merged into the later ROMs (no retraining):
     ROM-W'  = W / std          -> rom_data/rom_w_folded.csv  (128 x 32)
     ROM-P'  = P + bias - W*mean/std (rows 1..8), row 0 = P[0]
                                -> rom_data/rom_p_folded.csv  (9 x 128)
     Token   (unchanged)        -> rom_data/token.csv         (1 x 128)
  rom_data/fold_check.py proves it: folded path vs Token_position_output
  max|err| = 9.1e-13, the same as the normal path (see fold_check_result.txt).

  Data format: ap_fixed<25,1>  (1 sign bit, 24 fraction bits, step 6.0e-08)
  Expected C-sim: max|err| about 3e-08, tol 1e-06.
