Skip to content

Instruction Cache

Overview

Status: RTL complete, interim documentation

The L1 instruction cache generated by cachegen, its organization, hit and miss paths, and maintenance operations.

Related: IA tasks: TOOLS-004, TOOLS-005, BP-123; Frontend demo: fd13_l1i: L1I Hit, Miss and MSHR Merge; Frontend demo: fd19_fencei_cbo: FENCE.I and cbo.inval

Working specification

This page shows the planning documents and specifications for RTL tag fe-1.0.0.

icache_decisions.md

planning/arch/icache_decisions.md on GitHub

L1 Instruction Cache Micro-Architectural Decisions

 FILE:    icache_decisions.md
 SOURCE:  session-068 rulings; a survey cited as
          docs/superscalar_ooo_survey.md (NOT IN THE TREE,
          see section 1); INFRA-012; TOOLS-003
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

L1I-owned behaviour: geometry, indexing, storage, the two interfaces it presents, miss handling, maintenance and prefetch.


0. Scope and companion documents

  l1i_ifu_interfaces.md     the PORTS of sections 4 and 7.
                            This file is behaviour; that one is
                            the port list, the handshake and the
                            maintenance path
  ftq_ifu_interfaces.md     the FTQ <-> IFU boundary, specified
  ftq_decisions.md          FTQ-owned behaviour; section 0 states
                            the ICache position and needs the
                            amendment of L1I-2
  fe_decisions.md           front-end theory of operation; owns the
                            FE / TD-FE / FE-U registries
  pacino_cache.md           the generated description of the cgen
                            output tree, node l1i. GENERATED AND
                            DATED, not maintained; do not cite it
                            (PROJECT_CORE.md). Listed here as a
                            companion until session-072.

Written session-069; this list called them "Not yet written and cited here as stubs" until session-071:

  ifu_decisions.md          IFU-owned behaviour. Owns the line
                            buffer of L1I-14 (TD-IFU-7) and the
                            request pipeline the L1I latency sits in
  itlb_decisions.md         the ITLB. The L2 TLB below it is
                            mmu_decisions.md
  ibuf_decisions.md         the instruction buffer between IFU and
                            decode

REGISTRIES. This file owns L1I-1 through L1I-25, TD-L1I-1 through TD-L1I-9, and the items L1I-U1 through L1I-U7. OPEN: L1I-U7. L1I-U5 closed session-074. L1I-U1 is closed; L1I-U2, L1I-U3 and L1I-U4 were RULED session-069 (section 10.1, itlb_decisions.md, mmu_decisions.md); L1I-U6 was never issued. This line read "the open items L1I-U2 through L1I-U5 PLUS L1I-U7" (session-070), which listed three ruled items as open. Session-071. It does not duplicate the FE, TD-FE or FE-U registries; it does not use the IC- prefix, which is already an interface-check identifier in ftb_interfaces.md and sc_interfaces.md; and it does not use IF-, TD-IF- or IF-U, which are l1i_ifu_interfaces.md.

THE L1I IS A GENERATED MODULE. It is emitted by cgen from JSON configuration. This document is the SOURCE and the JSON is downstream of it: where a decision here has no field in the current configuration schema, the schema is what changes. Nothing here is scoped to what the tool emits today.

0.1 The three interfaces
  core   BOTH  to the IFU. Behaviour here, section 4; ports in
               l1i_ifu_interfaces.md 4 and 5
  maint  BOTH  to the IFU. Behaviour here, section 7; ports in
               l1i_ifu_interfaces.md 10. Same peer as core,
               separate port group and separate flow control
  mem    BOTH  to the L2. Specified here, section 5
  itlb   IN    the translated physical address. NAMED here,
               section 2.3; specified in itlb_decisions.md

There is no L1I-to-FTQ interface and there will not be one. The FTQ reaches the memory hierarchy through the IFU (ftq_ifu_interfaces.md), and ftq_decisions.md 0 records why. That argument is unchanged by L1I-2 below.


1. Geometry

THE SURVEY THIS DOCUMENT CITES IS NOT IN THE TREE. The header names docs/superscalar_ooo_survey.md; no such file exists, and PROJECT_CORE.md's description of docs/ lists none. The survey is the stated evidence for L1I-1 capacity and associativity, L1I-7 replacement and the L1I-12 MSHR count, and the Neoverse, Zen, XuanTie, Intel and XiangShan figures those rules cite appear nowhere else in planning/. The rulings stand as ruled; their evidence is recorded only here. Committing the survey, or recording where it lives, is outstanding. Session-072.

1.1 The numbers
  L1I-1   capacity 64 KiB, 8-way, 64-byte lines, 128 sets
  L1I-11  TWO BANKS, LINE INTERLEAVED. Demand fetch and the
          IFU-originated prefetch of L1I-19 would otherwise
          contend for one array port.

L1I-1 and L1I-11 are the INPUTS. Everything below is computed from them:

Derived Value From
sets 128 65536 / (8 * 64)
sets per bank 64 128 / 2
line bits 512 64 * 8
bytes per way 8192 65536 / 8

INFRA-012 CHECKED THIS AGAINST THE TOOL'S OWN DERIVATION and it agrees exactly, including the 1.2 decomposition below.

CAPACITY. 64 KiB is where current high-performance I-sides sit: every Neoverse and every Cortex-X, SiFive P870, XuanTie C910 and C930, XiangShan Kunminghu, and Intel from Redwood Cove onward. AMD holds 32 KiB and is the outlier among 8-wide machines, and does it with two independent fetch pipes each feeding its own decode cluster, which is not this design. Apple's 192 KiB is the other outlier. 32 KiB was the value in the initial pacino configuration and is below the class this machine targets.

ASSOCIATIVITY. 8-way is the common value; Kunminghu uses 4-way on the I-side against 8-way on the D-side, and that asymmetry is deliberate in designs that index virtually (section 2.2). Under PIPT the constraint that motivates it does not apply, so the I-side takes the same 8 ways as the D-side.

LINE SIZE. 64 bytes, matching every other node in pacino and every design in the survey except the IBM machines. Two 32-byte prediction blocks fit one line, which is the arrangement L1I-14 depends on.

1.2 Address decomposition

Fields are physical throughout (L1I-3). With 2 banks and line interleaving the bank select is taken OUT of the index rather than added beside it, so offset + index + tag == pa_bits still holds.

  offset   PA[5:0]     6 bits
  index    PA[12:6]    7 bits
  bank     PA[6]       1 bit    line interleaved
  setidx   PA[12:7]    6 bits   64 sets per bank
  tag      PA[pa_bits-1:13]     pa_bits - 13 bits
  L1I-20  pa_bits is 36. Ruled session-068, applied by TOOLS-003.
          XiangShan Kunminghu implements 36 under Sv39. RVA23
          does not fix it: Sv39 bounds it through the PTE's PPN
          field and the implementation chooses.

AT THE L1I-1 GEOMETRY the tag is 23 bits and the tag array is 128 * 8 * (23 + 1 valid) = 24576 bits.

THE CONFIGURED GEOMETRY IS L1I-1. The node carried 32 KiB with one bank, index 6 bits and tag 24, until the section 9 capacity and bank changes were applied; the emitted l1i is 64 KiB, 8-way, two banks, tag 23 (PROJECT_STATUS.md, Session-068). This paragraph said pacino "still carries 32 KiB with one bank" while section 9 marked both changes DONE. Session-071.


2. Indexing and translation

2.1 The decision
  L1I-3  The L1I is PHYSICALLY INDEXED AND PHYSICALLY TAGGED.
         Translation completes before the array is indexed.
2.2 Why not VIPT

VIPT works without alias handling only when index+offset fits inside the page offset, because those bits are untranslated. At 4 KiB pages the page offset is PA[11:0] and index+offset spans capacity/ways bytes:

  32 KiB 8-way    4096 bytes/way   [11:0]   0 alias bits
  64 KiB 8-way    8192 bytes/way   [12:0]   1 alias bit
  64 KiB 4-way   16384 bytes/way   [13:0]   2 alias bits
  64 KiB 16-way   4096 bytes/way   [11:0]   0 alias bits

At the L1I-1 geometry VA[12] is a translated bit, so two virtual addresses mapping to one physical line index two different sets.

For READ TRAFFIC that is benign: a duplicate line is wasted capacity, and with no write path there is no stale-data hazard. It is not benign for INVALIDATION. A cbo.inval naming a physical address does not know VA[12], so it must clear every aliasing set or leave a stale instruction line behind, and one stale instruction line after a FENCE.I is a correctness failure. Section 7 is therefore where the cost of VIPT would have landed.

Three configurations avoid it: 64 KiB 16-way (pays 16 comparators and a 15-bit PLRU state for nothing else), 32 KiB 8-way (pays capacity), or PIPT. PIPT was taken. It costs a translation ahead of the array, which the decoupled front end absorbs (2.4), and it makes the capacity and associativity choices free of the constraint entirely.

Kunminghu runs 64 KiB 4-way, which is two alias bits, so the aliasing configuration is shippable. It is not cheaper here.

2.3 The ITLB boundary
  L1I-4  The L1I receives a PHYSICAL address on its core
         interface. It performs no translation and holds no
         translation state.

The ITLB is above the L1I, in the fetch path, and is owned by itlb_decisions.md. What the L1I requires of it:

  T1  the physical address, valid, in the cycle the request is
      presented
  T2  a fault indication travelling with the request rather than
      through the L1I, so a translation fault does not become a
      cache access. The L1I never sees a faulting request
  T3  no L1I involvement in ITLB fill, shootdown or ASID
      management

T2 places the fault path between ITLB and IFU. The L1I has no exception behaviour of its own beyond what section 5 returns from the L2.

2.4 Latency
  L1I-5  Hit latency is 2 cycles. Tag compare is in the cycle
         after the array read (tag_compare_stage next_cycle).
         Hit THROUGHPUT is one request per cycle, pipelined.

Two is an array-timing figure: tag read, compare, way select and data mux at 64 KiB do not close in one clock at the frequency this machine targets, and forcing them to is what caps frequency.

LATENCY IS NOT THE FETCH-PATH NUMBER. Translation is a stage above the array (2.3), so the path from PC to instruction data is the ITLB latency plus 2. Record both; a reader taking 2 as end-to-end will size the IFU pipeline short.

Latency is not on the dependent-load critical path that produces the published 3- and 4-cycle L1D figures in the survey. On the I-side the FTQ run-ahead absorbs it (ftq_decisions.md 5.1), which is what the decoupled front end is for. THROUGHPUT is the figure that matters, and it is one 64-byte line per cycle.


3. Storage and replacement

  L1I-6  tag_array and data_array are inferred SRAM with
         registered read. valid_bits and replacement_bits are flop
         files with combinational read, cleared by reset.
  L1I-7  Replacement is tree-PLRU, 7 bits per set for 8 ways.
  L1I-8  Arrays are per-way with parallel access
         (array_per_way, parallel).

Flop-file valid bits are what makes reset clear the cache in one cycle. The l2 node declares its valid bits as SRAM and walks the sets after reset to clear them through an invalidate port; the L1I is small enough not to need that, and section 7's invalidate_all uses the same reset-branch clear.

Tree-PLRU out of reset selects way 0, so a cold set fills from way 0 upward. No entry is valid until written, so replacement state is not consulted before it is meaningful.

REPLACEMENT POLICY IS RARELY PUBLISHED and the survey carries only one data point: XuanTie C910 ships FIFO on both L1s. Tree-PLRU is the assumed policy everywhere else and is what the other pacino L1 uses. No case was found for revisiting it.


4. The core interface, to the IFU

4.1 Shape
  L1I-9   The core interface returns ONE FULL CACHE LINE, 64
          bytes, per request. The data path is 512 bits.
  L1I-10  Up to SIXTEEN requests may be outstanding, matching
          the sixteen MSHRs of L1I-12.

The port in the initial pacino configuration was 32 bits wide with one outstanding request. That is a test-agent port. It cannot feed an 8-wide front end, and a single outstanding request collapses the decoupling the FTQ exists to provide: the FTQ runs up to 64 entries ahead precisely so fetch can be pipelined across misses, and a blocking port serialises that back down.

THE PORT COUNT AND THE MSHR COUNT ARE THE SAME NUMBER, and that is the point. A request can only miss if it is outstanding, so the port caps in-flight misses: at eight outstanding against sixteen MSHRs, half the miss-tracking capacity is unreachable and the configuration would claim depth the design cannot use. Sixteen each means one MSHR per outstanding request and no dead entries.

The MSHR count is the one with an anchor behind it (section 6); the port follows it rather than the reverse.

HIT-UNDER-MISS IS THE PRIMARY VALUE, not miss-under-miss. A blocking port stalls the whole fetch stream on one miss, which makes the FTQ's run-ahead unusable: the queue fills and nothing drains. No published I-side in the survey is blocking.

4.2 The line buffer is the IFU's
  L1I-14  The IFU holds the returned line and extracts the
          32-byte PREDICTION block. The L1I holds no last-line
          register and answers every request from the array.

Two 32-byte prediction blocks fit one 64-byte line, so on sequential fetch the second block is served from the IFU's buffer and never reaches the L1I. That halves the L1I request rate on straight-line code, which an L1I-side register would not do -- it would save array power but the request would still cross the port.

The IFU also already knows about redirects, so a buffered line for an abandoned path is dropped by the module that knows it is stale. An L1I-side register would hold it until displaced. Harmless, since the tag still matches, but it is state nobody owns.

The buffer is specified in ifu_decisions.md, not here. What this document fixes is that the L1I does not have one.

4.2a Uncached requests
  L1I-24  THE CORE REQUEST CARRIES AN UNCACHED BIT. A request with
          it set is a miss whatever the tags hold, is filled from
          the L2 like any miss, is answered like any request, and
          is NOT written into the array: no allocation and no
          replacement update. A cacheable request merged onto the
          same MSHR (L1I-13) still allocates. The bit is never set
          with the prefetch bit of L1I-21 (MMU-14). Port:
          l1i_ifu_interfaces.md IF-44. RULED session-076 (Jeff),
          with ifu_decisions.md IFU-21 reversed to route uncached
          fetch through the L1I. BUILT by BP-123.

          THE MERGE POLICY (l1i_ifu_interfaces.md IF-44a). An
          uncached request merges only onto an MSHR whose line is
          sure to come from memory, so it is never answered from the
          array; otherwise it takes its own MSHR. A cacheable
          request prefers an MSHR that allocates, and sets
          allocation on the one it merges onto, including in the
          fill's own cycle. An uncached access to a resident line
          names that line's way, so a merged cacheable fill installs
          over it, not beside it. Built by BP-123 (D6), accepted
          session-077 (Jeff). The merge in the fill's own cycle has
          a directed test since BP-125 (tb_l1i unc_merge_fill),
          TD#172 closed.

          ALLOCATES INCLUDES THE REPLACEMENT UPDATE. BP-125 found a
          cacheable request merged onto an uncached MSHR installing
          the line without moving the replacement state: the
          uncached lookup skips the update, the merged request makes
          no lookup, and the fill wrote none, so the installed line
          stayed the set's next victim. Fixed at the install: a fill
          from a register taken uncached updates the replacement
          state for its way, through a second writer on the meta
          array beside the compare stage; when both name one set in
          one cycle the install's way is applied on top of the
          compare stage's value. A cacheable register's own install
          makes no second update. BUILT by BP-125 (D1), accepted
          session-077 (Jeff). That gate has no check; TD#177.
  L1I-25  THE L2 MAY HOLD A LINE FETCHED UNCACHED. Correct while
          the L2 is the point of coherence: every agent reaches
          memory through it (up_i, up_d, and the walker edge of
          mmu_decisions.md MMU-2). An agent that writes memory
          without passing through the L2, such as a DMA master,
          reopens this. RULED session-076 (Jeff).

Forcing the miss means a line left in the array by a cacheable alias of the same physical page is not returned for the uncached access. Aliases with different cacheability are software's responsibility under Svpbmt, which prescribes fence iorw,iorw; cbo.flush; fence iorw,iorw between such accesses. Checked session-076 against the ratified Svpbmt text. That text does not make it correct for a cache to hold a non-cacheable line that a later non-cacheable write bypasses, which is why L1I-25 states its condition.

4.3 Ordering and alignment
  R1  Requests carry a physical address (L1I-4) and are LINE
      ALIGNED. The IFU performs the block extract, so the L1I
      never sees a sub-line address
  R2  Responses may return OUT OF ORDER with respect to requests.
      A response carries the identifier of the request it answers.
      Requiring in-order return would make one miss block every
      hit behind it, which is the blocking behaviour L1I-10
      removes
  R3  The RVA23 C extension permits a fetch to begin on any
      2-byte boundary. That is the IFU's problem, not the L1I's,
      and is why R1 can be line aligned
  R4  The physical address of R1 is produced BEFORE the request,
      in a pipeline the L1I does not see. L1I-3 requires
      translation to complete before the array is indexed, so
      the IFU translates a block in a pipeline that runs ahead
      of its fetch pipeline and queues the result
      (ifu_decisions.md IFU-23a, IFU-24, IFU-25). The L1I is
      unchanged by this: it still receives one line-aligned
      physical address per request and knows nothing about
      where it came from

R4 IS STATED BECAUSE OF WHAT PACINO DID NOT COPY. XiangShan solves the same ordering problem inside its ICache: its prefetch pipeline queries the MetaArray and the ITLB together and writes the hit WAY and the translation into a WayLookup queue, so its main pipe reads the data array with the way already resolved and the tag compare out of the fetch path.

Pacino keeps the translation pipeline in the IFU and leaves the MetaArray alone. The L1I is emitted by cachegen, and a second pipeline, an ITLB client and a lookup queue inside it is a cachegen change of the class INFRA-012 sized for one node: 4 configuration, 5 schema, 8 emitter items. So the tag compare stays where L1I-5 puts it, in the cycle after the array read, inside the fetch path.

If that is ever revisited, the change is to cachegen and to this document, not to the IFU: the IFU would stop needing its own translation queue and would read a way and a translation from the L1I instead.


5. The memory interface, to the L2

5.1 Inclusion
  L1I-15  The L1I is NON-INCLUSIVE with respect to the L2. The L2
          does not track, and cannot invalidate, L1I lines.

Inclusion buys exactly one thing: an external coherence probe can be filtered at the L2 without disturbing the caches above it, because the L2's tags are a superset. Nothing probes the I-side. RISC-V does not make the instruction cache coherent with the data side -- FENCE.I is the architectural mechanism and the burden is on software -- so there is no probe traffic to filter and inclusion is cost with no return.

THE l2 NODE'S inclusive DECLARATION IS WRONG FOR ITS up_i INTERFACE. Inclusion is a property of a pair of caches and the current configuration encodes it twice: l1i declares nine and l2 declares inclusive. This decision resolves the disagreement in the l1i node's favour. Whether the l2 remains inclusive of the L1D is an L2 question and is not decided here. TD-L1I-1.

  L1I-16  TL-UH. Channels A and D only. No B channel and no probe
          path, which follows from L1I-15.
  L1I-23  SIXTEEN FILLS MAY BE IN FLIGHT, one per MSHR. a_source
          carries the MSHR index and d_source names the fill it
          answers, so D beats may return in any order. Ruled
          session-068.

One fill at a time makes fifteen MSHRs wait on the sixteenth, and L1I-12's count was derived from a design sustaining 4 IPC out of L2. A serialised memory side does not deliver that.

A prior reading of the configuration reported the absence of channel B as a defect, on the strength of the l2 node's inclusive declaration. With L1I-15 the link is correct as configured and needs no change.

  data width      256 bits, 32 bytes per beat
  refill beats    2 per 64-byte line
  beat order      critical first
  bypass          to upstream, enabled

CRITICAL FIRST DOES NOT SHORTEN THE MISS THAT CAUSED IT. An earlier revision claimed it did -- that the requested 32 bytes return in the first beat and are forwarded upstream as they arrive, saving a beat. THAT IS WRONG under L1I-9. The core interface answers with a whole 64-byte line, so the L1I cannot respond until the second beat has landed, and the beat saved by forwarding is spent waiting for it. The two links are independent: TileLink is the L2 side only, and a saving on that side does not reach the core requester.

BOTH FIELDS STAY, for a smaller reason. The refill order is observable to a SECOND requester that hits the line while it is filling, and ordering the beats usefully costs nothing. That is the whole of the claim; do not restore the stronger one.


6. Miss handling

  L1I-12  16 MSHRs.
  L1I-13  4 targets per MSHR.
  L1I-17  No victim buffer and no separate fill buffer. Fills
          land in the array; the MSHR carries the in-flight
          state.

MSHR COUNT. The survey's I-side figures: XuanTie C910 tracks 8 line fills; Neoverse V2 has a 16-entry L1i fill buffer, which Arm states is enough MLP to sustain 4 IPC running out of L2; Intel Lion Cove has 24 L1 fill buffers; AMD Zen 5 tracks 124 outstanding L1 misses across two independent fetch pipes. The Neoverse figure is the usable anchor: it is a per-core I-side structure with a published sustained-IPC claim attached to it. This machine targets 8 issue against Arm's 4 IPC from L2, so 16 is a floor derived from a design achieving half the target, not a comfortable margin. The initial pacino value of 4 is below every published I-side in the survey.

TARGETS PER MSHR. An earlier revision derived 2 as the minimum from the line holding two prediction blocks. THAT DERIVATION IS VOID under L1I-14: the second block is served from the IFU's buffer and never becomes a request, so there is no second-half merge on sequential fetch.

What does merge: a redirect returning to a line already in flight, and a non-consecutive repeat of a line still in flight. The IFU issue policy is written, ifu_decisions.md TD-IFU-8, session-074: in order, and a block whose line matches the previous request reuses that request, so consecutive blocks in one line never make a second request.

4 STANDS, matching the l1d and l2 nodes. It is an unmeasured choice rather than a derived one; the TD#128 harness is where it gets measured.


7. Maintenance and invalidation

  L1I-18  The only invalidate path is CORE SIDE, arriving through
          the IFU. There is no memory-side invalidate; L1I-15.
          invalidate_line and invalidate_all are supported;
          flush_line and flush_all are not.

          IT COVERS THE IFU'S LINE BUFFER TOO. L1I-14 puts a
          64-byte line in the IFU and the L1I cannot see it, so
          an invalidate that clears the array alone leaves a
          stale instruction line -- the correctness failure 2.2
          invokes to reject VIPT, by another route. The IFU
          clears its own buffer AFTER the L1I reports the array
          clear complete, or a draining response repopulates it.
          l1i_ifu_interfaces.md IF-36.

There is nothing to flush. The L1I is read-only, holds no dirty state, and has no write path to the L2.

DRIVERS:

  M1  FENCE.I. Invalidates the whole cache. DRAIN THEN CLEAR:
      the clear is the reset-branch clear of the flop valid
      bits (section 3) and takes one cycle, but a fill in flight
      when it happens lands afterwards and re-validates a line
      the fence removed. Every outstanding request drains first.
      l1i_ifu_interfaces.md IF-31
  M2  Zicbom. RVA23 mandates it. cbo.inval names one line by
      address. Under PIPT that address indexes directly and no
      alias search is needed, which is the second return on
      L1I-3

M2 IS ROUTED. Whether cbo.inval reaches an instruction cache is not fixed by the architecture, and pacino routes it (l1i_ifu_interfaces.md IF-41); the CBIE trap and remap are resolved in the backend before the port. This read "M2 IS NOT FULLY SPECIFIED ... what is undecided is what drives it"; TD-L1I-2 closed session-076.

L1I-18 IS BUILT IN THE PACINO RTL, NOT IN CACHEGEN, by cachegen_decisions.md CG-4: BP-123 copied the emitted l1i into rtl/core/frontend/icache and added the maintenance ports there, with the uncached bit of L1I-24; tb_fe_top's fencei and cboinval programs cover M1 and M2 end to end. BUILT by BP-123, accepted session-077 (Jeff). CG-5 brings cachegen to match later (TD#173).


8. Prefetch

  L1I-19  Instruction prefetch requests ORIGINATE AT THE IFU. The
          L1I has no prefetcher and no FTQ-facing prefetch path.

This is the pacino form of ftq_decisions.md 6.1, restated so it survives the restructuring of L1I-2. That section defers prefetch and records its structural cost; the ICache becoming a sibling of the IFU does not make an FTQ-to-ICache prefetch path any more available, because the run-ahead stream between fetch_ptr and alloc_ptr exists only inside the FTQ and the IFU is behind fetch_ptr by construction.

8.1 Arbitration
  L1I-21  THE CORE REQUEST CARRIES A PREFETCH BIT. One bit,
          set by the IFU, distinguishing a prefetch from a
          demand fetch. It is the only asymmetry between the
          two: same identifier space, same response, and a
          miss is invisible either way.
  L1I-22  THE PREFETCH MSHR RESERVE IS TWO. A prefetch is
          accepted only while at least two of the sixteen
          MSHRs of L1I-12 are free. Ruled session-068.
  P1  Demand fetch always wins. A prefetch is issued only in a
      cycle no demand request needs the port. IFU-internal;
      the L1I does not see it
  P2  A prefetch never occupies an MSHR a demand miss requires.
      THE L1I ENFORCES THIS, on the bit of L1I-21: a prefetch
      is refused unless TWO MSHRs remain free. L1I-22
  P3  A dropped prefetch is not retried. It was a hint

P2 NAMES MSHR STATE, AND ONLY THE L1I HOLDS MSHR STATE. Without L1I-21 the rule has no enforcer: the IFU can throttle on its own outstanding count, but that is a proxy, and merging makes it a bad one -- merged requests occupy one MSHR and the IFU cannot tell.

THIS IS A PARAMETER, NOT PROSE. The configuration schema gains a prefetch_arbitration field with an enumerated value naming this policy, so the rule is emitted rather than reimplemented per node. A policy stated only in a document is a policy that drifts from the RTL. TD-L1I-3 tracks the schema addition. The request bit is declared by custom.request_qualifiers since TOOLS-004, which closed TD-L1I-9; this read that "no link field can express" it. Session-071.

8.2 The hint path exists

TileLink's TlAIntent is already in the shared opcode package and is non-binding by construction, which is exactly the semantics P2 and P3 require. No new link feature is needed to carry a prefetch to the L2.


9. Configuration mapping

What the l1i node in pacino_caches.json must carry for the decisions above. Values differing from the initial configuration are marked.

Field Value Decision Changed
capacity_bytes 65536 L1I-1 DONE
line_bytes 64 L1I-1
associativity 8 L1I-1
banks 2 L1I-11 DONE
bank_interleave_granularity line L1I-11 DONE
indexing PIPT L1I-3 DONE
read_miss allocate
replacement tree_plru L1I-7
inclusion nine L1I-15
mshrs 16 L1I-12 DONE
mshr_targets 4 L1I-13 DONE
victim_buffer_entries 0 L1I-17
fill_buffer_entries 0 L1I-17
beat_order critical_first L1I-16
bypass_to_upstream true L1I-16
read_latency_cycles 2 L1I-5
tag_compare_stage next_cycle L1I-5
invalidate_line true L1I-18
invalidate_all true L1I-18
flush_line false L1I-18
flush_all false L1I-18
prefetch_arbitration demand_first L1I-19 NEW

Core link, replacing the pe_port shape:

Field Value Decision Changed
read_width_bits 512 L1I-9 DONE
address_width_bits 36 L1I-20 DONE
outstanding_requests 16 L1I-10 DONE
write_width_bits 0 read only DONE
handshake.read_data_return valid_with_id R2 DONE
id_width_bits 4 R2 DONE
request_qualifiers prefetch L1I-21 DONE
error_response true R2 DONE
handshake.response_accept none R2 DONE

NOTES.

  DONE  APPLIED BY TOOLS-003. addressing.pa_bits and all four link
      address widths moved together in one change, and the
      T-10.addr_width checker rule now makes a disagreement an
      error on any edge touching a cache or memory node. A link
      address width is still a LITERAL -- the input language has
      no symbolic reference -- so this row must move by hand if
      pa_bits ever moves again. T-10 is what makes forgetting it
      an error rather than a silent zero-extend on one side and
      truncation on the other.
  n2  CLOSED by TOOLS-004. write_width_bits takes 0 and is no
      longer required; the emitted bundle drops the write
      channel. TD-L1I-7 closed.
  n3  NOT A NEW FIELD. An earlier revision named this row
      `out_of_order_response`. The capability already exists under
      another name: handshake.read_data_return takes valid_with_id
      beside valid_flag, id_width_bits already exists, and the
      signal builder already emits the request id and the response
      id and rvalid. Nothing behind the wires consumes them, which
      is an emitter gap and not a schema one. Do not add a second
      field saying what read_data_return already says.
      id_width_bits 4 covers the sixteen of L1I-10.
  n4  CLOSED by TOOLS-004. custom.request_qualifiers declares
      the bit and the L1I-22 reserve that reads it. TD-L1I-9
      closed. Whether the reserve belongs on the link or on the
      node beside mshrs is L1I-U7.

pe_port is shared with the LSU-to-L1D edge. The I-side and D-side core ports are different shapes, and A LINK CANNOT BE PARAMETERISED PER EDGE -- the schema and the resolver both put the link on the endpoints rather than on the edge -- so the I-side has its own link type, pe_port_i, declared by TOOLS-004 and named by the ifu-to-l1i edge; pe_port is unchanged on the lsu-to-l1d edge. TD-L1I-4 closed. This paragraph described the second link type as a proposal. Session-071.

SYSTEM FIELDS. pa_bits is a system-level field carried by every node's package. Changing it is not an l1i-local edit; see L1I-U1.

STILL INERT AFTER TOOLS-005: both maintenance fields, both fill fields, the buffer counts and inclusion. mshrs, mshr_targets, banks and bank_interleave_granularity reach emitted logic since TOOLS-004, and read_latency_cycles and tag_compare_stage since TOOLS-005, which consumed them without changing their values (so their Changed cells stay blank); indexing still shapes only a diagnostic. This read "STILL INERT AFTER TOOLS-004" and listed both timing fields. Session-071.


10. Open items and technical debt

10.1 Open, blocking specification
  L1I-U1  CLOSED. pa_bits is 36; L1I-20, section 1.2. Ruled
          session-068 and applied by TOOLS-003.

  L1I-U2  The ITLB. Entries, associativity, page sizes, ASID
          width, and its own latency. Under PIPT it is on the
          fetch path, so 2.4's stated latency is incomplete until
          this is decided.
          RECOMMENDATION, from the survey and from XiangShan: 32
          entries, fully associative, all three Sv39 page sizes,
          ASID tagged, 1-cycle hit. Fully associative removes the
          index-versus-page-size problem that a set-associative
          TLB has with mixed page sizes.
          RULED session-069 at 64 entries, otherwise as
          recommended: itlb_decisions.md ITLB-1 to ITLB-5. TD#115
          closed. This read "NOT RULED" until session-071. The page
          sizes are four, not three: Svnapot is mandatory and adds
          64 KiB (ITLB-3, mmu_decisions.md MMU-U7, session-071).

  L1I-U3  The page table walker's position in the pacino
          topology. This is a NODE GRAPH change, not a parameter.
          XiangShan's arrangement, read from its design
          documentation: the MMU is L1 TLBs (ITLB, DTLB), a
          repeater, an L2 TLB, PMP and PMA; the L2 TLB contains
          the page cache, the walker, a last-level walker, a miss
          queue and a prefetcher; walker requests are arbitrated
          and sent over TileLink to the L2 cache, whose 512-bit
          width returns eight PTEs per access. The L1 TLBs are
          NON-BLOCKING: a miss is returned to the requester, which
          reschedules the query until it hits.
          RECOMMENDATION: a shared L2 TLB node containing the
          walker, with a TileLink master edge into l2 alongside
          up_i and up_d, and a non-blocking ITLB that returns miss
          to the IFU for retry.
          RULED session-069 as recommended: the walker side is
          mmu_decisions.md, the ITLB side itlb_decisions.md ITLB-8
          to ITLB-10. It adds a node and an edge to pacino. This
          read "NOT RULED" until session-071.

  L1I-U4  PMP and PMA. XiangShan places them in the MMU boundary
          and the walkers check physical addresses before
          accessing memory, with an access fault returned up to
          the L1 TLB, which raises an instruction access fault to
          the request source. Nothing in pacino has a PMP or PMA
          node. RULED session-069: PMP and PMA are in the MMU
          (mmu_decisions.md MMU-10 to MMU-16), and every check
          completes before any L1I request is issued
          (itlb_decisions.md ITLB-12). This read "Where they sit is
          undecided" until session-071.

  L1I-U5  CLOSED session-074 by ifu_decisions.md TD-IFU-7: the
          IFU line buffer's depth is a parameter, default 16, one
          slot per request identifier. Its redirect behaviour is
          TD#134.

  L1I-U7  WHERE THE L1I-22 RESERVE IS DECLARED. TOOLS-004 put it
          on the link, beside the prefetch bit it governs. The
          alternative is the node, beside mshrs, which is what it
          counts and where TD-L1I-3 would put
          prefetch_arbitration. NOT RULED.
10.2 Technical debt
  TD-L1I-1  The l2 node declares inclusive while l1i declares
            nine. L1I-15 resolves it for the I-side; the l2 node's
            declaration must be qualified per upstream interface,
            or the schema must carry inclusion on the pair rather
            than on each node. Schema question, not an l1i one.

  TD-L1I-2  CLOSED. cbo.inval is ROUTED to the I-side,
            l1i_ifu_interfaces.md IF-41 (ruled session-068), and
            the CBIE gate is resolved in the backend before the
            port (13.1, assumption A5). This entry was not updated
            when IF-41 was ruled; found by ifu_notes.md 7, closed
            session-076. It read: "cbo.inval reaching the L1I
            depends on menvcfg.CBIE and on the execution
            environment ... Check against the privileged
            specification before the IFU-side maintenance path is
            built."

  TD-L1I-3  prefetch_arbitration does not exist in the
            configuration schema. Section 8.1 states the policy;
            the schema must gain the field or the policy lives
            only in prose and will drift.
            NARROWED by TOOLS-004: the L1I-22 reserve is now
            expressible, on the link, as custom.request_qualifiers.
            What the field would still add is P1 and P3, which the
            core link does not see. Where the reserve belongs is
            L1I-U7. Session-071.

  TD-L1I-4  CLOSED by TOOLS-004. pe_port_i is declared and the
            ifu-to-l1i edge names it; pe_port is unchanged on the
            lsu-to-l1d edge.

  TD-L1I-5  Nothing in the l1i configuration covers parity or ECC
            on the tag or data arrays. Absent from the schema
            rather than declined. A read-only cache can recover
            from a detected error by invalidating and refetching,
            which is cheaper than the D-side case and worth
            taking. Not decided.

  TD-L1I-6  CLOSED by TOOLS-003. The T-10.addr_width checker rule
            reports an error when a link's address width differs
            from addressing.pa_bits on any edge touching a cache
            or memory node, with a negative fixture proving it.

  TD-L1I-7  CLOSED by TOOLS-004. write_width_bits takes 0 and the
            emitted bundle drops the write channel.

  TD-L1I-8  CLOSED at the l1i boundary by TOOLS-004 and TOOLS-005.
            TOOLS-004: the MSHR file exists, the core adapter is no
            longer single-outstanding, the request identifier
            reaches every module on the path, and prefetch has a
            notion in the tool. TOOLS-005: the bank is pipelined at
            one hit per cycle, the two-cycle latency comes from
            read_latency_cycles and tag_compare_stage, and sixteen
            fills are in flight, measured at the emitted testbench.

            NOT DELIVERED END TO END: the sixteen fills serialise at
            the l2, whose up_i slave holds one transaction, TD#118.
            THE Zicbom HALF WAS AN RVA23 GAP, not a preference:
            L1I-18 had no hardware, TD#119. CLOSED in the pacino RTL
            by BP-123 (section 7); the emission still lacks it until
            CG-5. Session-077.

            This read "PARTLY CLOSED by TOOLS-004" with the three
            TOOLS-005 items as remaining. Session-071.

  TD-L1I-9  CLOSED by TOOLS-004. custom.request_qualifiers.

11. Consequential edits elsewhere

  L1I-2  THE ICACHE IS AN INDEPENDENT MODULE within the front-end
         boundary. It is a SIBLING of the IFU, not instantiated
         inside it, and the IFU exposes the interface to it.

Two documents state the superseded position and must be amended, not deleted:

  ftq_decisions.md 0    reads that the ICache is encapsulated
                        behind the IFU. Amend to the sibling
                        relationship. WHAT MUST SURVIVE is the
                        rest of the section: there is still no
                        FTQ-to-ICache interface, and the argument
                        for that is the fanout pressure XiangShan
                        solved with register replication being a
                        PD-phase problem rather than a logical
                        interface carried from the start.
                        Independence changes the module hierarchy;
                        it does not change that.

  PROJECT_CORE.md       repeats the same sentence in its planning
                        inventory. Same amendment.

  ftq_ifu_interfaces.md 8 item 1
                        carries the same sentence. ADDED TO THIS
                        LIST session-069; it was missed when the
                        list was written and the omission is why
                        it survived two sessions after the other
                        two were named.

  PROJECT_STATUS.md     Module Status, the frontend top row.
                        ADDED session-069. It said the L1I is
                        outside the front end top, which was a
                        first-revision FE-16 wording, not L1I-2.

All are PA-direct edits. None is in scope for an IA task.

STATUS session-069: PROJECT_CORE.md, ftq_decisions.md 0, ftq_ifu_interfaces.md 8 and PROJECT_STATUS.md are all amended.


12. Document History

  2026-08-27  Created, session-068. Geometry, indexing, storage,
              both interfaces, miss handling, maintenance and
              prefetch decided as L1I-1 through L1I-19. PIPT taken
              over VIPT, which makes the 64 KiB 8-way geometry free
              of the alias constraint and removes the multi-set
              invalidate that section 7 would otherwise have
              needed. The L1I is non-inclusive with the L2, so
              TL-UH is correct as configured and there is no
              back-invalidate. Capacity, associativity and MSHR
              count derived from the published survey rather than
              from the initial configuration; the core port
              rewritten from a 32-bit single-outstanding test port
              to a 512-bit line-at-a-time port. pa_bits, the ITLB,
              the walker topology and PMP/PMA are recorded OPEN
              with recommendations and are not decided here.

  2026-08-28  INFRA-012 folded in, session-068. The core port is
              SIXTEEN outstanding, not eight: at eight against
              sixteen MSHRs half the miss tracking was unreachable.
              5.2's critical-first justification WITHDRAWN -- under
              L1I-9's whole-line core response the requester that
              missed cannot see the saving, and the earlier text
              attributed an L2-side saving to the core side. Both
              fields stay for the weaker second-requester reason.
              L1I-11 was cited three times and never stated; it is
              now stated in 1.1, and `banks` is no longer listed as
              a derived value. Four section 9 corrections, all
              found by reading the tool: the schema's name is
              bank_interleave_granularity; `nine` is the schema's
              spelling of non-inclusive and l1i ALREADY declares
              it, so that row changes nothing and contradicted 5.1
              as written; a link address width is a literal and
              cannot read pa_bits; out_of_order_response is not a
              new field but the existing read_data_return
              valid_with_id plus id_width_bits. TD-L1I-6, -7 and
              -8 opened. TD-L1I-8 is the finding that matters:
              thirteen of twenty-two node fields validate, are
              carried, and move no emitted logic.

  2026-08-29  TOOLS-003 folded in, session-068. Eight amendments,
              two of them CORRECTNESS and found by writing down
              what the IFU must drive.

              7 M1's single-cycle FENCE.I is WRONG once sixteen
              requests can be outstanding: a fill in flight lands
              after the clear and re-validates a line the fence
              removed. Drain then clear. L1I-18 did not cover the
              IFU's own line buffer, so a fence could clear the
              array and leave a stale line in the IFU; it now
              does, and the buffer clear follows the array clear
              rather than the request.

              8.1 P2 named MSHR state the IFU cannot see. THE
              CORE REQUEST NOW CARRIES A PREFETCH BIT, L1I-21,
              and the L1I enforces P2 on it. The reserve size is
              L1I-22, two, and the schema cannot express the
              bit, TD-L1I-9.

              pa_bits is 36, L1I-20; L1I-U1 and TD-L1I-6 close.
              Section 9's address_width_bits row is 36 and
              applied. Section 6's targets-per-MSHR derivation is
              VOID under L1I-14 -- the second prediction block is
              served from the IFU buffer and never becomes a
              request -- so 4 is now an unmeasured choice. 0.1
              gains the maintenance interface as a fourth. L1I-14
              said fetch block where it meant prediction block;
              FETCH_BLOCK_BYTES is 64 and FTB_BLOCK_BYTES is 32.

  2026-09-02  L1I-23 added: sixteen fills in flight on the memory
              side, one per MSHR, keyed by a_source and d_source.
              Ruled session-068. One fill at a time made fifteen
              MSHRs wait on the sixteenth and did not deliver the
              L1I-12 count's own derivation.

              TOOLS-004 folded in. TD-L1I-4, -7 and -9 closed.
              TD-L1I-8 partly closed and its remainder is the
              whole of TOOLS-005: pipelined hit throughput, the
              two-cycle latency, and L1I-23. Section 9's applied
              rows marked DONE, notes n2 and n4 closed, and the
              inert-field paragraph re-measured. L1I-U7 opened on
              where the L1I-22 reserve is declared.

  2026-09-15  session-069. 4.3 gains R4: the physical address of
              R1 is produced in the IFU's translation pipeline,
              which runs ahead of its fetch pipeline, because
              L1I-3 forbids issuing a request in the cycle the
              lookup begins. The L1I is unchanged. Records what
              was NOT copied from XiangShan: the MetaArray and
              way lookup stay out of the prefetch path, so the
              L1I-5 tag compare remains in the fetch path.

  2026-09-19  session-071. Brought up to date with session-069 and
              TOOLS-005: L1I-U2, U3 and U4 recorded as ruled (the
              registry line and 10.1 still said open); the three
              documents written in session-069 no longer called
              unwritten; the configured geometry is L1I-1;
              TD-L1I-8 closed at the l1i boundary with TD#118 and
              TD#119 as the remainder; the timing fields are
              consumed since TOOLS-005.

  2026-09-20  session-072. D6: pacino_cache.md marked generated and
              not to be cited (PROJECT_CORE).

  2026-09-20  session-072. E10: L1I-U7 moved into numeric order.
              E12: the history section's split fences merged.

  2026-09-20  session-072. E22: Document History sorted into date order;
              newer entries had been appended at the wrong end.

  2026-09-20  session-072. D33: the survey the header cites is not in
              the tree; recorded in the header and at section 1.

  2026-10-01  session-074. L1I-U5 closed by TD-IFU-7 (line buffer
              depth 16, one slot per identifier). Section 6: the
              IFU issue policy is written, so the merge cases are
              named; 4 targets stands, unmeasured.

  2026-10-09  session-076, rulings (Jeff). 4.2a: L1I-24, the
              uncached request bit, no allocation; L1I-25, the L2
              may hold an uncached line while it is the point of
              coherence (Svpbmt checked). Section 7: M2 routed,
              TD-L1I-2 closed; L1I-18 built in the pacino RTL under
              CG-4.

  2026-10-09  session-077, after BP-123, rulings (Jeff). L1I-24 and
              section 7 built; L1I-24 gains the merge policy as
              BP-123 built it (D6), with its untested same-cycle
              case, TD#172. TD-L1I-8: the Zicbom gap closed in the
              pacino RTL.

  2026-10-10  session-077, after BP-125. L1I-24: the same-cycle
              merge tested (TD#172 closed); a merged cacheable
              install now updates the replacement state (D1), its
              no-second-update gate untested, TD#177.
cachegen_decisions.md

planning/arch/cachegen_decisions.md on GitHub

Cache Generator Decisions

 FILE:    cachegen_decisions.md
 SOURCE:  session-074
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

Owns the CG-N, CG-GN and CG-UN registries.


1. Scope

What pacino needs from tools/cachegen that cachegen does not provide today, and the decisions about closing the gap. Every pacino cache is in scope: l1i, l1d, l2 and mem. Every TOOLS task that changes cachegen cites this document.

tools/cachegen is a git submodule of pacino, with its own repository and its own test environment.

The cache specification is not here. It is icache_decisions.md and l1i_ifu_interfaces.md, and they do not change to fit the generator. pacino_cache.md is a generated snapshot of the output tree and is not cited (PROJECT_CORE.md).


2. Approach

CG-1  Pacino drives. Its cache requirements are specified in its
      own planning documents first. What cachegen supports today
      does not constrain them.
CG-2  A TOOLS task then adds to cachegen what it needs to emit
      the pacino design. Its first step is the shortest path to a
      working pacino cache structure. Generality beyond pacino
      comes after.
CG-3  The emitted output goes under tools/regress.sh BEFORE any
      generator change (CG-G1). Features are not added to the one
      part of the tree with no automatic check.
CG-4  The pacino cache RTL may depart from what cachegen emits
      wherever the design needs it. An IA task working on a
      pacino cache may restructure it as appropriate; it is not
      held to the generator's output.
CG-5  Departures are reconciled afterwards, by two tasks in
      order: a comparison task that records every difference
      between what cachegen emits and what the design is, as
      CG-G entries here, then a gap-fixing task that closes them
      in cachegen.

Session-074, Jeff. CG-3 to CG-5 resolve handoff-074 Task 2.


3. What cachegen emits today

Figures are session-068's (TOOLS-003 to TOOLS-005), not re-measured.

  config      testcases/pacino
  output      tools/cachegen/output/, seven nodes, all lint clean
  l1i         64 KiB, 8-way, 64-byte lines, 128 sets, 2 banks
              PIPT, tree-PLRU, pa_bits 36
              core port 512 bits, one line per request
              16 outstanding, out-of-order return by ID
              16 MSHRs, 4 targets each, 2 reserved for prefetch
              hit latency 2, one hit per cycle, 16 fills in flight
  l1i_pkg     L1iPaBits 36, L1iReqIdBits 4, L1iMaxOutstanding 16
  suites      cachegen unit 108 passed; l1i 67 checks

import/l1i/ is an older emission (32-bit address) and is not used.


4. Gaps

CG-G1 NO REGRESSION. tools/cachegen/output/ is outside every
      Makefile regress.sh finds, so nothing checks that the
      generator still emits something that builds. Close: a
      Makefile with lint and a smoke sim of the emitted l1i.
      regress.sh scans rtl/ and the output is inside the
      submodule, so where that Makefile lives is part of the
      task. The cachegen unit suite is believed to run in the
      submodule's own environment, not under regress.sh; the
      CG-5 comparison task confirms it. Handoff-074 Task 2.
      First, by CG-3.
CG-G2 NO MAINTENANCE PORTS. No node emits an invalidate port of
      any kind, so L1I-18 has no hardware. Two layers: the schema
      describes maintenance as four booleans on the node and has
      nowhere to describe a port (l1i_ifu_interfaces.md 14.2 S8),
      and no emitter emits one (14.3 E7). Schema first, then
      emitter. Required for RVA23: Zifencei and Zicbom are
      mandatory. Session-068 also routes FENCE.I to the D-side,
      so the l1d needs a port as well. TD#119; gates TD#136.
CG-G3 L2 SERIALISES MISSES. The l1i has 16 fills in flight; the
      l2's up_i slave is a four-state machine latching one
      source, so they complete one at a time. Two changes: a
      per-source record in the l2 slave adapter, and the
      pipelined control TOOLS-005 built for the l1i. cachegen
      cannot express the first: NodeCtx::nonblocking reads
      outstanding_requests off a custom link and returns false
      for TileLink, and no field says how many transactions a
      TileLink slave accepts. The performance gap: miss
      throughput is the l2's, not the l1i's, and a change to the
      l1i alone does not fix it. TD#118.
CG-G4 PIPELINE FIELDS ARE L1I ONLY. read_latency_cycles and
      tag_compare_stage shape the l1i pipeline; l1d, l2 and mem
      have none. 14.3 E5, Open Item 20.
CG-G5 REPLACEMENT TIMING. The replacement state moves in the
      compare stage, so back-to-back accesses to one set read
      the pre-update state, and two misses to one set may pick
      the same victim. Correct, lower quality. Moving it to fill
      time needs two writers of one port and an arbiter no field
      describes. TD#120.
CG-G6 NO TLB SUPPORT. The ITLB and the walker are written RTL
      (itlb_decisions.md, mmu_decisions.md); there is no L2 TLB
      (MMU-1, reversed session-077). The walker needs a
      TileLink edge into the l2 (L1I-U3), a topology change the
      generated l2 must accept.
CG-G8 NO UNCACHED REQUEST. The core link has one request
      qualifier, prefetch (custom.request_qualifiers, TOOLS-004).
      icache_decisions.md L1I-24 needs a second, uncached, that
      forces a miss and suppresses allocation. Ruled session-076.
CG-G7 PACKAGE TIE. pacino declares the L1I parameters in
      bp_defines_pkg; the emitted l1i_pkg is checked equal at
      elaboration (TD#122, TD-IF-1, session-074). Generating
      l1i_pkg from pacino's parameters would remove the check.
CG-G9 THE UNCACHED MERGE POLICY. Beyond CG-G8's qualifier, the
      pacino l1i's MSHR file carries the merge policy of
      icache_decisions.md L1I-24 and l1i_ifu_interfaces.md IF-44a:
      per-register taken-uncached and allocate state, an uncached
      request merging only onto a register sure to fetch from
      memory, a cacheable merge setting allocation, and the
      resident way named for an uncached access. Found by BP-123
      (D6, differences 4 and 5), recorded session-077. BP-125 added
      to it: a fill from a register taken uncached updates the
      replacement state, through a second writer port on
      l1i_meta_array (fp_en, fp_set, fp_way) fed from l1i_mshr
      (b_fil_rpl) through l1i_bank and l1i_ctrl. That is a second
      writer of the replacement state for this case, which CG-G5
      describes as needing an arbiter no field describes; the copy
      merges the two same-cycle updates instead (icache_decisions.md
      L1I-24).
CG-G10 THE EMITTED TESTBENCH'S EXIT STATUS. The emitted l1i_tb
      finishes the same way whether cg_report returns failures or
      not, so its exit status does not carry the result. The pacino
      copy adds $fatal on failure, as CLAUDE.md requires of a
      testbench. Found by BP-123 (difference 9), recorded
      session-077.
CG-G11 THE EMITTED MAKEFILE AND FILE LIST. The pacino copy uses its
      own Makefile. The emitted l1i.f lists pe_port_pkg,
      pe_port_i_pkg and the tl_* packages, which nothing in the l1i
      imports; only cgen_tl_pkg is needed. Found by BP-123
      (difference 11), recorded session-077.

4a. Departures under CG-4

CG-D1 BP-123 copies the emitted l1i into rtl/core/frontend/icache
      and changes it there: the maintenance ports of CG-G2 and the
      uncached bit of CG-G8. The copy is under tools/regress.sh, so
      the pacino l1i is regressed; CG-G1, the emitted output, is
      not closed by it. CG-5 compares the copy against cachegen and
      records any further difference here. Ruled session-076
      (Jeff).
  BUILT by BP-123, accepted session-077 (Jeff). The unchanged
  copy passed the emitted testbench as sim_l1i_emitted before
  any edit. BP-123's Results Capture lists eleven differences
  between the copy and the emission. CG-G2, CG-G8, CG-G9,
  CG-G10 and CG-G11 cover nine of them. The other two are not
  gaps: difference 1, each copied file's header carrying a
  COPIED block in place of the GENERATED block, is provenance;
  difference 10, tb_l1i and the two assertion files, is
  pacino's own verification, which CG-5's comparison records
  without requiring cachegen to emit it. The CG-5 tasks are
  TD#173.

5. Open

CG-U1 What CG-2's shortest path is: generator changes for the
      pacino l1i first, or the minimum gap set (CG-G1, CG-G2)
      and then the rest.

CG-U2 Order of CG-G3 to CG-G7 after the shortest path.


6. Bindings

L1I-18    Maintenance, CG-G2.
L1I-23    Sixteen fills in flight, CG-G3.
L1I-U3    The walker edge, CG-G6.
TD#118    CG-G3.
TD#119    CG-G2.
TD#120    CG-G5.
TD#122    CG-G7.
TD#136    Built in the pacino RTL by BP-123 under CG-D1 and closed
          session-077; cachegen still waits on CG-G2.
L1I-24    The uncached request, CG-G8; its merge policy, CG-G9.
TD#173    The CG-5 comparison and gap-fixing tasks for CG-D1.

7. Document History

  2026-10-09  session-076. CG-G8, the uncached request qualifier.
              Section 4a: CG-D1, BP-123 changes the pacino l1i in
              rtl/core/frontend/icache under CG-4. This document had
              no history section; its earlier changes are in
              PROJECT_STATUS.

  2026-10-09  session-077, after BP-123, rulings (Jeff). CG-D1
              built. CG-G9 to CG-G11 from BP-123's difference list.
              CG-G6: the walker, not an L2 TLB.

  2026-10-10  session-077, after BP-125. CG-G9: the install-time
              replacement update, a further difference for CG-5.
l1i_ifu_interfaces.md

planning/interfaces/l1i_ifu_interfaces.md on GitHub

L1I to IFU Interface

 FILE:    l1i_ifu_interfaces.md
 SOURCE:  icache_decisions.md, ftq_ifu_interfaces.md, INFRA-012,
          TOOLS-003, tools/cachegen schema and testcases/pacino
 STATUS:  DRAFT
 UPDATED: 2026-10-14
 CONTACT: Jeff Nye

The L1I's core interface, and the maintenance path that reaches it. icache_decisions.md section 4 states the SHAPE of the core boundary and stops: one full 64-byte line per request, sixteen outstanding, out-of-order response carrying an identifier. There is no port list, no handshake, no backpressure rule and no maintenance path. This file is those four.

DIVISION OF LABOUR. icache_decisions.md specifies BEHAVIOUR and this file specifies PORTS. Where a behaviour is already decided there it is cited by its L1I number and not restated.

The IFU side of every port here is BUILT by BP-116 (session-074), except the maintenance ports of sections 10 and 11 (TD#136) and ifu_l1i_req_uncached (IF-44, added session-076), which BP-123 BUILT, accepted session-077 (Jeff). BP-123 also built the L1I side of both in the pacino copy of the L1I at rtl/core/frontend/icache (cachegen_decisions.md CG-D1). What follows describes the cachegen emission, which CG-5 brings up to the copy. The L1I is a generated module; since TOOLS-004 and TOOLS-005 its emitted core port carries the 512-bit line, sixteen identifiers and sixteen fills at the l1i boundary (section 14.3), and the maintenance ports of sections 10 and 11 are still not emitted (E7, TD#119). This read that the emitter "cannot yet produce any of this (TD-L1I-8)". Session-071.


1. Scope

Covered: - the fetch request, IFU to L1I - the line response, L1I to IFU - backpressure, the outstanding limit and merging - the maintenance request, IFU to L1I, and its completion - the maintenance request that reaches the IFU from the backend - what a cachegen link definition can and cannot express of the above

Not covered:
- L1I internals. Geometry, replacement, MSHR structure and the
  memory-side link are `icache_decisions.md` 1, 3, 5 and 6
- the IFU line buffer's depth and redirect behaviour, which is
  L1I-U5 and belongs to `ifu_decisions.md`
- the ITLB. Named in `icache_decisions.md` 2.3 as T1, T2 and T3;
  owned by `itlb_decisions.md`, with its IFU boundary in
  `itlb_ifu_interfaces.md`. This read "which does not exist";
  both were written session-069. Session-071
- the FTQ to IFU boundary, which is `ftq_ifu_interfaces.md` and is
  neither contradicted nor duplicated here
- prefetch policy. L1I-19 puts the requester at the IFU, so the
  choice of what to prefetch is IFU-internal. The request itself
  DOES cross this boundary and carries one bit; section 4.4

REGISTRIES. This file owns IF-1 upward for its decisions and its protocol rules, IF-U1 upward for open items, and TD-IF-1 upward for technical debt. It does not use IC-, which is an interface-check identifier in ftb_interfaces.md and sc_interfaces.md; it does not use L1I-, which is icache_decisions.md; and it does not use FE-, TD-FE- or FE-U, which are fe_decisions.md.


2. Naming

This document carries no stage suffixes, a choice rather than a gap: the IFU pipeline IS defined, F0 to F3 plus WB (ifu_decisions.md IFU-9). This read "The IFU pipeline is not defined". Session-070. No suffixes, for the same reason and with the same intent as ftq_ifu_interfaces.md section 2. Ports are named by direction.

  ifu_l1i_<signal>    IFU -> L1I
  l1i_ifu_<signal>    L1I -> IFU
  cmt_ifu_<signal>    backend commit -> IFU, section 11
  ifu_cmt_<signal>    IFU -> backend commit

If the suffixes are ever added here, record the rename here.


3. Widths

  IF-1   The core interface carries a PHYSICAL BYTE address,
         PA_WIDTH bits wide. L1I-4. PA_WIDTH is 36, ruled
         session-068, and this file uses no other value.

  IF-2   The request identifier is REQ_ID_BITS wide, 4 bits, giving
         sixteen identifiers, one for each of the sixteen
         outstanding requests of L1I-10.

  IF-3   The response data path is one full cache line,
         L1I_LINE_BITS = 512. L1I-9. There is no narrower response
         and no partial line.
3.1 The parameters

STATUS, session-074. All fifteen are declared in bp_defines_pkg: the nine ITLB/MMU widths by BP-109, the six L1I names by BP-115. VA_WIDTH is 41 and PPN_WIDTH is now PA_WIDTH - 12. l1i_param_chk checks the six against l1i_pkg at elaboration; its lint and lint_neg targets run under regress.sh.

Before that ruling bp_defines_pkg.sv carried no physical address width at all. The 36 of IF-1 lived only in tools/cachegen/testcases/pacino/pacino_topology.json, as addressing.pa_bits.

The IFU is hand written and reads bp_defines_pkg. The L1I is generated and its constants are in l1i_pkg, under a different naming convention. The two must agree; l1i_param_chk makes them, BP-115.

  this file        bp_defines_pkg     l1i_pkg         value
  ---------------- ------------------ --------------- -----
  PA_WIDTH         BP-115             L1iPaBits          36
  L1I_LINE_BYTES   BP-115             L1iLineBytes       64
  L1I_LINE_BITS    BP-115             L1iLineBits       512
  L1I_OFFSET_BITS  BP-115             L1iOffsetBits       6
  REQ_ID_BITS      BP-115             L1iReqIdBits        4
  MAX_OUTSTANDING  BP-115             L1iMaxOutstanding  16
  GPA_WIDTH        BP-109             (no counterpart)    41
  GVPN_WIDTH       BP-109             (no counterpart)    29
  VPN_WIDTH        BP-109             (no counterpart)    27
  PPN_WIDTH        BP-109             (no counterpart)    24
  ASID_WIDTH       BP-109             (no counterpart)    16
  VMID_WIDTH       BP-109             (no counterpart)    14
  PERM_WIDTH       BP-109             (no counterpart)     8
  CAUSE_WIDTH      BP-109             (no counterpart)     5
  PMA_WIDTH        BP-109             (no counterpart)     4
  FAULT_GPA_WIDTH  BP-124             (no counterpart)    56

FAULT_GPA_WIDTH was added session-077, after BP-123: the width of a faulting guest physical address (mmu_decisions.md MMU-23), which can exceed GPA_WIDTH. It is declared by BP-124.

The rows below MAX_OUTSTANDING were added session-070, GVPN_WIDTH session-073. The ITLB interfaces declare ports against every one of them except GVPN_WIDTH -- itlb_ifu_interfaces.md 2 and itlb_l2tlb_interfaces.md 2 -- and none was defined in any package until BP-109. Same class as PA_WIDTH above. TD#122.

ALL NINE NOW HAVE VALUES, ruled session-073. Their sources:

  GPA_WIDTH   41  MMU-20, Sv39x4 guest physical
  GVPN_WIDTH  29  the G-stage VPN, GPA_WIDTH - 12. VPN_WIDTH is
                  VS-stage only and one parameter cannot serve
                  both stages
  VPN_WIDTH   27  Sv39 VA, three levels of nine
  PPN_WIDTH   24  PA_WIDTH - 12, from IF-1's 36
  ASID_WIDTH  16  ITLB-7, the Sv39 maximum
  VMID_WIDTH  14  ITLB-7, the Sv39x4 maximum
  PERM_WIDTH   8  the PTE low byte, V R W X U G A D. IL-8 names
                  executable, user and global and is not
                  exhaustive; carrying the byte whole needs no
                  rule about what the I-side drops and serves the
                  D-side client of IL-3 unchanged
  CAUSE_WIDTH  5  exception codes 0 to 31. The three causes of
                  IT-6 are 1, 12 and 20; 20 sets the width
  PMA_WIDTH    4  one bit per MMU-13 attribute: cacheable,
                  coherent, executable, idempotent. IT-10 returns
                  the EFFECTIVE four. The PBMT of IL-9a is a
                  separate two-bit field and is not this
  FAULT_GPA_WIDTH
              56  MMU-23: a VS-stage PTE's 44-bit PPN can form a
                  56-bit guest physical address that faults, and
                  Shtvala requires htval to carry it. Session-077

A PTE PPN field is 44 bits in Sv39 and PPN_WIDTH is 24, so a PTE whose PPN has any bit set above bit 23 names a physical address this implementation cannot form. Raised session-073, when nothing in mmu_decisions.md said the walker faults it. CLOSED by mmu_decisions.md MMU-28 (session-077): the walker raises an access fault and never truncates a PPN. Built by BP-123.

l1i_pkg carries REQ_ID_BITS and MAX_OUTSTANDING as L1iReqIdBits and L1iMaxOutstanding since TOOLS-004, which also added L1iMshrs, L1iMshrTargets, L1iMshrIdxBits, L1iMshrTgtBits, L1iMshrCntBits and L1iQualReserve. Nothing made the hand-written and generated sides agree until BP-115. This read that l1i_pkg has no counterpart because the emitter did not consume outstanding_requests or id_width_bits (INFRA-012 E2 and E3). Session-071. Section 14 says which of these a configuration change can supply and which cannot.

ADDING THESE PARAMETERS IS NOT THIS FILE'S ACT. This file is a specification and writes no RTL. TD-IF-1 carried the addition; BP-109 and BP-115 made it.


4. The fetch request, IFU to L1I

4.1 Ports
  ifu_l1i_req_val                              NEW
  ifu_l1i_req_rdy                              NEW   L1I -> IFU
  ifu_l1i_req_id      [REQ_ID_BITS-1:0]        NEW
  ifu_l1i_req_paddr   [PA_WIDTH-1:0]           NEW
  ifu_l1i_req_prefetch                         NEW   L1I-21
  ifu_l1i_req_uncached                         NEW   L1I-24

Six wires and two buses (five until session-076 added ifu_l1i_req_uncached). There is no read/write strobe, no write data and no byte enable: the L1I is read only (L1I-15, section 7 of icache_decisions.md), so a request is always a read and a field saying so would carry one constant value.

4.2 Rules
  IF-4   A request is presented when ifu_l1i_req_val is high, and is
         ACCEPTED in a cycle where ifu_l1i_req_val and
         ifu_l1i_req_rdy are both high. The IFU holds req_id and
         req_paddr stable from the cycle val rises until the cycle
         of acceptance.

  IF-5   ifu_l1i_req_paddr is LINE ALIGNED: paddr[L1I_OFFSET_BITS-1:0]
         is zero in every accepted request. 4.3 R1. The L1I does not
         mask the low bits and does not check them in synthesis; the
         L1I testbench asserts on them and the check is on the L1I
         side, not the IFU side, so an IFU defect is caught at the
         boundary it crosses.

  IF-6   ifu_l1i_req_id is allocated by the IFU from a free list of
         MAX_OUTSTANDING identifiers. An identifier is IN FLIGHT
         from the cycle its request is accepted until the cycle its
         response is presented. The IFU MUST NOT present an
         identifier that is in flight.

  IF-7   Until the response returns, the IFU holds, per in-flight
         identifier: the line buffer slot the response will land in,
         the FTQ index or indices the request serves
         (ftq_ifu_start_pc and ftq_ifu_idx of
         ftq_ifu_interfaces.md 4), and paddr[L1I_OFFSET_BITS-1:0]
         for the block extract of L1I-14. The RESPONSE DOES NOT
         RETURN THE ADDRESS, so the low offset bits exist only in
         the IFU and nowhere else.

WHY THE FULL BYTE ADDRESS AND NOT PA[35:6]. Six of the thirty-six wires carry a constant zero by IF-5, and dropping them would save them. Rejected. The ITLB delivers a byte physical address (2.3 T1) and the IFU's own block extract is byte granular, so a line-granular port would make the L1I's address a different quantity from every other address in the front end and put a shift at the boundary. It would also turn IF-5 from a checkable rule into a structural property, and a rule a testbench can check is worth more than six wires. The cachegen schema CAN express the rejected form (address_granularity takes line beside byte), so this is a choice and not a limitation; section 14 records it.

4.3 What the IFU must have before it issues
  IF-8   The IFU issues a request only when the ITLB has returned a
         VALID, NON-FAULTING physical translation for it (2.3 T1 and
         T2). An ITLB miss and an ITLB fault both mean NO REQUEST IS
         PRESENTED. Section 8 states what happens instead.
4.4 Prefetch uses this port
  IF-9   An IFU-originated prefetch (L1I-19) is presented on the
         ports of 4.1 with ifu_l1i_req_prefetch high. It consumes
         an identifier, it is answered with a line, and the IFU
         discards the line.

  IF-38  THE BIT AFFECTS ONLY ready. A prefetch is refused unless
         at least L1I-22's TWO MSHRs are free; see IF-39. Once
         accepted it is answered like any other request, on the
         same identifier space, with the same response and the
         same latency, and a miss remains invisible (IF-19).
4.5 Uncached requests
  IF-44  ifu_l1i_req_uncached high marks an UNCACHED request:
         icache_decisions.md L1I-24. It is otherwise an ordinary
         request on the ports of 4.1 -- line aligned (IF-5), one
         identifier, one line returned (section 5). The IFU sets it
         for a block whose effective type is not both cacheable and
         idempotent (itlb_ifu_interfaces.md IT-11) and presents it
         only under the commit gate of ifu_decisions.md IFU-22. It
         is never high with ifu_l1i_req_prefetch. Ruled session-076
         (Jeff), with IFU-21 reversed.

  IF-44a MERGING AN UNCACHED REQUEST (icache_decisions.md L1I-24).
         An uncached request merges only onto an MSHR whose line is
         sure to come from memory, so it is never answered from the
         array; otherwise it takes its own MSHR. A cacheable request
         prefers an MSHR that will allocate, and one that merges
         onto an uncached MSHR makes that fill allocate. An uncached
         access to a resident line names that line's way, so a
         merged cacheable fill installs over it, not beside it. None
         of this is visible at this boundary (IF-19, IF-20). Built
         by BP-123 (D6), accepted session-077 (Jeff). A merged
         cacheable fill also updates the replacement state
         (icache_decisions.md L1I-24), built by BP-125.

icache_decisions.md 8.1 splits across the boundary. P1, demand fetch always wins, is the IFU choosing which of its own requests to present and this interface does not see it. P2 NAMES MSHR STATE, AND ONLY THE L1I HOLDS MSHR STATE, so the bit exists to let the L1I enforce it. P3, a dropped prefetch is not retried, is the IFU's response to a refusal.

WITHOUT THE BIT the IFU would have to throttle on its own outstanding count, which is a proxy for MSHR occupancy and a poor one: merged requests occupy one MSHR and the IFU cannot tell.


5. The response, L1I to IFU

5.1 Ports
  l1i_ifu_rsp_val                              NEW
  l1i_ifu_rsp_id      [REQ_ID_BITS-1:0]        NEW
  l1i_ifu_rsp_data    [L1I_LINE_BITS-1:0]      NEW
  l1i_ifu_rsp_err                              NEW

There is no l1i_ifu_rsp_rdy.

5.2 Rules
  IF-10  A response is presented when l1i_ifu_rsp_val is high. THE
         IFU ACCEPTS IT IN THAT CYCLE UNCONDITIONALLY. There is no
         ready and no retry.

  IF-11  l1i_ifu_rsp_id names the request the response answers, and
         that identifier is retired by the presentation: it returns
         to the IFU's free list and may be reissued in the next
         cycle.

  IF-12  Responses MAY be presented IN ANY ORDER with respect to the
         requests that produced them. 4.3 R2. The identifier is the
         ONLY correlation; the IFU must not infer order from
         anything else.

  IF-13  At most ONE response is presented per cycle.

  IF-14  A response naming an identifier MUST NOT be presented in the
         cycle that identifier's request is accepted. The minimum
         request-to-response separation is one cycle.

WHY NO READY ON THE RESPONSE. The IFU reserved the line buffer slot when it allocated the identifier (IF-7), so it always has somewhere to put the data and a ready it could deassert would be a ready it never deasserts. Adding one would need a second holding register in the L1I for the response the IFU refused, and that register can fill while an MSHR waits to retire into it, which is a deadlock the identifier scheme otherwise cannot have. THE IDENTIFIER FREE LIST IS THE FLOW CONTROL, and putting a second flow control beside it is what makes the two able to disagree.

WHY IF-14, AND WHY IT COSTS NOTHING. L1I-5 puts hit latency at two cycles, so a same-cycle response is already impossible at this geometry. Forbidding it makes the rule survive a later latency change and keeps the IFU from having to allocate and retire one identifier in one cycle. The cachegen link schema names this choice directly: handshake.read_data_return takes same_cycle beside valid_flag and valid_with_id, and this link declares valid_with_id.

5.3 rsp_err
  IF-15  l1i_ifu_rsp_err high with l1i_ifu_rsp_val means the refill
         that answered this request returned an ERROR FROM THE
         MEMORY SIDE. l1i_ifu_rsp_data is then undefined. It is NOT
         a translation fault and never can be: section 8.

The L1I has no exception behaviour of its own beyond what the L2 returns (icache_decisions.md 2.3). On the TL-UH link of L1I-16 that is d_denied or d_corrupt. The IFU turns it into an instruction access fault at the prediction block that requested the line, and reports it through ifu_ftq_fault_val and ifu_ftq_fault_pos (ftq_ifu_interfaces.md 6), which is the same path a translation fault takes. THE FAULT CODE DIFFERS AND IS NOT CARRIED HERE, for the reason ftq_ifu_interfaces.md 6 already gives: the architectural exception travels with the instruction stream to the backend.


6. Backpressure and the outstanding limit

  IF-16  ifu_l1i_req_rdy is the L1I's only backpressure. It may be
         deasserted for any internal reason: the array port is busy
         with a fill, the MSHR file cannot take the request (section
         7), or a maintenance operation is in flight (section 10).

  IF-17  ifu_l1i_req_rdy MUST NOT depend combinationally on
         ifu_l1i_req_val. IF-40 makes it independent of
         ifu_l1i_req_paddr as well.

  IF-18  A SEVENTEENTH OUTSTANDING REQUEST CANNOT BE PRESENTED. IF-6
         makes the identifier free list the limit, and sixteen
         identifiers cannot name a seventeenth request. The L1I
         carries an assertion that no accepted identifier is already
         in flight, and that assertion is the whole of its
         seventeenth-request handling. It has no counter and no
         recovery path.

  IF-39  THE PREFETCH RESERVE. ifu_l1i_req_rdy is low for a request
         with ifu_l1i_req_prefetch high whenever fewer than TWO of
         the sixteen MSHRs are free. L1I-22. A demand request is
         unaffected by the reserve and may take the last MSHR.
         This is the ONLY place the prefetch bit is read.

THE PORT COUNT AND THE MSHR COUNT ARE THE SAME NUMBER by L1I-10 and L1I-12, so the identifier space and the miss-tracking capacity are the same size and neither can exhaust before the other. That is why IF-18 needs no arithmetic: a request can only miss if it is outstanding, and there are exactly as many MSHRs as identifiers.


7. Misses and merging

  IF-19  A MISS IS NOT VISIBLE ON THIS INTERFACE. There is no hit
         indication, no miss indication and no way to distinguish
         the two other than by counting cycles. A miss is latency.

  IF-20  Two requests naming the same line while the first is in
         flight are MERGED BY THE L1I onto one MSHR (L1I-13, four
         targets). THE REQUESTER SEES NOTHING OF THIS: each request
         is answered separately, in its own cycle, carrying its own
         identifier, with the same 512 bits. Two merged requests
         return over two cycles because IF-13 allows one response
         per cycle.

  IF-21  A request that would need a FIFTH target on one MSHR IS NOT
         ACCEPTED. ifu_l1i_req_rdy is deasserted. The request is not
         queued, not rejected on a response channel, and not
         allocated a second MSHR for the same line.

  IF-40  READY IS COMPUTED CONSERVATIVELY. ifu_l1i_req_rdy is low
         whenever ANY MSHR holds four targets, whatever address the
         request names. Ruled session-068. It does not read
         ifu_l1i_req_paddr, so no address compare is in the ready
         path. Requests to unrelated lines are refused for as long
         as the full MSHR persists.

WHY NO HIT INDICATION. It would arrive after the request was issued and after the identifier was allocated, so there is nothing the IFU could do with it that it has not already done. The FTQ run-ahead absorbs the latency (ftq_decisions.md 5.1) and the decoupled front end is what makes that true. A PERFORMANCE COUNTER STROBE is a different thing and is permitted: an l1i_ifu_perf_miss output that no functional logic reads is outside this protocol and may be added without changing it. It is named here so that adding it later is not mistaken for a protocol change.

WHY A SECOND MSHR FOR ONE LINE IS WRONG. Two MSHRs on one line means two fills of one line, two writes to one set, and a replacement decision taken twice. The array would end with the line in two ways or with one fill overwriting the other's way, and neither is a state the tag compare of L1I-5 can be right about.

WHY REFUSE RATHER THAN REJECT. A reject needs a second response channel and forces the IFU to re-present, which reorders the fetch stream against the FTQ entry order ftq_ifu_interfaces.md 4 relies on. Refusing costs cycles and reorders nothing.

IF-40 REFUSES MORE THAN IF-21 REQUIRES. ifu_l1i_req_rdy is one wire and IF-40 does not qualify it by address, so a full MSHR refuses requests to every other line as well. The cost is throughput on a pattern the FTQ makes likely; the alternative put a 36-bit compare against sixteen MSHR line addresses in the ready path and was rejected.


8. Faults

  IF-22  A FAULTING REQUEST NEVER REACHES THE L1I, and this
         interface carries NO FAULT PORT IN EITHER DIRECTION. 2.3 T2
         places the fault path between the ITLB and the IFU, so a
         translation fault is not a cache access.

The absence is the specification, so what the IFU does instead is stated here rather than left to ifu_decisions.md:

  IF-23  On an ITLB FAULT for a prediction block, the IFU presents
         no request, allocates no identifier, terminates the
         prediction block at the faulting instruction position, and reports it
         with ifu_ftq_fault_val and ifu_ftq_fault_pos
         (ftq_ifu_interfaces.md 6). The L1I is not told.

  IF-24  On an ITLB MISS, the IFU presents no request and allocates
         no identifier. It retries the translation. The ITLB is
         non-blocking and returns miss to the requester;
         itlb_decisions.md ITLB-8 and ITLB-9, ruled session-069
         from L1I-U3.

IF-8, IF-23 AND IF-24 ARE SATISFIED BEFORE THIS PORT IS REACHED.
The IFU translates a block in a pipeline that runs ahead of its
fetch pipeline and queues the result (ifu_decisions.md IFU-23a).
A block reaches the fetch pipeline only with its translation
already resolved, so the hit, fault and miss cases above are
settled one pipeline earlier rather than in the cycle the request
would issue. The rules are unchanged; where they are evaluated is.

The three fault classes ftq_ifu_interfaces.md 6 names for ifu_ftq_fault_val are instruction access fault, page fault and guest page fault. Two of the three are ITLB-side and reach the FTQ by IF-23; guest page fault exists because H is mandatory in RVA23 via Sha and translation is two-stage. The third, instruction access fault, has TWO producers: the ITLB, by IF-23, and the L1I's memory side, by IF-15. They arrive on different paths and merge in the IFU. Nothing downstream can or needs to tell them apart.


9. Reset

  IF-25  While rstn is low the IFU holds ifu_l1i_req_val and
         ifu_l1i_inv_val low, and the L1I holds l1i_ifu_rsp_val,
         l1i_ifu_inv_done and ifu_l1i_req_rdy low.

  IF-26  The IFU's identifier free list resets to ALL SIXTEEN FREE.
         No identifier is in flight across reset, and no response is
         presented for a request issued before it.

  IF-27  The L1I may assert ifu_l1i_req_rdy in the FIRST CYCLE after
         rstn deasserts. Its valid bits are a flop file cleared by
         reset (L1I-6), so the array is coherent immediately and
         there is no post-reset walk. The l2 node needs one; the L1I
         does not, and section 3 of icache_decisions.md says why.

10. Maintenance, IFU to L1I

L1I-18 puts the only invalidate path core side, through the IFU, and supports invalidate_line and invalidate_all and neither flush.

10.1 Ports
  ifu_l1i_inv_val                              NEW
  ifu_l1i_inv_rdy                              NEW   L1I -> IFU
  ifu_l1i_inv_all                              NEW
  ifu_l1i_inv_paddr   [PA_WIDTH-1:0]           NEW
  l1i_ifu_inv_done                             NEW   L1I -> IFU

ONE GROUP, NOT TWO. invalidate_line and invalidate_all differ in one bit of what to do and share every other wire, and IF-28 allows only one of either in flight, so two port groups would be two ways to drive one piece of hardware.

There is no flush port. There is nothing to flush: the L1I is read only, holds no dirty state and has no write path to the L2.

THE L1I KEEPS THE EMISSION'S NAMES on its own side. The pacino copy of the L1I names these ports core_inv_val, core_inv_rdy, core_inv_all, core_inv_addr and core_inv_done, and the request qualifier of IF-44 core_uncached; fe_top maps them one to one to the names above. Built by BP-123, accepted session-077 (Jeff).

10.2 Rules
  IF-28  AT MOST ONE MAINTENANCE OPERATION IS IN FLIGHT. The IFU
         presents the next one only after l1i_ifu_inv_done for the
         previous one. There is no maintenance identifier and no
         maintenance queue.

  IF-29  ifu_l1i_inv_all high means invalidate the WHOLE CACHE and
         ifu_l1i_inv_paddr is ignored. Low means invalidate the ONE
         LINE containing ifu_l1i_inv_paddr, in every way of its set.
         The address IS NOT REQUIRED TO BE LINE ALIGNED, unlike
         IF-5: cbo.inval names any address within the block and the
         architecture does not require the software to align it, so
         the L1I masks the offset bits.

  IF-30  FETCH DOES NOT PROCEED WHILE AN INVALIDATE IS IN FLIGHT.
         From the cycle a maintenance operation is accepted until
         the cycle l1i_ifu_inv_done is asserted, the L1I holds
         ifu_l1i_req_rdy low and accepts no new request. The range
         is INCLUSIVE of the done cycle: ready may rise the cycle
         after done. As BP-123 built it (its Assumption 3);
         CONFIRMED session-079 (Jeff).

  IF-31  l1i_ifu_inv_done IS NOT ASSERTED UNTIL EVERY FILL THE
         INVALIDATE MUST DEFEAT HAS LANDED OR BEEN DISCARDED, and
         until the clear itself has been applied. Specifically:
           - inv_all waits for EVERY outstanding request to have
             been answered, then clears
           - inv_line waits only for an MSHR whose line matches
             ifu_l1i_inv_paddr, if there is one, then clears
         The responses for those requests ARE STILL PRESENTED on the
         ports of section 5 and the IFU still accepts them by IF-10.
         A drain is not a discard at this boundary.

  IF-32  l1i_ifu_inv_done is one cycle wide.

  IF-42  THE CLEAR TAKES ONE CYCLE. After the drain of IF-31,
         inv_line clears its set in one cycle and inv_all clears
         the array in one cycle. l1i_ifu_inv_done asserts the
         cycle after the clear. Ruled session-068.

WHY IF-31 IS THE WHOLE POINT. icache_decisions.md 7 M1 says FENCE.I is "implemented by the reset-branch clear of the flop valid bits, so it is a single-cycle operation". THE CLEAR IS SINGLE CYCLE AND THE OPERATION IS NOT. With sixteen requests outstanding, a fill in flight when the clear happens lands in the array afterwards and re-validates a line the fence was supposed to remove. FENCE.I is drain then clear. See section 15, defect D1.

WHY inv_line DRAINS ONLY ITS OWN MSHR. A fill for a different line cannot re-validate the line being invalidated, so waiting for it buys nothing. The comparison of ifu_l1i_inv_paddr against the MSHR file's line addresses is the SAME COMPARISON THE MERGE OF IF-20 ALREADY PERFORMS, so this reuses a mechanism rather than adding one. The alternative, draining everything for both forms, was rejected: a range invalidation loop would then drain sixteen outstanding requests per line, and that is a JIT's inner loop.

WHY inv_all DRAINS EVERYTHING. There is no line to compare against.


11. Maintenance, backend to IFU

FENCE.I and cbo.inval are EXECUTED INSTRUCTIONS. Something upstream must tell the front end, and no document in this tree names that boundary. This section names it. There is no producer built and no producer specified, so section 12 lists every assumption this section makes about it and marks each unverifiable.

11.1 The boundary

THE PRODUCER IS THE BACKEND COMMIT STAGE, not execute. Two reasons, and only the second is decisive.

The weak reason: an invalidate on a wrong path is architecturally harmless, because an empty instruction cache is always a legal instruction cache. It costs refills and nothing else.

THE DECISIVE REASON: FENCE.I HAS COMPLETION SEMANTICS. The instruction is not finished until every prior store is visible to instruction fetch, and the pipeline restart that follows it must not begin before that. Something must be able to say WHEN, and only a stage that can hold the restart can use the answer. Execute cannot; commit can.

11.2 Ports
  cmt_ifu_maint_val                            NEW
  cmt_ifu_maint_rdy                            NEW   IFU -> commit
  cmt_ifu_maint_op    [0:0]                    NEW
  cmt_ifu_maint_paddr [PA_WIDTH-1:0]           NEW
  ifu_cmt_maint_ack                            NEW   IFU -> commit
  cmt_ifu_maint_op    0   MAINT_FENCE_I     whole cache
                      1   MAINT_CBO_INVAL   one line at paddr
11.3 Rules
  IF-33  cmt_ifu_maint_paddr is a PHYSICAL address. cbo.inval names
         a virtual address in rs1; the backend translates it before
         it reaches this port. The IFU performs no translation and
         has no path to the DTLB. See assumption A2.

  IF-34  AT MOST ONE MAINTENANCE OPERATION IS IN FLIGHT ACROSS THIS
         BOUNDARY, for the same reason as IF-28 and with the same
         consequence: no identifier and no queue.

  IF-35  ifu_cmt_maint_ack IS REQUIRED. It is asserted for one cycle
         and only after everything the operation covers is complete:
           - l1i_ifu_inv_done for the operation has been received
           - the IFU's own line buffer (L1I-14) has been cleared,
             see IF-36
         WITHOUT THIS PORT FENCE.I HAS NO COMPLETION SEMANTICS. The
         commit stage would have to guess when to release the
         restart, and any guess is either wrong or a fixed delay
         that pins an L1I latency into the backend.

  IF-36  THE IFU CLEARS ITS OWN LINE BUFFER on MAINT_FENCE_I, and on
         MAINT_CBO_INVAL when the buffer holds the named line. L1I-14
         puts a 64-byte line in the IFU and L1I-18 puts the only
         invalidate path through the IFU, so a fence that clears the
         array and not the buffer leaves a stale instruction line
         the L1I cannot see and cannot be asked about. See section
         15, defect D2.

         THE CLEAR FOLLOWS l1i_ifu_inv_done, NOT THE REQUEST.
         IF-31 drains rather than discards, and IF-10 makes the
         IFU accept every draining response unconditionally. A
         buffer cleared on receipt of the maintenance request is
         therefore repopulated by the next response to land --
         which is D1's defect one layer up, on the structure D2
         exists to cover.

         WHAT IS CLEARED is the line the IFU can serve without an
         L1I request: the previous-request register of
         ifu_decisions.md TD-IFU-8. Slots held by blocks in flight
         belong to blocks younger than the maintenance instruction.
         After FENCE.I the restart flushes them (ifu_decisions.md
         IFU-28); after cbo.inval software has no fetch-coherence
         guarantee (13.2). As BP-123 built it (its Assumption 2);
         CONFIRMED session-079 (Jeff).

  IF-37  cmt_ifu_maint_val and the fetch request path are
         independent at this boundary. The IFU may still be holding
         in-flight requests when a maintenance request arrives; IF-30
         and IF-31 dispose of them.

  IF-41  cbo.inval REACHES THE I-SIDE. MAINT_CBO_INVAL is driven
         and the port group of 11.2 is live logic. Ruled
         session-068. Section 13 records that the architecture
         does not decide this and pacino must.

  IF-43  MAINT_FENCE_I IS ALSO ROUTED TO THE D-SIDE. The backend
         drives an equivalent operation to the LSU on the same
         instruction. Ruled session-068. ifu_cmt_maint_ack covers
         the I-side only, so the backend gates the post-fence
         restart on both acknowledgements.

12. What this file assumes about the producer

No backend commit document, no LSU document and no DTLB document exists in this tree. Each assumption below is stated so that the document that eventually specifies the producer can be checked against it. EVERY ONE IS UNVERIFIABLE TODAY.

  A1  UNVERIFIABLE. The commit stage can hold the post-FENCE.I
      pipeline restart until ifu_cmt_maint_ack. If it cannot, IF-35
      buys nothing and the fence is not architecturally complete
      when the instruction retires. IF-43 makes this TWO
      acknowledgements, not one: the I-side and the D-side.

  A2  UNVERIFIABLE. The backend translates cbo.inval's rs1 through
      the DTLB and presents a PHYSICAL address on
      cmt_ifu_maint_paddr. If translation is left to the front end,
      the IFU needs an ITLB lookup on the maintenance path, which
      this interface does not have and section 10 does not carry.

  A3  UNVERIFIABLE. The backend raises the address-related faults of
      cbo.inval, and no faulting maintenance operation reaches
      cmt_ifu_maint_val. This is the same division as IF-22 on the
      fetch path.

  A4  UNVERIFIABLE. Only one hart drives this boundary. FENCE.I is
      per hart and is not broadcast; a multi-hart pacino would need
      software to run a fence on each hart, which is the
      architectural expectation and not a hardware path.

  A5  UNVERIFIABLE. The backend gates cbo.inval on menvcfg.CBIE
      before it reaches this port. Section 13 says what that gate
      is. If the gate is not in the backend, MAINT_CBO_INVAL must
      grow the trap and remap behaviour, which does not belong in
      the front end.

13. cbo.inval, menvcfg.CBIE and what is determinable

icache_decisions.md TD-L1I-2 carries this as unverified. It is PARTLY DETERMINABLE, and the two halves are different in kind.

13.1 Determinable, and checked

menvcfg.CBIE is a two-bit field at bits [5:4], with senvcfg.CBIE and henvcfg.CBIE at the same position. Checked in this session against tools/spike, the reference implementation carried in this tree:

  encoding.h:189    MENVCFG_CBIE == 0x30, so bits [5:4]
  csrs.cc:1057      the M, S and H field positions are asserted equal
  csrs.cc:1061-2    value 2 is RESERVED, and a write of it is
                    normalised to 0
  decode_macros.h:205  require_envcfg: below M with the field 0,
                    cbo.inval raises an ILLEGAL INSTRUCTION trap, or
                    a VIRTUAL INSTRUCTION trap when V is set
  insns/cbo_inval.h  the instruction executes as an invalidate or is
                    REMAPPED to a flush, depending on the field

So the three behaviours the architecture permits are real and the gate is real:

  CBIE 00  traps below M: illegal instruction, or virtual
           instruction when V is set
  CBIE 01  the instruction executes and performs a FLUSH
  CBIE 10  reserved
  CBIE 11  the instruction executes and performs an INVALIDATE

AN EARLIER REVISION OF THIS PARAGRAPH HAD 01 AND 11 SWAPPED, saying 1 invalidates and 3 remaps to a flush. The Zicbom field definition is the other way round and the CMO specification's cbo.inval pseudocode confirms it: the flush branch is taken when the governing CBIE field is 01 and the invalidate branch is the else. Corrected session-069 against the ratified CMO and machine ISA text. The Spike citations above are neutral on which value maps to which and did not carry the error.

The remap direction matters here: 01 is the RESTRICTIVE setting, a machine-mode supervisor downgrading a guest's invalidate into a flush so it cannot discard modified data it does not own. Reading it the other way inverts a safety property into a hazard.

ONE CAVEAT ON THE EVIDENCE. Spike's cbo_inval.h treats any non-zero CBIE below M as the flush case and reaches the invalidate case only at M-mode. That is a functional-model simplification and NOT evidence about the 1-against-3 distinction: in a model with one coherent memory, a flush and an invalidate of a clean block are the same act. The field positions, the reserved value and the trap behaviour are evidence; the 1-against-3 mapping above is from the privileged specification and is not what spike demonstrates.

13.2 NOT determinable, and why

WHETHER cbo.inval REACHES AN INSTRUCTION CACHE AT ALL IS NOT FIXED BY THE ARCHITECTURE. Zicbom is written against a coherent memory hierarchy and names "the cache block"; it does not enumerate which caches a hart has. The instruction cache is, in RISC-V, architecturally NOT coherent with the data side: FENCE.I is the mechanism and the burden is on software. It follows that software CANNOT RELY on cbo.inval to make a store visible to instruction fetch, whatever an implementation chooses to do, and an implementation is therefore free to route it to the I-side or not.

That is a real answer, not a gap: the specification does not decide it, so pacino must.

13.3 The port for both readings

The port list of sections 10 and 11 is UNCHANGED under either reading. cmt_ifu_maint_op MAINT_CBO_INVAL either arrives or does not, and the trap and remap of 13.1 are resolved in the backend before this boundary (A5). The two readings differ only in the backend:

  cbo.inval REACHES the I-side     the backend, having decided the
                                   instruction executes, drives
                                   MAINT_CBO_INVAL to the IFU and
                                   the equivalent to the LSU
  cbo.inval DOES NOT reach it      the backend drives only the LSU.
                                   MAINT_CBO_INVAL is never asserted
                                   and the IFU path is dead logic

ROUTED. IF-41, ruled session-068. MAINT_CBO_INVAL is live and IF-29's line form is built.


14. What a cachegen configuration can and cannot say

INFRA-012 problem 4 assessed this and TOOLS-003 confirms it against the schema and the tool. Confirmed means read this session, in tools/cachegen/planning/schema and cli/src, and where a claim was testable it was tested.

STATUS AS OF SESSION-071. This section is the TOOLS-003 assessment. TOOLS-004 and TOOLS-005 closed most of it, and each item below now says so. TOOLS-004 closed S2, S3, S6, S7 and S9, each with its consumer, and E1 (both sites), E2, E3 and E4; TOOLS-005 closed E5. Still open: S1, S8 and E7.

14.1 Expressible today, no tool change

For a custom link carrying the interface of sections 4 and 5:

  address_width_bits           36    yes. And AS OF TOOLS-003 the
                                     new T-10 checker rule makes a
                                     value that disagrees with
                                     addressing.pa_bits an error,
                                     which closes TD-L1I-6
  address_granularity          byte  yes. `line` is also available,
                                     which is the rejected form of
                                     section 4.2
  address_alignment_bytes      64    yes, the enum carries 64
  read_width_bits              512   yes, the maximum is 4096
  handshake.accept             ready yes, IF-16
  handshake.read_data_return
                       valid_with_id yes, IF-12 and IF-14
  id_width_bits                4     yes, IF-2
  outstanding_requests         16    yes, and consumed since
                                     TOOLS-004, 14.3 E2
  read_byte_enables            false yes
  write_response               false yes
14.2 Needs a schema change
  S1  prefetch_arbitration. TD-L1I-3, unchanged. IF-9 and 4.4
      narrow what the field means: P1 is IFU-internal and this
      interface cannot see it, so the field describes P2 and P3
      only.

  S2  CLOSED by TOOLS-004. A READ-ONLY LINK: write_width_bits
      takes 0 and is no longer required, and the emitted bundle
      drops the write channel. TD-L1I-7 closed
      (`icache_decisions.md` 9 n2). As assessed by TOOLS-003:
      custom.write_width_bits had minimum 8 and was required, so
      `0` could not be declared.

  S3  CLOSED by TOOLS-004: valid_with_id now requires
      id_width_bits of at least 1, proved by the negative fixture
      neg_id_width_zero. As assessed by TOOLS-003:
      A CONSTRAINT TYING read_data_return `valid_with_id` TO A
      NON-ZERO id_width_bits. Unchanged from INFRA-012. IF-2 and
      IF-11 are exactly the pair that would disagree without it.
  S6  CLOSED by TOOLS-004. custom.error_response is a boolean;
      the bundle gains rerr and the slave adapter drives it from
      rsp_err instead of tying it off. TD-IF-2 closed. As assessed
      by TOOLS-003:
      AN ERROR RETURN ON A CUSTOM LINK. NEW, and not in INFRA-012's
      list. IF-15's l1i_ifu_rsp_err CANNOT BE DECLARED. There is no
      field for it, and the consequence is already visible in the
      emitted tree: l1i_core_slv.sv carries
        // the link declares no error return, so a slave error is
        // dropped here
      and ties rsp_err into an unused net. The node knows it can
      return an error and the link has no way to say so. TD-IF-2.

  S7  CLOSED by TOOLS-004. custom.handshake.response_accept takes
      none or ready, and pe_port_i declares none, which is IF-10:
      a declared absence, not a tool policy. TD-IF-3 closed. As
      assessed by TOOLS-003:
      A RESPONSE-SIDE HANDSHAKE. NEW. `handshake.accept` governs the
      REQUEST side only. IF-10's deliberate ABSENCE of a response
      ready cannot be declared, and neither could its presence. The
      emitted adapter's response behaviour is a tool policy, not a
      configured one. TD-IF-3.

  S8  THE MAINTENANCE PORTS. The four booleans of the node's
      `maintenance` group say WHETHER the capability exists. Nothing
      anywhere says what its PORTS are, and the group is on the NODE
      rather than on a LINK, so there is no object for section 10's
      port list to attach to. This is a larger gap than E7 below: E7
      is an emitter that does not emit a port, S8 is a schema with
      nowhere to describe one. TD-IF-4.

  S9  CLOSED by TOOLS-004. THE PREFETCH REQUEST BIT is declared by
      custom.request_qualifiers, with the L1I-22 reserve that
      reads it. TD-L1I-9 closed (`icache_decisions.md` 9 n4).
      Where the reserve is declared is L1I-U7. As assessed by
      TOOLS-003: ifu_l1i_req_prefetch could not be declared,
      because a custom link's bundle carried no requester-supplied
      qualifier.
14.3 Needs an emitter change

INFRA-012 E1 through E8 stood at TOOLS-003. Two of them were TESTED then rather than read, and one grew. E1 to E5 have since closed, as marked; E7 is open:

  E1  CLOSED by TOOLS-004, both sites: the package emits the
      one-word-per-line shape with no [-1:0], and the testbench
      driver has no write path on a read-only link. The emitted
      l1i carries the 512-bit core port and is lint clean. The
      TOOLS-003 finding follows.
      THE 512-BIT CORE PORT BREAKS THE PACKAGE. CONFIRMED BY
      EXPERIMENT, not by reading. A scratch copy of pacino with a
      second core link at read_width_bits 512 emits cleanly, and
      Verilator then reports on l1i_pkg.sv:
        %Error: Size-changing cast to zero or negative size: 0
        %Warning-ASCRANGE: Ascending bit range vector: [-1:0]
      at l1i_word_of, exactly as INFRA-012 derived. It is a hard
      ERROR and not a warning.

      AND IT IS WORSE THAN INFRA-012 REPORTED. The same experiment
      also produces, in the emitted TESTBENCH:
        %Warning-WIDTHTRUNC: core_wdata = d;   512 into 32
        %Warning-WIDTHTRUNC: core_wstrb = be;  64 into 4
      The testbench driver task sizes its write path from
      write_width_bits and its data argument from the read width, so
      an asymmetric link breaks the testbench as well as the
      package. That is a second site and it is not in E1's fix.

  E2  CLOSED by TOOLS-004: the core adapter is no longer
      single-outstanding; sixteen outstanding are emitted. At
      TOOLS-003, outstanding_requests reached nothing, and IF-6,
      IF-18 and section 6 had no emitted counterpart.

  E3  CLOSED by TOOLS-004: the request identifier reaches every
      module on the path. At TOOLS-003 the identifiers were wires
      from link_sig consumed by nothing.

  E4  CLOSED by TOOLS-004: the MSHR file exists, sixteen MSHRs of
      four targets, with sixteen fills in flight since TOOLS-005.
      At TOOLS-003 there was none, and section 7 was the largest
      single gap between this file and the tool.

  E5  CLOSED by TOOLS-005: read_latency_cycles and
      tag_compare_stage set the emitted two-cycle latency. At
      TOOLS-003 both were dead for a cache node.

  E7  NO NODE EMITS AN INVALIDATE PORT OF ANY KIND. The whole of
      section 10 is unemittable. With S8, the maintenance path needs
      a schema change AND an emitter change, in that order.
14.4 The one thing that got better

TOOLS-003 closed TD-L1I-6. addressing.pa_bits and every link's address width are now checked against each other, on any edge touching a cache or memory node, as T-10.addr_width. The silent zero-extend into l1i_addr_t and the silent truncation out of mem_a_address that INFRA-012 found are now build errors.


15. Defects found in icache_decisions.md

Reported, not worked around. This file was read-only in TOOLS-003 and the PA drafted the amendment.

ALL SIX ARE APPLIED as of icache_decisions.md 2026-08-29, plus a seventh the PA found in the same pass. Kept here as the record of what was found and why; do not re-report them.

  D1  APPLIED. 7 M1 is drain then clear
  D2  APPLIED. L1I-18 covers the IFU buffer; ordering in IF-36
  D3  APPLIED. Section 9 reads 36; TD-L1I-6 closed
  D4  APPLIED, by adding the port. L1I-21 and L1I-22; IF-38 and
      IF-39 in this file
  D5  APPLIED. L1I-20; L1I-U1 closed; 23 and 24 disambiguated
  D6  APPLIED. 0.1 carries a maint row
  D7  APPLIED, PA-found. Section 6's targets-per-MSHR derivation
      was void under L1I-14 -- the second prediction block never
      becomes a request -- so 4 is now an unmeasured choice

16. Open items

EVERY IF-U IS CLOSED. None is reused.

  IF-U1  CLOSED. Conservative, IF-40.

  IF-U2  CLOSED. It asked whether the ITLB assumed by IF-24 holds.
         IF-24 was written on that assumption, so the item asked
         about its own premise. The ITLB is non-blocking; L1I-U3.

  IF-U3  CLOSED. Routed. IF-41.

  IF-U4  CLOSED. One cycle. IF-42.

  IF-U5  CLOSED. FENCE.I is routed to the D-side as well. IF-43.

NO OPEN ITEMS REMAIN IN THIS FILE.


17. Technical debt

  TD-IF-1  REOPENED session-070 as TD#122. The closure text below was
           correct when written and was overtaken by mmu_decisions.md
           MMU-19..MMU-23 in session-069.
           It read: "VA_WIDTH is 40 and addressing.va_bits is 39. These
           are different quantities: 40 is the Sv39 address plus its
           sign bit, the vaddrBitsExtended convention. No action."
           VA_WIDTH IS 41. H is mandatory through Sha, the G-stage is
           Sv39x4, and Shvsatpa requires vsatp to support Bare because
           Svbare requires it of satp, so with V=1 and vsatp.MODE=Bare
           the fetch PC is a 41-bit GUEST PHYSICAL address, zero
           extended. A sign-extended 40-bit field cannot hold it, and
           sign extension corrupts any GPA with bit 38 set.
           fe_decisions.md FE-19. TD#122 tracks the RTL.

           SECOND SCOPE, ruled session-074 (Jeff). The 3.1 table
           has used this ID for the L1I names as well. They go in
           bp_defines_pkg, not yet declared -- PA_WIDTH, L1I_LINE_BYTES,
           L1I_LINE_BITS, L1I_OFFSET_BITS, REQ_ID_BITS,
           MAX_OUTSTANDING, and MAINT_FENCE_I / MAINT_CBO_INVAL of
           11.2 -- and checked equal to the emitted l1i_pkg at
           elaboration. PPN_WIDTH becomes PA_WIDTH - 12. TD#122.
           CLOSED by BP-115, session-074: declared, and checked by
           rtl/core/frontend/l1i_param_chk.

  TD-IF-2  CLOSED by TOOLS-004, section 14.2 S6. Original text:
           A CUSTOM LINK CANNOT DECLARE AN ERROR RETURN. Section
           14.2 S6. IF-15 is unemittable and the emitted adapter
           already ties the signal off with a comment saying so.

  TD-IF-3  CLOSED by TOOLS-004, section 14.2 S7. Original text:
           A CUSTOM LINK CANNOT DECLARE ITS RESPONSE-SIDE
           HANDSHAKE. Section 14.2 S7. IF-10's absence of a response
           ready is a tool policy today, not a configured property.

  TD-IF-4  THE SCHEMA HAS NOWHERE TO DESCRIBE A MAINTENANCE PORT.
           Section 14.2 S8. The `maintenance` group is four booleans
           on the node saying whether a capability exists. Section
           10's port list has no object to attach to, so E7's
           emitter work has nothing to read.

  TD-IF-5  THE PREDECODE WRITEBACK AND THE LINE RESPONSE ARE NOT
           ORDERED AGAINST EACH OTHER. ftq_ifu_interfaces.md 6 has
           the IFU return one writeback per prediction block; IF-12 lets
           the line responses that feed those blocks return out of
           order. The IFU therefore reorders between its two
           boundaries, and nothing in either file says what bounds
           the reordering buffer that implies. It belongs in
           ifu_decisions.md and is named here because this file is
           the half that introduces the out-of-order return.

           RESOLVED session-074 by TD#116 (Jeff). The line buffer
           is the reorder store, consumed in allocation order, one
           slot per identifier (IF-7). Its depth is a parameter,
           default 16 = MAX_OUTSTANDING, so the identifier free
           list bounds it. Closes when ifu_decisions.md carries it.

18. RVA23 compliance note

  Zicbom     MANDATORY in RVA23U64. cbo.inval is section 11's
             MAINT_CBO_INVAL and section 13 is its gate.
  Zifencei   MANDATORY in RVA23S64, which pacino is: it implements
             Sv39 and supervisor mode. FENCE.I is section 11's
             MAINT_FENCE_I.

Both were re-checked session-072 against rva23-profile.adoc, which PROJECT_CORE.md names the reference for every compliance claim in this tree: Zicbom is under RVA23U64 Mandatory Extensions and Zifencei under RVA23S64 Mandatory Extensions, where the note says it is mandated as the only standard way to support instruction-fetch coherence. Both claims stand.

The earlier check cited tools/cachegen/tools/jnutils/ncurses/ rva23.md, a cachegen working file outside planning/ that PROJECT_CORE.md does not list. Session-072.

BP-123 CLOSED THE GAP IN THE PACINO RTL, under cachegen_decisions.md CG-4: the l1i is copied to rtl/core/frontend/icache and the ports of sections 10 and 11 are added there, with tb_fe_top's fencei and cboinval programs. Accepted session-077 (Jeff). cachegen keeps the gap below until CG-5; the pacino front end no longer uses the emission (fe_decisions.md FE-21). Session-076, built session-077.

FOR THE EMISSION ONLY, THE GAP IS UNCHANGED BY THIS FILE. L1I-18 has no hardware (icache_decisions.md TD-L1I-8, TD#119), and section 14.3 E7 confirms it: no generated node emits an invalidate port of any kind. This file specifies the ports; it does not build them, and RVA23 conformance for both extensions remains blocked on the emitter work.

There is no C-extension consequence here. A fetch may begin on any 2-byte boundary, but IF-5 makes every request line aligned and the block extract is the IFU's (4.3 R3), so nothing in this interface sees a 2-byte boundary.


19. Document History

  2026-08-29  Created, TOOLS-003. Closes the port-list half of
              icache_decisions.md section 4, which stated the shape
              and stopped. Sixteen identifiers with an IFU-owned
              free list are the flow control, and the response
              carries no ready because of it. A miss is not visible;
              merging is not visible; a fifth target on one MSHR is
              refused by ready rather than rejected on a channel. A
              translation fault reaches the L1I never and adds no
              port, so section 8 specifies an absence. Maintenance
              is specified at both ends: a drain-then-clear
              invalidate from the IFU, and a commit-stage boundary
              with a required acknowledgement, because without one
              FENCE.I has no completion semantics.

              SIX DEFECTS REPORTED against icache_decisions.md, of
              which two are correctness rather than tidiness: 7 M1's
              single-cycle FENCE.I is wrong once sixteen requests
              can be outstanding (D1), and L1I-14's IFU line buffer
              is not covered by L1I-18's invalidate path (D2).

              menvcfg.CBIE checked against tools/spike rather than
              asserted. The gate is real and the field is two bits
              at [5:4] with value 2 reserved; whether cbo.inval
              reaches an instruction cache at all is NOT fixed by
              the architecture, so the port is specified for both
              readings and the choice is recorded as IF-U3.

              Three NEW schema gaps beyond INFRA-012's list, all
              found by writing the port list down: no error return
              on a custom link, no response-side handshake, and
              nowhere at all to describe a maintenance port.

  2026-08-30  THE PREFETCH BIT ADDED, session-068. 4.4 said P2 was
              not enforceable and left it; Jeff ruled the port in.
              ifu_l1i_req_prefetch is one bit, read in exactly one
              place: IF-39 refuses a prefetch unless two MSHRs are
              free, L1I-22. Everything else about a prefetch is
              identical to a demand fetch, so IF-19's invisible
              miss and the shared identifier space both stand.
              S9 and TD-L1I-9: no link field can express the bit.

              IF-36 GAINED ITS ORDERING. The rule said the IFU
              clears its buffer and did not say when. IF-31 drains
              rather than discards and IF-10 makes the IFU accept
              every draining response, so a clear on receipt is
              repopulated by the next response -- D1's defect one
              layer up. The clear follows l1i_ifu_inv_done.

              All six reported defects are applied in
              icache_decisions.md, with a seventh the PA found.
              Section 15 records their status.

  2026-08-31  IF-U1 closed as IF-40, conservative ready. IF-U2
              deleted, circular. IF-17, IF-24 and section 7
              updated. Section 15's duplicated defect text
              removed; the status block stands.

  2026-09-01  IF-U3, IF-U4 and IF-U5 closed, session-068.
              cbo.inval is routed to the I-side, IF-41. The
              invalidate clear takes one cycle, IF-42. FENCE.I is
              routed to the D-side as well, IF-43, so the backend
              gates the post-fence restart on two
              acknowledgements. 13.3 and A1 follow. No open item
              remains in this file.

  2026-09-19  session-071. Section 14 brought up to date with
              TOOLS-004 and TOOLS-005, checked against the
              TOOLS-004 report: S2, S3, S6, S7, S9 and E1 to E5
              marked closed; TD-IF-2 and TD-IF-3 closed; the 3.1
              table names L1iReqIdBits and L1iMaxOutstanding.
              Section 1: the ITLB documents exist. TOOLS-004 had
              listed these amendments and they were never
              applied.
  2026-09-19  session-071. "Fetch block" replaced by "prediction
              block" in section 5, IF-23 and TD-IF-5, where the
              32-byte unit was meant. The fetch block is the 64-byte
              L1I line (fe_decisions.md Conventions).

  2026-09-20  session-072. D16: the section 18 compliance claims
              re-checked against rva23-profile.adoc, the reference
              PROJECT_CORE.md names; the earlier check cited a
              cachegen working file.

  2026-09-20  session-072. E22: Document History sorted into date order;
              newer entries had been appended at the wrong end.

  2026-09-20  session-072. E24: the 14.2 schema gaps in numeric
              order.

  2026-09-22  session-073. The 3.1 table: the seven TBD values
              are filled and GVPN_WIDTH is added, ruled this
              session. Sources listed below the table. Raised:
              nothing faults a PTE PPN above PPN_WIDTH.

  2026-10-01  session-074. 3.1 status: the ITLB/MMU widths are
              declared, the L1I names ruled into bp_defines_pkg.
              TD-IF-1 gains that ruling; TD-IF-5 resolved by the
              TD#116 ruling. Then BP-115: the six L1I names are
              declared and checked, the table reads BP-109 and
              BP-115, and TD-IF-1 is closed. After BP-116: the
              header records the IFU side as built; a repeated
              paragraph in section 2 removed.

  2026-10-09  session-076. 4.1 and 4.5: ifu_l1i_req_uncached and
              IF-44 (IFU-21 reversed, L1I-24). Header and section
              18: the maintenance ports are built in the pacino RTL
              by BP-123 under CG-4.

  2026-10-09  session-077, after BP-123, rulings (Jeff). Header and
              section 18: built. 3.1: FAULT_GPA_WIDTH 56 (MMU-23);
              the PPN-above-bit-23 note closed by MMU-28. IF-44a:
              the merge policy (D6). 10.1: the L1I side keeps the
              emission's core_ names. IF-30 inclusive of the done
              cycle; IF-36 names what is cleared (BP-123
              Assumptions 3 and 2, as built, for Jeff to confirm).

  2026-10-10  session-077, after BP-125. IF-44a: a merged cacheable
              fill updates the replacement state (L1I-24).

  2026-10-14  session-079. IF-30 and IF-36 confirmed (Jeff).
itlb_decisions.md

planning/arch/itlb_decisions.md on GitHub

L1 Instruction TLB Decisions

 FILE:    itlb_decisions.md
 SOURCE:  session-069
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

Owns the ITLB-N, TD-ITLB-N and ITLB-UN registries. The numbers are issue order and the sections are topical, so they do not run in numeric order: section 7 runs ITLB-13, ITLB-13a, ITLB-14, ITLB-13b. Session-072.

Scope is the L1 instruction TLB only. The page table walker and the PMP and PMA checkers are in mmu_decisions.md. There is no L2 TLB now: an ITLB miss goes to the walker directly (MMU-1, reversed session-077). This document names the ITLB side of each boundary and does not restate the other side.

The ITLB is written from this document. cachegen currently does not support TLB generation.


1. Origin

icache_decisions.md L1I-U2 asked for the ITLB parameters and L1I-U3 for the walker topology. Both were ruled in session-069. This document records the ITLB half. TD#115 closes on it.

L1I-3 makes the L1I physically indexed, so translation sits in the fetch path ahead of the array. l1i_ifu_interfaces.md IF-8 has the IFU issue only on a valid non-faulting translation.


2. Array

ITLB-1 64 entries.

ITLB-2 Fully associative.

ITLB-3  One array holds every page size: the three Sv39 sizes,
        4 KiB, 2 MiB and 1 GiB, and the 64 KiB Svnapot case. No
        separate large-page array. A NAPOT entry is HELD ONCE and
        matched across its range by masking VPN[3:0] out of the
        compare; on a hit the output PPN[3:0] is VPN[3:0], not the
        stored value, which is the size marker (mmu_decisions.md
        MMU-U7, ruled session-071). Svnapot is mandatory in
        RVA23S64. This read "all three Sv39 page sizes".
        A response whose size code is reserved (3'b1xx,
        itlb_l2tlb_interfaces.md IL-7) is never installed; it is
        handled as a reserved status (IT-4). Built by BP-119.
ITLB-3a Each entry also holds the page's PBMT, the more restrictive
        of the two stages' values as returned on
        itlb_l2tlb_interfaces.md IL-9. On a hit it is combined with
        the region attributes of the physical address to give the
        effective type (mmu_decisions.md MMU-U6). Session-071.
ITLB-4  ASID tagged. Entries carry an ASID field and a global bit
        taken from the PTE G bit. A global entry matches
        regardless of ASID.
ITLB-4a VMID tagged as well, and carry a V bit. H is mandatory in
        RVA23 through Sha, so an entry is either a `V=0`
        single-stage translation or a `V=1` two-stage one, and a
        `V=1` entry belongs to one guest. A hit requires the V bit
        to match, and for `V=1` the VMID to match. The global bit
        applies within a VMID, not across guests.
ITLB-5  Hit latency is one cycle. The PMP and PMA check is not in
        this path. See ITLB-12.

64 fully associative holding all page sizes in one array is the Zen shape, which is the largest fully associative L1 ITLB found in the survey. Neoverse N1 and V2 and XiangShan Kunminghu are at 48. The only 128-entry L1 ITLB in the survey, Broadwell, is 4-way with a separate 8-entry array for large pages, so it is not evidence that 64 fully associative can be exceeded.


3. Replacement and sizing

ITLB-6 Replacement is not-most-recently-used over the 64 entries.

ITLB-7  ASID width is 16 bits, the Sv39 maximum. VMID width is 14
        bits, the Sv39x4 maximum.

Neither of these was in the L1I-U2 recommendation. Both are required to build the array and are recorded here rather than left unstated.


4. Miss protocol

ITLB-8  The ITLB is non-blocking. On a miss it returns a miss
        response to the requester and remains available to serve
        hits from other requests while the walk is outstanding.
ITLB-9  The requester re-requests. The ITLB does not hold the
        faulting request and does not retry on the requester's
        behalf.
ITLB-10 The ITLB tracks outstanding walks and does not issue a
        second walk for a VA and ASID that already has one in
        flight. A re-request that matches an in-flight walk
        receives a miss response without generating walk traffic.

ITLB-10 is the consequence of ITLB-9. The requester re-requests the same VA while the walk is outstanding, so without a match against in-flight walks the ITLB issues duplicate walks for every retry. This is the same shape as the L1I-14 MSHR target problem.

ITLB-10a A WALK FAULT IS HELD in its tracker slot until the IFU
         re-requests that address, and is answered then as a
         fault. Under ITLB-9 the requester re-requests rather than
         waiting, so the fault has to be kept for it. An invalidate
         drops held faults (ITLB-14). Built by BP-118, accepted
         session-075 (Jeff). The held fault keeps everything the
         walker returned with it: the cause, the GPA and its
         implicit-access kind (IL-11a, IL-11b, IT-6c); session-077.
ITLB-10b A HELD FAULT RECORDS THE PRIVILEGE AND V it was raised at.
         The walker's U check depends on them (mmu_decisions.md
         MMU-8c), so a fault raised at one privilege is not the
         answer at another. A re-request whose privilege or V
         differs from the held fault's drops the held fault and
         issues a new walk at the current privilege; one that
         matches is answered with the held fault as ITLB-10a says.
         Every held fault is tagged, whatever its cause, so the
         rule has no per-cause case. RULED session-077 (Jeff),
         after BP-123; BUILT by BP-124. As built, a held fault for
         the same page is dropped when a request at another
         privilege or V is answered miss; ASID and VMID do not enter
         the condition, since a change of V changes which one is
         compared (BP-124 Assumption 6).
ITLB-U1 CLOSED session-075 (Jeff) by ITLB-15. The question was
        the depth of the in-flight walk tracker. One outstanding
        walk makes ITLB-8 mean only that hits continue during a
        miss. More than one requires the walker to accept more
        than one, which is an `mmu_decisions.md` question and is
        bounded by how many transactions the l2 slave accepts,
        TD#118.
ITLB-15 The walk tracker depth is a parameter, default 1. The
        walker performs one walk at a time (MMU-U2, ruled
        session-077), so more buys nothing until it performs more.
        IL-1's two-bit tag allows up to four and is not tied to
        this value. This read "The l2 serialises walks (TD#118,
        MMU-U2)".

5. Faults

ITLB-11 The ITLB returns a fault cause, not a single non-faulting
        bit. Three outcomes: hit, miss, fault.

The faulting virtual address is not returned on the port. The IFU supplied it and holds it against the request tag, and pairs it with the cause on the way into ifu_pd_pkt_t (this read predecode_pkt_t; DCD-16, session-075). itlb_ifu_interfaces.md IT-5. The pair still reaches the backend as Sstvala requires; it is assembled one step later.

Three fault causes reach the IFU: instruction access fault, cause 1, from the PMP or PMA check in mmu_decisions.md; instruction page fault, cause 12, from a single-stage or VS-stage translation; and instruction guest-page fault, cause 20, from the G-stage. The third exists because H is mandatory in RVA23 through Sha. The IFU cannot collapse them.

Sstvala is mandatory in RVA23S64 and requires stval to carry the faulting virtual address for page-fault, access-fault and misaligned exceptions, and for breakpoint exceptions that write an address; it does not name the guest-page fault, cause 20, for which the profile mandates Shtvala and Shvstvala instead (mmu_decisions.md 7, rva23-profile.adoc). The VA travels with the cause on all three here because the IFU pairs them (IT-5), not because Sstvala requires it on cause 20. On cause 20 the guest PHYSICAL address travels separately, on IT-6a, for htval (MMU-23). This named page-fault and access-fault only, then all three. Session-072.

l1i_ifu_interfaces.md needs no amendment for this. IF-8 is a gate condition, issue only on a valid non-faulting translation, and section 8 already separates what lies behind it: IF-23 is the fault case and IF-24 the miss case. Nothing there collapses two causes into one bit.


ITLB-16 THE PTE PERMISSION CHECK IS MADE ON EVERY HIT, against
        the current privilege, and raises cause 12. The entry
        holds the permission byte of IL-8. A fetch faults when X
        is clear; in U-mode, or VU-mode for a V=1 entry, when U is
        clear; in S-mode, or VS-mode, when U is set. SUM does not
        apply to instruction fetch, and MXR concerns loads only.
        Ruled session-075 (Jeff).
    It cannot be made once at walk time and cached as a
    result: privilege changes without a fence, so the same
    entry can be legal at one hit and faulting at the next.

    G-STAGE PERMISSIONS ARE NOT CHECKED HERE. Every G-stage
    access is treated as a user-mode access, so the result
    does not depend on the current privilege, and the walker
    checks it and returns cause 20 (mmu_decisions.md MMU-26).

    THIS CHECK APPLIES ONLY WHEN A SINGLE-STAGE OR VS-STAGE
    LEAF EXISTS. A G-stage-only entry (V=1, vsatp.MODE Bare)
    holds the G-stage leaf's byte with G cleared (IL-8,
    mmu_decisions.md MMU-31); a G-stage leaf always has U set,
    so applying this check faulted every VS-mode fetch through
    such an entry. Found and fixed by BP-123 (D7), accepted
    session-077 (Jeff). This read as applying to every hit.

    THE WALKER ALSO CHECKS U, ONCE, BEFORE IT SETS A
    (mmu_decisions.md MMU-8c), so a walk never sets A on a
    leaf this check would fault. The check on every hit stands:
    privilege changes without a fence. Ruled session-077
    (Jeff); BUILT by BP-124.
ITLB-17 The ITLB reads its translation regime from a CSR input
        group on the front-end boundary: V, the current privilege,
        satp ASID and MODE, vsatp ASID and MODE, hgatp VMID and
        MODE. It holds no CSR of its own. fe_decisions.md FE-20.
        Ruled session-075 (Jeff).
    A WALK REQUEST CARRIES THE ACCESS TYPE AND THE PRIVILEGE
    (itlb_l2tlb_interfaces.md IL-3d, mmu_decisions.md MMU-24c).
    The ITLB presents execute on `itlb_l2t_acc` and its current
    privilege from this group on `itlb_l2t_priv`, with V on
    `itlb_l2t_v`. Ruled session-077 (Jeff); BUILT by BP-124.
    As built, `itlb_l2t_priv` is the privilege recorded when the
    miss allocated its tracker slot, the one the walk is for and
    the one a held fault is tagged with; it is not re-read while
    the request waits (BP-124 Assumption 5).
    BP-123 built `itlb_l2t_acc` on the walker only (D2), tied to
    execute in tb_fe_top.

6. Check placement

ITLB-12 The PMP permission check, the PMA executable check and the
        read of the EFFECTIVE cacheable and idempotent attributes
        (ITLB-3a, mmu_decisions.md MMU-14) all complete BEFORE any
        L1I request is issued. A request that fails them is never
        made. This read "the PMA idempotent read"; the effective
        type includes the PTE's PBMT. Session-071.
ITLB-12a None of these checks is in the ITLB-5 hit path. They run
         in the translation pipeline, `ifu_decisions.md` IFU-23a,
         which is a whole pipeline ahead of the fetch pipeline
         that issues to the L1I. The translation returns at the
         ITLB-5 latency and the checks complete before the result
         leaves the queue.

AN EARLIER REVISION OF ITLB-12 HAD THE CHECK GATE THE RESPONSE RATHER THAN THE REQUEST, on the reasoning that a serial check after a fully-associative hit would not fit in one cycle and that L1iReadLatency of 2 left a cycle to hide it in. Two things were wrong with it.

It contradicted l1i_ifu_interfaces.md IF-22, which states that a faulting request never reaches the L1I and that this interface carries no fault port in either direction. Letting a PMP failure reach the array and blocking only the response is exactly the traffic IF-22 forbids.

And its timing argument counted sixty-four PMP range compares. MMU-11 sets sixteen entries.

The argument is moot in any case. The IFU now translates in a pipeline ahead of fetch, so the checks have a pipeline to complete in rather than a cycle, and gating the request costs nothing. Session-069.

The idempotent read was separated from the other two in an earlier revision because a check that gates a response cannot also decide whether a request is made. With ITLB-12 gating the request, the separation is unnecessary: all three are read before the request and all three can stop it. MMU-14 and IT-11 are unchanged.


7. Maintenance

ITLB-13 SFENCE.VMA invalidates ITLB entries by VA, by ASID, by
        both, or all. GLOBAL ENTRIES ARE EXCLUDED BY THE TWO FORMS
        THAT NAME AN ASID, not by everything except the all form.
        The four forms, from RISC-V Privileged Architecture
        chapter 11, Supervisor-Level ISA version 1.13, section
        11.1.2.1 (library version v20260120):
  rs1=x0,  rs2=x0    all entries, all address spaces   global INCLUDED
  rs1=x0,  rs2!=x0   that ASID                         global EXCLUDED
  rs1!=x0, rs2=x0    that VA, all address spaces       global INCLUDED
  rs1!=x0, rs2!=x0   that VA and that ASID             global EXCLUDED
    The specification attaches "except for entries containing
    global mappings" to the two rs2!=x0 forms only. The
    address-only form invalidates entries for the address in
    rs1 "for all address spaces", with no exclusion stated.
    Corroborated from the other side by the G bit description
    in 11.1.3.1: global mappings need not be flushed when
    SFENCE.VMA is executed with rs2!=x0. The exclusion is tied
    to rs2!=x0 exactly.

    AN EARLIER REVISION SAID "global entries are invalidated
    only by the all form". That dropped the address-only form
    and would leave a stale global translation alive across
    `sfence.vma rs1, x0`. That is a correctness bug, not a
    prediction-quality one: the ITLB would answer a later fetch
    from an invalidated mapping. Corrected session-070.

    It affects `V=0` entries and, when executed in VS-mode, the
    current guest's VS-stage entries.
ITLB-13a HFENCE.VVMA invalidates `V=1` VS-stage entries for the
         current VMID, by VA and by ASID. HFENCE.GVMA invalidates
         `V=1` entries by guest physical address and by VMID.
         Both arrive on the ITLB-14 port with an operation field.
     HFENCE.VVMA CARRIES THE SAME GLOBAL RULE AS ITLB-13. The
     privileged specification says its effect "is much the same
     as temporarily entering VS-mode and executing SFENCE.VMA",
     so it has the same four rs1/rs2 forms and global entries
     are excluded only by the two that name an ASID (rs2!=x0).
     The VA-only form invalidates global VS-stage mappings for
     that address. Global is per-VMID here, not across guests,
     ITLB-4a. Checked session-070 when ITLB-13 was corrected.

     HFENCE.GVMA HAS NO GLOBAL CASE. It selects by guest
     physical address and VMID and takes no ASID, so the
     exclusion has nothing to key on.

     GVMA INVALIDATES EVERY V=1 ENTRY OF THE VMID, or of all
     VMIDs, whatever address it names. An entry holds the
     guest virtual page and the final physical page, not the
     guest physical address, so it cannot be matched by GPA.
     Invalidating more than required is legal. Built by BP-118,
     accepted session-075 (Jeff).
ITLB-14 The invalidate port is a distinct port, not carried on the
        translation request path. It is written with the module.
        The front-end top exposes it as a boundary input, since its
        producer is the backend, which does not exist (FE-20).
        Ruled session-075 (Jeff). AS BUILT BY BP-118, one cycle, no
        ready:
  bkend_itlb_inv_val                      backend -> ITLB
  bkend_itlb_inv_op     [1:0]             0 VMA   SFENCE.VMA,
                                                  SINVAL.VMA
                                          1 VVMA  HFENCE.VVMA,
                                                  HINVAL.VVMA
                                          2 GVMA  HFENCE.GVMA,
                                                  HINVAL.GVMA
                                          3 reserved, all
  bkend_itlb_inv_rs1_nz                   select by address
  bkend_itlb_inv_rs2_nz                   select by ASID (VMA,
                                          VVMA) or VMID (GVMA)
  bkend_itlb_inv_vpn    [VA_WIDTH-13:0]   the rs1 page
  bkend_itlb_inv_asid   [ASID_WIDTH-1:0]
  bkend_itlb_inv_vmid   [VMID_WIDTH-1:0]  VVMA the current VMID;
                                          GVMA rs2's VMID
    VMA acts on V=0 entries and VVMA on the V=1 entries of
    inv_vmid; global entries are excluded only when rs2_nz
    (ITLB-13). An SFENCE.VMA in VS-mode is presented as VVMA
    with the current VMID. SFENCE.W.INVAL and SFENCE.INVAL.IR
    are not presented (ITLB-13b). Every invalidate releases the
    walk tracker: unsent walks are dropped, in-flight walks are
    killed and install nothing (IL-13, IL-14), and held faults
    (ITLB-10a) are dropped.
ITLB-13b Svinval, mandatory in RVA23S64, per mmu_decisions.md
         MMU-U8 (adopted session-071): SINVAL.VMA acts as
         SFENCE.VMA with ITLB-13's four forms and global rule,
         HINVAL.VVMA as HFENCE.VVMA and HINVAL.GVMA as HFENCE.GVMA
         (ITLB-13a), all on the ITLB-14 port. SFENCE.W.INVAL and
         SFENCE.INVAL.IR do nothing at the ITLB.

TD#119 does not reach this document. It is the cachegen schema gap that stops the emitted L1I from carrying an invalidate port. The ITLB is written from this document, so its port is written with it.


8. Open

None. ITLB-U1 closed session-075 by ITLB-15.

MMU-U6, MMU-U7 and MMU-U8, which bounded ITLB-3, ITLB-3a, ITLB-12 and section 7, were ruled session-071.


9. Bindings

L1I-3     PIPT, translation ahead of the array.
L1I-U2    Ruled session-069 at 64 entries, ITLB-1 to ITLB-5.
L1I-U3    Ruled session-069 as recommended, walker side in
          `mmu_decisions.md`, ITLB side in section 4.
IF-8      The gate condition. IF-23 and IF-24 behind it already
          separate fault from miss.
TD#115    Closed by this document.
IT-*      The IFU boundary is `itlb_ifu_interfaces.md`.
IL-*      The walker boundary is `itlb_l2tlb_interfaces.md`; there
          is no L2 TLB now (MMU-1).
          IL-5 is deliberately the opposite of ITLB-8: a miss
          there holds the transaction open rather than ending it.
TD#118    Bounded ITLB-U1, now closed. The walker has its own
          memory port (MMU-2), so TD#118 bounds only the L2 plan.

10. Document History

  2026-09-17  session-070 audit. ITLB-13 corrected. It read "Global
              entries are invalidated only by the all form", which
              is short by one form: the ratified privileged
              specification attaches the global exclusion to the
              two SFENCE.VMA forms with rs2!=x0, so the
              address-only form (rs1!=x0, rs2=x0) invalidates
              global mappings for that address. All four forms are
              now stated explicitly rather than summarised, since
              summarising them is what produced the error.

              Not a prediction-quality issue. A global mapping
              surviving sfence.vma rs1, x0 is a stale translation
              the ITLB will hit on.

              mmu_decisions.md MMU-17 needed no separate fix: it
              says the L2 TLB uses "the same forms as the L1 TLBs",
              which is a pointer to this rule. A cross-reference
              was added there.

  2026-09-19  session-071. ITLB-3 includes the Svnapot 64 KiB case
              and points to MMU-U7 for how it is held; section 7
              records that Svinval's five instructions are MMU-U8;
              section 8 names both. Both extensions are mandatory
              and the document stated a complete set without them.
  2026-09-19  session-071, rulings. ITLB-3: NAPOT held once with a
              masked match and PPN[3:0] substituted. ITLB-3a: the
              entry holds the page's PBMT. ITLB-12: the effective
              attributes gate the request. ITLB-13b: Svinval as
              its fence equivalents.

  2026-09-20  session-072. ITLB-11: the Sstvala sentence named
              page-fault and access-fault only; all three causes
              carry stval.

  2026-09-20  session-072. D30: same Sstvala correction. E26: the
              header records that the registry numbers are issue
              order.

  2026-10-07  session-075, rulings (Jeff). ITLB-15: tracker depth a
              parameter, default 1, closing ITLB-U1. ITLB-16: the
              PTE permission check on every hit, cause 12; G-stage
              permissions are the walker's. ITLB-17: the CSR input
              group. ITLB-14: the invalidate port list is proposed
              by BP-118. ITLB-11: ifu_pd_pkt_t, not predecode_pkt_t.

  2026-10-07  session-075, after BP-118. Built at rtl/mmu/itlb.
              ITLB-14 records the invalidate port as built.
              ITLB-13a: GVMA drops every V=1 entry of the VMID.
              ITLB-10a: walk faults are held for the re-request.

  2026-10-07  session-075, after BP-119. ITLB-3: a reserved size
              code is not installed and is handled as IT-4.

  2026-10-09  session-077. No L2 TLB: the scope paragraph and
              ITLB-15 name the walker as the ITLB's server
              (MMU-1 reversed, MMU-U2 one walk). ITLB-10a: a held
              fault keeps its GPA and implicit-access kind.

  2026-10-09  session-077, after BP-123, rulings (Jeff). ITLB-16
              applies only when a single-stage or VS-stage leaf
              exists (D7), and the walker also checks U before
              setting A (MMU-8c). ITLB-10b: a held fault records
              the privilege and V. ITLB-17: the walk request carries
              the access type and the privilege.

  2026-10-10  session-077, after BP-124. ITLB-10b and ITLB-17
              built, with the drop condition and the recorded
              privilege as built (Assumptions 6 and 5).
itlb_ifu_interfaces.md

planning/interfaces/itlb_ifu_interfaces.md on GitHub

IFU to Instruction TLB Interface

 FILE:    itlb_ifu_interfaces.md
 SOURCE:  session-069
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

Owns the IT-N registry.


1. Scope

Two groups cross this boundary: the IFU asks the ITLB to translate a virtual address, and the ITLB answers.

The requester is the IFU's TRANSLATION pipeline, ifu_decisions.md IFU-24, which runs ahead of the fetch pipeline and queues its results. It is not F0 of the fetch pipeline. Nothing in this document depends on which of the two it is, but a reader placing these ports in the fetch stages would put them in the wrong pipeline. The ITLB's own miss path into the page table walker is not here; it is itlb_l2tlb_interfaces.md. This read "into the shared L2 TLB"; there is no L2 TLB now (mmu_decisions.md MMU-1), session-077.


2. The groups

  ifu_itlb_req_val                        IFU  -> ITLB
  ifu_itlb_req_rdy                        ITLB -> IFU
  ifu_itlb_vpn   [VA_WIDTH-13:0]          IFU  -> ITLB
  ifu_itlb_tag                            IFU  -> ITLB

  itlb_ifu_rsp_val                        ITLB -> IFU
  itlb_ifu_tag                            ITLB -> IFU
  itlb_ifu_status [1:0]                   ITLB -> IFU
  itlb_ifu_ppn   [PPN_WIDTH-1:0]          ITLB -> IFU
  itlb_ifu_cause [CAUSE_WIDTH-1:0]        ITLB -> IFU
  itlb_ifu_gpa   [FAULT_GPA_WIDTH-1:0]    ITLB -> IFU
  itlb_ifu_gpa_imp [1:0]                  ITLB -> IFU
  itlb_ifu_pma   [PMA_WIDTH-1:0]          ITLB -> IFU
IT-16 `ifu_itlb_vpn` is VA_WIDTH - 12 = 29 bits, the fetch
      address above the page offset, not VPN_WIDTH (27). With V=1
      and vsatp.MODE=Bare the fetch PC is a 41-bit guest physical
      address, and with V=0 and satp.MODE=Bare a fetch address
      above bit 35 must reach the PMA check to fault (FE-19). A
      27-bit port drops both. Ruled session-074 (Jeff); this read
      [VPN_WIDTH-1:0]. The IFU port is built at this width on
      both lookups by BP-117, TD#146 closed.
IT-1  One request port. A block that crosses a page needs two
      translations and they are issued on successive cycles, not
      on a second port.
IT-2  `ifu_itlb_tag` is one bit and names which half of the block
      the request covers. 0 is the block's own page, 1 is the
      page the straddle reaches into.
IT-3  The response carries the tag back. Responses may return out
      of order, so the tag is how the IFU attributes them.

IT-1 is the reason IT-3 exists. Two requests are in flight when a block crosses a page, the first can miss while the second hits, and the hit returns first. A second request port would avoid the tag at the cost of a second set of 64 comparators against the fully associative array of ITLB-2, spent on a case that occurs only at a page boundary.


3. The result

IT-4 itlb_ifu_status is three-way, which is ITLB-11.

  2'b00   hit    ppn valid, cause and the block's PMA valid
  2'b01   miss   a walk has started. ppn and cause are invalid.
  2'b10   fault  cause valid. ppn invalid.
  2'b11   reserved
  A reserved status, or a fault whose cause is not 1, 12 or
  20, is treated by the IFU as an instruction access fault.
  Session-074, as BP-116 built it.
IT-5  The virtual address the fault applies to is not returned.
      The IFU supplied it and holds it. Returning it would give
      one fact two producers.
IT-6  `itlb_ifu_cause` distinguishes three causes: instruction
      access fault, cause 1, from the PMP or PMA check of MMU-10
      and MMU-12; instruction page fault, cause 12, from a
      single-stage or VS-stage translation; and instruction
      guest-page fault, cause 20, from the G-stage. H is
      mandatory in RVA23 through Sha, so the third is not
      optional.
IT-6a `itlb_ifu_gpa` carries the faulting GUEST PHYSICAL address
      and is valid only when the cause is 20. Shtvala requires
      `htval` to be written with it, and unlike the virtual
      address of IT-5 the IFU never had it: it is produced inside
      the walk. So it returns here and IT-5 does not apply to it.
      It is FAULT_GPA_WIDTH = 56 bits (mmu_decisions.md MMU-23).
      For kind 00 the ITLB passes the walker's page and the IFU
      fills the offset (ifu_decisions.md IFU-2a). This was
      [GPA_WIDTH-1:0]. Ruled session-077 (Jeff), after BP-123;
      BUILT by BP-124.
IT-6b Nothing about the translation regime is on this port. The
      IFU presents a virtual address and no more.
  The ITLB reads what it needs directly: the V bit, the ASID
  and the VMID for the tag match of ITLB-4 and ITLB-4a, and
  the MODE fields to know whether translation is enabled or
  Bare.

  IT DOES NOT READ THE ROOT POINTERS. The ITLB does not walk,
  so `satp.PPN`, `vsatp.PPN` and `hgatp.PPN` are no use to it.
  They belong to the walker, `itlb_l2tlb_interfaces.md` IL-3c
  and mmu_decisions.md MMU-24a. An earlier revision of this
  rule had the ITLB read all three; until session-077 this
  placed the walker inside an L2 TLB.
IT-6c `itlb_ifu_gpa_imp` is the implicit-access kind of
      `itlb_l2tlb_interfaces.md` IL-11b, valid with IT-6a: 2'b00
      the fetch's own guest physical address, 2'b01 an implicit
      read of a VS-stage page table, 2'b10 an implicit write of
      one, 2'b11 reserved. The ITLB passes it through from the
      walker, holding it with a held fault (ITLB-10a). The IFU
      carries it into `ifu_pd_pkt_t` beside the GPA (DCD-16); the
      backend needs it for htinst (mmu_decisions.md MMU-29). Added
      session-077 (Jeff).

IT-5 is a departure from how ITLB-11 is worded. That rule has the ITLB return the fault cause and the faulting virtual address together, because the pair is what must reach the backend under Sstvala. The pair is assembled in the IFU: it already holds the VA, it receives the cause here, and it carries both into ifu_pd_pkt_t at IB-9 (DCD-16; this read predecode_pkt_t until session-074). Nothing is lost and the VA does not make a round trip.


4. Miss

IT-7  A miss response ends the transaction. The ITLB does not
      hold the request and does not answer it later.
IT-8  The IFU re-requests. It may re-request in any cycle after
      the miss response and the ITLB does not require a minimum
      interval.
IT-9  A re-request for a virtual address with a walk already in
      flight receives a miss response and starts no second walk.
      The ITLB matches against its in-flight walks. This is
      ITLB-10 and it is stated here because the IFU's behaviour
      depends on it: the IFU may re-request freely and cannot
      cause duplicate walk traffic.

5. PMA

IT-10 `itlb_ifu_pma` returns the attributes of MMU-13 on a hit,
      at the bit positions MMU-13 fixes: [0] cacheable,
      [1] coherent, [2] executable, [3] idempotent. They are the
      EFFECTIVE attributes: the region table combined with the
      entry's PBMT, the most restrictive of the two
      (mmu_decisions.md MMU-U6, ITLB-3a). Executable and coherent
      come from the region table alone.
IT-11 The IFU reads cacheable and idempotent to decide the path. A
      fetch with both set is an ordinary L1I request; otherwise it
      is an UNCACHED L1I request (ifu_decisions.md IFU-21,
      l1i_ifu_interfaces.md IF-44), presented only under the commit
      gate of IFU-22, and never allocates in the L1I (MMU-14). So a
      page marked NC or IO never allocates in the L1I. This read
      "otherwise it takes the uncached path of IFU-21 and does not
      reach the L1I"; IFU-21 reversed session-076. Before that it
      read "The IFU reads idempotent" against the region alone.
      Session-071.
IT-12 A PMP or PMA failure arrives ON THIS RESPONSE as status
      fault, cause 1. The checker instance beside the ITLB
      (mmu_decisions.md MMU-10a, MMU-10b) evaluates the translated
      address, and the IFU consumes the result before it issues an
      L1I request; it does not check. On a hit `itlb_ifu_pma` is
      the effective attributes of IT-10, which decide the cached
      or uncached path (IT-11). ITLB-12 and ITLB-12a.
  This read that the checks do not gate this response and that
  the IFU consumes "the PMP and PMA results" from it, which
  left where a denial appears unstated; BP-118 built it as
  cause 1, as MMU-10b already said. Ruled session-075 (Jeff).
IT-12a No L1I request is issued for a block that fails PMP or
       PMA. `l1i_ifu_interfaces.md` IF-22: a faulting request
       never reaches the L1I and that interface has no fault port
       in either direction. The translation pipeline of IFU-23a
       is what makes this free; there is no cycle to save by
       letting the request go and killing the response.

6. Flow control

IT-13 `ifu_itlb_req_rdy` deasserts when the ITLB cannot accept a
      lookup. The IFU holds the request stable until it is taken.
IT-14 The response has no ready. The IFU accepts every response
      in the cycle it is presented. It has a slot for each of the
      two outstanding requests IT-1 permits and cannot run out.

7. Maintenance

IT-15 SFENCE.VMA does not cross this boundary. ITLB-14 gives the
      ITLB a distinct invalidate port and the IFU is not on that
      path.

8. Open

None here. Two items elsewhere bear on this port without changing it: the in-flight walk tracker depth, ITLB-U1, closed by ITLB-15 at a parameter of 1 with the walker performing one walk at a time (MMU-U2), and IT-9 holds at any depth. This read "bounded by TD#118"; session-077. IFU-U5, the translation queue depth that sets how far ahead of the fetch pipeline these requests are issued, was closed session-074 at a parameter of 4; a page-crossing block issues its two lookups on successive cycles (IFU-25, IT-1).


9. Bindings

ITLB-2 The fully associative array IT-1 avoids duplicating. ITLB-5 One cycle hit, preserved by IT-12. ITLB-8 Non-blocking, IT-7. ITLB-9 The requester re-requests, IT-8. ITLB-10 In-flight walk match, IT-9. ITLB-11 Three-way result, IT-4. The VA half is IT-5. ITLB-12 Check placement, IT-12. ITLB-14 Invalidate port, IT-15. IFU-7 Two lookups per block, IT-1 and IT-2. IFU-21 The uncached path IT-11 selects. MMU-13 The attributes of IT-10. IB-9 Where the cause and VA are paired. MMU-29 The implicit-access kind of IT-6c.


10. Document History

  2026-10-09  session-077, rulings (Jeff). IT-6c and
              itlb_ifu_gpa_imp, the implicit-access kind. Section 1
              and IT-6b: the walker is the ITLB's server, with no
              L2 TLB (MMU-1 reversed). This document had no history
              section; its earlier changes are in PROJECT_STATUS.

  2026-10-09  session-077, after BP-123, ruling (Jeff). IT-6a:
              itlb_ifu_gpa is FAULT_GPA_WIDTH = 56.

  2026-10-10  session-077, after BP-124. IT-6a built.
itlb_l2tlb_interfaces.md

planning/interfaces/itlb_l2tlb_interfaces.md on GitHub

Instruction TLB to L2 TLB Interface

 FILE:    itlb_l2tlb_interfaces.md
 SOURCE:  session-069
 STATUS:  DRAFT
 UPDATED: 2026-10-15
 CONTACT: Jeff Nye

Owns the IL-N registry.


1. Scope

Two groups cross this boundary: the ITLB presents a miss, and the server answers with a translation or a fault.

THE SERVER IS THE PAGE TABLE WALKER. There is no L2 TLB now (mmu_decisions.md MMU-1, reversed session-077); an ITLB miss goes to the walker directly. The port was written for an L2 TLB and its shape is unchanged: a walker also holds the transaction open until the walk completes (IL-5). An L2 TLB added later sits behind this same port. THE PORT NAMES KEEP l2t, ruled session-077 (Jeff): they are built, and renaming them buys nothing a reader of this paragraph needs. Where the rules below say L2 TLB, read the walker until an L2 TLB exists.

The walk itself, the walker's memory port, and the A and D bit handling are mmu_decisions.md and ptw_mem_interfaces.md.

The L1 data TLB will be a second client of this same port shape. Nothing here is I-side specific and the port is written to be instantiated twice.


2. The groups

  itlb_l2t_req_val                        ITLB   -> walker
  itlb_l2t_req_rdy                        walker -> ITLB
  itlb_l2t_vpn   [VA_WIDTH-13:0]          ITLB   -> walker
  itlb_l2t_asid  [ASID_WIDTH-1:0]         ITLB   -> walker
  itlb_l2t_vmid  [VMID_WIDTH-1:0]         ITLB   -> walker
  itlb_l2t_v                              ITLB   -> walker
  itlb_l2t_tag   [1:0]                    ITLB   -> walker
  itlb_l2t_acc   [1:0]                    ITLB   -> walker
  itlb_l2t_priv  [1:0]                    ITLB   -> walker

  l2t_itlb_rsp_val                        walker -> ITLB
  l2t_itlb_tag   [1:0]                    walker -> ITLB
  l2t_itlb_status [1:0]                   walker -> ITLB
  l2t_itlb_ppn   [PPN_WIDTH-1:0]          walker -> ITLB
  l2t_itlb_size  [2:0]                    walker -> ITLB
  l2t_itlb_perm  [PERM_WIDTH-1:0]         walker -> ITLB
  l2t_itlb_pbmt  [1:0]                    walker -> ITLB
  l2t_itlb_cause [CAUSE_WIDTH-1:0]        walker -> ITLB
  l2t_itlb_gpa   [FAULT_GPA_WIDTH-1:0]    walker -> ITLB
  l2t_itlb_gpa_imp [1:0]                  walker -> ITLB

The far end is the page table walker (section 1). This list read L2TLB at the far end (DOC-002, D9). Session-080.

IL-1a `itlb_l2t_vpn` is VA_WIDTH - 12 = 29 bits, for the reason
      itlb_ifu_interfaces.md IT-16 gives for the IFU side: with V=1
      and vsatp.MODE=Bare the address is a 41-bit guest physical
      address, and a 27-bit field drops bits 40:39. BP-118 built
      it at 29. This read [VPN_WIDTH-1:0]. Session-075.
IL-1  `itlb_l2t_tag` is two bits. Up to four requests may be
      outstanding from one client. The walker accepts one at a
      time (MMU-U2, closed session-077) and answers others retry,
      IL-6; the tag width is unchanged.
IL-2  The response carries the tag back. Responses may return out
      of order.

Two bits covers the two translations IT-1 allows in flight on the I side and leaves headroom. The tracker depth is a separate decision, ITLB-U1, and can change without touching this port. Sizing the tag to the tracker would couple them.

IL-3  The translation context IDENTITY travels with the request:
      the V bit, the ASID and the VMID. The L2 TLB does not hold a
      current ASID or VMID; the client already holds both for its
      own tag match, so sending them keeps one producer.
IL-3c THE MMU DOES READ CSRs. IL-3 is about identity, not about
      the whole CSR file. What the WALK needs is regime state and
      is read directly, not carried per request:
  satp.PPN                 single-stage root
  vsatp.PPN, hgatp.PPN     VS-stage and G-stage roots, MMU-19
  the MODE fields          whether translation is on, and Bare
  menvcfg.ADUE             Svade against Svadu, MMU-7
  henvcfg.ADUE             the same for the VS-stage, MMU-7a
  menvcfg/henvcfg.PBMTE    the PBMT walker checks, MMU-U6

These reach the walker on its own CSR input group, not through the front-end top (mmu_decisions.md MMU-24a). The root pointers are narrower than the architectural fields (MMU-24b).

The division is that identity is a property of the REQUEST and the regime is not. A root pointer is not something one request has and another does not, and putting it on the port would make every client a producer of it.

AN EARLIER REVISION OF IL-3 said the L2 TLB does not read a CSR, full stop. That contradicted MMU-7 and MMU-7a, which already have the MMU read the ADUE bits, and it left the walker with no source for the root it walks from. Session-069.

IL-3a The VMID and the V bit travel with it for the same reason.
      H is mandatory in RVA23 through Sha, so a request is either
      a `V=0` single-stage translation or a `V=1` two-stage one,
      and a two-stage request names its guest. ITLB-4a.
IL-3d THE ACCESS TYPE AND THE PRIVILEGE travel with the request,
      as identity does, because they are properties of one
      request (mmu_decisions.md MMU-24c). `itlb_l2t_acc` is 0
      read, 1 write, 2 execute, 3 reserved; the ITLB always
      presents execute. BP-123 built it on the walker only (D2),
      tied to execute in tb_fe_top, accepted session-077; BP-124
      has the ITLB drive it and fe_top carry it.
      `itlb_l2t_priv` is 2'b00 U or 2'b01 S, with `itlb_l2t_v`
      the effective privilege the walker checks a leaf's U bit
      against before setting A (MMU-8c). Ruled session-077 (Jeff);
      BUILT by BP-124. 2'b10 (reserved) and 2'b11 (M) are never
      presented. SUM and MXR join the request with the DTLB.
IL-3b A `V=1` request commits the walker to a NESTED walk,
      MMU-21, which is several times the work of a single-stage
      one. The port does not distinguish them beyond the V bit;
      the cost difference is the walker's to absorb and is why
      IL-6 exists. This read "the L2 TLB"; session-077.

3. The result

IL-4 l2t_itlb_status is three-way.

  2'b00   hit    ppn, size and perm valid
  2'b01   fault  cause valid, ppn invalid
  2'b10   retry  no walk was started, re-request
  2'b11   reserved
IL-5  There is no miss status. An accepted request starts a walk
      and the response is deferred until the walk completes. The
      transaction stays open. This is the opposite of ITLB-8,
      where a miss ends the transaction and the requester
      re-requests. This read "An L2 TLB miss starts a walk";
      session-077.
IL-6  `retry` is not a miss. It means the walker could not accept
      the request, because it is performing another walk
      (MMU-U2), so nothing is in flight and the client must ask
      again. It exists because IL-5 makes the transaction
      long-lived. This read "into its tracker" of an L2 TLB;
      session-077.

IL-5 is why this port differs from the one above it. The ITLB answers the IFU immediately because the IFU has other work and a prediction block to abandon. The ITLB has nothing else to do with a missed translation, so holding the transaction open costs it nothing and saves a re-request path.

This read "a fetch block to abandon"; the fetch block is the 64-byte L1I line (fe_decisions.md Conventions). Session-071.


4. Page size and permissions

IL-7  `l2t_itlb_size` names which page size the translation
      covers: 4 KiB, 64 KiB (Svnapot), 2 MiB or 1 GiB. THREE bits,
      RULED session-075 (Jeff): 3'b000 4 KiB, 3'b001 64 KiB,
      3'b010 2 MiB, 3'b011 1 GiB, 3'b1xx reserved for a future
      size. Ascending, so a larger code always masks more VPN
      bits. BP-118 built two bits; BP-119 widened to three. A
      response that hits with a reserved size code is handled as a
      reserved status (IT-4, IL-4), built by BP-119. The ITLB
      installs the entry at that size, ITLB-3; a 64 KiB entry is
      held once with a masked match (mmu_decisions.md MMU-U7).
      The PPN returned for a 64 KiB page is the PTE's, with
      PPN[3:0] the size marker; the ITLB substitutes on its
      output. This read "which of the three Sv39 page sizes".
      Session-071.
IL-7a For a `V=1` translation the size is the SMALLER of the two
      stages' leaf sizes, and the PPN is the final supervisor
      physical page at that size (mmu_decisions.md MMU-27).
      Session-077. Built by BP-123: the PPN is the final page for
      the request's address (D7, accepted session-077).
IL-8  `l2t_itlb_perm` carries the PTE permission and attribute
      bits the ITLB must hold to answer later hits without asking
      again. Included are the executable, user and global bits.
      The global bit sets the ITLB entry's global flag of
      ITLB-4. For a G-stage-only translation (V=1, vsatp.MODE
      Bare) it is the G-stage leaf's byte with G cleared, and the
      ITLB does not apply ITLB-16 to it (mmu_decisions.md MMU-31).
      Built by BP-123 (D7), accepted session-077.
IL-9  The PMA attributes of MMU-13 are not returned here. They
      come from the static region table and are a function of the
      physical address, so the ITLB derives them from the PPN it
      was given rather than being told.

IL-9 is a placement choice and it follows MMU-15 for the attributes the region table decides. Svpbmt is mandatory in RVA23S64, so the PTE's PBMT field is a second memory type source, per translation, that the region table cannot supply (mmu_decisions.md MMU-U5). This paragraph said a PMA "is a property of an address range, not of a translation" and that returning one would make the L2 TLB "a second source for something the region table already decides", which MMU-U5 contradicts. Session-071.

IL-9a `l2t_itlb_pbmt` returns the page's memory type on a hit: the
      more restrictive of the G-stage and VS-stage PBMT, ordered
      PMA < NC < IO, and PMA (2'b00) when neither stage sets one.
      The ITLB stores it (ITLB-3a) and combines it with the region
      attributes into the effective type, the most restrictive of
      the three (mmu_decisions.md MMU-U6, ruled session-071). A
      reserved PBMT, or a non-zero one with PBMTE clear, never
      reaches this port: the walker faults it.

5. Faults

IL-10 A fault response ends the transaction. The cause
      distinguishes three: a page fault from a single-stage or
      VS-stage walk, a GUEST page fault from the G-stage, and an
      access fault. MMU-16. The access fault has five sources: the
      PMP check the walker makes on every access (MMU-10, MMU-10d),
      the PMA check on every access (MMU-12), a page table outside
      cacheable coherent memory (MMU-12a), a PPN naming an address
      this implementation cannot form (MMU-28), and an error from
      the walker's memory port (ptw_mem_interfaces.md WM-7). This
      named the PMP check only; session-077.
IL-11 The faulting virtual address is not returned. The client
      supplied it and holds it against the tag.
IL-11a The faulting GUEST PHYSICAL address IS returned on
       `l2t_itlb_gpa`, valid on a guest page fault only. The
       client never had it; it is
       produced inside the nested walk. Shtvala requires `htval`
       to carry it. This is the one address that travels back on
       this port, and it continues to the IFU as
       `itlb_ifu_gpa`, IT-6a. It is FAULT_GPA_WIDTH = 56 bits and
       carries every faulting GPA whole (mmu_decisions.md MMU-23).
       For kind 00 (IL-11b) the walker returns the page and the
       IFU fills the offset. Ruled session-077 (Jeff), after
       BP-123; BUILT by BP-124. This read "It is 0 when the
       faulting guest physical address does not fit GPA_WIDTH
       (MMU-30)"; MMU-30 is withdrawn.
IL-11b `l2t_itlb_gpa_imp` says what the GPA is, valid on a guest
       page fault only: 2'b00 the fetch's own guest physical
       address, 2'b01 an implicit read of a VS-stage page table,
       2'b10 an implicit write of one (the Svadu update), 2'b11
       reserved. The backend needs it to write htinst, which must
       be a pseudoinstruction for an implicit-access fault with a
       non-zero htval (mmu_decisions.md MMU-29). It continues to
       the IFU as `itlb_ifu_gpa_imp`, IT-6c. Added session-077
       (Jeff).

6. Maintenance

IL-12 SFENCE.VMA does not cross this boundary, and neither do
      HFENCE.VVMA and HFENCE.GVMA, nor the Svinval instructions,
      which act as those three (mmu_decisions.md MMU-U8). The ITLB
      has its own invalidate port, ITLB-14. The walker has none,
      because it holds no translation (MMU-17); an L2 TLB, when
      added, has its own (MMU-18). Neither forwards to the other.
      MMU-17a.
IL-13 A walk in flight when an invalidate arrives completes. The
      walker installs nothing in any case; an L2 TLB, when added,
      does not install the result. MMU-17. Whether the response is
      still returned to the client, or suppressed so the client's
      tracker entry must time out, is the one thing this port must
      state and IL-14 states it.
IL-14 The response is returned normally. The client installs
      nothing, because a client that received an invalidate in
      the same window discards its own tracker entry. A
      suppressed response would leave the client's tag allocated
      with nothing to release it.

7. Open

None. MMU-U6, MMU-U7 and MMU-U8, which reached IL-7, IL-9 and IL-12, were ruled session-071; IL-9a adds l2t_itlb_pbmt. MMU-U9 was ruled session-077; IL-10, IL-11a and IL-11b carry it.


8. Bindings

ITLB-3    Page sizes, IL-7.
ITLB-4    ASID and global, IL-3 and IL-8.
ITLB-8    Contrasted by IL-5.
ITLB-10   The in-flight match that keeps duplicate requests off
          this port.
ITLB-14   The ITLB invalidate port, IL-12.
ITLB-U1   Tracker depth, decoupled from IL-1 by design.
IT-1      Two outstanding I-side translations, the sizing input
          to IL-1.
MMU-3     The L1 TLBs are clients of this port.
MMU-10    The walker's PMP check, the access-fault cause of IL-10.
          This read "the second cause"; IL-10 lists it third.
          Session-071.
MMU-13    PMA attributes, deliberately absent by IL-9.
MMU-15    The static region table IL-9 defers to.
MMU-17    Invalidate during a walk, IL-13 and IL-14.
MMU-18    The L2 TLB invalidate port, when there is one, IL-12.
MMU-1     No L2 TLB now; the walker is the server, section 1.
MMU-27    The two-stage size, IL-7a.
MMU-29    The implicit-access kind, IL-11b.
MMU-23    FAULT_GPA_WIDTH, IL-11a.
MMU-24c   The access type and privilege, IL-3d.
MMU-31    The G-stage-only permission byte, IL-8.

9. Document History

  2026-10-09  session-077, rulings (Jeff). The server is the walker,
              not an L2 TLB (MMU-1 reversed); the port names keep
              l2t. l2t_itlb_gpa_imp and IL-11b added. IL-7a, the
              two-stage size. IL-10 names every access-fault
              source. IL-1, IL-3b, IL-5, IL-6, IL-12 and IL-13
              restated for a walker. This document had no history
              section; its earlier changes are in PROJECT_STATUS.

  2026-10-09  session-077, after BP-123, rulings (Jeff). IL-3d:
              itlb_l2t_acc as BP-123 built it (on the walker only;
              BP-124 has the ITLB drive it), and itlb_l2t_priv.
              IL-11a: l2t_itlb_gpa is FAULT_GPA_WIDTH = 56, the
              zero sentinel withdrawn. IL-8: the G-stage-only
              permission byte.

  2026-10-10  session-077, after BP-124. IL-3d and IL-11a built.

  2026-10-15  session-080, after DOC-002. Section 2: the far end is
              the walker.
ifu_decisions.md

planning/arch/ifu_decisions.md on GitHub

Instruction Fetch Unit Decisions

 FILE:    ifu_decisions.md
 SOURCE:  session-069
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

Owns the IFU-N, TD-IFU-N and IFU-UN registries. The numbers are issue order and the sections are topical, so they do not run in numeric order: IFU-5 follows IFU-1 in section 1, IFU-4 follows TD-IFU-5 in section 3, and IFU-23 is in section 7 after IFU-23a to IFU-27 in 5.1. Session-072.

Scope is the IFU. Its boundaries are held elsewhere: ftq_ifu_interfaces.md upstream, l1i_ifu_interfaces.md for the instruction side, itlb_ifu_interfaces.md for translation, and ifu_ibuf_interfaces.md downstream. TD#116 closes on this document as revised session-074; section 8 records the rulings.


1. Compressed instruction expansion

IFU-1  Compressed instructions are expanded to their 32-bit form
       in the IFU, before the instruction buffer.

Three consequences follow and are not separate rulings.

The ibuf holds uniform 32-bit slots. It does not pack halfwords, its read and write ports are fixed width, and the only variability on the write side is how many slots are valid in a cycle.

The IFU owns the straddle. A 32-bit instruction can begin in the last halfword of a prediction block. The IFU fetches the 17th halfword (IFU-8), so the instruction completes inside its own block, and the next block, which begins on its tail, walks from position 1 (IFU-11). Nothing downstream sees a partial instruction. This read that the IFU holds the leading halfword across the boundary. Session-074.

The PC is carried per slot. Expansion breaks the correspondence between slot position and address, because a compressed instruction advances the PC by two and occupies a full slot.

IFU-1 matches XiangShan, where RVC expansion sits in the IFU ahead of the IBuffer so the backend decoders see one instruction format.

IFU-5  The IFU presents the ibuf a fixed-width vector of 16 slots
       every cycle with one per-slot enable mask. It does not
       compact. The ibuf compacts on write.

A 32-byte block holds at most 16 instructions, so 16 slots covers the widest case and the port never changes width. Compaction is a shift by a variable amount, and doing it in the IFU puts that shifter in series with expansion and predecode in the same cycle. Moving it into the ibuf puts it against the write port instead.

One mask, not two. The start-within-range of DCD-12 and the truncation by the prediction check of IFU-15 are both IFU-internal and the ibuf needs only the result. ifu_ibuf_interfaces.md IB-2 and IB-3. The port detail belongs to ifu_ibuf_interfaces.md.


2. Slot payload

IFU-2  Each slot delivered to the ibuf is an `ifu_pd_pkt_t`,
       whose fields are `dcd_decisions.md` DCD-16 and
       `ifu_ibuf_interfaces.md` 4: the expanded instruction, its
       start PC, its position within the prediction block, its
       FTQ index, its fault cause, faulting VA and faulting GPA
       with the GPA's implicit-access kind, is_rvc, and its control
       flow classification. Declared in `bp_structs_pkg`, BP-115;
       the kind added session-077. is_vsetvl and needs_vtype were
       also carried until BP-125 removed them (dcd_decisions.md
       TD#148, ruled session-077; ifu_pd_pkt_t 192 -> 190 bits).

This read "its position within the buffer" and "its FTQ pointer", and did not list the faulting VA that IFU-2a refers to. The position is within the prediction block and the index is FTQ_IDX_BITS, the value ftq_resolve_t returns. Session-074.

The start PC and the position are both needed and are not the same thing. Expansion breaks the correspondence between the two, because a compressed instruction advances the PC by two and occupies a full slot.

The fault cause is per slot, not per prediction block. itlb_decisions.md ITLB-11 returns one of three causes and the exception has to reach the backend attached to the instruction it belongs to.

IFU-2a A slot whose cause is an instruction guest-page fault, cause
       20, also carries the faulting GUEST PHYSICAL address. It
       comes back on the translation port, IT-6a, because the IFU
       never had it. Shtvala requires `htval` to be written with
       it. The virtual address of IFU-2 is still carried for
       `stval` and `vstval` under Shvstvala. The GPA's
       implicit-access kind comes with it (IT-6c) and is carried
       the same way; the backend needs it for htinst
       (mmu_decisions.md MMU-29). Session-077.
   THE GPA IS FAULT_GPA_WIDTH = 56 BITS (mmu_decisions.md
   MMU-23), on IT-6a, in the queue of IFU-25 and in
   `ifu_pd_pkt_t.fault_gpa`. For kind 00 the walker returns
   the faulting page and the IFU fills `fault_gpa[11:0]` from
   the faulting halfword's virtual address, ALWAYS, so the
   field is the faulting guest physical address itself; the
   trap path forms htval from it (htval holds the GPA shifted
   right by 2). For kinds 01 and 10 the field is the VS-stage
   PTE's guest physical address, unchanged. Built by BP-123
   (D5) with an exception for a GPA of 0, MMU-30's sentinel;
   RULED session-077 (Jeff), after BP-123, without the
   exception, MMU-30 being withdrawn; the width and the
   unconditional fill BUILT by BP-124.

H is mandatory in RVA23 through Sha, so the guest case is not optional and the GPA field is not conditional on a build option.

TD-IFU-1  CLOSED by `dcd_decisions.md` DCD-16 and BUILT by
          BP-115. The bundle view is a NEW struct, `ifu_pd_pkt_t`,
          in `bp_structs_pkg`; `predecode_pkt_t` in `decode_pkg.sv`
          is not changed and is retired with decode's move to the
          new struct, TD#143. This read that DCD-16 redefines
          `predecode_pkt_t` and that a `decode_pkg.sv` edit
          remained. Session-074.
      `predecode_pkt_t` in `decode_pkg.sv` carries valid, the
      32-bit instruction, three vtype annotations and a branch
      hint. It has no PC, no FTQ index, no fault cause and no
      faulting VA, and nothing else in the package carries
      them. IFU-2 requires all four and they are additions.

3. Predecode

The predecode correction is written back to the FTQ from the IFU and ftq_ifu.sv is Complete including that writeback, so the boundary this section specifies already exists in RTL.

IFU-3 Predecode is in the IFU and is specified in this document.

Decode has no planning document because it is close to a direct translation of the RISC-V specification. Predecode is not in that specification, so it has no home there and would otherwise have none at all.

TD-IFU-5  CLOSED by `dcd_decisions.md`. The predecoder is written
          fresh from that document and neither `predecode.sv` nor
          the old `predecode_pkt_t` constrains it. Retained for
          the record.
      `predecode.sv` as built does not do what IFU-16
      requires. Its output struct carries `may_be_branch`,
      documented as a conservative hint set on the JAL, JALR
      and BRANCH opcodes with full resolution deferred to
      decode, and it is 8 slots wide. IFU-16 needs a 2-bit
      type separating conditional from JAL from JALR, plus
      is_call and is_ret, plus a computed target, across the
      16 positions of `ftq_pd_info_t`. The built module is a
      decode-side helper and the one specified here is a
      different module. Its location under
      `rtl/core/frontend/decode/` is a path and not the
      issue.
IFU-4  Expansion runs before predecode. Predecode operates on the
       expanded buffer and recognises base-ISA branch encodings
       only.

Expansion does not need to know where instructions start. At each 2-byte position the four bytes beginning there are taken, and the low bits of that position alone decide whether a compressed instruction is expanded or a 32-bit one passes through. Every position expands independently, so the start mask and the expanders run in parallel.

The gain is in predecode. On the expanded buffer it recognises JAL, JALR, BEQ and BNE and not also C.J, C.JAL, C.JR, C.JALR, C.BEQZ and C.BNEZ.

XiangShan orders these the other way, predecode at F2 and expansion at F3, and its predecode therefore carries both the instruction-start and RVC detection and the branch classification. IFU-4 splits those: the start mask is computed separately and predecode keeps only the classification.


4. Straddle

A 32-bit instruction can begin in the last halfword of one prediction block and end in the next. Because RVC makes instructions 2-byte aligned, this also happens at a line boundary and at a page boundary, so the second half can miss, can translate differently, and can fault on its own.

IFU-6  The prediction block is not aligned. It begins at the
       predicted target, which is any 2-byte address.
IFU-7  The IFU fetches two cache lines when the block start falls
       in the upper half of a line, and one otherwise.
IFU-8  The IFU covers 34 bytes, not 32: the 32-byte block plus
       the 2 bytes a straddling 32-bit instruction takes from the
       line after it. That is 17 halfword positions. Only the
       first 16 can be instruction starts, so IFU-5 stays at 16
       slots.

IFU-6 is the XiangShan arrangement and IFU-7 and IFU-8 follow from it rather than being separate choices. An unaligned block starting in the upper half of a line runs past the line end, so the second line is needed for the ordinary case, not the edge case.

The second line is a separate translation. It can be in another page, so it can hit in the ITLB when the first missed, fault when the first did not, and arrive at its own time.

The fault raised on the second half belongs to the instruction that started in the first. XiangShan carries an exception mask on its IFU-to-IBuffer boundary that can mark the first instruction of either prediction block for this reason. XiangShan's "fetch block" is its 32-byte prediction block, not pacino's 64-byte fetch block (fe_decisions.md Conventions). Session-071.


5. Pipeline

IFU-9  Five stages: F0, F1, F2, F3 and WB. This is the XiangShan
       segmentation.

IFU-10 Stage contents.

   F0  Accept the FTQ request. Read the translation queue
       head, IFU-25. Issue the L1I request with the physical
       address it supplies, two requests under IFU-7, or none
       when the block's line matches the previous request
       (TD-IFU-8) or the translation faulted (IF-23).
   F1  Compute the PC of every 2-byte position in the block.
       The cache access is in flight.
   F2  L1I data returns. Check it against the request, form
       the per-instruction fault information from the line's
       fault information, compute the jump and fall-through
       ranges, and select the 17 halfword positions of
       IFU-8.
   F3  Expand, predecode, check the prediction, mask, and
       present the slot vector of IFU-5 to the ibuf.
   WB  Write the predecode correction back to the FTQ.

F0 does NOT start a translation. Translation happens in a separate pipeline that runs ahead of this one, section 5.1. L1I-3 makes the L1I physically indexed with translation complete before the array is indexed, so a request issued in the same cycle the lookup began would carry an address that does not exist yet. IF-8 says the same from the other side. An earlier revision of IFU-10 did exactly that.

IFU-11 A 32-bit instruction starting at position 15 completes in
       its own block from the 17th halfword (IFU-8, DCD-2). F3
       holds a register with the address of that tail. A block
       whose start equals it begins its walk at position 1
       (DCD-5). The tail's translation and fault are its own
       block's second result when the straddle crosses a page
       (IFU-25).
   RULED session-074 (Jeff), as BP-116 built it. This read
   that the register holds the leading halfword, its PC and
   its fault, and that the instruction completes in the next
   block. That contradicted IFU-8, and an instruction carried
   into the next block would sit at position -1, which
   ifu_pd_pkt_t.pos cannot express.

L1iReadLatency is 2, so F1 and F2 are mostly the wait for data. That is why five stages carry what BOOM does in four: BOOM's fetchWidth is 4 or 8 instructions and pacino is 16 positions over a 32-byte block, so its F3 work does not compress the same way.

IFU-12 Expansion stays in F3. F3 holds expansion, predecode, the
       prediction check and the mask.

IFU-4 puts expansion ahead of predecode, the reverse of XiangShan, so F2 and F3 do not hold what XiangShan's do. Expansion is a mux per position and predecode on expanded encodings is a narrow decode. The prediction check is a priority encode over the 16 positions to find the earliest control flow instruction, feeding a 40-bit target compare, target[VA_WIDTH-1:1] at VA_WIDTH 41 (fe_decisions.md FE-19, TD-FE-3), and a 4-bit position compare. This read "a 39-bit target compare", the floor computed against the retired 40-bit address. Session-071. F2 keeps the data return, the fault information and the position select.

5.1 The translation pipeline
IFU-23a The IFU has two decoupled pipelines. The TRANSLATION
        pipeline runs ahead and produces physical addresses. The
        FETCH pipeline of IFU-10 consumes them. A queue joins
        them.
IFU-24  The translation pipeline is driven by its own pointer
        into the FTQ, ahead of the pointer the fetch pipeline
        uses. It reads a block's start PC, performs the ITLB
        lookup of `itlb_ifu_interfaces.md`, and enqueues the
        result.
IFU-25  The translation queue holds, per block: the physical
        address, the PMA attributes of IT-10, the fault cause and
        status of IT-4, and the guest physical address of IT-6a
        with its implicit-access kind of IT-6c when the cause is
        20. F0 reads the head. The kind added session-077. The GPA
        is FAULT_GPA_WIDTH = 56 bits in both results (IFU-2a);
        session-077, after BP-123, BUILT by BP-124.
    A BLOCK THAT CROSSES A PAGE HOLDS TWO RESULTS in its one
    entry: the second page's physical address, PMA attributes,
    fault cause, GPA and its kind, valid only for a crossing
    block and filled by a second ITLB lookup in the next cycle.
    A fault on the second page belongs to the positions in it
    (DCD-15).
    Ruled session-074 (Jeff). Ending blocks at page boundaries
    instead would change built BPU and FTQ block semantics for
    an event on well under 1% of sequential blocks.
IFU-26  A block whose effective type is not both cacheable and
        idempotent is marked in the queue and is issued to the L1I
        as an UNCACHED request (IFU-21), under the commit gate of
        IFU-22. This read "is not issued to the L1I. It takes the
        uncached path of IFU-21"; IFU-21 was reversed session-076. MMU-14 and
        IT-11; the effective type includes the PTE's PBMT
        (mmu_decisions.md MMU-U6). This read "translates to a
        non-idempotent region". Session-071.
IFU-27  On a redirect both pipelines are flushed of everything at
        or after the flush index (ftq_ifu_interfaces.md 5). The
        fetch pipeline then stalls until the translation pipeline
        refills the head. How the flush is applied with requests in
        flight is IFU-28 to IFU-32, section 6.1, built by BP-118.
        This read "the queue is emptied" (session-074), and until
        session-075 described the BP-116 stub that cleared all
        state, legal only with nothing outstanding.
    THE COST DEPENDS ON WHETHER F ALREADY HAS CONTENT. From the
    redirect cycle to the first cycle the FTQ presents the
    translation request for the flush index F:
          p2, p3          1 cycle     BP-125, tb_ftq K4, K11
          predecode       2 cycles    BP-117, tb_ftq G5
          backend         2 cycles    BP-113, tb_ftq G11, G16
    For a backend redirect, and for a predecode redirect since
    BP-117 put F at K+1, F is the redirect target block and its
    p1 content write lands at the end of the redirect cycle, so
    there is nothing to translate until then. A p2 or p3
    redirect corrects K, which already has content; BP-125
    measured that row at 1 cycle (this read that it is inferred,
    since tb_ftq drove no p2 or p3 redirect). ftq_decisions.md
    5.1 carries the same table.

    This read "front-end (p2, p3, predecode) 1 cycle" from
    BP-113, measured while predecode still flushed at K.
    Before that, "at least one cycle" for both. Session-075.

This is the XiangShan arrangement with one part left out. XiangShan's IPrefetchPipe queries the MetaArray and the ITLB and writes hit way, ECC and exception information into a WayLookup queue for MainPipe to read, and it documents the same reset and redirect cost: WayLookup is empty, the prefetch and fetch pointers reset together, and MainPipe stalls one extra cycle.

WHAT IS LEFT OUT, AND THIS IS A CHOICE. XiangShan puts the prefetch pipeline inside the ICache and queues the hit WAY along with the translation, so its main pipe reads the data array with the way already resolved. Pacino's L1I is EMITTED by cachegen. Putting a second pipeline, an ITLB client and a lookup queue inside it is a cachegen change of the class INFRA-012 sized for one node: 4 configuration, 5 schema, 8 emitter items. So the translation pipeline is placed in the IFU instead, the L1I is unchanged and still receives a physical address on the l1i_ifu_interfaces.md port, and the queue holds translation only, not the hit way.

The cost of that choice is that the L1I tag compare stays in the fetch path where L1I-5 puts it, so the way is resolved during F1 and F2 rather than ahead of F0. The benefit is that nothing in the emitted L1I changes.

IFU-U5 CLOSED session-074 (Jeff). The translation queue depth is
       a parameter, default 4. An entry frees when its block enters
       F1, whether it issued a request, reused the previous line or
       faulted; the translation result travels with the block.
       Freeing on data return would make the queue cover everything
       in flight, up to 32 blocks at a line buffer of 16. Four
       covers the one-cycle ITLB hit of ITLB-5 at one block per
       cycle. A longer hit would cut throughput whatever the
       depth: the one-bit tag of IT-2 allows one block at the ITLB
       at a time. Translation stays in order, IT-14. XiangShan
       exposes theirs as nWayLookupSize.

The FTQ side is xlate_ptr, ftq_decisions.md 5.1, and the port is ftq_ifu_interfaces.md 4.1. Both were written session-069 with this section. FQ-1 becomes commit_ptr <= fetch_ptr <= xlate_ptr <= alloc_ptr.


6. Prediction check and writeback

ftq_ifu.sv is Complete and is the FTQ half of this boundary, so this section records a contract rather than deciding one. The port names are its port list.

IFU-13 The IFU reports, it does not redirect. There is no
       IFU-to-FTQ redirect port. The FTQ derives the redirect
       from the writeback, which keeps one producer for the fact.
IFU-14 The writeback carries, per block: `pdwb_val`, `pdwb_idx`,
       `pdwb_gen`, a `ftq_pd_info_t` for each of `FTQ_PD_WIDTH`
       positions, `pd_range`, `cfi_val` and `cfi_pos`, `mis_val`
       and `mis_pos`, `target`, `fault_val` and `fault_pos`.
IFU-15 `cfi_pos` and `mis_pos` are different facts. `cfi_pos`
       names the first control flow instruction predecode found.
       `mis_pos` names the position that failed the check. They
       coincide in one of the four mispredict cases and not in
       the others.
IFU-16 Predecode emits, per position: valid, a 2-bit type where
       00 is not a control flow instruction, 01 a conditional
       branch, 10 JAL and 11 JALR, plus is_call and is_ret.
IFU-17 Predecode computes a target for direct branches and JAL.
       For JALR the target field carries no meaning and the FTQ
       does not read it.
IFU-18 Predecode proves a direction only for an unconditional
       branch. It cannot know a conditional's direction, TAGE and
       SC own that, and the entry's prediction stands.
IFU-19 The generation bit issued with the request is carried
       through the IFU and returned with the writeback. A
       writeback whose bit does not match is dropped entirely.
IFU-20 On a flush the IFU drops every in-flight fetch whose index
       is at or after the flush index and discards everything it
       holds for those entries. A request presented in a flush
       cycle is ignored (ftq_ifu_interfaces.md 5, TD#138). Both
       pipelines of IFU-23a are flushed by the one group. This read
       that the flush applies first and that request is the first
       fetch of the corrected stream. Session-074.

IFU-20 is load-bearing beyond the IFU. The generation tag is one bit, and one bit is only sufficient because a stale writeback cannot outlive the flush cycle. If the IFU ever holds a writeback longer than that, the tag width has to be revisited.

6.1 How the flush is applied -- TD#134

RULED session-075 (Jeff). BUILT by BP-118. IFU-28 to IFU-32 say how IFU-20 is met with requests still in flight. They replace the BP-116 stub, which cleared all IFU state and was legal only with nothing outstanding. Clearing all is wrong because the FTQ does not rewind fetch_ptr or xlate_ptr past an entry older than the flush index F (ftq_decisions.md 5.5 R1), so a block older than F that the IFU drops is never presented again.

IFU-28 SURVIVAL. A block SURVIVES a flush when it is older than F,
       measured from the commit pointer: with
       age(i) = (i - ftq_ifu_commit_ptr) mod FTQ_DEPTH, a block with
       FTQ index i survives when age(i) < age(F). Every block the
       IFU holds is at or after commit_ptr, because an entry commits
       only after its instructions have left the IFU, so the age is
       well defined without a wrap bit. Surviving blocks continue in
       every structure: both pipelines, the translation queue and
       the line buffer. Non-surviving blocks are dropped from all of
       them in the flush cycle. RC_UNSPEC, where F is commit_ptr,
       drops everything with no special case.
IFU-29 L1I RESPONSES FOR DROPPED BLOCKS. The L1I has no cancel and
       the IFU accepts every response (l1i_ifu_interfaces.md IF-10).
       At the flush, every in-flight request identifier whose blocks
       all fail IFU-28 is marked KILLED. When a killed identifier's
       response arrives its data is discarded, and the identifier
       and its line buffer slot are freed as for any response
       (IF-11). No generation counter is needed: an identifier
       cannot be reissued while it is in flight (IF-6), so a killed
       identifier cannot be confused with a later request.
IFU-30 A SHARED LINE BUFFER SLOT. A slot that serves more than one
       block (TD-IFU-8, IF-7) survives when any block it serves
       survives; the blocks that fail IFU-28 are removed from it.
       Blocks are taken in order, so the removal is one cut at the
       first non-surviving block.
IFU-28a THE STRADDLE REGISTER (IFU-11) survives a flush only when
        the block after the one that set it survives; otherwise it
        is cleared, and the corrected block at the same address
        walks from position 0. Built by BP-118, accepted session-075
        (Jeff).
IFU-29a A REQUEST ALREADY PRESENTED IS NOT WITHDRAWN. When a flush
        drops a block whose L1I request is presented and not yet
        accepted, the request stays presented, unchanged, until the
        L1I accepts it (l1i_ifu_interfaces.md IF-4), and its
        response is then discarded by IFU-29. F0 accepts nothing
        else meanwhile. Built by BP-118, accepted session-075
        (Jeff).
IFU-31 ITLB LOOKUPS IN FLIGHT. ITLB responses have no ready and may
       return out of order under a one-bit tag naming the half of a
       block (itlb_ifu_interfaces.md IT-2, IT-3, IT-14). When the
       block being translated fails IFU-28, its outstanding lookups
       are DEAD: their responses are dropped, and translation of a
       new block does not start until every dead lookup has
       answered, so a tag value is never shared between a dead and
       a live lookup. When the block being translated survives,
       translation continues. How long the wait lasts is the
       ITLB's miss latency, a property of the ITLB and not of the
       IFU; a testbench model of the ITLB answers when the
       stimulus says and so cannot measure it. What the IFU must
       guarantee is that translation of a new block starts the
       cycle after the last dead lookup answers, and not before.
       This read "BP-118 measures it". Session-075.
IFU-32 THE GENERATION BOUND. After the flush cycle the IFU presents
       no writeback (ftq_ifu_interfaces.md 6) for a block that
       failed IFU-28. This is what keeps one generation bit
       sufficient (IFU-20, ftq_ifu_interfaces.md 6.1), and an
       assertion checks it.

TD#135 (uncached) and TD#136 (maintenance) stayed stubbed after BP-118; BP-123 BUILT both (section 7, l1i_ifu_interfaces.md 10 and 11), accepted session-077 (Jeff). A request presented in a flush cycle is still ignored (IFU-20).

The fault takes two paths and they carry different things. The architectural exception travels with the instruction to the backend, which is the fault cause and faulting VA of IFU-2. The FTQ is told only that the block ended early, which is why fault_pos is declared on the port and not read.

FTB_BLOCK_BYTES is 32, so FTQ_PD_WIDTH is 16 and FTQ_PD_POS_BITS is 4. The writeback array covers the 16 positions that can be instruction starts. The 17th position of IFU-8 has no entry and needs none: it can only be the tail of a straddling instruction, never a start, and it is consumed inside the IFU.


7. Uncached fetch

Fetch from a page whose effective type is non-idempotent or non-cacheable (MMU-14, MMU-U6) cannot use the normal path. MMU-14 forbids speculating into it, and a memory mapped device must not see a read for an instruction that is not on the committed path.

IFU-21 UNCACHED FETCH GOES THROUGH THE L1I, MARKED UNCACHED.
       The request carries ifu_l1i_req_uncached
       (l1i_ifu_interfaces.md IF-44); the L1I serves it from the L2
       whatever its tags hold and does not allocate the line
       (icache_decisions.md L1I-24). RULED session-076 (Jeff),
       REVERSING the session-069 rule, which read "The IFU has a
       second instruction source for uncached fetch, separate from
       the L1I. The L1I is not involved." The L1I's miss path
       already does what an uncached fetch needs; a second source
       would duplicate it as a second memory port, a second response
       path and a second L2 client. TD#135.
IFU-22 The FTQ drives its commit pointer to the IFU continuously.
       The IFU compares the index of the uncached block against
       it and issues the bus transaction only when every earlier
       instruction has committed.

IFU-22 and IFU-23 STAND under the new IFU-21 (confirmed session-076, Jeff): the uncached request is presented only when every earlier instruction has committed, and its instructions are delivered one at a time, each after the previous has committed. They are the no-speculation rule MMU-14 requires.

The IFU cannot learn this any other way. Stopping fetch is what allows the pipeline to drain, but the drain takes an unknown number of cycles and the IFU has no way to observe that it has finished. The FTQ already holds the commit pointer, so what is added is its export, not the knowledge.

The FTQ cannot gate the request instead. Whether a block is uncached is learned in the IFU's translation pipeline, from the PMA result, and marked in the queue entry (IFU-25, IFU-26), after the FTQ has handed the translation request over. This read "from the PMA result at F2". Session-074.

IFU-23 Uncached fetch returns one instruction at a time. It is
       sent to the ibuf alone, and the IFU waits for it to commit
       before issuing the next. Since the request returns a whole
       line (IFU-U4), the next instruction may come from the line
       the IFU already holds or from a new uncached request; either
       meets this rule.
IFU-23b HOW IFU-23 IS MET: EACH UNCACHED INSTRUCTION IS ITS OWN FTQ
        ENTRY. F3 delivers an uncached block's first instruction
        alone. When the block would deliver more, the writeback
        marks that position with `mis_val` and `mis_pos` and sets
        `ifu_ftq_uc_end` (ftq_ifu_interfaces.md 6); the FTQ takes
        the successor as start + 2 * mis_pos + the instruction's
        length, 2 or 4 (ftq_ifu_interfaces.md 7, W3U). The next
        instruction is then the next entry, and IFU-22 gates it at
        F0 against the commit pointer like any uncached block. A
        JALR is delivered alone with no redirect: its target is
        unknown to the IFU, so its successor is the backend's.
        This is XiangShan's MMIO scheme. The alternative,
        per-instruction commit visibility inside the IFU, has no
        port. Built by BP-123 (D1), accepted session-077 (Jeff).
TD-IFU-4  CLOSED. `ftq_ifu_commit_ptr` was added to the fetch
          request group by BP-114 (TD#142). It is a driven value,
          not a query with a response, so it adds no handshake.
          This read that ftq_ifu.sv has no commit pointer output.
IFU-U4 CLOSED session-076 (Jeff). An uncached fetch reads a whole
       L1I line, because pacino never executes from non-idempotent
       physical memory (mmu_decisions.md MMU-15b). The only uncached
       fetch is then from main memory whose PTE marks it NC or IO,
       where reading the bytes around the instruction has no side
       effect. No narrow bus and no split transaction. This read
       "Bus width and the split it forces. XiangShan's MMIO bus is
       8 bytes ... Pacino's uncached bus width is not set.
       Unresolved."

8. The line buffer, issue and reordering

Ruled session-074 (Jeff), closing TD#116. These were listed here as unruled.

TD-IFU-7  CLOSED. The line buffer of `icache_decisions.md` L1I-14
          has a depth that is a parameter, default 16 =
          MAX_OUTSTANDING. One slot is reserved per L1I request
          identifier when it is allocated (`l1i_ifu_interfaces.md`
          IF-7), because the response carries no ready and must
          always have somewhere to land. Size it later with the
          TD#128 harness. What a redirect does to it is IFU-29
          and IFU-30 (TD#134). A slot's reader count is sized by a
          parameter, default the maximum derived from the pipeline,
          with an assertion at the limit; it was fixed at 32 against
          a possible 33 (TD#153, ruled session-075). BUILT BY
          BP-119: parameter LB_RD_MAX, default 2*LB_DEPTH+1 = 33,
          the count stored in 6 bits, and assertion U5 firing when a
          count exceeds the parameter (the default is reachable and
          legal). The 6-bit count never overflowed; the defect was
          the fixed bound only.
TD-IFU-8  CLOSED. Issue is in order, oldest first, whenever a
          translated block, a free identifier and a free slot all
          exist. A block whose line matches the PREVIOUS request
          reuses that request's line-buffer slot and makes no
          request; it shares no identifier, which may already be
          retired. A slot frees when its last block is consumed.
          One comparator catches the common case, consecutive
          blocks in one line. The previous-request register is
          what l1i_ifu_interfaces.md IF-36 clears after a
          maintenance operation's done, as BP-123 built it (its
          Assumption 2, for Jeff to confirm). So two
          sequential blocks make one L1I request, and what merges
          in the L1I MSHRs is a redirect back to a line in flight
          or a non-consecutive repeat.
TD-IFU-9  CLOSED. The reordering store of TD-IF-5 is the line
          buffer itself, consumed in allocation order. A response
          lands in the slot its identifier reserved; F2 takes slots
          in order. No separate structure, and the identifier free
          list bounds it.
TD-IFU-10 MOVED to TD#136. The maintenance path of
          `l1i_ifu_interfaces.md` 11; its producer is the backend
          commit stage, which has no document. Section 7 here
          covers uncached fetch, not this.

9. Open

IFU-U4  CLOSED session-076. Section 7, MMU-15b.
IFU-U6  Instruction prefetch. L1I-19 puts the requester in the IFU
        and ftq_decisions.md 6.1 defers prefetch. Nothing is built;
        ifu_l1i_req_prefetch is driven 0. DEFERRED, session-074.

10. Bindings

ITLB-11   Supplies the fault cause and VA of IFU-2.
M1 to M4  The four mispredict tests are the IFU's to make. M4,
          a predicted taken position outside the fetched range,
          is named explicitly in `ftq_ifu.sv` as the IFU's test.
DCD-*     The predecoder of IFU-3 and IFU-16 is specified in
          `dcd_decisions.md`. This document states where it sits
          and what it must produce; that one states how.
IB-*      The ibuf boundary is `ifu_ibuf_interfaces.md`.
IT-*      The translation boundary is `itlb_ifu_interfaces.md`.
          Its requester is the translation pipeline of IFU-24,
          not the fetch pipeline.
L1I-3     PIPT. The reason F0 cannot start a translation.
L1I-5     2-cycle hit, tag compare after the array read. Stays
          in the fetch path under the IFU-23a placement.
MMU-14    Requires the uncached path of section 7, which goes
          through the L1I since session-076 (IFU-21).
MMU-15b   No execution from non-idempotent memory; closes IFU-U4.
IFU-7     Two lines means up to two ITLB lookups per block.
          `itlb_ifu_interfaces.md` carries both.
IF-8      NOT amended. It is a gate condition -- issue only on a
          valid non-faulting translation -- and stands as written;
          the three causes and the VA are behind it at IF-23 and
          IF-24 (itlb_decisions.md 5). This read "Amended by
          TD-ITLB-1, single non-faulting condition becomes two
          causes plus the VA": no TD-ITLB-1 was ever issued in the
          registry itlb_decisions.md owns, and two causes is three.
          Session-072.
TD#116    Closed by section 8, session-074.
TD#136    Carries TD-IFU-10.
TD#118    The IFU outstanding-request depth has no real target
          until the l2 transaction limit is known. Not yet
          recorded as a decision.
MMU-29    The implicit-access kind of IFU-2a and IFU-25.
MMU-23    FAULT_GPA_WIDTH, the width of the GPA of IFU-2a and
          IFU-25.

11. Document History

  2026-10-09  session-077, ruling (Jeff). IFU-2, IFU-2a and IFU-25
              carry the implicit-access kind of a guest physical
              address (MMU-29). This document had no history
              section; its earlier changes are in PROJECT_STATUS.

  2026-10-09  session-077, after BP-123, rulings (Jeff). IFU-2a:
              the GPA is FAULT_GPA_WIDTH = 56 and the kind-00
              offset fill is unconditional. IFU-25: the queue's GPA
              width. IFU-23b: one uncached instruction per FTQ
              entry, as BP-123 built it (D1). TD-IFU-8: the register
              IF-36 clears (Assumption 2, for Jeff to confirm).
              6.1: TD#135 and TD#136 built.

  2026-10-10  session-077, after BP-124. IFU-2a and IFU-25 built:
              the 56-bit GPA and the unconditional kind-00 fill.
  2026-10-10  session-077, ruling (Jeff). IFU-2: is_vsetvl and
              needs_vtype leave ifu_pd_pkt_t (TD#148, BP-125).

  2026-10-10  session-077, after BP-125. IFU-27: the p2, p3 row
              measured, 1 cycle. IFU-2: the two fields removed.

Tags

Status: RTL complete, interim documentation

The L1I tag and metadata arrays and the hit check.

Specification: icache_decisions.md (in the Overview above)

Related: IA task: TOOLS-004; Frontend demo: fd13_l1i: L1I Hit, Miss and MSHR Merge

Data Arrays

Status: RTL complete, interim documentation

The L1I data arrays, their banking and how a fetch block is read.

Specification: icache_decisions.md (in the Overview above)

Related: IA task: TOOLS-004

I-TLB

Status: RTL complete, interim documentation

The instruction TLB, its lookup, permission checks and refill from the page table walker.

Specification: itlb_decisions.md, itlb_ifu_interfaces.md, itlb_l2tlb_interfaces.md, icache_decisions.md (in the Overview above)

Related: IA tasks: BP-118, BP-124; Frontend demo: fd14_translation: Sv39 Walk, Sv39x4 Nested Walk and Svadu CAS; Frontend demo: fd15_faults: Page, Access and Guest-Page Fetch Faults

PLRU

Status: RTL complete, interim documentation

Tree pseudo-LRU replacement in the L1I and how a victim way is chosen.

Specification: icache_decisions.md (in the Overview above)

Related: IA task: TOOLS-004

Victim Buffer

Status: Not in the current design, interim documentation

Why pacino does not implement a victim buffer for the L1I (L1I-17).

Specification: icache_decisions.md (in the Overview above)

MSHRs

Status: RTL complete, interim documentation

The L1I miss status holding registers, miss merging, and the reserve kept for demand misses.

Specification: icache_decisions.md (in the Overview above)

Related: IA task: TOOLS-004; Frontend demo: fd13_l1i: L1I Hit, Miss and MSHR Merge

Prefetcher

Status: RTL planned, interim documentation

Instruction prefetch; the L1I has no prefetcher, prefetch requests are to come from the IFU, and they are deferred (IFU-U6).

Specification: icache_decisions.md, ifu_decisions.md, l1i_ifu_interfaces.md (in the Overview above)

IL2 Interface

Status: RTL complete, interim documentation

The L1I memory-side port, the TileLink requests it sends on a miss and how fills return.

Specification: icache_decisions.md (in the Overview above)

Related: IA task: TOOLS-004; Frontend demo: fd13_l1i: L1I Hit, Miss and MSHR Merge