Deadlock-safe mode

[da-gazzi]

Deadlock-Safe Read Mode

Summary

• Add an optional, runtime-configurable mode that prevents iDMA read requests
  from overcommitting the backend dataflow buffers.
• Avoid read/write deadlocks caused by issuing more read data than the
  byte-lane FIFOs can hold while the write path is backpressured.
• Preserve the existing unrestricted behavior when deadlock-safe mode is
  disabled.

Backend

• Add a read reservation gate between the read metadata FIFO and the
  protocol-specific read module.
• Track the theoretical occupancy of every byte-lane FIFO independently.
  Each accepted read-address request reserves exactly the entries required by
  its byte count and starting lane; entries are released as bytes leave the
  dataflow buffer.
• Admit a read request in deadlock-safe mode only when all affected lanes have
  sufficient capacity for its complete response.
• Continue accounting for unrestricted requests so the mode can safely change
  between pipelined transfers.
• Keep current-cycle buffer pops out of the admission decision to avoid a
  combinational path from the dataflow output back to read-address valid.
• Add assertions for counter integrity, request sizing, and parameter validity.

Legalization And Configuration

• Add deadlock_free to the backend option structure and propagate it through
  the register, descriptor, synthesized, midend, legalizer, backend, and
  transport-layer interfaces.
• In deadlock-safe mode, enable source burst-length reduction and clamp each
  legalized read burst to the per-lane buffer capacity. This guarantees that
  an individual request can be reserved without overflowing a lane FIFO.
• Disable the mode when the hardware legalizer is not present, since compatible
  burst sizing cannot then be guaranteed by the backend.
• Expose the option through the register frontend and descriptor flags while
  keeping it disabled by default for compatibility.
• NOTE: for improved performance, it is recommended to manually set a maximum burst length that is less than the buffer depth. Otherwise, the burst length will be set to BufferDepth and AR bursts can only be submitted when the buffer is fully drained, which introduces bubbles.

Integration And Verification

• Extend generated backend type metadata and transport-layer plumbing with the
  byte count, starting lane, and mode bit required for reservation decisions.
• Register the new reservation-gate RTL source in Bender.
• Update descriptor and register-frontend documentation and testbench stimulus
  to encode and propagate the new configuration bit.

[taitashaw]

Reading idma_read_reservation_gate.sv at HEAD (2766d33), the unaligned case looks handled correctly. complete_lane_rows = num_bytes_i >> LaneWidth gives the full rows and byte_remainder = lane_idx_t'(num_bytes_i) the tail, then per lane lane_distance = lane - start_lane_i (wrapping in lane_idx_t) with lane_reservation = complete_lane_rows + (lane_distance < byte_remainder). That places the +1 remainder entries on exactly the byte_remainder lanes starting at start_lane_i, cyclically, so a non zero start offset reserves the right lanes.

On the "theoretical occupancy" question: it is tracked, not measured. Admission compares a modeled per lane counter, projected_usage = lane_usage[lane] + lane_reservation[lane] <= BufferDepth, with the same cycle pop deliberately left out of available_capacity (comment at lines 91 through 93) to avoid the ar_valid to w_ready combinational loop, so the check is conservative. The counter is only decremented by buffer_pop_i (buffer_out_handshake, transport tpl line 308).

So safety rests on one thing the gate does not check directly: that the R data actually pushed into each byte lane FIFO matches (num_bytes_i, start_lane_i) captured at AR time. Only NoLaneUsageUnderflow catches a mismatch, and only indirectly, via cumulative pops exceeding reservations. I did not trace the read shifter, so I cannot confirm the push time lane mapping always equals the AR time reservation for an unaligned later burst. If those can diverge, the counter under reserves and a lane FIFO can still overflow. An assertion binding the pushed lane strobe to the reserved lanes would close that gap.