fix(axi4_mem_model): address self-review findings on PR #8

Self-review by code-reviewer agent flagged 3 HIGH findings:

  HIGH 1. Write-write conflict between loader and AXI4 FSM was
          undefined behaviour per SV NBA semantics across separate
          always blocks. Verilator happens to make the loader win
          but other simulators may differ.

          Fix: collapsed the standalone loader always block into the
          AXI4 write FSM's always block, sequenced as the LAST NBA in
          the procedural step. SV guarantees the last NBA in a single
          procedural block wins on conflicts — deterministic loader-
          wins-on-conflict semantics across all SV-compliant tools.

  HIGH 2. Misaligned loader_addr silently corrupted adjacent 32-bit
          slots (or wrote past bit 255 of the cache line at offsets
          29-31).

          Fix: added 'assert (loader_addr[1:0] == 2'b00) else $error'
          inside the loader branch. Misaligned addresses now produce
          a clear simulator error instead of silent corruption.
          Synthesis ignores the assertion.

  HIGH 3. Loader always block had no reset arm — inconsistent with
          every other always block in the file.

          Fix: subsumed by HIGH 1 fix. The merged always block
          inherits the AXI4 FSM's '@(posedge clk or negedge rst_n)'
          sensitivity list and reset semantics.

Also addressed LOW finding:

  LOW. README.md in src/popsolutions/axi4/ did not document the
       loader port contract, semantics, conflict resolution rule,
       alignment requirement, or synthesis tie-off convention.

       Fix: appended a 'Memory loader back-door' section covering
       all of the above.

Test status (verified locally, all green):
  axi4_mem_model:        6/6 pass (no regression)
  axi4_master_simple:    5/5 pass (no regression)
  core_axi4_adapter:     5/5 pass (no regression)
  inner_jib_top (IJ7EA): 2/2 pass (no regression — full sum_ints
                                   still runs end-to-end)

  18/18 across both repos.

Deferred MEDIUM findings (not blocking):
  - Test coverage gap for slots 3-7 within a cache line and explicit
    misalignment negative test. Will land as a follow-up PR with
    test_loader_all_slots and test_loader_misalign_errors.
  - Bit-width arithmetic note already covered by the new alignment
    assertion (the unsafe path now errors at runtime).

Signed-off-by: Marcos <m@pop.coop>

Author: Marcos

src/popsolutions/axi4/README.md

@@ -99,3 +99,40 @@ Signal naming convention:
 - [ADR-006 — Internal bus: AXI4](../../../docs/popsolutions/ADRS.md)
 - [ADR-002 — Project topology: MAST trunk + N Sails](../../../docs/popsolutions/ADRS.md)
 - [`docs/popsolutions/architecture/PARAMETER_TAXONOMY.md`](../../../docs/popsolutions/architecture/PARAMETER_TAXONOMY.md)
+
+## Memory loader back-door (since v0.2)
+
+`axi4_mem_model` carries three additional input ports for testbench /
+boot-ROM-style program loading:
+
+| Port | Width | Meaning |
+|---|---|---|
+| `loader_en` | 1 | Pulse high for one cycle to commit a write |
+| `loader_addr` | `phys_addr_width` | **Byte address**, must be 4-byte aligned |
+| `loader_data` | `data_width` (32 bits) | Datum to land in the addressed slot |
+
+**Semantics.** When `loader_en` is high on a rising clock edge, the
+32-bit `loader_data` is written into the correct slot of the targeted
+256-bit cache line. The slot is selected by `loader_addr[4:2]` (which
+of the eight 32-bit slots within the 32-byte line). The cache line
+index is `loader_addr[OFF_WIDTH +: IDX_WIDTH]`.
+
+**Conflict resolution.** The loader write is sequenced as the LAST
+non-blocking assignment in the AXI4 write FSM's `always` block, so on
+simultaneous loader-and-AXI4 writes to the same cache line the loader
+wins by SystemVerilog NBA semantics — not by simulator-specific cross-
+block ordering.
+
+**Alignment enforcement.** A simulation `assert` fires if `loader_addr`
+is not 4-byte aligned (would silently corrupt adjacent slots otherwise).
+
+**Synthesis.** Production builds tie `loader_en` to `1'b0`. The `if
+(loader_en) ...` branch becomes constant-false and standard synthesis
+tools (Yosys, Synopsys, Cadence) prune the entire loader path — no
+backing logic, no extra registers. The unused `loader_addr` and
+`loader_data` input ports may leave port-buffer cells in the netlist
+under hierarchical synthesis flows; this is negligible for our use.
+
+Test wrappers that don't need the back-door tie all three signals to
+constants in their instantiation — see `verif/axi4_master_simple/` and
+`verif/core_axi4_adapter/`.

src/popsolutions/axi4/axi4_mem_model.sv

@@ -96,11 +96,13 @@ module axi4_mem_model #(
     // bit position within the cache line where the 32-bit datum lands
     wire [OFF_WIDTH+2:0]  loader_bit_off  = {loader_byte_off, 3'b000};
 
-    always @(posedge clk) begin
-        if (loader_en) begin
-            mem[loader_idx][loader_bit_off +: data_width] <= loader_data;
-        end
-    end
+    // The actual loader write is sequenced AT THE END of the AXI4 write
+    // FSM's always block (see write side FSM below). This guarantees that
+    // when the loader and the AXI4 write fire in the same cycle on the
+    // same cache line, the loader's NBA is the LAST one in the procedural
+    // step and therefore wins by SystemVerilog NBA semantics — not by
+    // simulator-specific cross-block ordering. Production synthesis with
+    // loader_en tied to 0 prunes the loader branch entirely.
 
     // ====================================================================
     // Write side FSM
@@ -192,6 +194,23 @@ module axi4_mem_model #(
 
                 default: wr_state <= WR_IDLE;
             endcase
+
+            // ============================================================
+            // Loader back-door write — placed AT THE END of this block so
+            // its NBA fires after the AXI4 FSM's NBAs in the same step.
+            // Loader-wins-on-conflict is therefore deterministic.
+            // ============================================================
+            if (loader_en) begin
+                // Misaligned loader_addr would silently corrupt adjacent
+                // 32-bit slots (or write past bit 255 of the cache line).
+                // Catch this in simulation before it propagates.
+                assert (loader_addr[1:0] == 2'b00)
+                    else $error(
+                        "axi4_mem_model: loader_addr 0x%0h not 4-byte aligned",
+                        loader_addr
+                    );
+                mem[loader_idx][loader_bit_off +: data_width] <= loader_data;
+            end
         end
     end