Skip to content

Instruction Fetch

Overview

Status: RTL complete, interim documentation

The instruction fetch unit, how it takes FTQ entries, reads the L1I, translates through the ITLB and writes the instruction buffer.

Related: IA tasks: BP-116, BP-123, BP-125; Frontend demo: fd13_l1i: L1I Hit, Miss and MSHR Merge; Frontend demo: fd16_page_cross: A Prediction Block Crossing a Page; Frontend demo: fd20_backpressure: Backpressure

Working specification

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

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.
ibuf_decisions.md

planning/arch/ibuf_decisions.md on GitHub

Instruction Buffer Decisions

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

Owns the IBUF-N, TD-IBUF-N and IBUF-UN registries. The numbers are issue order and the sections are topical, so they do not run in numeric order: IBUF-8, IBUF-8a and IBUF-8b are the redirect rules and sit in section 6, after IBUF-9 to IBUF-11. Session-072.

Scope is the instruction buffer between the IFU and decode. The write side is fixed by ifu_decisions.md and recorded here rather than decided. The port itself is ifu_ibuf_interfaces.md.

BUILT by BP-118 (session-075) as rtl/core/frontend/ibuf, with tb_ibuf and three bound properties.


1. Why the document is short

The ibuf holds instructions the RISC-V specification already defines, so it decides nothing about them. IFU-1 puts compressed expansion in the IFU, so every entry is a 32-bit instruction and the buffer has no variable-length packing. What is left is depth, port widths, and behaviour on a redirect.


2. Structure

IBUF-1  A FIFO. In order in, in order out. No reordering, no
        out-of-order read.
IBUF-2  Entries are uniform. Each holds one `ifu_pd_pkt_t`, the
        struct IFU-2 delivers: `dcd_decisions.md` DCD-16 and
        `ifu_ibuf_interfaces.md` 4.

The start PC is stored per entry rather than derived. Expansion breaks the correspondence between position and address, because a compressed instruction advances the PC by two and fills a whole entry.


3. Write side

IBUF-3  The write port is 16 entries wide with one per-entry
        enable mask. The IFU does not compact. The ibuf compacts
        on write, which is IFU-5. The port is
        `ifu_ibuf_interfaces.md`.
IBUF-4  A block is accepted whole or not at all. The ibuf asserts
        ready only when 16 entries are free, whatever the block
        actually contains.

IBUF-4 is the simplifying choice and it costs capacity. Accepting a partial block means the write logic handles a block split across two cycles and the IFU holds the remainder, which puts state back in F3 that IFU-5 moved out. Requiring 16 free entries wastes up to 15 at the tail and needs no such state.

IBUF-5  Uncached fetch is an ordinary write with one entry valid.
        IFU-23 sends one instruction at a time and the ibuf needs
        no separate path for it.

4. Read side

IBUF-6  The read port is the decode width, in order, from the
        head.
IBUF-7  When the buffer is empty a write bypasses to the read
        port in the same cycle.

IBUF-7 exists because without it every redirect pays an extra cycle refilling an empty buffer, and a redirect is when that cycle is least affordable. The cost is that the write data feeds the read mux combinationally.

IBUF-9  The read port is 8 wide. `instr_decoder.sv` is an 8-wide
        parallel decoder and every port is `[SLOTS-1:0]`.

The ibuf is therefore the width converter of the front end: 16 positions in from one prediction block, 8 out to decode.

IBUF-10 The entry delivers an `ifu_pd_pkt_t` to decode, which
        takes it since BP-118 (dcd_decisions.md DCD-17 to DCD-20).
        This read that `instr_decoder` still took
        `predecode_pkt_t`. Session-075.
TD-IBUF-1  CLOSED by `dcd_decisions.md` DCD-16 and BUILT by BP-115:
           `ifu_pd_pkt_t`, a new struct in `bp_structs_pkg`,
           carries everything IBUF-2 requires. This read that
           DCD-16 redefines `predecode_pkt_t` and that a
           `decode_pkg.sv` edit remained. Session-074.

ftq_pd_info_t, the 16-position predecode array of IFU-14, and ifu_pd_pkt_t, the per-slot bundle here, are different views of the same predecode. The first goes to the FTQ. The second goes through the ibuf, 16 wide on the write port and 8 on the read port; the width belongs to the port, not the type (DCD-1).

IBUF-U1 CLOSED session-075 (Jeff) for this build: NOT BANKED.
        Banking changes only how the 8 read outputs are selected,
        not what the buffer does, and the timing it would fix
        cannot be measured under Verilator. Reopen at physical
        design. The question as raised: a flat depth-to-1 mux per
        read output may be too expensive at 8 outputs, and
        banking replaces it with a per-bank mux followed by a
        select across banks. If banked, the bank count is at
        least the 8 of IBUF-9, since the bank count caps dequeue.
        XiangShan banks for exactly this reason, requires the
        count to be at least its decode width, and sits at 6 and
        6 with no margin. Banking changes nothing about enqueue:
        every entry keeps its own write mux.
IBUF-12 THE READ PORT HAS ONE READY. The ibuf presents up to 8
        valid entries from the head, in order. A single ready from
        downstream dequeues every valid one presented in that
        cycle together; there is no partial dequeue. Ruled
        session-075 (Jeff). Decode is combinational and the stall
        comes from rename, which does not exist, so the ready is a
        front-end boundary input until it does.
    As built by BP-118 the read port is `ibuf_dec_slot
    [0:IBUF_RD_WIDTH-1]` of `ifu_pd_pkt_t` with ready
    `dec_ibuf_rdy`; IBUF_RD_WIDTH is 8.

5. Depth

IBUF-11 The depth is a parameter. 64 to start.

IBUF-4 requires 16 free entries to accept a block, so 32 is the floor: below it the buffer stalls the IFU with entries still free. XiangShan uses the same rule, gating enqueue on IBufSize minus PredictWidth, and sits at 48 against a PredictWidth of 16, which is the floor plus one more bundle. Their decode width is 6, so 48 is eight times it. Pacino decodes 8 wide, and the same ratio gives 64.

The number that would settle it rather than reason toward it is how long a fetch bubble the buffer has to cover at 8 instructions per cycle, and the bubble that matters is an L1I miss, whose real latency is unknown until TD#118 closes.


6. Redirect

IBUF-8  A BACKEND redirect clears the buffer entirely. Nothing in
        it is on the corrected path, because the redirecting
        instruction has executed, is therefore past decode and out
        of the buffer, and everything remaining is younger.
IBUF-13 The clear is `bkend_ftq_redir_val`, wired by the front-end
        top directly to the ibuf: the same signal that enters the
        FTQ (ftq_backend_interfaces.md 5), on every cause including
        RC_UNSPEC. Ruled session-075 (Jeff). Not the FTQ's IFU
        flush, IB-12. In the clear cycle the buffer presents
        nothing and discards that cycle's write, as BP-118 built
        it.
IBUF-8a A predecode redirect does NOT clear the buffer. The
        prediction check and the ibuf write are both in F3
        (`ifu_decisions.md` IFU-12), and the truncation at
        `mis_pos` is in the enable mask (`ifu_ibuf_interfaces.md`
        IB-2), so the instructions after the mispredict never
        enter the buffer. What the buffer holds is blocks older
        than the one being corrected and that block up to
        `mis_pos`, all on the corrected path. So the refetch starts
        at K+1, not K, or K's head would enter twice (IB-13,
        TD#146). Session-074.
IBUF-8b A p2 or p3 redirect does NOT clear the buffer. It fires
        one or two cycles after p1, and FQ-1 gives
        commit_ptr <= fetch_ptr <= xlate_ptr <= alloc_ptr with the
        named entry at or near alloc_ptr. Nothing at or after it
        has been fetched, so nothing at or after it can be in the
        buffer.

AN EARLIER REVISION OF IBUF-8 had every redirect clear the buffer, justified by everything it holds having been fetched after the redirecting instruction. That holds only for the backend case. For a predecode redirect it discards the part of the block before mis_pos that the IFU had just correctly enqueued. Session-069.


7. Open

None. IBUF-U1 closed session-075, not banked; reopen at physical design.


8. Bindings

IFU-2     Sets the entry contents of IBUF-2.
IFU-5     Gives the compaction to IBUF-3.
IFU-23    Uncached fetch, IBUF-5.
IB-12     The clear source, backend redirect alone.
IB-13     The flush index: K for p2, p3 and backend with _self
          set; K+1 for predecode and for backend with _self clear.
          This read "K for predecode", true until BP-117.
          Session-075.
ITLB-11   The fault cause and VA carried in IBUF-2 originate
          here.
IB-*      The write port is `ifu_ibuf_interfaces.md`.
TD#118    Bounds IBUF-11.
ifu_ibuf_interfaces.md

planning/interfaces/ifu_ibuf_interfaces.md on GitHub

IFU to Instruction Buffer Interface

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

Owns the IB-N registry.


1. Scope

One group crosses this boundary: the IFU presents a prediction block's instructions to the ibuf. There is no return path other than the handshake.

The ibuf read side into decode is not here. It is ibuf_decisions.md IBUF-6 and IBUF-9, because decode has no planning document and an interface file into it would be the only planning artifact in that unit.


2. The group

  ifu_ibuf_val                            IFU -> ibuf
  ifu_ibuf_en   [FTQ_PD_WIDTH-1:0]        IFU -> ibuf
  ifu_ibuf_slot [0:FTQ_PD_WIDTH-1]        IFU -> ibuf
                ifu_pd_pkt_t
  ibuf_ifu_rdy                            ibuf -> IFU

FTQ_PD_WIDTH is 16.

IB-1  The port is fixed width. All 16 slot positions are
      presented every cycle a block is offered, whatever the block
      contains. The IFU does not compact and the width does not
      vary.
IB-2  `ifu_ibuf_en` is the per-slot write enable and is the only
      statement of which slots are real. A clear bit means the
      position is not an instruction start, or is outside the
      fetched range, or was truncated by the prediction check.
      The ibuf does not distinguish those cases and does not need
      to.
IB-3  `ifu_pd_pkt_t.valid` is not driven on this port. It is
      produced by the ibuf on its read side, where it says whether
      a read slot holds an instruction. Driving it here would give
      one fact two producers.

IB-2 collapses three IFU-internal facts into one bit. DCD-12's per-position valid is a start within the fetched range, and the prediction check of IFU-15 may truncate the block further at mis_pos. The ibuf sees only the result.


3. Handshake

IB-4  Decoupled valid and ready. `ifu_ibuf_val` asserts when the
      IFU has a block at F3. `ibuf_ifu_rdy` asserts when the ibuf
      can take it.
IB-5  A block transfers whole in one cycle or not at all. There
      is no partial acceptance and no multi-cycle block.
IB-6  `ibuf_ifu_rdy` asserts only when `FTQ_PD_WIDTH` entries are
      free, whatever `ifu_ibuf_en` actually contains. This is
      IBUF-4.

IB-6 is why IB-5 holds. The ibuf reserves for the widest case, so an accepted block always fits and the IFU never holds a remainder. IFU-5 moved compaction out of F3 and a partial transfer would put it back.

IB-7  The IFU holds `ifu_ibuf_val` and the whole payload stable
      while ready is low. F3 does not advance.

4. Payload

Each slot carries ifu_pd_pkt_t as defined in dcd_decisions.md DCD-16:

  valid        produced by the ibuf on its read side, not driven
               here (IB-3)
  instr        the expanded 32-bit instruction
  start_pc     the address of this instruction
  pos          its halfword position in the prediction block,
               counted from the block start
  ftq_idx      the FTQ entry this block came from
  fault_cause  access fault, page fault, guest-page fault, none
  fault_va     the faulting virtual address
  fault_gpa    the faulting guest physical address, valid only on
               a guest-page fault; FAULT_GPA_WIDTH = 56 bits, and
               for kind 00 the whole address, offset included
               (mmu_decisions.md MMU-23, ifu_decisions.md IFU-2a).
               Session-077, after BP-123; BUILT by BP-124
  fault_gpa_imp  the GPA's implicit-access kind, valid with
               fault_gpa: 00 the fetch's own GPA, 01 an implicit
               read of a VS-stage page table, 10 an implicit write
               of one, 11 reserved. DCD-16, session-077
  is_rvc       the instruction was a 16-bit encoding; expansion
               erases the length
  br_type      DCD-7: 00 not a CFI, 01 branch, 10 JAL, 11 JALR;
               the ftq_pd_info_t encoding, not bp_br_type_e
  is_call      DCD-7 and DCD-11
  is_ret       DCD-7 and DCD-11
  is_vsetvl    REMOVED by BP-125 (TD#148): decode computes its
  needs_vtype  own (DCD-17) and nothing read these. Ruled
               session-077 (Jeff); built, 192 -> 190 bits
IB-8  `start_pc` and `pos` are both carried and neither derives
      from the other. Expansion breaks the correspondence: a
      compressed instruction advances the PC by two and fills a
      whole slot.
IB-9  The fault fields are per slot, not per block. The
      architectural exception travels with the instruction it
      belongs to. The block-level fault report is a different
      thing and goes to the FTQ, not here. IFU-2 and DCD-15.
IB-9a Three causes, not two. H is mandatory in RVA23 through Sha,
      so a guest-page fault is a normal outcome and its guest
      physical address rides here for Shtvala. MMU-16. Its
      implicit-access kind rides with it, because htinst must be a
      pseudoinstruction when htval holds the GPA of an implicit
      access (mmu_decisions.md MMU-29). Session-077.
IB-9b On a slot that faulted at fetch only valid, start_pc, pos,
      ftq_idx and the fault fields mean anything; the rest of the
      payload is not to be read. dcd_decisions.md DCD-16a, ruled
      session-075.

vtype_hazard is not on this port. It is an intra-bundle property and the ibuf regroups instructions across bundle boundaries, so a value computed before the ibuf is wrong after it. TD-DCD-1; decode computes it, DCD-17, which closed DCD-U1 session-075. This read "open as DCD-U1"; session-077.


5. Uncached fetch

IB-10 An uncached fetch is an ordinary transfer with one bit set
      in `ifu_ibuf_en`. There is no separate port and no separate
      protocol. IFU-23 and IBUF-5. Built by BP-123 (ifu_decisions.md
      IFU-23b).

The IFU's serialisation for uncached fetch happens before this boundary. By the time a block is offered here the ordering obligation is already met.


6. Redirect

IB-11 The redirect does not cross this boundary. The ibuf clears
      from its own connection, not through the IFU. FE-18 has
      each unit take the redirect by the path it declares, and
      forwarding it through the IFU would delay the ibuf clear by
      the IFU's own handling.
IB-12 The ibuf clear source is the BACKEND REDIRECT ALONE. It is
      not the FTQ flush group of `ftq_ifu_interfaces.md` 5.

That group carries four sources. Two of them cannot have put anything wrong in the ibuf, so clearing on them destroys valid work:

  predecode redirect   truncated by the IB-2 mask in the same
                       stage as the write, so the bad instructions
                       never arrive. IBUF-8a
  p2 / p3 redirect     fires before the named entry is fetched,
                       FQ-1. IBUF-8b
  backend redirect     the only one that can. IBUF-8

The IFU and the ibuf therefore take different events, deliberately rather than by disagreement: the IFU flushes on all four because it has in-flight fetches for entries at or after the named one, and the ibuf holds only what has already been enqueued.

IB-13 The flush index is K for a p2 or p3 redirect and for a
      backend redirect with `_self` set. For a p2 or p3 redirect
      K is not yet fetched and including it is required, because
      the correction changes `taken_pos` and a fetch issued
      against the old prediction would truncate in the wrong
      place. For a PREDECODE redirect it is K+1: K's positions up
      to mis_pos are already in the ibuf by IB-2, the ibuf does
      not clear on it (IB-12), and refetching K would deliver
      them twice. `ftq_ifu_interfaces.md` 7 W3. Ruled session-074
      (Jeff); this read K for predecode too, "including it costs
      nothing". The predecode arm at K+1 is built by BP-117,
      TD#146 closed.
      A backend redirect with `_self` clear flushes at K+1: K is
      fetched and its instructions stand, and refetching it would
      deliver them twice (ftq_decisions.md 5.5 R1,
      ftq_backend_interfaces.md 5 D5). IB-12 is unaffected: the
      ibuf clears on every backend redirect whatever the index.
      This read "The flush index names entry K, not K+1" for the
      flush group as a whole. Session-071. BUILT by BP-112,
      session-073, TD#126 closed: until then the RTL flushed at
      K+1 for a surviving entry on every cause, because the
      redirect CAUSE cannot express the distinction this rule
      needs -- ftq_npc drives RC_MISPREDICT with `_self` clear for
      p2, p3, predecode and the backend alike. The FTQ resolves it
      from ftq_npc's arm_win instead (ftq_decisions.md 5.5 R1).

7. Open

None. IB-U1 closed session-069 as IB-12.


8. Document History

  2026-10-10  session-077, after BP-125. Section 4: the removal
              built.
  2026-10-10  session-077, ruling (Jeff). Section 4: is_vsetvl and
              needs_vtype removed by BP-125 (TD#148).
  2026-10-10  session-077, after BP-124. Section 4: fault_gpa built
              at 56 bits.
  2026-10-09  session-077, after BP-123, ruling (Jeff). Section 4:
              fault_gpa is FAULT_GPA_WIDTH = 56 (MMU-23). IB-10
              built.
  2026-10-09  session-077. Section 4 and IB-9a: fault_gpa_imp, the
              implicit-access kind (MMU-29). The vtype_hazard note
              no longer calls DCD-U1 open.
  2026-10-07  session-075. IB-9b: what a faulting slot carries.
  2026-10-06  session-075. IB-13: the predecode arm at K+1 is built
              by BP-117, TD#146 closed.
  2026-10-01  session-074. The payload struct is ifu_pd_pkt_t,
              a new struct, not a redefined predecode_pkt_t.
              dcd_decisions.md DCD-16. Section 4 gains is_rvc,
              lists valid, and names the DCD-7 fields as the
              struct declares them (BP-115). After BP-116: IB-13,
              a predecode redirect flushes at K+1, TD#146.
  2026-09-22  session-073. IB-13: BUILT by BP-112, TD#126 closed,
              with the note that the rule cannot be keyed on the
              redirect cause.

9. Bindings

IFU-5     Fixed-width vector, compaction in the ibuf. IB-1.
IFU-15    The prediction check truncation folded into IB-2.
IFU-23    Uncached, IB-10.
DCD-7     The classification carried in section 4.
DCD-12    Start and range, folded into IB-2.
DCD-16    Defines the payload.
MMU-29    The implicit-access kind of fault_gpa_imp.
MMU-23    The width of fault_gpa.
IBUF-4    The ready rule, IB-6.
IBUF-5    Uncached as an ordinary write, IB-10.
IBUF-8    The backend clear. IBUF-8a and IBUF-8b are the two
          redirects that do not clear.
TD-DCD-1  Keeps `vtype_hazard` off this port.
ftq_decisions.md

planning/arch/ftq_decisions.md on GitHub

FTQ Micro-Architectural Decisions

 FILE:    ftq_decisions.md
 SOURCE:  fe_decisions.md sections 4.3, 5 and 6
 STATUS:  DRAFT
 UPDATED: 2026-10-15
 CONTACT: Jeff Nye

FTQ-owned behaviour: how the entry is stored, how long it lives, and what it holds for restore.


0. Scope and companion documents

  ftq_entry_formats.md      the two entry structures, field by field
  ftq_bpu_interfaces.md     the ports crossing the BPU boundary
  ftq_ifu_interfaces.md     the ports crossing the IFU boundary
  ftq_backend_interfaces.md the ports crossing the backend boundary
  fe_decisions.md           the BPU <-> FTQ paths: prediction,
                            redirect, slot correction, update
  bp_structs_pkg.sv         the reference declaration

Registries stay in fe_decisions.md and are NOT duplicated here. Front-end invariants are FE-1 through FE-21, technical debt is TD-FE-1 through TD-FE-8, and open items are FE-U1 through FE-U11, all in fe_decisions.md sections 11, 13, 14 and 15. This file cites them by number. This read FE-1 through FE-19 and sections 11, 13 and 14; FE-15 to FE-21 are in section 15. Session-077.

The FTQ has three logical external interfaces, all specified:

  ftq_bpu       BOTH   specified, ftq_bpu_interfaces.md
  ftq_ifu       BOTH   specified, ftq_ifu_interfaces.md (TD-FE-1)
  ftq_backend   IN     specified, ftq_backend_interfaces.md:
                       resolution, redirect, commit

A fourth, ftq_icache, is DELIBERATELY NOT DEFINED. The ICache is an INDEPENDENT MODULE inside the front-end top, a SIBLING of the IFU and not instantiated within it, and the IFU exposes the interface to it (icache_decisions.md L1I-2, fe_decisions.md FE-16). An earlier revision read that the ICache is encapsulated behind the IFU, which stated a hierarchy the design does not have.

THAT CHANGES THE MODULE HIERARCHY AND NOT THIS SECTION'S POINT. There is still no FTQ-to-ICache interface, and the reason is unchanged: XiangShan drives it from its FTQ for physical reasons -- critical path and register replication, with the evidence cited in ftq_ifu_interfaces.md 8 item 1 -- and if pacino meets the same pressure the answer is a pass-through or alternative path created during physical design, not a logical interface carried from the start.


1. Entry storage

bp_ftq_entry_t is read every cycle by fetch. The FTQ reads it again on redirect, to rewrite the named slot, to re-derive the block successor across the slots (fe_decisions.md 2.4), and to present the checkpoint and the RAS snapshot of the entry being corrected (section 3.2 and fe_decisions.md 9). It is read a third time at resolution, for pc and the slot's br_type (fe_decisions.md 7.2).

NO PREDICTOR READS IT, and neither does bp_cluster. The redirect comparison is made inside the cluster, against the prediction the cluster formed at p1 and holds in its own stage registers (FE-4). A prior revision of this section attributed a read to "every redirecting predictor's cluster-boundary comparison". That read does not exist and must not be counted when the fast-path read ports are sized.

SIX FAST-PATH READ PORTS ARE BUILT. The three readings above are the three PURPOSES; they are not the port count, because two of them need two ports each and one needs a port of its own, and BP-112 added a sixth, pc only, for the translation request of xlate_ptr (7.5):

  fetch          the entry ftq_ifu is requesting
  redirect       the entry the winning redirect names, addressed by
                 the ROLLBACK index -- the arbitration's output
  predecode      the entry a writeback names, addressed by the
                 writeback's own index. It CANNOT share the redirect
                 port: the predecode redirect is an INPUT to the
                 arbitration whose output addresses that port, and
                 the correction must be formed in the same cycle
  resolve x2     ftq_backend_interfaces.md 4 fixes resolution at
                 NUM_RESOLVE_PORTS per cycle and the two channels may
                 name DIFFERENT entries, so one port cannot serve both

The commit payload of 5.4 reads the entry at commit_ptr as well; BP-107 formed it inside ftq_entry from commit_step_val rather than exporting a sixth port, because the qualification -- whether the block holds a call or a return -- lives in the entry.

bp_ftq_meta_t is read once per RESOLUTION, so it needs TWO read ports for the same reason the fast path does.



2. Entry Lifetime

  p1            allocate. Fast-path entry written, all slots.
  p2, p3        slots rewritten ON EVERY PREDICTION, per slot, not
                only on a redirect. The later stage wins for the
                slot it names. fe_decisions.md 2.5 and FE-13,
                ftq_bpu_interfaces.md 4a.
  p2, p3        bp_ftq_meta_t written, per slot.
  post-execute  bp_ftq_meta_t read. Updates formed and enqueued.
  commit        entry FREED. 5.3.

The entry's metadata is read at post-execute resolution; the ENTRY IS FREED AT COMMIT (5.3), not at resolution. Allocation and deallocation policy is section 5; FE-U7 is RESOLVED there.

This block read "rewritten by redirect", omitted commit, said the entry "persists until its post-execute resolution", and called the policy "otherwise unspecified (FE-U7)". All four were overtaken by section 5. Corrected session-070.



3. Checkpoint and Restore

The BPU owns all branch history state. Only the FTQ-facing checkpoint and restore are specified here; internal history management is out of scope.

3.1 What is check-pointed

A checkpoint consists of the GHR and PHR circular-buffer pointers, one pair per FTQ entry, indexed by the FTQ entry index:

  ghist_ptr   8    GHR circular buffer pointer
  phist_ptr   5    PHR circular buffer pointer

A checkpoint is block granular: one pair per FTQ entry, covering the bundle (G20). Checkpoints are written with post-update pointer values.

The RAS snapshot (bp_ras_snapshot_t) is a separate field of the fast-path entry, not part of the checkpoint. It is restored on the same redirect (section 3.2):

  TOSR   top of stack read pointer
  TOSW   top of stack write pointer
  BOS    bottom of stack
3.2 Restore

On redirect the FTQ presents the INDEX of the entry being corrected, on ftq_rollback_val / ftq_rollback_idx, and bp_cluster restores ghist_ptr and phist_ptr from its own copy of that entry's checkpoint.

THIS SECTION PREVIOUSLY SPECIFIED THE VALUE FORM -- the FTQ presenting the two pointers themselves. BP-102 settled it as the index form and this wording follows. The checkpoint array inside bp_history and the checkpoint field of the FTQ entry are written from the same p1 allocation and are one to one against an FTQ_IDX_BITS index, so the index selects the same pointer pair at FTQ_IDX_BITS = 6 bits rather than 13 -- ghist_ptr is 8 and phist_ptr is 5 (3.1). This read 14 for the 13; session-070. It read 7 for the index, which is FTQ_PTR_BITS, the pointer with its wrap bit, not this port (ftq_backend_interfaces.md); session-072. The entry still CARRIES the pointer pair (section 2); nothing reads it across this interface.

The index names the entry whose END-of-block pointer state is to be restored, and it is THE ENTRY THE REDIRECT NAMES, bkend_ftq_redir_idx, on every instruction-naming cause and whether bkend_ftq_redir_self is set or clear (ftq_backend_interfaces.md 5 D1). The history and the RAS (D2) restore from the same entry. bp_cluster applies the index it is given and does not validate it.

RULED session-071 (Jeff). This read that with _self set "the naming entry is squashed too and the index is the one before it". That fails in the case _self exists for. A precise trap is taken when the trapping instruction is the oldest in flight, so its entry K is at commit_ptr and K-1 has already been committed and FREED (5.3): its index may be reallocated, and it lies outside the live window 5.5 R2 requires a redirect to name. It also made the history and the RAS restore from different entries for one redirect.

The FTQ arm outranks both of the cluster's own redirect arms unconditionally (ftq_backend_interfaces.md 8).

RAS restoration is ras_decisions.md 4.3 and 4.4, and fe_decisions.md 9. It is the same pointer restore on every redirect cause and needs nothing from this section.



4. Next fetch PC

THE FTQ IS THE REQUESTER. bp_cluster takes ftq_pred_pc_p0 as an INPUT and does not self-steer. PROJECT_STATUS.md said the opposite until 2026-08-19; that describes the XiangShan model, where the BPU holds its own PC and the FTQ supplies only ready and redirect (ia_context/background/fe_qaa.md). Pacino inverted it. The port direction settles it, and this section is the selection the inversion makes the FTQ responsible for.

4.1 The register

One register and its valid, driving the section 3 request group of ftq_bpu_interfaces.md directly:

  r_next_pc   [VA_WIDTH-1:0]  ->  ftq_pred_pc_p0
  r_next_val                  ->  ftq_pred_val_p0

ftq_pred_idx_p0 is the index the FTQ allocates for the request, not part of this selection.

4.2 Selection

Priority, highest first:

  0  reset               the reset vector (4.7)
  1  backend redirect    bkend_ftq_redir_pc
  2  predecode redirect  derived from the IFU writeback,
                         ftq_ifu_interfaces.md 7 W3, or W3U when
                         ifu_ftq_uc_end is set
  3  p3 redirect         bpu_redir_p3[s].target_pc
  4  p2 redirect         bpu_redir_p2[s].target_pc
  5  p1 successor        selection across slots, fe_decisions.md 2.4
  6  hold                retain r_next_pc, deassert r_next_val (4.5)

ARM 2 ALSO CARRIES THE UNCACHED SUCCESSOR. When a writeback sets ifu_ftq_uc_end with ifu_ftq_mis_val (ifu_decisions.md IFU-23b), the successor is not re-derived across the slots: it is start + 2 * mis_pos + the length of the instruction at mis_pos, 2 or 4 (ftq_ifu_interfaces.md 7 W3U), so the next uncached instruction is the next entry and IFU-22 gates it at F0. Every uncached instruction after a block's first therefore costs one arm-2 redirect. Built by BP-123 (D1), accepted session-077 (Jeff). As BP-124 reported, the flush index is K+1, as for any predecode redirect, and W1 and W2 treat the slot as for any predecode redirect (ftq_ifu_interfaces.md 7 W3U).

4.3 The priority is age order, not an axiom

The rule that matters is that THE CORRECTION NAMING THE OLDEST FTQ ENTRY WINS, because everything younger than it is squashed by it anyway. The fixed priority of 4.2 IS that order in a correctly operating pipeline, so no wrap-aware age comparator is needed on this path:

  • Backend resolution is many stages behind fetch, so the entry it names is always older than any entry still inside the BPU or the IFU.
  • Predecode follows fetch, which follows p1, so its entry is always older than the entry at p2 or p3.
  • p3 lags p2 by one cycle, so in a moving stream p3 names the older entry. When the stream is stalled the two hold the same entry and FE-3 decides: the later stage wins. bp_cluster.sv line 945 already resolves the history rollback index exactly this way.

Stated as a consequence rather than an assumption so that a future source which does NOT fit the depth ordering is recognised as such. The fallback is the age comparison itself, and that needs the wrap or generation bit. FE-U7 is RESOLVED (section 5) and did NOT add one: ftq_backend_interfaces.md 9 records that it resolved without adding a generation bit to this interface, and rule R3 still requires one. This said "the wrap or generation bit FE-U7 must define". Session-070.

4.4 The p1 successor and the zero-bubble loop

The p1 successor is the fe_decisions.md 2.4 selection: the first taken slot's target, or the block fall-through bp_ftq_entry_t.pft_addr, delivered at p1 on bpu_pred_pft_p1.

TIMING. To sustain one block per cycle with no bubble, the path from the p1 group through this selection into ftq_pred_pc_p0 must be COMBINATIONAL: the request for the next block is presented in the same cycle this block's prediction is formed. This is the critical loop of the front end and the reason the uBTB exists -- ftb_decisions.md 1 names it the zero-bubble predictor that supplies the fast next-PC. The FTB, TAGE, ITTAGE and SC results all arrive later and correct by redirect; none of them is in this loop.

Redirect targets do NOT need the same treatment. A redirect has already cost the cycles between the mispredicted block and the correcting stage, so one register stage on the redirect path is off the critical loop. Registering the redirect sources and leaving only the p1 successor combinational is the expected implementation.

4.5 Hold conditions

r_next_val deasserts and r_next_pc holds when any of these holds:

  H1  a queued predictor cannot accept a request: any of
      tage_pq_not_full or ittage_pq_not_full low. NOT
      sc_uq_not_full: SC has no prediction queue (bp_arb_spec.md
      5.5), sc_uq_not_full is its UPDATE queue status, and sc.sv
      ties it to 1'b1 (TD#123). ftq_bpu_interfaces.md 3 names only
      pq_not_full outputs as the hold condition. Corrected
      session-070.
      The cluster has NO request-ready output, so
      ftq_bpu_interfaces.md 3 makes this the FTQ's obligation.
  H2  the FTQ has no free entry. Section 5 (FE-U7, resolved).
  H3  the entry at the head of the live window has its FAULT bit
      set. ftq_entry_formats.md 4.3 R1: predicting past a block
      that faulted would queue work that will not be fetched.
      Applies only INSIDE the live window -- a stale bit on a
      committed entry does not hold.
  H4  an FTB update issues in the next cycle (ftq_ftb_sched's
      issue_next). The update takes the FTB's single read port,
      and a lookup presented in that cycle was dropped (TD#162,
      ftb_interfaces.md IC-FTB-09). RULED session-075 (Jeff,
      BP-121 decision 1), BUILT by BP-121 (D7). The RTL signal
      in ftq_npc.sv is h3_ftb_upd; the H numbers here are this
      document's, not the RTL's. Costs one p0 bubble per FTB
      update.
  H5  a predictor's RAM init walk has not finished: any of
      tage_rdy, ittage_rdy or sc_ready low. The RAM Init Interface
      sections of tage_, ittage_ and sc_interfaces.md leave this to
      upstream logic; the FTQ is that logic, and TAGE and ITTAGE do
      not gate on their own readies. RULED session-080 (Jeff),
      BUILT by BP-137. Holds only until the slowest walk ends.

H1 INCLUDES sc_uq_NOT_FULL SINCE BP-121 (read from the RTL by BP-122). The starvation hold of bp_arb_spec.md 4.5 drops tage_pq_not_full, ittage_pq_not_full or, for SC, sc_uq_not_full for one cycle, and ftq_npc holds on all three: w_hold = ~tage_pq_not_full | ~ittage_pq_not_full | ~sc_uq_not_full | h2_ftq_full | r1_fault_hold | h3_ftb_upd | ~tage_rdy | ~ittage_rdy | ~sc_ready, the last three H5 (BP-137). Withholding that p0 request leaves no block at p2 two cycles later, and the SC arbiter grants the waiting update. H1's text above, which excludes sc_uq_not_full because sc.sv ties it to 1'b1, describes sc.sv; at the cluster boundary the signal is the arbiter's. Session-076.

NOT a hold condition: ftq_ifu_req_rdy low. The IFU being unable to accept a fetch does not stop the FTQ predicting ahead. That is the point of a decoupled front end and the FTQ's depth is the decoupling buffer; prediction rate and fetch rate are deliberately separate. Only running out of entries, H2, couples them.

H3 WAS MISSING FROM THIS LIST until BP-107. It is stated in ftq_entry_formats.md 4.3 R1 and was never mirrored here, so a reader working from section 4 alone built two hold conditions where there are three.

4.6 In-flight responses after a redirect

A redirect does not reach into the cluster. bp_cluster has no flush input, so requests already at p0, p1, p2 and p3 for entries the redirect squashed still complete and still present their results.

THE FTQ DROPS THEM. Every cluster response carries the entry index it belongs to -- bpu_pred_idx_p1, bpu_slot_idx_p2, bpu_slot_idx_p3, bpu_blk_idx_p2, bpu_redir_idx_p2, bpu_redir_idx_p3, bpu_meta_idx_p2, bpu_meta_idx_p3 -- and the FTQ ignores any naming an entry it has squashed.

THE MECHANISM IS 5.6 AND NEEDS NO GENERATION BIT. A cluster response returns a fixed number of stages after its request, so the FTQ holds the full pointer of every request in flight in its own shadow and accepts a response only on shadow valid and index match. A reallocated index is told apart from its squashed use by the shadow, not by anything the response carries. This is NOT the situation of ftq_backend_interfaces.md R3: backend resolution latency is unbounded, nothing can shadow it, and R3 still needs the generation bit FE-U7 did not supply (section 5, ftq_backend_interfaces.md 9). This section said the two rules shared that prerequisite, which contradicted 5.6 and 5.8. Session-071.

4.7 Reset vector

bp_defines_pkg::RESET_VECTOR, a parameter, VA_WIDTH wide, default 41'h0_0080_0000_00 -- the same address, 0x8000_0000, at the wider width. It initialises the next-PC register of 4.1 and is selected by arm 0 of 4.2. The literal read 40'h00_8000_0000 until VA_WIDTH went to 41 (fe_decisions.md FE-19); built by BP-109, TD#122 closed.

The privileged specification leaves the reset PC implementation defined. 0x8000_0000 is the RISC-V convention for the base of main memory and the target of the Spike boot ROM; the tree carries no memory map of its own, so the convention stands. Override it at elaboration for a different map.

The first request presents the reset vector in the cycle the last of tage_rdy, ittage_rdy and sc_ready rises (4.5 H5). With the fast-init plusargs that is the first cycle after reset.

It must be FTB_BLOCK_BYTES aligned. 0x8000_0000 satisfies this and the parameter comment records the requirement.

This is a requirement on the RESET VECTOR only and says nothing about prediction blocks in general. Blocks are NOT aligned: a block begins at the lookup PC, which is a taken branch target and so any 2-byte address (4.7, ftb_decisions.md 3). The FTB and the uBTB INDEX on the block-aligned PC, which is a different thing from the block starting there, and it is why two lookup PCs in one 32-byte region share an entry and why ftb_decisions.md 4.5 bounds checks the fall-through.

The reset vector is constrained because there is no preceding block to have established a start: an unaligned reset vector would make the first fetch a partial block with no entry describing it.


5. Queue management (FE-U7, resolved)

5.1 Four pointers

FTQ_DEPTH is 64 and FTQ_IDX_BITS is 6. Pointers are SEVEN bits: the low six index the array, the top bit is the wrap generation.

  alloc_ptr    head.   Next entry to allocate. Advances when a
                       prediction request is accepted at p0.
  xlate_ptr    second. Next entry to translate. Advances on
                       ftq_ifu_xlate_val & _rdy. Session-069.
  fetch_ptr    third.  Next entry to issue a fetch request for.
                       Advances on ftq_ifu_req_val & _rdy.
  commit_ptr   tail.   Next entry to commit and free. Advances at
                       most one entry per cycle; see 5.4.

INVARIANT FQ-1: commit_ptr <= fetch_ptr <= xlate_ptr <= alloc_ptr, in wrap-aware order. The gap between commit_ptr and fetch_ptr is the fetched but unretired stream; the gap between fetch_ptr and alloc_ptr is the PREDICTED BUT UNFETCHED run-ahead, and that gap is the decoupling the FTQ exists to provide. At 64 entries of one 32-byte block it is at most 2 KiB of instruction stream.

xlate_ptr divides that run-ahead in two. Between fetch_ptr and xlate_ptr are blocks whose translation is done and whose fetch has not issued; beyond xlate_ptr are blocks that are predicted and not yet translated.

XLATE_PTR IS BUILT, by BP-112 (session-073), closing TD#127. It resets equal to fetch_ptr, advances on the translation handshake, stops at the written frontier below, cannot be passed by fetch_ptr (FQ-1) and takes the wrap-aware minimum of itself and F on a redirect. ftq_ifu.sv carries the 4.1 request group and ftq_entry.sv a sixth read port, pc only, at xlate_idx. Until then the built FTQ was the three-pointer design: BP-107 completed the unit before session-069 added the fourth pointer.

WHY IT EXISTS. L1I-3 makes the L1I physically indexed with translation complete before the array is indexed, so a fetch request cannot be issued in the same cycle its translation begins. Rather than serialise the two inside the fetch pipeline, the IFU runs translation as a separate pipeline ahead of fetch and queues the results (ifu_decisions.md IFU-23a, IFU-24). xlate_ptr is what drives that pipeline. XiangShan does the same and calls the pair prefetchPtr and fetchPtr.

xlate_ptr is subject to the same unwritten-content hazard as fetch_ptr: it must measure to the fetchable frontier, not to alloc_ptr. See the paragraph below, which applies to both.

OUT OF RESET xlate_ptr and fetch_ptr are set to the same entry. AFTER A REDIRECT each moves back to the flush index if it was past it and is otherwise left where it is (5.5 R1). In the usual case both were past it, land on it together, and the translation queue is empty from that entry on, so the fetch pipeline stalls until translation of that entry completes. That is one or two cycles of added redirect latency, by source as tabulated below, and it is the cost of the scheme; XiangShan documents the identical stall.

THE CASES DIFFER BY WHETHER F ALREADY HAS CONTENT. Counting from the redirect cycle to the first cycle the translation request for F is presented:

  p2, p3                          1 cycle    tb_ftq K4, K11, BP-125
  predecode                       2 cycles   tb_ftq G5, BP-117
  backend                         2 cycles   tb_ftq G11, G16

When F is the redirect target block itself -- the backend case, and the predecode case since BP-117 put F at K+1 -- its p1 content write lands at the end of the first cycle, so there is nothing to translate until then. For p2 and p3, F is K, an entry that already has content, so the request can go out a cycle sooner. MEASURED by BP-125 at 1 cycle for both (tb_ftq group K); this read that the row is inferred, since tb_ftq drove no p2 or p3 redirect. ifu_decisions.md IFU-27 carries the same table.

This table read "front-end (p2, p3, predecode) 1 cycle, tb_ftq G5" from BP-113. G5 was the predecode case, measured while predecode still flushed at K. Session-075.

Both were one cycle worse until BP-113: the p0 request in a redirect cycle carried the pre-rewind alloc index, so its in-flight p1 counted against alloc_ptr-1 and the frontier lagged. TD#139.

This read that after a redirect both "are set to the same entry", which skips unfetched entries older than the flush index when the IFU is behind. Session-071.

THE FETCHABLE FRONTIER IS NOT alloc_ptr. alloc_ptr advances at p0 (5.2) and the entry CONTENT is written at p1, so for one cycle the newest entry in that gap has an index and no content. A fetch issued on the raw gap presents an UNWRITTEN pc to the IFU, and this is reachable in the first two cycles out of reset -- not a corner. The same applies to xlate_ptr, and more often, because xlate_ptr is the pointer nearest alloc_ptr and so meets the frontier first.

The fetchable count is therefore the gap MINUS the requests still in flight between p0 and p1. ftq_shadow already knows: its p1 stage IS that request (5.6), so it exports the count and ftq_ptr subtracts it. FQ-1 is unaffected; what changes is which frontier fetch_pending measures to. Found by BP-107, which is also why the crossing appears in 7.2.

  empty   all four equal
  full    alloc_ptr[5:0] == commit_ptr[5:0]
          and alloc_ptr[6] != commit_ptr[6]

Full is hold condition H2 of section 4.5. It is the only condition under which the FTQ stops predicting.

THE 64-ENTRY FULL CONDITION DEPENDS ON THE COMMIT WATERMARK CARRYING A GENERATION BIT. At 64 live entries the set of values bkend_ftq_commit_idx may legally hold is SIXTY-FIVE, not 64: the 64 live entries, plus the entry just committed, which ftq_backend_interfaces.md 6 promises may sit on the port indefinitely because repeating a watermark is harmless. FTQ_IDX_BITS cannot separate 65 values, and the two readings of the aliased value demand opposite responses -- accepting frees 63 live entries and issues 63 false RAS commits, rejecting deadlocks, since a full FTQ predicts nothing and so can never advance the watermark again. The state is reached by ordinary traffic: the FTQ refilling to full before the backend retires one more block.

The watermark is therefore FTQ_PTR_BITS wide (ftq_backend_interfaces.md 6). Found by BP-106, which built against the narrow port and held allocation at FTQ_DEPTH-1 to remove the 65th value; the port was widened instead and the limit reverted. If the port is ever narrowed again, full must return to FTQ_DEPTH-1 live entries and this paragraph is why.

5.2 Allocation

The index is committed at p0, not at p1. ftq_pred_idx_p0 leaves with the request, so alloc_ptr must advance when the request is accepted. The ENTRY CONTENT is written at p1 from the p1 group. One p1 response is produced for every p0 request -- bpu_pred_val_p1 derives from the staged request valid -- so allocation cannot leak.

fe_decisions.md 2.3 says the FTQ allocates at p1. That describes the entry write. The index is spoken for one cycle earlier.

IN A REDIRECT CYCLE THE INDEX LEAVING AT p0 IS THE REWOUND ONE. The redirect target ftq_npc presents at p0 is allocated from the head 5.5 R1 rewinds to, in that same cycle, and alloc_ptr ends ONE PAST that head when the request is accepted, or on it when H2 holds it. The R1 value itself is unchanged. ftq_ptr exports alloc_req_ptr for this and alloc_idx is cut from it, so ftq.sv's ftq_pred_idx_p0 stays a rename. THE ORDER IS REWIND FIRST, THEN ALLOCATE FROM THE REWOUND HEAD: a redirect outranks an allocation, it does not discard it.

Until BP-113 the index still carried the old alloc_ptr, so the target block was written at p1 to an entry the redirect squashed and never fetched, and the next index issued held target+32. THE FIRST BLOCK OF THE CORRECTED STREAM WAS LOST, on every redirect cause including RC_TRAP and RC_UNSPEC. Instructions that had to execute did not. TD#139, found by BP-112 and fixed by BP-113; five existing checks in tb_ftq and tb_ftq_ptr had encoded the defect as expected behaviour.

ftq_pred_idx_p0 is now combinational on the winning redirect arm, as ftq_pred_pc_p0 already was. A later timing pass moves both together.

Allocation is unconditional: an entry is allocated for every prediction block, including one the p1 predictors miss, so a later stage has an entry to correct (fe_decisions.md 2.3).

5.3 Deallocation

IN ORDER, tail first, one source only: commit. An entry is freed when commit_ptr passes it.

A slot off the executed path never resolves (fe_decisions.md 7.2), so resolution can never free an entry. Squashed entries are freed by the REDIRECT that squashed them, by rewinding the head; see 5.5.

5.4 The commit walk

bkend_ftq_commit_idx is a watermark and may jump several entries at once (ftq_backend_interfaces.md 6). commit_ptr advances toward it at MOST ONE ENTRY PER CYCLE.

The limit is the RAS, not the FTQ. ras_commit_val and its payload group are scalar on bp_cluster -- no slot dimension -- so one commit operation per cycle is the port's capacity. FE-11 guarantees at most one RAS-OPERATING INSTRUCTION per block and therefore ONE SNAPSHOT PER ENTRY, so one entry per cycle is exactly one RAS commit per cycle and the walk never falls behind what the port can carry.

An earlier revision said FE-11 guarantees "at most one RAS operation per entry". Since session-069 that is false: a JALR whose rd and rs1 are both link registers and unequal pops then pushes, two operations at one position (dcd_decisions.md DCD-11, ras_decisions.md 2). The conclusion is unaffected, because the commit carries the entry's post-op snapshot rather than a per-operation record, so two operations at one position still commit as one. Corrected session-070.

An entry cannot be freed before its RAS commit is issued: the commit payload reads bp_ras_snapshot_t out of the entry. Commit and free are therefore the same pointer, not two.

THE WALK COMMITS ONLY WHAT EXECUTED. It reads the RAS operation from the entry's slots, so the slots must hold what resolved. Since BP-121 (D2) every resolution writes its slot and clears the slots above a resolved end (ftq_entry_formats.md 2), and the backend commits an entry only after every resolution naming it is accepted (ftq_backend_interfaces.md 10 A7, ruled session-075). Before BP-121 the walk committed calls that never executed and missed return-calls predicted not taken (TD#161).

ras_decisions.md 4.5 rules restore > commit > hold for BOS, so the FTQ SUPPRESSES the RAS commit it would have issued in a cycle where a redirect restore fires. The walk does not advance that cycle.

RC_UNSPEC ABANDONS THE WALK. A walk in progress may cover entries that have architecturally retired but whose RAS commit has not yet issued. ftq_backend_interfaces.md 5.1 U3 squashes EVERY entry, so those entries are gone and their pending RAS commits are DISCARDED rather than drained. That is correct, not merely tolerable: the RAS is a predictor, so a lost commit costs accuracy and not correctness; U5 already rules both structures self-correcting from committed state; and RC_UNSPEC is reset and debug-mode entry, where draining first would stall entry by up to FTQ_DEPTH cycles to warm a predictor that is about to be re-warmed anyway.

The walk end is snapped back to commit_ptr and NO STEP IS TAKEN in the RC_UNSPEC cycle. Stepping while clearing the end is not a wasted commit but a POINTER OVERRUN: the end lands one entry behind commit_ptr, the age computes as -1, and the walk becomes 2*FTQ_DEPTH-1 entries long. BP-106 hit this in its first draft.

5.5 Redirect rewind

On a redirect naming index K (ftq_backend_interfaces.md 5, or a BPU or predecode redirect):

  R1  alloc_ptr rewinds to K, or K+1 when the naming entry itself
      survives. xlate_ptr and fetch_ptr do NOT follow alloc_ptr.
      Each becomes the wrap-aware MINIMUM of its current value and
      the flush index F of ftq_ifu_interfaces.md 5, so it moves
      only if it was ahead of F. FQ-1 holds because F is never
      past the new alloc_ptr.

        backend, _self clear   F = K+1. K is fetched and its
                               instructions stand; refetching it
                               would deliver them twice
        backend, _self set     F = K
        p2, p3                 F = K. K survives, corrected, and
                               must be fetched against the
                               correction (ftq_ifu_interfaces.md
                               7 W3)
        predecode              F = K+1. K is fetched and its head
                               is already in the ibuf, which does
                               not clear on it; refetching K
                               delivers that head twice. Ruled
                               session-074 (Jeff); this row read
                               K with p2 and p3. Built by BP-117,
                               TD#146 closed
        RC_UNSPEC              F = commit_ptr. U3 squashes EVERY
                               entry, so the oldest live one is
                               the only index that drops every
                               in-flight fetch
                               (ftq_backend_interfaces.md 5.1).
                               This table did not carry the row;
                               ftq_ifu.sv drove fetch_idx and left
                               the fetches between commit_ptr and
                               fetch_ptr unflushed. TD#141, built
                               by BP-114

      BUILT. BP-112 (session-073, TD#126) built the two backend
      rows and the p2, p3 row; xlate_ptr takes the same minimum.
      BP-112 put the predecode arm at F = K with p2 and p3; BP-117
      (session-075, TD#146) moved it to K+1, keyed on arm_win. The
      RC_UNSPEC row is BP-114.

      THE CAUSE BUS CANNOT EXPRESS THIS TABLE. ftq_npc drives
      RC_MISPREDICT with _self clear for p2, p3, predecode and the
      backend alike, so no consumer of the redirect bus can tell
      which row applies. BP-112 routed ftq_npc's arm_win, the
      arbitration arm that won, to ftq_ifu and ftq_ptr. Arms 2, 3
      and 4 are predecode, p3 and p2: arms 3 and 4 take F = K and
      arm 2 takes F = K+1. This read that all three "are the
      front-end set and take F = K", against the predecode row
      above; session-075. THE ARBITRATION ARM, NOT THE CAUSE, IS
      WHAT DISTINGUISHES A FRONT-END REDIRECT, and a reader who
      keys new logic on the cause will rebuild the TD#126 defect.

      Before BP-112: ftq_ifu.sv drove F by _self alone, so it used
      K+1 for a surviving entry on every cause and the p2, p3 and
      predecode row was not built, and ftq_ptr.sv rewound fetch_ptr
      to K+1 with it, so the refetch of K never issued.

      This read "fetch_ptr rewinds with it, since FQ-1 forbids
      fetch_ptr running ahead of alloc_ptr". That made fetch_ptr
      K+1 whenever K survives, so the refetch of K that W3 requires
      never issued, and it moved fetch_ptr FORWARD past unfetched
      entries when the IFU was behind K. Session-071.
  R2  commit_ptr NEVER rewinds. Committed is architectural. A
      redirect can only name an index at or after commit_ptr;
      ftq_backend_interfaces.md R2 makes that the backend's
      obligation and the FTQ does not arbitrate it.
  R3  the entries between the new alloc_ptr and the old one are
      free immediately. No walk, no commit.
5.6 Stale responses, and why the wrap bit is not carried

Section 4.6 requires the FTQ to drop cluster responses naming squashed entries. The response indices -- bpu_pred_idx_p1, bpu_slot_idx_p2/p3, bpu_blk_idx_p2, bpu_redir_idx_p2/p3, bpu_meta_idx_p2/p3 -- are FTQ_IDX_BITS wide and carry NO wrap bit. A rewind can therefore re-allocate an index while a response for the squashed use of that same index is still in flight, and the index alone cannot separate them.

The FTQ keeps a four-deep IN-FLIGHT SHADOW of its own requests, one stage per cluster stage:

  shadow[p1..p3]  { valid, ptr[FTQ_PTR_BITS-1:0] }     3 x 8 bits

FOUR STAGES, THREE FLOPS. Stage p0 is the request being PRESENTED this cycle and is registered NOWHERE -- not in the FTQ and not in the cluster. Building it as four registers is not a subtle error: the p1 response for a request issued at T arrives at T+1, when a four-register shadow still holds that request at stage 0, so every response is checked against the stage behind it, EVERY RESPONSE IS DROPPED, and the front end stops after one block. BP-107 built it that way first and only the unit-level testbench could see it; no leaf test can.

IT CARRIES A FULL POINTER, not an index. Deciding WHICH stages a redirect clears is a wrap-aware AGE comparison and an index cannot make it. Clearing every stage instead is wrong: stage 3 holds an OLDER request than stage 2, so a p2 redirect naming the stage 2 entry squashes stages 1 and 0 and must LEAVE STAGE 3 ALONE. This is not the widening rejected below -- that was FTQ_IDX_BITS at every bp_cluster port and in four metadata structs; this is THREE bits inside the FTQ, one per stored shadow stage. This read "four bits", counting the four stages rather than the three that are flopped.

It shifts every cycle in lockstep with the cluster's own stage registers, which advance unconditionally. A redirect clears the shadow stages holding squashed entries. A response is accepted only if its stage's shadow is valid AND its index matches; otherwise it is dropped.

REJECTED ALTERNATIVE: widening the carried index to include the wrap bit. It would change FTQ_IDX_BITS at every bp_cluster port and widen branch_id in tage_pred_meta_t, sc_pred_meta_t, ittage_pred_meta_t and bp_ftq_entry_t, for no functional gain over 24 bits of shadow in the FTQ. (This and the table above read four stages and 32 bits, against the FOUR STAGES, THREE FLOPS rule immediately below the table. Corrected session-070.)

REJECTED ALTERNATIVE: draining the cluster before re-issuing after a redirect. Correct, and free of the aliasing entirely, but it adds up to three cycles to EVERY redirect. A p2 redirect costs two cycles today; this would more than double it.

5.7 The FTB update scheduler (G9 / IC-FTB-09, resolved)

BUILT by BP-100 as rtl/core/frontend/ftq/rtl/ftq_ftb_sched.sv, the first module of the FTQ unit. The rule below is implemented as written; the properties of 5.7.4 are bound to it by module name and run in its sim target.

The same class of problem as 5.4 and the reason it sits here: a SCALAR predictor port fed by more than one source.

The FTQ has NUM_PRED_SLOTS update channels and ftq_backend_interfaces.md 4 fixes the resolution input at two per cycle. Every predictor takes two except the FTB, whose update is 14 FLAT ports with no slot dimension (ftq_bpu_interfaces.md 8) and which declares NO ready. There is no handshake protecting it: presenting two updates in one cycle silently loses one. The scheduler is therefore a correctness requirement, not an optimisation, and it belongs to the FTQ because the FTQ is what has two channels.

Scope: the FTB ONLY. tage, ittage, sc and ubtb are all per-slot. The RAS is scalar too but is fed from the commit walk of 5.4.

5.7.1 Why one per cycle is not enough

In steady state resolution rate equals prediction rate: every predicted branch eventually resolves. At the 8-issue target of CLAUDE.md, with 15 to 20 percent of dynamic instructions being branches, that is 1.2 to 1.6 branch resolutions per cycle. Every one writes the FTB -- fe_decisions.md 7.2 lists the FTB in all four fan-out rows, and ftb_decisions.md 5.5 steps conf on every resolve.

One write per cycle is therefore below the stated target rate, not below a rare peak. And under FE-5 as originally written the deficit could not be absorbed: no update may be dropped, so the backlog backpressures resolution, which stalls the backend. A PREDICTOR TRAINING limit becomes a MACHINE THROUGHPUT limit. That is the defect this section removes.

IC-FTB-09 was open, not decided. ftb_interfaces.md deferred multi-branch update scheduling to bp_cluster integration and no throughput analysis was ever done. There was no trade to reopen.

5.7.2 Update value

An FTB-bound update is HIGH value when it allocates or corrects:

  HIGH   the FTB missed at predict (ftb_pred_meta_t.hit == 0), so
         this update ALLOCATES the entry. Without it the branch is
         never predicted at all.
  HIGH   the branch mispredicted (ftq_resolve_t.mispredict), so
         this update CORRECTS the thing that was wrong.
  LOW    hit at predict and predicted correctly: a routine conf
         step on a counter already in the right direction.

Both terms are available at update formation with no new state: mispredict arrives on the resolution channel, hit is read from the slow path with the rest of bp_ftq_meta_t.

A dropped LOW update is a DELAYED training step, not a lost entry. The FTB entry still exists with its previous counter, and the next resolve of that branch trains it.

5.7.3 The rule
  S1  FTB-bound means the resolved br_type is anything other than
      NO_BRANCH.
  S2  Pending = the skid entry, if occupied, plus the FTB-bound
      channels accepted this cycle. The skid is ONE deep.
  S3  Issue exactly one: the skid entry when occupied, else the
      highest-value new one, slot 0 breaking a tie. Issuing the
      skid first preserves resolution order (FE-6).
  S4  Retain the highest-value remaining pending update in the
      skid.
  S5  Anything still remaining is DROPPED if LOW.
  S6  A HIGH update is NEVER dropped. If accepting one would force
      S5 to drop a HIGH, the FTQ instead deasserts
      ftq_bkend_rsv_rdy for that channel and the backend holds it.

S6 is what keeps this narrow. Backpressure survives only for allocations and mispredict corrections, and a sustained two-per-cycle rate of those is self-limiting: a mispredict causes a redirect, which flushes the pipeline. Steady state is dominated by correct predictions, which are LOW, so in steady state the FTQ never stalls resolution.

Capacity follows from S2 to S4: one issues and at most one is retained, so at most two new FTB-bound updates can be accepted with the skid empty, and at most one with it occupied.

5.7.4 Properties

Written as concurrent SVA because that is what a formal tool consumes; the BPU tree currently has none -- its three assertion files use procedural immediate assertions and are simulation only. They are BOUND, by MODULE name, in ftq_ftb_sched's sim target (BP-100). TD#109 is the cautionary case: an assertion file bound to an INSTANCE name rather than a module name, instantiated by nothing, warned about by nothing.

Signal names below are the scheduler's port list, as built.

  // P1  A lone FTB-bound update is never dropped and never held.
  property p_ftb_lone_issues;
    @(posedge clk) disable iff (!rstn)
      (n_acc_ftb == 1 && !skid_val) |=> ftb_upd_valid_u0;
  endproperty

  // P2  A HIGH-value update is never dropped. This is the whole of
  //     the FE-5 relaxation: only LOW updates may be lost.
  property p_ftb_high_never_dropped;
    @(posedge clk) disable iff (!rstn)
      drop_val |-> !drop_is_high;
  endproperty

  // P3  The skid never overflows. It is one deep, so a write may
  //     only coincide with the entry leaving.
  property p_ftb_skid_bounded;
    @(posedge clk) disable iff (!rstn)
      (skid_val && skid_wr) |-> skid_issue;
  endproperty

  // P4  An occupied skid always issues NEXT, so the older update
  //     goes first and resolution order is preserved (FE-6).
  //
  //     CORRECTED BY BP-100, from |-> to |=>. As first written this
  //     property and P1 could not both hold in any implementation:
  //     P1 asserts ftb_upd_valid_u0 with |=>, which requires a
  //     REGISTERED output, and P4 asserted the same signal with
  //     |->, which requires a combinational one. The registered
  //     form was built. The intent is unchanged.
  property p_ftb_skid_first;
    @(posedge clk) disable iff (!rstn)
      skid_val |=> (ftb_upd_valid_u0 && ftb_upd_from_skid);
  endproperty

  // P5  Resolution is never stalled when every pending FTB update
  //     is LOW. This is the throughput claim of 5.7.1: training
  //     pressure must not reach the backend.
  property p_ftb_no_stall_on_low;
    @(posedge clk) disable iff (!rstn)
      (n_pend_ftb > 0 && !any_pend_high) |-> (&ftq_bkend_rsv_rdy);
  endproperty

The signal names above are the scheduler's PORT LIST, not internal nets. ftq_ftb_sched carries skid_val, skid_wr, skid_issue, drop_val, drop_is_high and the two pending counts as outputs so the bind reads only ports and makes no hierarchical reference into the module (TD#109). ftq_bkend_rsv_rdy appears on the scheduler as upd_rdy: the scheduler owns only the FTB reason for deasserting it, and the FTQ ANDs that with its others.

P2 and P5 are the two that carry the design intent. P2 bounds the accuracy cost; P5 bounds the throughput cost. P1, P3 and P4 are the structural checks that make the other two meaningful.

Proving P1 to P5 also retires a verification cost. Without them a testbench must model the collision and the priority rule to predict FTB contents at all. With them, simulation can restrict stimulus to non-colliding sequences and check the datapath normally, leaving the drop behaviour to proof. This is a two-input arbiter with a one-bit priority function and one skid register: bounded state, no sequential depth, entirely control.

5.7.5 Not mergeable, and what is left on the table

Two updates naming the same entry hit the same set AND the same way -- the carried hit and way come from ftb_pred_meta_t, which is scalar within the entry -- so their fields are different bit ranges inside one FTB_RAM_ENTRY_WIDTH slice of ftb_array. One RAM write could carry both. That is a real optimisation and it needs NO second write port: ftb_array.sv is a single 512-set array with one write port, and this would widen the write data rather than duplicate the port.

It is NOT taken here. It covers only the same-block case, it requires widening the update payload and reworking ftb_cntrl's write logic in a verified module, and the drop rule above already removes the throughput problem. Recorded as the first escalation if measurement ever shows the LOW drop rate matters.

The second escalation is banking ftb_array by index so two updates to different sets proceed in parallel. Two banks give roughly 1.5 effective writes per cycle for random addresses, not 2.

Neither can be chosen without measurement, and the repository has no simulator to measure with.

5.8 What this settles
  FE-U7  RESOLVED by this section.
  G23    Checkpoint slot reclaim. The checkpoint is a field of the
         entry, so it is reclaimed with the entry at 5.3. No
         separate protocol.
  4.5 H2 Full is defined: 5.1.
  4.6    The drop rule has a mechanism: 5.6.
  G9     Update channel arbitration. The SC half was already done
         and tested (BP-094 group H); the FTB half is 5.7.

The three IFU-facing entry fields deferred by ftq_ifu_interfaces.md 8 item 3 -- request-issued, writeback-received, fault -- are now decidable, and were decided. request-issued is redundant: fetch_ptr already says which entries have been issued. The other two are per-entry status and are ftq_entry_formats.md 4, held in flops outside both SRAMs.


6. Open policy

Collected for navigation. Each is recorded in fe_decisions.md or PROJECT_STATUS.md; none is decided here.

  FE-U7    RESOLVED. Section 5.
  FE-U2    Flush handling. The FTQ side is answered by
           ftq_backend_interfaces.md 5. The RAS behaviour behind D3
           is CLOSED -- it is D2 and nothing more,
           ras_decisions.md 4.4. The flush EVENT and the FTB half
           are CLOSED too, BP-105: there is no flush event, a
           flush is a redirect (fe_decisions.md FE-14). TD#96,
           G24 and IC-FTB-07 all closed.
  FE-U3    bp_ftq_slot_t.confidence has no consumer.
  TD-FE-1  CLOSED, in full. The IFU interface is
           ftq_ifu_interfaces.md; the entry fields it needs are
           ftq_entry_formats.md 4. Two were added, wb_rcvd and
           fault; request-issued was rejected as a second encoding
           of fetch_ptr.
  TD-FE-8  CLOSED. A predecode writeback in flight when its entry
           was squashed and its index reallocated set the status
           bits on the wrong use of that index. One generation bit
           on the IFU path, toggled per allocation.
           ftq_entry_formats.md 4.4, ftq_ifu_interfaces.md 6.1.
  TD-FE-2  The slow-path overload is defined and DEFERRED. See
           ftq_entry_formats.md 3.1.
  TD-FE-3  bp_ftq_entry_t.pc and the per-slot target are VA_WIDTH,
           now 41 (FE-19, TD#122). The floor is 40 as addr[40:1],
           not 39, and 35 is NOT available because blocks do not
           start on an FTB_BLOCK_BYTES boundary (4.7, IFU-6).
           This read "40 bits; 39 suffice under the C extension,
           35 if a block always starts on an FTB_BLOCK_BYTES
           boundary". fe_decisions.md 13 is the owner.
           Session-070.
  TD-FE-4  bp_ftq_slot_t.pred_src is diagnostic only.
  G9       RESOLVED. Section 5.7.
  G23      RESOLVED. The checkpoint is a field of the entry and is
           reclaimed with it at 5.3. Section 5.8.
  RESETVEC RESOLVED. bp_defines_pkg::RESET_VECTOR. Section 4.7.
  PREFETCH Instruction prefetch is DEFERRED and the deferral has a
           structural cost. Section 6.1.
  TD-FE-7  CLOSED by BP-102. bp_cluster gained ftq_rollback_val
           and ftq_rollback_idx, with priority over its own p2/p3
           arms. ftq_backend_interfaces.md 8, section 3.2.

Next-PC selection was on this list and is now section 4. NOTHING remains open from it: the reset vector is bp_defines_pkg::RESET_VECTOR (4.7), which is the RESETVEC entry above. This paragraph said the reset vector "has no source anywhere in the tree", contradicting both 4.7 and the RESETVEC line six rows up. Corrected session-070.

6.1 Instruction prefetch -- DEFERRED, with impact

DECIDED 2026-08-19, alongside the decision not to define an ftq_icache interface. Pacino specifies no instruction prefetcher and no FTQ-sourced prefetch path.

WHAT THIS FORECLOSES, and it is not the same thing the ftq_icache decision defers. That one is PHYSICAL and PD can undo it. This one is FUNCTIONAL and PD cannot.

An instruction prefetcher wants the FTQ's RUN-AHEAD: the entries between fetch_ptr and alloc_ptr (section 5.1), which the BPU has predicted and the IFU has not yet fetched. That stream exists ONLY in the FTQ. The IFU is by construction behind fetch_ptr, so an IFU-encapsulated memory path has no access to it, and no amount of physical-design work creates the access.

XiangShan carries this as a separate consumer, not as part of its ICache path: FtqToPrefetchIO, toPrefetchPcBundle, and a dedicated pfPtr read port in ftq_pc_mem. The pointer sits between its ifuPtr and its bpuPtr, exactly in the run-ahead gap.

IMPACTED IF PREFETCH IS LATER WANTED:

  ftq_decisions.md 5.1   a FIFTH pointer, prefetch_ptr, between
                         fetch_ptr and alloc_ptr, with FQ-1
                         extended to order it. This said "fourth";
                         5.1 has four already -- alloc_ptr,
                         xlate_ptr, fetch_ptr, commit_ptr -- since
                         session-069 added xlate_ptr.
                         Session-070
  ftq_decisions.md 5.5   the rewind rule gains a pointer
  fast-path read ports   a further reader of bp_ftq_entry_t, on top
                         of the six of section 1. This read "five";
                         section 1 counts six since session-074
  a new interface        FTQ to prefetcher, or an extension of
                         ftq_ifu_interfaces.md
  redirect fan-out       the prefetcher must be told to drop stale
                         requests, as XiangShan does with
                         BpuFlushInfo on FtqToPrefetchIO

The pointer model of section 5 was written so the run-ahead is explicit rather than implicit, so adding prefetch_ptr later is an extension rather than a restructure. That is the whole of the insurance taken here.


7. Module decomposition

The FTQ is SEVERAL MODULES. ftq.sv is the top and is PURELY STRUCTURAL: instantiation and wiring, no logic of its own, no always block, no state. Anything that needs a decision made in it belongs in a leaf instead.

7.1 The partition rule

EVERY PIECE OF STATE HAS EXACTLY ONE OWNER MODULE. Everything else reads it through a port. The partition below is derived from that rule and from nothing else, which is why it does not follow the section order of this document: two sections that touch the same register belong in one module, and one section that owns two unrelated registers splits.

  ftq.sv             structural top, no state, no logic
  ftq_ptr.sv         alloc_ptr, xlate_ptr,
                     fetch_ptr                      5.1 5.2 5.5
  ftq_commit.sv      commit_ptr, the commit walk    5.3 5.4
  ftq_npc.sv         the next-PC register, and the
                     redirect arbitration that
                     feeds it                       4
  ftq_entry.sv       the fast-path array            1 2
  ftq_meta.sv        the slow-path array            3
  ftq_status.sv      wb_rcvd, fault, gen            entry_formats 4
  ftq_shadow.sv      the four-deep response shadow  5.6
  ftq_ifu.sv         request, flush, writeback,
                     predecode redirect             ftq_ifu_ifs
  ftq_resolve.sv     resolution intake, placement
                     of an unmapped branch, and
                     update fan-out                 backend_ifs 4
  ftq_upd_conv.sv    per-predictor update payloads
                     from bp_update_t, BUILT BP-119 ftq_bpu_ifs 8
  ftq_ftb_sched.sv   BUILT, BP-100                  5.7

ftq.sv does NOT instantiate bp_cluster. The BPU is a separate unit; a front-end top above both wires them together. The // OLD: comment lines BP-117 left in ftq.sv were removed by BP-125.

7.2 Why the pointers split

ftq_ptr owns alloc_ptr, xlate_ptr and fetch_ptr. ftq_commit owns commit_ptr.

XLATE_PTR IS IN ftq_ptr FOR THE SAME REASON fetch_ptr IS. Its advance is a local decision on a handshake, ftq_ifu_xlate_val and _rdy, exactly as fetch_ptr advances on ftq_ifu_req_val and _rdy. It is bounded by the same fetchable frontier as fetch_ptr and meets it first, being the pointer nearest alloc_ptr, so the frontier logic is shared rather than duplicated. And FQ-1 orders all four together. Added session-069 with the pointer itself; the decomposition predates it.

The request port it drives is ftq_ifu.sv's, alongside the fetch request, per ftq_ifu_interfaces.md 4.1. Pointer in ftq_ptr, port in ftq_ifu, mirroring fetch_ptr exactly.

Section 5.1 presents all four together and the partition rule splits commit_ptr out anyway, because it is the only one whose advance is not a local decision: 5.4 rate-limits it to one entry per cycle against the scalar RAS commit port, reads bp_ras_snapshot_t out of the entry to form the commit payload, and SUPPRESSES the advance in any cycle a redirect restore fires. That is a different job from allocating and issuing.

THE CROSSING IS BIDIRECTIONAL. Each module owns its pointers and reads the other's:

  commit_ptr   ftq_commit -> ftq_ptr
  alloc_ptr    ftq_ptr    -> ftq_commit

ftq_ptr needs commit_ptr for TWO things, not one. Besides full, it reconstructs the wrap generation of bkend_ftq_redir_idx, which is FTQ_IDX_BITS wide and carries none: the named entry lies at or after commit_ptr by 5.5 R2, so an index below commit_ptr's low bits belongs to the next generation. Without it a rewind across a wrap lands FTQ_DEPTH entries wrong.

ftq_commit needs alloc_ptr to bound the walk end to the live window. This is not defensive. It is what rejects the held stale watermark of 5.1: without alloc_ptr there is no way to tell a repeated watermark from a forward one, and section 6's idempotence promise cannot be met.

One writer and one reader per pointer, and no shared state, so the partition rule holds. What does not hold is that the dependency runs one way. Neither module reaches into the other's ADVANCE DECISION, which is the test that matters: each reads the other's resulting value. Suppression in particular turns out to be entirely local to ftq_commit once the redirect is an input. Reported by BP-106.

7.3 Why redirect arbitration is in ftq_npc

Four redirect sources reach the FTQ -- backend, p2, p3, and predecode -- and 4.3 orders them by AGE, not by an axiom. That ordering exists to answer one question: what does fetch do next. The winner is therefore the next-PC source, and putting the arbiter anywhere else would mean exporting the priority result to the module that already has to consume it.

ftq_npc publishes the winning redirect to ftq_ptr for the rewind of 5.5. Those two act on it; neither decides it.

THE RESOLVED SQUASH RANGE IS EXPORTED BY ftq_ptr, NOT DERIVED TWICE. This section originally sent the winning redirect to ftq_status as well and left the masked clear of ftq_entry_formats.md 4.2 W4 to it. Built that way, ftq_status repeats the wrap-generation reconstruction ftq_ptr already performs on bkend_ftq_redir_idx -- two copies of one derivation, free to disagree -- and ftq_shadow needs a third. ftq_ptr therefore exports the RESOLVED range, half open and FTQ_PTR_BITS wide, and both consumers take an age.

7.4 Why status is not inside ftq_entry

Different storage class. ftq_entry is an SRAM read every cycle; ftq_status is 192 flops with a masked range clear. Keeping them apart makes the storage class STRUCTURAL rather than a comment, and ftq_entry_formats.md 4.1 is the argument for why they cannot share one.


7.5 Ports this decomposition did not anticipate

BP-107 built the eight remaining modules and needed seven signals 7.1 through 7.4 do not name. NONE breaks the partition rule -- each is a value one module owns and another reads, and no module reaches into another's advance decision -- but the list belongs here rather than being rediscovered.

  ftq_shadow  -> ftq_ptr     alloc_inflight, the p0-to-p1 gap (5.1)
  ftq_npc     -> ftq_entry   pred_pc_p1, the block start PC. NO p1
                             PORT CARRIES IT; see
                             ftq_bpu_interfaces.md 4. The FTQ must
                             stage its own request, and r_next_pc
                             already is that value one cycle on
  ftq_ptr     -> ftq_status  squash_val / _start / _end, above
              -> ftq_shadow  the same range
  ftq_entry   -> (cluster)   ras_commit_*, formed here because the
                             has-a-RAS-operation qualification lives
                             in the entry (5.4, FE-11)
  ftq_entry                  a SECOND resolve read port
  ftq_meta                   a SECOND resolve read port
  ftq_entry                  a predecode read port, distinct from the
                             redirect port. See section 1
  ftq_entry   -> (cluster)   restore_snapshot, D2 of
                             ftq_backend_interfaces.md 5, as its own
                             port so ftq.sv wires name to name

BP-112 added three more, all of them consequences of 5.1 and 5.5 R1 being built:

  ftq_npc     -> ftq_ptr     arm_win, the winning redirect arm. The
              -> ftq_ifu     cause cannot carry the front-end split
                             (5.5 R1). It existed before and was
                             terminated in ftq.sv
  ftq_ptr     -> ftq_entry   xlate_rd_idx, a SIXTH read port, pc
                             only, for the 4.1 request
  ftq_ptr     -> ftq_ifu     xlate_idx and xlate_pending, the 4.1
                             request group's source

BP-113 added two more, both from 5.2's redirect-cycle allocation:

  ftq_ptr     -> ftq_shadow  alloc_req_ptr, the pointer the request
              -> ftq_entry   actually leaves with, so the shadow
                             stages the entry the cluster was given
  ftq.sv      -> ftq_shadow  req_rewound, wired from squash_val: the
                             p0 pointer is the rewound head exactly
                             when a squash is applied, and without it
                             the shadow's index test squashes the
                             target's own p1 write

BP-123 added one more, from ifu_decisions.md IFU-23b:

  (IFU)       -> ftq.sv      ifu_ftq_uc_end, the uncached-end bit of
              -> ftq_ifu     the writeback (ftq_ifu_interfaces.md 6),
                             selecting the W3U successor on arm 2
                             (4.2). ftq_ifu forms W3U, as
                             w_corr_succ in predecode_correct, and
                             ftq_npc only selects it on arm 2
                             (BP-124)

BP-137 added three inputs, from 4.5 H5:

  (cluster)   -> ftq.sv      tage_rdy, ittage_rdy, sc_ready, the RAM
              -> ftq_npc     init readies, held on as 4.5 H5

Section 1 counts six, since session-074.

8. Document History

  2026-08-19  Created. Sections 4.3, 5 and 6 moved here whole from
              fe_decisions.md; no content changed in the move.
              Numbering: fe_decisions 4.3 -> section 1, 5 ->
              section 2, 6 -> section 3. Section 0 added, naming the
              companion documents, stating that the FE / TD-FE / FE-U
              registries are NOT duplicated here, and listing the
              four FTQ interfaces. Section 4 added: a navigation list
              of open policy items, by reference only, plus the
              next-PC ownership gap.

  2026-08-19  ftq_ifu_interfaces.md added and TD-FE-1 closed. The
              interface table in section 0 and the open policy list
              in section 4 updated to match.

  2026-08-19  ftq_backend_interfaces.md added: resolution, redirect
              and commit as three separate events. Section 0 and
              section 4 updated. FE-U2's FTQ side is answered
              there; FE-U7 and G23 are unblocked but not decided.
              TD-FE-7 opened against bp_cluster. Also repaired the
              FE-U7 entry, which had lost the words "flush is" to a
              cross-reference edit earlier the same day.

  2026-08-19  Section 4 added: the next fetch PC. The FTQ is the
              requester and owns the selection. Priority is stated
              as a CONSEQUENCE of entry age rather than an axiom,
              with the argument for why the depth ordering
              reproduces it. The p1 successor path is identified as
              the zero-bubble critical loop and the only source that
              must be combinational. IFU backpressure is explicitly
              NOT a hold condition. Cluster responses for squashed
              entries are dropped by index, needing the same FE-U7
              generation bit as ftq_backend R3. 4.7 opens the reset
              vector, which has no source anywhere in the tree.
              Open policy renumbered 4 -> 5, history 5 -> 6.

  2026-08-19  FE-U7 RESOLVED as section 5, queue management. Three
              pointers with a wrap bit: alloc at p0 (the index
              leaves with the request, one cycle before the entry
              write), fetch, and a single commit pointer that both
              issues the RAS commit and frees, walking at one entry
              per cycle because ras_commit_* is scalar. Redirect
              rewinds head and fetch, never commit. Stale responses
              are caught by a four-deep in-flight shadow rather
              than by carrying a wrap bit through bp_cluster; both
              rejected alternatives are recorded with their cost.
              G23 falls out. Section 6.1 records the instruction
              prefetch deferral and what it forecloses. Open policy
              renumbered 5 -> 6, history 6 -> 7.

  2026-08-19  G9 RESOLVED as section 5.7, the FTB update scheduler.
              The FTB update is 14 flat ports with NO slot dimension
              and NO ready, so presenting two in a cycle loses one
              silently: the scheduler is a correctness requirement,
              not an optimisation, and it is the FTQ's because the
              FTQ is what has two channels. Slot 0 first into a
              one-deep skid, with resolution backpressure bounding
              it. Scope is the FTB alone; every other predictor
              takes two per cycle and the scalar RAS port is fed
              from the 5.4 commit walk. The one-per-cycle FTB
              ceiling is recorded as a known limit rather than
              reopening the single-port choice of FTB-3 /
              IC-FTB-09.

  2026-08-19  RESETVEC resolved. bp_defines_pkg::RESET_VECTOR,
              parameter, 40'h00_8000_0000, block aligned. Section
              4.7 rewritten from an open item to the decision. It
              was never a hard choice -- it was on the list because
              nothing in the tree named a reset PC at all.

  2026-08-19  5.7 REWRITTEN, superseding the G9 entry above. That
              entry said the one-per-cycle ceiling was recorded as a
              known limit "rather than reopening the single-port
              choice of FTB-3 / IC-FTB-09". There was no choice to
              reopen: ftb_interfaces.md had IC-FTB-09 marked OPEN
              and deferred to bp_cluster integration, and no
              throughput analysis had been done.
              5.7.1 does it: at the 8-issue target 1.2 to 1.6
              branches resolve per cycle and every one writes the
              FTB, so one write per cycle was below target, and
              FE-5's no-drop rule turned the deficit into
              backpressure on resolution -- a training limit
              stalling the backend.
              5.7.2 defines update value, 5.7.3 the drop rule: LOW
              may be dropped, HIGH never, backpressure only to
              protect a HIGH. 5.7.4 specifies five concurrent SVA
              properties for the unbuilt scheduler; P2 bounds the
              accuracy cost, P5 the throughput cost. 5.7.5 records
              the two escalations not taken. FE-5 amended narrowly
              as FE-5a; IC-FTB-09 resolved. The FTB is unchanged.

  2026-08-20  TD-FE-8 CLOSED by one generation bit on the IFU
              path. Section 6 registry updated.

  2026-08-20  Section 7 added: module decomposition. The FTQ is
              several modules with a purely structural ftq.sv top,
              partitioned by ONE rule -- every piece of state has
              exactly one owner. Document History renumbered 7 to
              8; nothing referenced 7.

  2026-08-20  The last two open entry fields decided and placed
              in ftq_entry_formats.md 4, closing TD-FE-1 in full.
              Section 6 registry updated; TD-FE-8 opened for the
              in-flight writeback race.

  2026-08-20  Section 5.7.4 P4 CORRECTED, |-> to |=>. P1 and P4
              as written could not both hold in any implementation:
              one required a registered output and the other a
              combinational one, on the same signal. Found by
              building the scheduler (BP-100). 5.7.4 also gains a
              note that the property signal names are the module's
              port list, which is what BP-100 delivered.

  2026-08-20  Section 3.2 CORRECTED. It specified the value form,
              the FTQ presenting ghist_ptr and phist_ptr; BP-102
              built the index form and closed TD-FE-7, so the FTQ
              presents ftq_rollback_idx and the cluster reads its own
              checkpoint copy. The conflict was between this document
              and fe_decisions.md 13, which had recorded the choice
              as open; building it settled the choice.

  2026-08-21  BP-107 results folded in, six corrections. Section 1
              counted three fast-path reads where five ports are
              needed, and the slow path needs two; the count is now
              separated from the three purposes. 4.5 gains H3, the
              fault hold, which ftq_entry_formats.md 4.3 R1 stated
              and this section never mirrored. 5.1: the fetchable
              frontier is not alloc_ptr, because the entry is written
              at p1 and allocated at p0. 5.6: four stages is THREE
              FLOPS, and the shadow carries a full pointer, not an
              index. 6.1 cited a "two-read-port decision of section
              1" that section 1 never made. 7.3 corrected and 7.5
              added, listing the seven ports the decomposition did
              not anticipate.

  2026-08-21  BP-106 results folded in. 5.1 gains the watermark
              aliasing argument: the 64-entry full condition is only
              safe because bkend_ftq_commit_idx now carries a
              generation bit. 5.4 gains the RC_UNSPEC / commit-walk
              interaction, which no document specified and which
              BP-106's first draft got wrong. 7.2 corrected: the
              crossing between ftq_ptr and ftq_commit is
              bidirectional, not one-way.

  2026-08-21  Cross-reference repair. No content change. 4.2 arm 0
              cited the reset vector as 4.6; it is 4.7. The section
              6 G23 entry cited 5.7, which is the FTB update
              scheduler; the checkpoint is reclaimed with the entry
              at 5.3 and 5.8 is what records it. 5.7.4's lead-in and
              closing note still described the scheduler as unbuilt,
              which BP-100 ended; the section header above them
              already said BUILT.

  2026-09-15  session-069. 5.1 gains xlate_ptr, a fourth pointer
              between alloc_ptr and fetch_ptr, driving the IFU's
              translation pipeline (ifu_decisions.md IFU-24).
              FQ-1 extended. Out of reset and after a redirect
              xlate_ptr and fetch_ptr are equal and the fetch
              pipeline stalls one cycle.
  2026-09-15  session-069. 4.7 clarified: the FTB_BLOCK_BYTES
              alignment requirement is on the RESET VECTOR only.
              Prediction blocks are not aligned; a block begins at
              the lookup PC, which is a taken target and so any
              2-byte address. Indexing on the block-aligned PC is a
              separate fact and is why ftb_decisions.md 4.5 bounds
              checks the fall-through.
  2026-09-19  session-071. 3.2: the history restores from the entry
              the redirect names on every cause, _self set included,
              as the RAS does (ruled, Jeff). 4.6: the drop rule's
              mechanism is 5.6 and needs no generation bit; only
              backend R3 does. bpu_blk_idx_p2 added to the response
              index lists (ftq_bpu_interfaces.md 4c). 5.1: xlate_ptr
              recorded as not built, TD#127; the post-redirect rule
              for xlate_ptr and fetch_ptr is 5.5 R1. 5.5 R1:
              xlate_ptr and fetch_ptr take the minimum of their
              current value and the flush index, with F stated per
              cause; the W3 row is unbuilt, TD#126.

  2026-09-20  session-072. E3: 7.4 and 7.5 in numeric order. E6:
              a sentence fragment left by the D18 edit removed.

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

  2026-09-22  session-073, after BP-112. 5.1: xlate_ptr is BUILT,
              TD#127 closed, and the one-cycle redirect latency is
              measured as two because of TD#139. 5.2: the index
              leaving at p0 in a redirect cycle is the pre-rewind
              one, TD#139. 5.5 R1: BUILT, TD#126 closed, with the
              arm_win note -- the cause bus cannot express the
              table. 7.5: three more crossings, and ftq_entry has
              six read ports, not three. 4.7: RESET_VECTOR built
              at 41 bits by BP-109.

  2026-09-22  session-073, after BP-113. 5.2: the redirect-cycle
              allocation is fixed -- rewind first, then allocate
              from the rewound head -- and TD#139 is closed. 5.1:
              the post-redirect translation latency is measured and
              the front-end and backend cases are SEPARATED, 1 and
              2 cycles; IFU-27 needs the same split. 7.5: two more
              crossings, alloc_req_ptr and req_rewound.

  2026-09-22  session-073, after BP-114. 5.5 R1's F-by-source
              table gains the RC_UNSPEC row it never had, F =
              commit_ptr; TD#141.

  2026-10-01  session-074. 5.5 R1: predecode flushes at F = K+1,
              p2 and p3 stay at K (TD#146). 5.1: IFU-27 carries the
              split. Section 1: six read ports, as 7.5 says. The
              session-073 entries moved into date order.

  2026-10-06  session-075. 5.5 R1: the arm_win paragraph gave the
              predecode arm F = K against the table's K+1 row; arm
              2 takes K+1, arms 3 and 4 take K. The BUILT note now
              says which task built which row.

  2026-10-06  session-075, after BP-117. 5.5 R1: the predecode row
              is built, TD#146 closed. 5.1: the post-redirect
              translation latency is 2 cycles for predecode as well
              as backend, since F is now the target block; the p2,
              p3 row of 1 cycle is marked unmeasured.

  2026-10-07  session-075, after BP-119. 7.1: ftq_upd_conv added;
              ftq_resolve places an unmapped branch.

  2026-10-08  session-076, PA-direct correction recording BP-121.
              4.5: H4, hold p0 the cycle before an FTB update
              (TD#162, D7); H1 flagged for the SC starvation hold.
              5.4: the walk commits only what executed (D2, A7).

  2026-10-09  session-076, recording BP-122. 4.5: H1 holds on
              sc_uq_not_full, as built.

  2026-10-09  session-077, after BP-123, ruling (Jeff). 4.2: arm 2
              carries the W3U uncached successor (IFU-23b, D1). 7.5:
              ifu_ftq_uc_end. Section 0: FE-1 through FE-21, section
              15. 6.1: section 1 counts six read ports, not five.

  2026-10-10  session-077, after BP-124. 4.2: the W3U flush index is
              K+1. 7.5: ftq_ifu forms W3U.

  2026-10-10  session-077, after BP-125. 5.1: the p2, p3 row is
              measured, 1 cycle. 7.1: ftq.sv's OLD lines removed.

  2026-10-15  session-080, after BP-137. 4.5: H5, the init hold; the
              w_hold equation. 4.7: when the first request goes out.
              7.5: the three init readies.
fe_decisions.md

planning/arch/fe_decisions.md on GitHub

 FILE:    fe_decisions.md
 SOURCE:  various
 STATUS:  DRAFT
 UPDATED: 2026-10-15
 CONTACT: Jeff Nye

Overview

This document holds front end decisions. It carries two kinds of content and they have different scopes.

The prose sections are the paths between the branch prediction cluster and the fetch target queue, sections 1 to 3 and 7 to 10, and the front end top, section 15.

The registries are front end wide and are not split: invariants in section 11 and, for the front-end top, section 15; technical debt in section 13, unresolved items in section 14. FE-15 to FE-18 are issued in section 15, beside the top they describe, and FE-13 follows FE-14 in section 11: the numbers are issue order, not document order. This read that the invariants are in section 11. Session-072. An FE, TD-FE or FE-U number may be issued for any front end subject, not only for the BPU and the FTQ.

The two paths

BPU to FTQ carries predictions. The FTQ allocates an entry on the initial prediction and issues a fetch from it. Later predictors correct that entry by redirect.

Correction and redirect are the same thing. A predictor at p2 or p3 may override the p1 prediction held in the entry, replacing the corrected slot's target and redirecting fetch to the new address. A redirect names one FTQ entry index and carries a corrected target per slot. Redirects supersede by stage order. The mechanism is section 3.

FTQ to BPU carries updates. On post-execute resolution the FTQ reads the metadata captured at prediction time and forms an update for each predictor named by the resolved branch type. Updates reach the predictors through per-predictor update queues.

Predictor internals are out of scope here, as is the RAM arbitration model. These sections state what each predictor contributes to the FTQ, when, and the handshakes that carry it.

Conventions

Stage labeling is p0 through p3 for prediction and u0/u1 for update.

One FTQ entry holds one PREDICTION block: FTB_BLOCK_BYTES, 32 bytes, beginning at any 2-byte address (ftq_decisions.md 4.7). A prediction block carries NUM_PRED_SLOTS predictions, one per prediction slot. The slots are the branch fields of one FTB block; see section 10.

A FETCH block is a different thing: FETCH_BLOCK_BYTES, 64 bytes, the unit the IFU reads from the L1I, which is one cache line held in the IFU line buffer (ifu_decisions.md TD-IFU-7). The IFU takes one prediction block per request and extracts it from the line it read (IFU-7, IFU-8). No RTL reads FETCH_BLOCK_BYTES; it is the L1I line size under a second name. The front end DELIVERS one prediction block per cycle (TD#133, ftq_ifu_interfaces.md 8 item 2); two per cycle would not be IFU-internal. The two sizes must not be collapsed, and "fetch block" is not a name for the 32-byte unit.

RULED session-071 (Jeff). This read "One FTQ entry holds one fetch block", and section 10 defined a fetch block as one 32-byte FTB block. The misuse had spread to most of the front-end documents and to RTL comments.

The rest of the front end

Each unit owns its own document and issues its own numbers. This document does not restate them.

  IFU                    ifu_decisions.md
  predecode              dcd_decisions.md
  instruction buffer     ibuf_decisions.md
  instruction TLB        itlb_decisions.md
  page table walker      mmu_decisions.md (no L2 TLB now)
  FTQ internals          ftq_decisions.md, ftq_entry_formats.md
  predictors             one document per predictor

The L1I is specified in icache_decisions.md. Its RTL is the pacino copy of the cachegen emission at rtl/core/frontend/icache (cachegen_decisions.md CG-D1, built by BP-123); this read that it "is emitted by cachegen rather than written". FE-16 keeps it inside the front end top as a sibling of the IFU, per L1I-2.


1. Stages

  p0   Indices and addresses presented to the RAMs. PC hash and
       folded history available. RAS top of stack read.
  p1   RAM outputs available. The initial prediction is formed. The
       FTQ allocates an entry and issues a fetch.
  p2   FTB result valid; branch type available. TAGE final. ITTAGE.
       RAS push or pop executes.
  p3   SC final.

  u0   Update address and write data presented to the RAMs.
  u1   RAM write completes.

Predictor stage assignments:

  p0   RAS top of stack read
  p1   uBTB, LP
  p2   FTB, TAGE, ITTAGE, RAS push/pop
  p3   SC

The FTQ never stalls waiting for a predictor later than p1. Every stage after p1 is a redirect source.


2. BPU to FTQ: The Initial Prediction

2.1 Selection at p1

The LP and uBTB are one-cycle predictors. NEITHER HAS AN SRAM. The uBTB is combinational from pred_pc_p0: ubtb.sv derives index and tag by continuous assign and produces every output field in one always_comb reading a flop array, with no register in the path, so the result is valid within the p0 cycle and the cluster registers it (bp_arb_spec.md 7.1, ftq_bpu_interfaces.md 4). The loop predictor is a registered counter array (sram_init.md). An earlier revision said both used "two single port RAMs in each predictor"; that is wrong for both, and section 7.3 of this document already said the uBTB is combinational. Corrected session-070.

Both LP and uBTB support dual prediction, they will present two predictions per cycle when requested. THE TWO PREDICTORS DIFFER IN HOW. The uBTB's slots SHARE ONE LOOKUP: one lookup returns one entry describing one 32-byte block, and the slots are that entry's br0 and br1 fields (section 10, FE-10, ubtb_interfaces.md). The loop predictor's slots ARE independent: its table is replicated as one bank per slot (TI6) and a write to one bank cannot change another (loop_pred_interfaces.md), as the next paragraph says.

An earlier revision said of both that the slots "share no resources and operate fully independently", which is the retired two-PC-range model and wrong for the uBTB. A session-070 revision then over- corrected to "THE SLOTS ARE NOT INDEPENDENT AND SHARE THE LOOKUP" for both, which is wrong for the LP and contradicted the paragraph below it. Corrected session-070.

The loop predictor was retrofitted to NUM_PRED_SLOTS in BP-091: every prediction and update port carries a slot dimension and the internal tables are per-slot banks (TI6). Its prediction output is named pred_p1.

The remaining discussion focuses on a single slot for clarity, the decisions and operation of the 2nd slot are identical.

Both LP and uBTB outputs are valid at p1. There is a selection mux which choses the prediction to present.

  lp_pred_is_loop set   ->  the LP supplies the direction
  else ubtb slot valid  ->  the uBTB supplies the slot
  else                  ->  this slot carries no prediction

The LP has no valid output. lp_pred_is_loop is set only on a hit at confidence cnf == LP_CONF_LEVEL, tested inside loop_pred (loop_pred_interfaces.md Semantics); lp_hit alone does not qualify. The LP supplies a direction only, and the target comes from the uBTB entry (ftq_bpu_interfaces.md 4, which owns this mux). The uBTB slot valid is pred_p1[s].valid. This keyed the mux on an "LP output valid" and said both predictors assert a valid. Session-072.

The LP or uBTB p1 predictions are not sources for redirects since they both are the 1st prediction in the pipeline. Since BP-122 the LP also re-reads at p2, and that p2 direction can raise a p2 redirect (3.2, 3.3); the p1 LP direction is an early guess that p2 corrects.

When neither the LP nor the uBTB hits, the slot carries no prediction. The successor PC for that case is defined in section 2.4.

2.2 Returns

RAS SUPPLIES A TARGET only for return branch types; it is also PUSHED by calls, which is an update rather than a prediction (section 7.2, FE-U9, ras_decisions.md 2). This read "RAS is only active for return branch types". Corrected session-070. The RAS presents its top-of-stack entry as the predicted target. THE TOP OF STACK IS READ AT p0: ras.sv declares ras_tos_addr_p0 and ras_tos_valid_p0. The cluster registers that value and applies it when the p1 selection mux forms a RETURN slot.

The RAS does not participate in the uBTB/LP selection. It supplies the target for one branch type, the return, taken from its stack rather than from a prediction table.

The return branch type is available at p1 from the uBTB entry (ubtb_entry_t.br_type), so the RAS is engaged without waiting for the FTB branch-type classification at p2.

2.3 Allocation

The FTQ allocates an entry at p1, when the initial prediction is formed, and issues the fetch from it. Allocation is unconditional: an entry is allocated for every prediction block, including a block the p1 predictors miss. The p1 predictors are early in the pipeline; FTB, TAGE, ITTAGE, and RAS can each find or correct a branch at p2 or p3, and a redirect names an FTQ entry index, so the FTQ entry is allocated in p1 for a later stage to correct it. A p1 miss allocates an entry whose slots carry no taken prediction and whose successor is the fall-through address.

The FTQ entry index is the 6-bit index into the 64-entry FTQ. It identifies one prediction block and is the value carried in branch_id. All NUM_PRED_SLOTS predictions for that block occupy the one entry.

The entry written at p1 records the prediction and the architectural state it was made against (ftq_entry_formats.md 2), so the block can be restored on a later redirect (ftq_decisions.md 3).

The IFU-FTQ interface carries fetch requests and a predecode writeback. It is specified in ftq_ifu_interfaces.md.

2.4 Successor PC

The successor PC is the start PC of the next prediction block: the address fetched after this block. It is selected across the block's slots, priority-ordered top to bottom:

  slot 0 valid and taken   ->  slot 0 target
  slot 1 valid and taken   ->  slot 1 target
  otherwise                ->  fall-through address

The fall-through address for the not-taken case arrives on the p1 output group as bpu_pred_pft_p1, one value per prediction, qualified by bpu_pred_val_p1 (TD#108, BP-092). Before that port existed the block end stayed inside the cluster and the FTQ had no source for it on a not-taken block.

The FTQ writes that value into the allocated entry as bp_ftq_entry_t.pft_addr (ftq_entry_formats.md 2). bpu_pred_pft_p1 is present only in the p1 cycle, and the selection above is re-evaluated on every redirect, so the not-taken arm has to be read back from the entry rather than resampled from the cluster.

Both slots are predicted at p1. The selection chooses which slot's target is the successor; it does not gate whether a slot is predicted.

The per-slot successor the redirect comparison uses follows the same order: chained from the highest slot down, and a slot after a taken slot is unreachable and raises no redirect (ftq_bpu_interfaces.md 6, BUILT by BP-121, D5 and D15).

The selection is re-evaluated whenever a redirect rewrites a slot.

2.5 Slot correction at p2 and p3

The p1 prediction is the uBTB and loop-predictor view. The FTB classifies the block at p2 and supplies the in-block position of each branch field. Those are corrections to the RECORD, and they are needed whether or not fetch has to be resteered.

The cluster therefore publishes its view of every slot again at p2, and once more at p3 with the SC direction applied:

  bpu_slot_val_p2   bpu_slot_idx_p2   bpu_slot_p2 [0:NUM_PRED_SLOTS-1]
  bpu_slot_val_p3   bpu_slot_idx_p3   bpu_slot_p3 [0:NUM_PRED_SLOTS-1]

Each group carries one bp_ftq_slot_t per slot, the same type the p1 group delivers. The FTQ overwrites the slot description of the named entry with the latest group it has received.

THE GROUP IS NOT GATED ON A REDIRECT (FE-13). A redirect fires only when the p2 successor differs from the p1 successor, and the case that matters most does not qualify: a conditional branch the uBTB missed and the FTB found, predicted not taken. Both views end the block at the same address, no redirect fires, and without this group the entry would keep br_type NO_BRANCH and pos zero for its whole life -- so section 7.2 would form no update for it and no predictor would ever be trained on that branch. See TD-FE-6.

A slot holding the block's jump field takes the jump field's own position, not a conditional field's, matching the lowest-free-slot placement rule of section 10.

p3 changes only taken, and pred_src when SC actually moved the direction. SC corrects direction, not branch type, so br_type, pos and target are carried through the p2 to p3 register unchanged.

The port specification is ftq_bpu_interfaces.md section 4a.


3. BPU to FTQ: Redirects

Correction and redirect are synonymous terms. A later-stage predictor may change -- correct -- the prediction currently held in the FTQ entry. Every correction after p1 is a redirect. A redirect identifies one FTQ entry index and carries a corrected target per slot.

3.1 Interface

NO PREDICTOR DECLARES A REDIRECT PORT. INFRA-011 confirmed this across all 140 ports of the eight top-level BPU modules, and the inventory now stands at 141: session-071 added ubtb's blk_p1, making ubtb 6 (bpu_port_inventory.md Coverage). Session-072. A prior revision of this section named <pred>_redir_val_<pN>, <pred>_redir_tgt_<pN> and <pred>_redir_ftq_idx_<pN> as a per-predictor port group. No such ports exist and none is planned.

The redirect is DERIVED at the bp_cluster boundary. The cluster compares a predictor's stage output against the prediction it formed at p1 and carried forward in its own stage registers (FE-4). bp_cluster does not read the FTQ.

The groups are named by STAGE, not by predictor:

  bpu_redir_p2      bp_redirect_t [0:NUM_PRED_SLOTS-1]
  bpu_redir_idx_p2  [FTQ_IDX_BITS-1:0]
  bpu_redir_p3      bp_redirect_t [0:NUM_PRED_SLOTS-1]
  bpu_redir_idx_p3  [FTQ_IDX_BITS-1:0]

bp_redirect_t is the per-slot payload and carries target_pc and valid. The array is per slot; the index is scalar alongside it, because both slots occupy one prediction block, which is one FTQ entry.

p2 carries the FTB, TAGE, ITTAGE and RAS corrections. p3 carries the SC correction.

The comparison reduces both views of a slot to ONE quantity, the address fetched after that slot. Two not-taken views therefore compare equal and raise no redirect. The p1 operand is formed at p1 from the p1 view only: the slot target when taken, the uBTB fall-through on a hit, the LOOKUP PC plus FTB_BLOCK_BYTES on a miss.

Not the block-aligned PC. Prediction blocks are unaligned: a block begins at the lookup PC, which is a taken branch target and so any 2-byte address (ftq_decisions.md 4.7, ifu_decisions.md IFU-6). A miss does not resync the stream to a 32-byte boundary (bp_cluster.md, Block width). An earlier revision said block-aligned and predates the session-069 ruling.

The p3 comparison is against the p2-corrected value, not the raw p1 prediction, so a p3 redirect fires only when SC changes what the cluster published at p2.

Every p2 and p3 comparison is qualified by branch_id equal to the FTQ index held in the matching stage register, so a queued or back-pressured response cannot be compared against the wrong entry. The redirect logic assumes no fixed predictor latency.

The port specification is ftq_bpu_interfaces.md section 6.

3.2 Sources
  p2   FTB, TAGE, ITTAGE, RAS, LP (its p2 re-read, BP-122)
  p3   SC

The uBTB is not a redirect source since it forms the initial prediction. THE LP IS ONE SINCE BP-122: its p2 re-read (pred_p2) supplies a trusted direction at p2, which can change the successor and so raise a p2 redirect (3.3). This read "The uBTB and the LP are not redirect sources".

3.3 Direction and target

A redirect's payload is always a target (section 3). The FTB, RAS, and ITTAGE produce a target directly; TAGE and SC produce a direction, which then selects a target.

The FTB identifies the branch type of each slot at p2. That type selects the target source for the slot:

  return        RAS ras_pop_addr_p2
  indirect      ITTAGE
  conditional   direction from TAGE, then SC (see below)
  direct unc.   FTB branch target

Return and indirect are different branch types. The RAS and ITTAGE are never both consulted for the same branch.

For a conditional branch, TAGE (p2) then SC (p3) supplies the direction, which selects the target:

  taken      ->  FTB branch target
  not taken  ->  fallthrough address

The branch target and the fallthrough address both derive from the FTB result. The derivation is an FTB-internal operation with a description found in the FTB documentation. The contents of this documentation is not necessary to follow the remaining discussion.

TAGE overrides the FTB direction on conditional branches only. At p3 the SC may override the TAGE direction; the FTB result is still available, so both target candidates are present when the SC direction selects between them.

A TRUSTED LOOP PREDICTION OUTRANKS ALL THREE. RULED session-076 (Jeff, BP-122 decision 2), BUILT by BP-122: a trusted p2 loop direction is the slot's direction at p2, over TAGE, and SC does not override it at p3. The direction ranking is LP (trusted) > SC > TAGE

FTB. Before this ruling TAGE and SC overrode the LP's p1 direction, so a correct loop exit could never remove the mispredict. As built, the trusted LP direction also stands over an FTB fast-path direction (ftb_confidence_override_rules.md 4.3).

A redirect rewrites its slot. The block's successor PC is then re-derived across all slots per section 2.4.

3.4 Supersession

A redirect from a later stage supersedes any earlier redirect for the same FTQ entry index and the same slot. The FTQ tracks which redirects are stale and discards them.

Redirects do not cross slots. A p3 redirect on slot 1 does not discard a p2 redirect on slot 0 of the same entry; the two correct different branches.

A p2 redirect and a p3 redirect for one entry index and slot can be in flight in consecutive cycles, and the fetch stream started by the p2 redirect is already speculative when the p3 redirect arrives. The FTQ does not compare targets to settle this. The later stage wins for the entry index and slot it names.


4, 5, 6. MOVED

The FTQ entry formats, the entry lifetime, and the checkpoint and restore behaviour left this document on 2026-08-19. They are FTQ internals; this document is the BPU <-> FTQ boundary.

  was 4.1  fast path bp_ftq_entry_t  ->  ftq_entry_formats.md 2
  was 4.2  slow path bp_ftq_meta_t   ->  ftq_entry_formats.md 3
  was 4.2.1 overload scheme          ->  ftq_entry_formats.md 3.1
  was 4.3  read rates                ->  ftq_decisions.md 1
  was 5    entry lifetime            ->  ftq_decisions.md 2
  was 6    checkpoint and restore    ->  ftq_decisions.md 3

Section numbers 4, 5 and 6 are retired rather than reused, so every "section 7.2" and "section 2.4" reference in this document and in ftq_bpu_interfaces.md still resolves.

The registries stay here, as the Overview says: invariants in section 11 and, for the front-end top, section 15; technical debt in section 13, unresolved items in section 14. They cover the front end as a whole and are not split. This read that the invariants are in section 11 alone, against FE-15 to FE-18 in section 15. Session-072.


7. FTQ to BPU: Updates

7.1 Trigger

Updates are triggered at post-execute resolution. Updates do not wait for retirement.

There is one update channel per prediction slot, upd_ch[0] through upd_ch[NUM_PRED_SLOTS-1]. Each channel carries both conditional and indirect resolution.

7.2 Formation

On resolution of a branch at FTQ entry index k, slot s, the FTQ reads slot s of bp_ftq_meta_t[k] from the slow-path SRAM, and reads pc and slot s br_type from the fast-path entry.

The slot's br_type determines the set of predictors updated. It is the FTB classification, placed in the entry by the p2 slot correction group (section 2.5), not the p1 uBTB view (TD-FE-6):

  conditional    uBTB, LP, FTB, TAGE, SC
  indirect       uBTB, FTB, ITTAGE
  return         uBTB, FTB, RAS
  direct unc.    uBTB, FTB
  direct call    uBTB, FTB, RAS
  indirect call  uBTB, FTB, ITTAGE, RAS
  return-call    uBTB, FTB, RAS (pop, then push)
  no branch      none

The last four rows close FE-U9, session-075 (Jeff). RETURN_CALL does not train ITTAGE: its target comes from the RAS pop, and ITTAGE is never consulted for a RAS-predicted branch (section 3.3), so training it would fill an entry nothing reads.

Every row is built, BP-119. The return-call row was not met before it (found by BP-118, TD#152), and before it only the FTB and RAS rows trained in the front-end top, because no unit formed the per-predictor payloads (TD#151; now ftq_upd_conv, ftq_bpu_interfaces.md 8).

A BRANCH ITS FTQ ENTRY DOES NOT HOLD. On its first execution a conditional branch or a JALR the FTB does not hold has no slot in its FTQ entry: the p2 slot correction carries only what the FTB returned, and predecode writes a slot only on a structural mispredict. RULED session-075 (Jeff), built by BP-119: its resolution is placed in a slot of its entry in program order (the ftq_ifu W1 rule) and trains every predictor of its row from that slot's prediction-time metadata, the FTB allocating on a miss. Before this ruling such a resolution formed no update, so the FTB never learned the branch and TAGE, SC, LP and ITTAGE never trained (ftq_entry_formats.md 3.1).

ITEM C (Jeff, 2026-10-18; built by BP-139). A placed resolution whose slot holds another valid branch trains the uBTB and the FTB only: the slot's prediction-time metadata is the other branch's (TAGE is indexed by block start per slot), so TAGE, SC, LP and ITTAGE are suppressed, as R2 does for a type disagreement (ftq_entry_formats.md 3.1). It replaces the paragraph above for that case only. fd09 at one slot: the back edge trained into B's TAGE entries on 101 of 256 iterations before BP-139, 0 after.

TAGE and SC predict direction and are updated only for conditional branches. ITTAGE is updated only for indirect branches. RAS IS UPDATED BY BOTH: a return pops it and a call pushes it, and INDIRECT_CALL updates ITTAGE for the target and the RAS for the return address (FE-U9, session-061 ruling). This read "RAS is updated only for returns". Corrected session-070. The SC is excluded when disabled by its CSR bit (FE-U6).

A predictor that missed at prediction time is still updated. Each predictor derives allocate-versus-train from its own bp_ftq_meta_t slice and the resolved outcome; that decision is predictor-internal.

The update path uses the metadata captured at predict. It does not recompute predictor state from the PC or the history.

EXCEPT THE LOOP PREDICTOR. RULED session-075 (Jeff), after BP-121, reversing BP-121 decision 6: the loop predictor's update reads the entry before writing it, which its table allows because it is flops, not RAM. BUILT by BP-122 (TD#169). loop_pred_interfaces.md is the home of the rule.

A slot off the executed path never resolves and forms no update.

7.3 Enqueue

Each RAM-based predictor EXCEPT THE FTB has an update queue in front of it. The queue is a FIFO with two write ports, so up to two updates may be enqueued per cycle. Two write ports serve NUM_PRED_SLOTS = 2 update channels.

THE FTB HAS NO QUEUE AND NO READY. It has a single update port, scheduled by ftq_ftb_sched outside the predictor: ftq_decisions.md 5.7, ftb_interfaces.md 2.5, ftq_bpu_interfaces.md 8. This paragraph said "each RAM-based predictor" without the exception. Corrected session-070.

Updates reach a predictor in resolution order. This is an out-of-order machine and resolution order is not program order. The FIFO is not reordered.

The uBTB is combinational and has no queue; it updates immediately. The RAS is register-file based and has no queue; its update is snapshot-based, described in section 9.


8. Handshakes

The RAM arbitration model is specified in bp_arb_spec.md and is out of scope here. Three handshakes cross the BPU/FTQ boundary.

Prediction issue. The FTQ can be back-pressured. A prediction request is stalled. When the FTQ cannot accept the uBTB output, the uBTB holds its output stable.

Update enqueue. The FTQ presents upd_val and upd_inp per channel. The update queue asserts upd_rdy when it accepts. When the queue is full, upd_rdy deasserts and the FTQ holds valid until accepted.

Prediction delivery. The predictor presents pred_rdy when its result is valid. The TAGE result is consumed by both the FTQ and the SC.

consumer_ready IS SC's, NOT THE FTQ's. It is an input port on tage.sv and is driven in bp_cluster.sv from SC state alone, ~sc_enable | (sc_ready & ~w_sc_grant_upd): it says whether SC can take the TAGE p2 result this cycle. The cluster drives it rather than sc.sv because deriving it from tage_pred_rdy_p2 would close a combinational loop. An earlier revision of this paragraph named the FTQ, and bp_arb_spec.md 4.7 named either. Both corrected session-070 against the RTL.

A prediction may be granted ahead of a pending update to the same RAM entry, and reads pre-update state. The potential accuracy loss from the stale prediction state is accepted.


9. RAS

Only the FTQ-facing RAS behavior is stated here. RAS internals are in ras_decisions.md.

The RAS is register-file based. It has no prediction queue, no update queue, and no arbiter.

  p0   top-of-stack read. ras.sv declares ras_tos_addr_p0 and
       ras_tos_valid_p0. The cluster registers the value and applies
       it at p1 as the predicted target for a return (section 2.2).
       It is NOT the section 3.3 entry: that table selects at p2,
       where the return target is ras_pop_addr_p2.
  p2   push or pop executes once the FTB branch type confirms a call
       or a return. Participates in the p2 redirect.

bp_ras_snapshot_t is written into the FTQ entry at p2 for EVERY valid block, whether or not the block operated on the RAS: the state after both slots' operations, carried on ftq_bpu_interfaces.md 4c (ras_decisions.md 4.2). A block with no call or return records the unchanged state. On a misprediction or flush the RAS is restored from the snapshot in the entry the redirect names (ftq_backend_interfaces.md 5 D2). This read "checkpointed into the FTQ entry at the time of the call or return that updated the RAS". Session-071.

One snapshot per FTQ entry is sufficient under dual slot. A RAS operation is a call or a return, both taken branches, so one in slot 0 ends the block before slot 1 is reached. At most one RAS-operating INSTRUCTION therefore occurs per block, and one snapshot covers it -- including the DCD-11 JALR that pops and then pushes, since both happen at one position. The cluster enforces this by gating p2 RAS operations on reachability across slots (FE-11).

RAS flush behavior is CLOSED: a flush restores the RAS by the same pointer restore as any redirect (ras_decisions.md 4.4). There is no flush event at all -- FE-14. TD #96, G24 and IC-FTB-07 are closed.


10. Prediction Slots

NUM_PRED_SLOTS parameterizes the number of prediction slots and the number of update channels, upd_ch[0] through upd_ch[NUM_PRED_SLOTS-1].

One FTQ entry holds all NUM_PRED_SLOTS predictions for one prediction block.

A prediction block is one 32-byte FTB block (FTB_BLOCK_BYTES). It is not the fetch block; see Conventions. This read "A fetch block is one 32-byte FTB block". Session-071. Both slots are predicted from one FTB lookup: slot 0 is the block's first branch field, slot 1 the second. The slots are not two PC ranges; they are the two branch fields of one block (ftb_decisions.md 2.1, 2.3).

The uBTB follows the same model. BP-086 rewrote ubtb.sv to a single lookup returning one entry that describes one block and supplies both slots; the pred_pc_p0 + 32 slot-1 lookup is retired.

dual_pred_en, when clear, gates the second prediction slot off at runtime. It does not change the structure: the slots and the channels exist either way.

A BRANCH NO SLOT CARRIES (BP-139, option A, ruled by Jeff 2026-10-18; BP-138 D1 option b was the jump case). Slot 0 carries the FTB's br0, a higher slot br1, and the jump the lowest slot with no conditional. When the FTB reports a branch that no slot carries, the block ends at the PC of the first such branch: the p2 fall-through, bpu_blk_pft_p2, is that PC (w_cut_p2, w_cut_pos_p2). The next block starts there and places the branch in slot 0. At one slot this is br1, or the jump behind br0 when there is no br1; at two slots, a jump behind two conditionals. Every branch the FTB reports is predicted at every slot count.

A BACKSTOP SINCE BP-140. The FTB stores at most NUM_PRED_SLOTS branches per entry and ends the entry at the first branch it does not keep (the split at update, ftb_decisions.md 3), so from an entry it wrote it never reports a branch no slot carries, and the block ends at that PC by the stored end. The cut stays, unchanged, for an entry that reports more (none in tb_fe_top: 0 cut groups at both slot counts, 280 / 2409 before). FD-23 of examples/fe_demo, written for the cut, was re-pointed at the split by DOC-007; it reports the cut count, 0. w_jmp_cut_p2 is now read by nothing.


11. Invariants

Proposed numbering. Stated here for the first time; not carried from bp_cluster.md or bp_arb_spec.md.

  FE-1   The FTQ allocates an entry and issues a fetch from the p1
         prediction. It never waits for a predictor later than p1.

  FE-2   The initial prediction is formed by selection at p1 between
         the LP and the uBTB, per slot. Every correction after p1 is
         a redirect naming an FTQ entry index and a slot.

  FE-3   A redirect from a later stage supersedes an earlier redirect
         for the same FTQ entry index and slot. The later stage wins
         by stage order. The FTQ does not compare targets to settle
         it. Supersession does not cross slots.

  FE-4   The redirect comparison is made at the cluster boundary,
         between a predictor's stage output and the prediction the
         cluster formed at p1 and holds in its own stage registers.
         No predictor is compared against another predictor, and the
         cluster does not read the FTQ.

  FE-5   No prediction is dropped, and no update is dropped except
         as FE-5a permits. A full prediction path stalls fetch. A
         full update queue stalls the update path.

  FE-5a  AMENDMENT 2026-08-19. An FTB update may be dropped on
         collision, and ONLY when it is low value: the FTB hit at
         predict and the branch was predicted correctly, so the
         update is a routine conf step on a counter already in the
         right direction. An update that allocates an entry or
         corrects a mispredict is never dropped; where dropping one
         would otherwise be required the FTQ backpressures
         resolution instead. The FTB update port is scalar and the
         8-issue target resolves more than one branch per cycle, so
         without this the FTB training rate would stall the backend.
         Applies to the FTB path alone. Every other predictor takes
         one update per slot per cycle and keeps FE-5 unqualified.
         ftq_decisions.md 5.7, IC-FTB-09.

  FE-6   Updates reach a predictor in resolution order. The update
         queue is a FIFO and is not reordered.

  FE-7   The FTQ history checkpoints are pointer-only and block
         granular, one per FTQ entry.

  FE-8   The update path uses metadata generated during predict. The
         set of predictors updated is determined by the slot's
         br_type.

  FE-9   A prediction granted ahead of a pending update to the same
         RAM entry reads pre-update state. The prediction accuracy
         loss from the stale read is accepted.

  FE-10  One FTQ entry holds one prediction block and all NUM_PRED_SLOTS
         predictions for it. The slots are the branch fields of one
         FTB block. The slot is the array index; no slot identifier
         field is carried. The index is ORDERED as of IC-FTB-16:
         slot 0 is the block's first branch in program order.
         THAT HOLDS AT p1 AS WELL. The uBTB does not reorder its
         slots (ruled session-073, ubtb_interfaces.md), so a uBTB
         slot 1 can lie below slot 0. bp_cluster swaps the two p1
         slots into position order. BUILT by BP-121 (D12); before
         it such a block was sent to the later branch's target.

  FE-11  At most one RAS-OPERATING INSTRUCTION occurs per block. A
         RAS operation is a taken branch, so one in slot 0 ends the
         block before slot 1 is reached. One RAS snapshot per FTQ
         entry is therefore sufficient.

         THAT INSTRUCTION MAY PERFORM TWO OPERATIONS. A JALR whose
         rd and rs1 are both link registers and are not equal is a
         pop followed by a push (dcd_decisions.md DCD-11). The
         snapshot conclusion is unaffected: two operations at one
         position need no second recovery point. An earlier
         revision said at most one RAS OPERATION per block, which
         excluded that case. Corrected session-069;
         ras_decisions.md 6.2 RAS-DS1.

  FE-12  No predictor declares a redirect port. Redirects exist only
         as cluster-derived, stage-named groups (section 3.1).

  FE-14  A FLUSH IS A REDIRECT. The front end has no flush event
         distinct from a redirect and no flush protocol. Clearing a
         predictor is done by WITHHOLDING ITS STAGE VALID, not by
         asserting a flush: a stage whose valid is low does not
         advance, so nothing downstream of it acts. bp_cluster
         already works this way -- w_any_redir_p2 / w_any_redir_p3
         and the FTQ arm of BP-102 clear the stage valids, and no
         predictor is told anything.

         Corroborated by XiangShan, which has NO flush port on ANY
         predictor: BasePredictorIO carries s0_fire..s3_fire,
         s2_redirect, s3_redirect, update and redirect, and nothing
         else. BPU.scala 383 derives its stage flushes from
         redirect_req.valid and they never leave the BPU.

         CONSEQUENCE. ftb_flush_px and ras_flush_val/_snapshot are
         redundant. They are LEFT IN PLACE, unread or nearly so,
         and are not evidence of unfinished work. See
         ras_decisions.md 4.4.2 for the RAS half and
         ftb_interfaces.md 2.6 for the FTB half.

         AS BUILT by BP-121 (D8, D9), which found the squash was
         not applied: blocks younger than a redirect still
         performed RAS operations. The block at p1 is squashed by
         any rollback. The block at p2 survives only its own p2
         redirect; a squashed block at p2 performs no RAS
         operation (ras_p2_keep). The RAS restore is not applied
         when the rollback is the cluster's own p2 or p3 redirect,
         because the redirecting block's own operation stands
         (ras_decisions.md 4.3).

  FE-13  The cluster publishes its view of every slot on every
         prediction, at p2 and again at p3, not only when a redirect
         fires. A redirect says fetch must be resteered; the slot
         correction group says what the entry must record. The two
         are different questions and fire at different rates.

  FE-19  A FETCH ADDRESS IS 41 BITS AND ITS HIGH BITS ARE CHECKED
         BEFORE IT NARROWS. VA_WIDTH is 41 because H is mandatory
         through Sha, MMU-20 makes the G-stage Sv39x4, and Shvsatpa
         requires vsatp to support Bare. With V=1 and
         vsatp.MODE=Bare the fetch PC is a guest physical address of
         up to 41 bits. Sv39x4 requires bits 63:41 to be zero or the
         access guest-page faults.

         The backend computes a JALR target with 64-bit arithmetic
         and may produce a PC with bits 63:41 set. That must fault.
         Narrowing it to VA_WIDTH discards the evidence, so
         bkend_ftq_redir_pc is checked WHERE IT IS FORMED, in the
         backend, before it narrows. The front end does not
         re-derive this and has no means to.

         HOW A REJECTED ADDRESS IS SIGNALLED IS NOT DECIDED, FE-U11.
         An earlier draft of this invariant said the FTQ receives a
         redirect "already marked malformed". No such marking
         exists: the redirect group of ftq_backend_interfaces.md 5
         carries four cause values, MISPREDICT, TRAP, REPLAY and
         UNSPEC, and none of them means this. Either the backend
         traps before forming the redirect at all, or a fifth cause
         is added. FE-U11.

         This is not new with 41 bits. The same hole exists at 40
         today; two-stage translation moves the boundary from 39 to
         41 and makes it visible.

         WITHIN 41 BITS, LEGALITY IS THE ITLB'S. THREE REGIMES, not
         two:

         - translation on, V=0 with satp.MODE=Sv39 or V=1 with
           vsatp.MODE=Sv39: a legal address has bits 40:39 equal to
           bit 38.
         - V=1 with vsatp.MODE=Bare: the fetch PC is a guest
           physical address and all 2^41 patterns are legal, which
           is why VA_WIDTH is 41.
         - V=0 with satp.MODE=Bare: THE FETCH ADDRESS IS PHYSICAL.
           Svbare is mandatory (rva23-profile.adoc), so this regime
           is reachable, and it is the one the machine resets into.
           No sign-extension rule applies and nothing translates;
           the address is bounded by pa_bits = 36
           (icache_decisions.md L1I-20), and an address above that
           is out of implemented physical space, which the PMP and
           PMA checks answer with cause 1 rather than a page fault
           (MMU-10, MMU-12). V=1 with both vsatp.MODE and
           hgatp.MODE Bare reaches physical space the same way.

         The same value is legal in one regime and a fault in
         another, and only the ITLB holds V, satp.MODE and
         vsatp.MODE. MMU-16 has cause 12 and cause 20 for the
         translating regimes and cause 1 for the third. No predictor
         and no FTQ stage evaluates this.

         This enumeration carried two regimes and attributed the
         sign-extension rule to the whole of V=0, which is wrong
         wherever satp.MODE is Bare. Session-072.

         CONSEQUENCE FOR PREDICTORS. Predictor storage need not
         represent every address exactly. An FTB tag that does not
         cover bit 40 aliases, and is caught by predecode at the
         block end. MMU-14 already keeps speculation out of
         non-idempotent regions. Architectural addresses -- pc,
         pft_addr, target_pc, ftq_resolve_t.target,
         bkend_ftq_redir_pc, RESET_VECTOR -- may not truncate.
         FTB_TAG_BITS is pinned at 26 on that basis, TD#122.

         THE ITTAGE STORES THE WHOLE TARGET. Since BP-111 (TD#132)
         its target field is VA[40:1], IT_MAX_TGT_WIDTH is 40, and
         no site infers a target bit. This read that
         IT_MAX_TGT_WIDTH was pinned at 38 and that the ITTAGE
         reconstruction zero-extended bits 40:39, which no
         extension rule could get right for both a V=1 guest
         physical address and a V=0 Sv39 kernel address.
         Session-074.

         NOT FE-13. FE-13 republishes the cluster's own view of the
         block, which on an alias is the aliased one, so it cannot
         detect its own error. Predecode reads the fetched bytes and
         is the independent check: ftq_ifu_interfaces.md 6 and 7.

         POINTER MASKING DOES NOT REACH THIS INVARIANT. Ssnpm is
         mandatory in RVA23S64, so it is fair to ask whether bits
         40:39 are masked. They are not. The ratified Pointer
         Masking specification v1.0 applies the ignore
         transformation to explicit memory accesses only -- loads,
         stores, atomics, FP loads and stores -- and states it does
         NOT apply to implicit accesses such as page-table walks or
         instruction fetches. Every address this invariant covers is
         a fetch address, so Ssnpm has no front-end consequence.

         RECORDED SO IT IS NOT RE-RAISED. A session-070 draft of
         this invariant claimed the opposite, sourced to the J
         extension working draft, whose discussion of masking the
         two extra Sv39x4 GPA bits under vsatp.MODE=Bare concerns
         DATA accesses. It was applied to the fetch path in error.

12. Source Document Conflicts

There is a known difference in pipe stage labeling. RESOLUTION: all documents will transition to the p0/p1/p2/p3 labeling. This document uses it.

bp_arb_spec.md contains errors. Where this document departs from it, it does so deliberately:

  2, 7.1   uFTB output presented at p0 -- AS A PORT NAME AND AN
           ALLOCATION POINT, which is the error. The uBTB result
           IS combinationally valid within the p0 cycle (7.1 is
           cited for exactly that in section 2.1 of this document
           and in ubtb_interfaces.md Timing); what is wrong is
           treating p0 as the stage at which the prediction is
           FORMED and the FTQ allocates. Session-070: the two
           readings were being confused, this entry being read as
           rejecting 7.1 outright.
           RESOLUTION: the initial prediction is formed at p1 and the
           FTQ allocates there. This entry said bp_arb_spec.md 7.2
           refers to "the uBTB p1 prediction"; 7.2 contains no such
           text. Session-071.

  2, 7.2   The RAS top-of-stack read at p0 called "the initial p0
           prediction", and in section 2 the RAS said to drive the
           FTQ directly at p0.
           RESOLUTION: the p0 TOS read is an INPUT to the p1
           prediction. The cluster registers it and applies it when
           the p1 selection mux forms a RETURN slot (section 2.2).
           The RAS drives no FTQ port at p0 and forms no prediction
           of its own. Session-071.

  2, 5.2   LP listed as RAM-based, with a prediction queue, update
           queue and credit arbitration.
           RESOLUTION: the LP has no SRAM; loop_pred.sv is a
           registered counter array (sram_init.md) and declares no
           PQ, UQ or arbiter. bp_arb_spec.md section 2 marks the
           column NO* and 5.2 is retained only in case the LP is
           given a RAM. Added session-072; bp_arb_spec.md 5.2 had
           flagged the omission since session-070.

  2, 3.4   LP listed as a redirect source (lp_redir_val_p2).
           RESOLUTION: the LP is not a redirect source. It is selected
           against the uBTB by mux at p1. lp_redir_val_p2 does not
           exist. No predictor declares any redirect port (FE-12).

  3.3      "SC > TAGE > FTB/LP > uFTB/RAS" presented as an override
           priority.
           RESOLUTION, NARROWED session-070. The chain as written
           mixes two quantities and only one of them is ranked.

           DIRECTION IS ONE QUANTITY and IS ranked. The FTB submits a
           direction for every valid conditional (conf MSB on
           ftb_brI_taken_p2), TAGE supersedes it at p2, SC supersedes
           TAGE at p3: SC > TAGE > FTB on direction. Section 3.3 of
           this document says so, and
           ftb_confidence_override_rules.md 4.3 and 8 are the owning
           rules. Suspended per branch when ftb_fastpath_p2 fires,
           where the FTB direction stands and neither TAGE nor SC
           overrides it, though both are still requested and trained.

           EVERYTHING ELSE IS NOT RANKED. Targets are selected by
           branch type -- RAS for a return, ITTAGE for an indirect
           with the FTB target on an ITTAGE miss, FTB otherwise --
           and the uBTB and LP at p1 produce a whole prediction that
           a later stage supersedes. Those do not contend and there
           is no ordering among them beyond stage order, FE-3.

           AN EARLIER REVISION of this resolution read "there is no
           priority chain. These predictors do not produce the same
           quantity and do not contend." That reason is true of LP,
           uFTB and RAS and false of SC, TAGE and FTB, which all
           produce a direction, so the resolution contradicted
           section 3.3 of this same document. Narrowed rather than
           withdrawn: the wider chain is still rejected.

  3.3      "ITTAGE (p2) > RAS (p0)" presented as an override chain.
           RESOLUTION: there is no chain. br_type selects the RAS for
           a return and the ITTAGE for an indirect. The two are never
           both consulted for one branch.

  4.4, 6.2 The update queue producer described as commit. 6.2 was
           added session-071; it carried the same statement with no
           annotation.
           RESOLUTION: the producer is post-execute resolution. The
           two write ports and the backpressure behavior are retained
           as written.

  4.4      Updates described as program-order.
           RESOLUTION: this is an out-of-order machine. Updates are
           enqueued and delivered in resolution order (FE-6).

  naming   uFTB.
           RESOLUTION: the predictor is the uBTB. This document uses
           uBTB throughout.

Prior revisions of this document assigned the two prediction slots to fixed PC ranges (slot 0 pred_pc+0:31, slot 1 pred_pc+32:63), citing G8 and G17. That split does not apply to the FTB. NOR DOES IT APPLY TO TAGE OR ITTAGE ANY MORE: tage_interfaces.md TI3 has slot 1's PC supplied on tage_pred_inp_p0[1].pc and records pred_pc+32 as an error that was removed. This paragraph called it "the TAGE/ITTAGE bundle split", which sent the reader to a convention TAGE disowns. There is no pred_pc+32 split anywhere. Corrected session-070; the FTB conclusion below is unchanged.

The FTB prediction block is one 32-byte block and one FTB lookup supplies both predictions (ftb_decisions.md 2.1, 2.3); the two slots are the block's two branch fields, not two PC ranges. Section 10 now follows ftb_decisions.md, and BP-086 removed the retired model from ubtb.sv.


13. Technical Debt

  TD-FE-1  CLOSED 2026-08-19. The IFU interface is specified in
           planning/interfaces/ftq_ifu_interfaces.md. Section 2.3 of
           this document referenced the gap and now names the file.
           The predecode writeback forms NO predictor update: FE-8
           keeps update formation post-execute, and a second
           producer in a different order would break FE-6. The
           writeback is the third correction of a slot, after the p2
           and p3 slot correction groups.

           The three entry fields it left open are now decided:
           ftq_entry_formats.md 4 adds wb_rcvd and fault as flop
           vectors outside both SRAMs, and rejects request-issued
           as a second encoding of fetch_ptr. Nothing of TD-FE-1
           remains.

  TD-FE-8  CLOSED. A predecode writeback in flight when its entry
           is squashed and its index reallocated arrived after the
           new allocation cleared the status bits, and set them on
           the WRONG use of that index.

           ftq_decisions.md 5.6 solves the same problem for cluster
           responses with a four-deep in-flight shadow, and that
           mechanism does not transfer: it works because the
           cluster's stage registers advance unconditionally, so
           the shadow shifts in lockstep. IFU latency is neither
           fixed nor bounded -- an ICache miss makes it arbitrary
           -- so there is no stage count to shadow.

           ftq_ifu_interfaces.md 5 has the IFU discard what it
           holds for flushed entries, which covers everything
           except a writeback already presented in the flush cycle.
           Whether that race is real depends on the IFU's flush
           timing, which is not specified.

           THE FIX, as taken: one generation bit, ftq_ifu_gen out
           with the request and ifu_ftq_pdwb_gen back on the
           writeback, TOGGLED on each allocation, held in a third
           flop vector beside wb_rcvd and fault. A writeback whose
           tag does not match is dropped entirely.

           A toggle rather than the pointer's wrap bit: a rewind can
           reallocate an index within one wrap, where a wrap-derived
           value does not discriminate. ONE bit is sufficient
           because the IFU flush BOUNDS the stale writebacks in
           flight to one per flush, not because of the encoding --
           if that contract changes the width must be revisited.

           The 5.6 rejection of carried wrap bits does not apply --
           it was rejected for widening FTQ_IDX_BITS at every
           bp_cluster port and in three predictor metadata structs,
           and the IFU path touches none of those.
           ftq_entry_formats.md 4.4, ftq_ifu_interfaces.md 6.1.

  TD-FE-2  CLOSED. bp_ftq_meta_t field overloading. Resolved in
           ftq_entry_formats.md 3.1: a two-arm packed union, u.cond
           holding
           tage, sc and lp, u.ind holding ittage, with ftb outside
           the union. The member is chosen by
           bp_ftq_slot_t.br_type; there is NO wr_br_type
           discriminant -- it was dropped 2026-08-19 as redundant.
           421b -> 278b per slot. The slot dimension is unaffected:
           the union is inside bp_ftq_meta_t and the array is still
           declared at instantiation.

           IT IS DEFINED AND DEFERRED, NOT APPLIED. Section 16 of
           this document, ftq_entry_formats.md 3.1, ftq_decisions.md
           6 and the PROJECT_STATUS ftq_meta.sv row all say so, and
           G10 still lists the overload as outstanding. "CLOSED"
           here means the SCHEME is decided.

           This entry read "420b -> 280b per slot" with a
           wr_br_type discriminant. Both were superseded on
           2026-08-19; ftq_bpu_interfaces.md 10 item 17 carried a
           third pair, 420b -> 277b. ftq_entry_formats.md 3.1 is
           the owner and gives 421b -> 278b. Corrected
           session-070.

  TD-FE-3  bp_ftq_entry_t.pc and per-slot target are VA_WIDTH bits.
           REVERSED session-070, TD#122. This entry read that 39
           bits suffice because RVA23 mandates C so bit 0 of an
           instruction address is always zero, and that 39 was the
           floor. That was computed against a 40-bit sign-extended
           Sv39 address. VA_WIDTH is 41: the fetch PC may be a
           41-bit guest physical address under V=1 with
           vsatp.MODE=Bare, FE-19. The floor is therefore 40, as
           addr[40:1], not 39.
           The reduction to 35 remains unavailable for the reason
           recorded in session-069: it assumed a prediction block always
           begins on an FTB_BLOCK_BYTES boundary, and blocks are
           unaligned (ftq_decisions.md 4.7, ifu_decisions.md IFU-6).
           Any move to 40 is an ENCODING change, from addr[40:0] to
           addr[40:1], not a width trim, and every producer and
           consumer changes with it. Held at 41 until the design is
           working; revisit at the optimization step, together with
           the width of bp_redirect_t.target_pc, which carries the
           same quantity. The per-slot target is replicated
           NUM_PRED_SLOTS times, so the saving scales with the slot
           count.
           To be merged into the project tech debt list.

  TD-FE-4  bp_ftq_slot_t.pred_src has no functional consumer. Update
           fan-out is determined by br_type (section 7.2); redirect
           supersession is by stage and slot (section 3.4); each
           predictor derives its own training decision from its
           bp_ftq_meta_t slice. The field is retained for diagnostic
           attribution of which predictor supplied the fetched
           prediction, and for performance counters. Nothing
           functional reads it. It is now replicated per slot.

           Removal requires cleanup outside this document:
           ftq_entry_formats.md section 2 lists pred_src as the
           predictor that won, with no consumer; bp_structs_pkg.sv
           carries
           the field and its encoding. Remove the field and its enum
           when both are updated.

           To be merged into the project tech debt list.

  TD-FE-7  CLOSED by BP-102. bp_cluster derived its bp_history
           rollback entirely from its own p2 and p3 redirects and
           declared no input by which the FTQ could request one. The
           RAS could be restored on a backend mispredict, because
           ras_restore_val is an input, but the history rollback
           could not be triggered at all.

           THE STATE WAS NOT MISSING. bp_history.sv holds the full
           checkpoint array, ckpt_gptr and ckpt_pptr of FTQ_DEPTH
           entries indexed by FTQ index, and rolls back by reading
           it. Every checkpoint the machine needs was already inside
           the cluster. What was missing was the TRIGGER: for a p2
           or p3 redirect the cluster knows the index from its own
           stage registers, but for a backend redirect the index is
           known only to the FTQ and no port carried it in.

           The fix, as built: two input ports, ftq_rollback_val and
           ftq_rollback_idx -- a valid and an FTQ_IDX_BITS index, no
           history data -- ORed into the existing rollback with
           priority over the cluster's own, since an architectural
           correction outranks a speculative one. bp_history is
           unchanged.

           THE INDEX FORM WAS TAKEN, and the alternative is now
           closed. The two copies of a checkpoint -- the array
           inside bp_history and the field in the FTQ entry -- are
           written from the same p1 allocation and are one to one
           against an FTQ_IDX_BITS index, so presenting the index
           selects the same pointer pair the values would have, at
           FTQ_IDX_BITS = 6 bits rather than 13, and leaves
           bp_history untouched. SEVEN IS FTQ_PTR_BITS, the pointer
           with its wrap bit, which this port does not carry: the
           port is [FTQ_IDX_BITS-1:0] (ftq_backend_interfaces.md,
           ftq_bpu_interfaces.md) and FTQ_IDX_BITS is 6. This read
           seven in both places. Session-072.
           (13, not 14: ghist_ptr is 8 and phist_ptr is 5,
           ftq_decisions.md 3.1, ftq_entry_formats.md 2,
           bp_history_decisions.md 7. Session-070.)
           ftq_decisions.md 3.2 was worded for the value form and
           was corrected to match.

           The FTQ arm is a flat override, NOT a new level in the
           FE-3 stage order. FE-3 orders speculative corrections
           among themselves; an architectural correction is not a
           later stage, it is a different kind of thing. FE-3 still
           orders p3 over p2 between themselves.

           Unblocks ftq_backend_interfaces.md section 5 D1. Same
           class as TD-FE-6 and found the same way, by writing down
           what the FTQ would have to drive.

  TD-FE-6  CLOSED. bp_ftq_slot_t.br_type and .pos held the p1 uBTB
           values for the entry's whole life. bp_cluster formed the
           FTB classification in w_br_type_p2 and the FTB positions
           in w_ftb_br0_pos_p2 / w_ftb_br1_pos_p2, but no port
           carried any of them out: bp_redirect_t holds target_pc
           and valid only. Section 7.2 keys update fan-out off
           br_type, so a block the uBTB missed and the FTB hit read
           NO_BRANCH at resolution and formed NO update at all --
           the case where training matters most. Section 7.4 of
           ftq_bpu_interfaces.md claimed pos came from the FTB,
           which no port made possible.
           Carrying the type on bp_redirect_t does NOT fix it: a
           redirect fires only when the p1 and p2 successors differ,
           and the defining case is a not-taken conditional the uBTB
           missed, where both views end the block at the same
           address and no redirect fires. The classification is
           needed on every prediction, the redirect is an exception
           path.
           Fixed by the section 2.5 slot correction group, valid on
           every prediction the FTB answers. tb_bp_cluster group I,
           24 checks; sim_bp_cluster 973 -> 997. Proven by mutation:
           gating bpu_slot_val_p2 on w_any_redir_p2 reproduces the
           defect and I1 catches it.

  TD-FE-5  CLOSED, verified session-070. It read:
           bp_structs_pkg.sv comments branch_id as "FTQ slot index"
           in bp_ftq_entry_t, tage_pred_meta_t, sc_pred_meta_t, and
           ittage_pred_meta_t; the field is the FTQ entry index.
           The package contains no "FTQ slot index" string; every
           branch_id comment reads "FTQ entry index". PROJECT_STATUS
           recorded it done at session-063 and this entry and
           ftq_bpu_interfaces.md 10 item 3 both stayed open.

14. Unresolved

  FE-U1  CLOSED session-075 (Jeff). Return identification before
         p1. The RAS presents its top-of-stack as the initial
         predicted target for a return, but the FTB branch type
         does not exist until p2. The uBTB entry's br_type is what
         identifies the return at p1 (section 2.2); the residual
         question was what happens when the uBTB misses and the
         block contains a return. Nothing at p1: the FTB
         identifies the return at p2 and the p2 redirect corrects
         the successor from ras_pop_addr_p2 (section 3.3). The
         cost is the p2 redirect latency on a uBTB miss, which
         every other branch type the uBTB misses already pays.

  FE-U2  CLOSED for the FTQ side, 2026-08-19. A backend mispredict
         flush reaches the FTQ on the redirect group of
         ftq_backend_interfaces.md section 5, which serves
         mispredict, trap and replay from one port set.

         The RAS behaviour behind D3 is CLOSED TOO, 2026-08-20, and
         was answered by ras_decisions.md 4.4 long before that: a
         flush restores the RAS by the same pointer restore as any
         redirect, which is D2 and is built. The unread
         ras_flush_* ports are redundant, not unfinished (4.4.2).

         NOTHING REMAINS. BP-105 closed the flush EVENT and the
         FTB half by decision: there is no flush event, a flush is
         a redirect, FE-14. TD #96, G24 and IC-FTB-07 all closed.

  FE-U3  bp_ftq_slot_t.confidence, 4 bits. bp_cluster.md marks the
         purpose TBD and FTQ_CONF_BITS a placeholder. Nothing in
         either path reads it; the cluster drives it to zero.

  FE-U4  PHR contribution to index and tag hashing. OPEN, and not
         deferred to anything: the TAGE and ITTAGE implementation
         sessions it was deferred to are done, both units are
         Complete, and every fold is still GHR-derived
         (bp_cluster.md History Module, bp_history_decisions.md HI2). This
         read that bp_cluster.md defers it to those sessions, a
         deferral bp_cluster.md retired session-070. Session-072.

  FE-U5  Indirect chain update and correction semantics.
         bp_arb_spec.md defers RAS and ITTAGE to a later spec.

  FE-U6  SC CSR enable. bp_arb_spec.md 0 states that when the SC is
         disabled the control logic issues no SC updates, does not
         process the SC response queue, and does not wait on it,
         while SC-related buffering and storage continue as normal.
         The phrasing is not yet placed in the specification.

  FE-U7  CLOSED 2026-08-19. FTQ allocation and deallocation policy
         is ftq_decisions.md 5. FOUR pointers with a wrap bit --
         xlate_ptr was added session-069 and this read "Three":
         alloc advances at p0 when the request is accepted, since
         ftq_pred_idx_p0 leaves with it; fetch advances on the IFU
         handshake; one commit pointer both issues the RAS commit
         and frees, walking at one entry per cycle because
         ras_commit_* is scalar. Full is alloc catching commit and
         is the only condition that stops the FTQ predicting.
         Redirect rewinds alloc and fetch, never commit.

  FE-U8  CLOSED. Prediction block to FTQ entry mapping. bp_ftq_entry_t now
         carries a per-slot array of target, taken, and br_type, so
         one entry represents one prediction block with NUM_PRED_SLOTS
         predicted branches. See ftq_entry_formats.md 2, where the
         fast path moved, and section 10, FE-10. This read
         "sections 4.1 and 10"; 4.1 is retired (section 6, MOVED).
         Session-072.

  FE-U9  CLOSED session-075 (Jeff) by the section 7.2 table:
         RETURN_CALL trains uBTB, FTB and RAS, not ITTAGE. The
         item as raised: br_type update fan-out covers four of the EIGHT
         bp_br_type_e encodings. The section 7.2 table has rows for
         conditional, indirect, return, and direct unconditional.
         FOUR have no row: DIRECT_CALL, INDIRECT_CALL, NO_BRANCH and
         RETURN_CALL. Both call encodings push the RAS, and per the
         session-061 ruling INDIRECT_CALL updates ITTAGE for the
         target and RAS for the return address. NO_BRANCH forms no
         update. Independent of the slot count.

         RETURN_CALL AT 3'b111 IS THE FOURTH AND ITS FAN-OUT IS NOT
         DETERMINED. It was added session-069 (ras_decisions.md 2,
         dcd_decisions.md DCD-11a) for the JALR that pops then
         pushes, which made the enum eight encodings, not seven.
         That it drives the RAS twice is settled. Whether it also
         trains ITTAGE for its target, as INDIRECT_CALL does, is
         not: it is an indirect JALR whose predicted target comes
         from the pop. Resolve with the 7.2 table. An earlier
         revision of this item read "four of the seven" and named
         three unlisted encodings. Corrected session-070.

  FE-U11 How a backend redirect PC with bits 63:41 set is signalled.
         FE-19 requires the check where the redirect is formed and
         does not say what the backend does with the result. The
         ftq_backend_interfaces.md 5 cause field has no value for
         it. Two candidates: the backend traps on the JALR and forms
         no redirect, which needs nothing here; or a fifth cause is
         added, which changes that port. The first is likely right
         and is not this document's to rule -- no backend document
         exists. TD#122 carried it until that TD closed,
         session-074; it now waits on the backend document.

15. Front End Top

TD#117 records that there is no front-end top and that ftq.sv deliberately does not instantiate bp_cluster. This section is the level above both. It closes TD#117.

15.1 Contents
  FE-15  The front end top is structural. It instantiates
         bp_cluster, ftq, the IFU, the L1I, THE ITLB, the ibuf and
         decode, and wires them. It holds no state and makes no
         decision. The ITLB is inside by FE-U10 and was missing
         from this list; session-070. THE L1I INSTANCE IS THE PACINO
         COPY at rtl/core/frontend/icache (FE-21, CG-D1). Built by
         BP-123, accepted session-077 (Jeff).
         The same rule ftq_decisions.md 7 applies to ftq.sv
         applies here.

ftq.sv is a structural top over the FTQ modules and bp_cluster is a structural top over the predictors. The front end top is the third of these and the last; nothing above it is front end.

15.2 The L1I
  FE-16  The L1I is INSIDE the front end top and is instantiated
         there, as a SIBLING of the IFU. It is not inside the IFU.
         The IFU exposes the interface to it. This is
         icache_decisions.md L1I-2 and this section does not
         restate that document.

The point of L1I-2 is that the cache is SELF CONTAINED, not that it is elsewhere. Keeping it a sibling rather than a child of the IFU is what lets physical design treat it in isolation, and that purpose is met wherever the instantiation sits.

An earlier revision of FE-16 put the L1I outside the front end altogether. It was written session-069 and contradicted L1I-2, which predates it. L1I-2 is the ruling.

The L1I's source is the pacino copy of the cachegen emission, in the front end tree at rtl/core/frontend/icache, since BP-123 (FE-21). This read that its source "is the emitter and the configuration, not a file in the front end tree". Either is a build fact and does not move the module. Its port into the l2, named mem (FE-21; this read up_i), is a topology edge and is not a front end connection.

15.3 The boundary
  FE-17  TWO groups cross the front end boundary, and one listed
         here does not. This read THREE until session-076, when the
         uncached group ceased to exist (IFU-21 reversed). This read "Four groups cross",
         counting a row it then calls not a boundary group, and
         placed the IFU-to-ITLB path on the boundary when FE-U10
         puts the ITLB inside the top. Corrected session-070.

         instruction       NOT a boundary group. The IFU to L1I
                           path, l1i_ifu_interfaces.md, is INTERNAL
                           to the top under FE-16. What crosses is
                           the L1I's l2-side port, `mem` (FE-21;
                           this read `up_i`), a topology edge.

         translation       the ITLB to the page table walker, and
                           that alone (itlb_l2tlb_interfaces.md).
                           There is no L2 TLB now and the walker
                           is outside the top (mmu_decisions.md
                           MMU-1, MMU-1a, session-077); this read
                           "the ITLB to the shared L2 TLB". The
                           IFU to the ITLB, itlb_ifu_interfaces.md,
                           is INTERNAL: FE-U10 puts the ITLB inside
                           the top, a sibling of the IFU.
                           itlb_decisions.md and mmu_decisions.md.

         uncached          NO LONGER A GROUP. Uncached fetch goes
                           through the L1I marked uncached
                           (ifu_decisions.md IFU-21, reversed
                           session-076), so it leaves by the L1I's
                           `mem` port like any fetch. This row read "the IFU's
                           second instruction source, IFU-21. It
                           does not pass through the L1I."

         backend           decode to rename and dispatch; the FTQ
                           to the backend for resolution, redirect
                           and commit (ftq_backend_interfaces.md);
                           and the commit stage to the IFU for
                           FENCE.I and cbo.inval
                           (l1i_ifu_interfaces.md 11, built by
                           BP-123, accepted session-077).

fe_top has outputs that no group above names: ftq_full and ftq_empty, and decode_bundle, vec_decode_bundle and pd_out. They are listed in examples/fe_demo/docs/fe_top_connectivity.md (DOC-002, D5 and D6). Which group each belongs to is open. Session-080.

The backend group is two unrelated paths that happen to share a direction. Decode hands instructions forward. The FTQ exchanges control with the backend and is not in the instruction path at all.

15.4 Reset and redirect
  FE-18  The top introduces no redirect source and no flush
         mechanism. FE-14 holds across it: a flush is a redirect,
         and a redirect reaches each unit by the path that unit
         already declares.

bp_cluster clears its stage valids from its own p2 and p3 arms and from the FTQ arm of BP-102. The FTQ drives the IFU flush of ftq_ifu_interfaces.md 5. The ibuf clears on a BACKEND redirect only, IBUF-8, 8a and 8b, ifu_ibuf_interfaces.md IB-12. This read "clears on redirect", which would include the p2 and p3 cluster redirects; those do not clear it. Corrected session-070. There is no front-end-wide flush signal and the top does not create one.

15.4a Inputs the top takes because their producers do not exist
  FE-20  Ruled session-075 (Jeff). Three groups cross the boundary
         INWARD in addition to FE-17's, each standing in for a
         unit that does not exist yet. The top passes them through
         and decides none of them.

         csr           V, the current privilege, satp, vsatp and
                       hgatp ASID, VMID and MODE fields, and the
                       pmpcfg and pmpaddr registers. ITLB-17 and
                       MMU-11a. The CSR file does not exist. The
                       walker is outside the top and takes its own
                       CSR group (mmu_decisions.md MMU-24a); this
                       group does not carry the roots or the
                       envcfg bits. Session-077.

         config        the cluster configuration: sc_enable,
                       ftb_fastpath_en (G25), tage_enable_aging,
                       tage_aging_interval, ittage_enable_aging and
                       ittage_aging_interval, and decode's
                       ext_enable. What eventually drives them is
                       the CSR file's question, not the top's. This
                       listed dual_pred_en, which no module has
                       (section 10 describes it), and omitted the
                       aging inputs and ext_enable; found by BP-118.
                       Session-075. sc_enable goes to the cluster
                       and the FTQ (the converter applies the
                       SC-disabled rule), BP-119.

         maintenance   the ITLB invalidate port of ITLB-14. Its
                       producer is the backend.

         And one OUTWARD dependency: decode's output to rename is
         qualified by the ibuf read ready of IBUF-12, which comes
         in on the backend group until rename exists.

  FE-21  The L1I is the cachegen emission under
         tools/cachegen/output/l1i, instantiated from that path,
         as rtl/core/frontend/l1i_param_chk already compiles
         against it. Its l2-side port leaves the top as a
         boundary edge; a testbench answers it. The emission names
         that port `mem` (link tl_l1i_l2), and its core port
         `core_*`, not the `ifu_l1i_*` and `l1i_ifu_*` of
         l1i_ifu_interfaces.md; widths agree and fe_top maps them
         one to one. This read `up_i`. BUILT by BP-118 as
         rtl/core/frontend/fe_top. Session-075.

         SUPERSEDED by cachegen_decisions.md CG-D1. Since BP-123
         fe_top and rtl/core/frontend/l1i_param_chk instantiate the
         pacino copy at rtl/core/frontend/icache, and nothing in
         rtl/ compiles the emission under tools/. The copy keeps the
         emission's names: `mem` for the l2-side port and `core_*`
         for the core port, including core_uncached and the
         core_inv_* group, which fe_top maps one to one to
         l1i_ifu_interfaces.md (10.1). Its l2-side port still leaves
         the top, and tb_fe_top's memory model answers it from the
         image that also answers the walker (ptw_mem_interfaces.md
         WM-10). Built by BP-123, accepted session-077 (Jeff).
15.5 Unresolved
  FE-U10 CLOSED by the FE-16 ruling. The ITLB is inside the front
         end top, a sibling of the IFU on the same reasoning:
         written RTL, serving the IFU alone, self contained. The
         boundary falls between the ITLB and the shared translation
         level, which serves the data side and is outside: the
         page table walker, with no L2 TLB now (mmu_decisions.md
         MMU-1, session-077; this named the L2 TLB). FE-17 is
         written for that reading.

16. Document History

  2026-07-09  tmp_004. Written from bp_cluster.md rev 1.0,
              bp_arb_spec.md rev 1.0, and bp_structs_pkg.sv. Covers
              the BPU to FTQ prediction and redirect path and the FTQ
              to BPU update path. Predictor internals and the RAM
              arbitration model are out of scope. Departures from
              bp_arb_spec.md are recorded in section 12.

  2026-07-23  fe_decisions.md. Renamed from tmp_004.md. Dual-slot FTQ
              entry applied, closing FE-U8. bp_ftq_entry_t split into
              block-scalar fields and a per-slot bp_ftq_slot_t array;
              bp_ftq_meta_t carried per slot. Redirect val and tgt
              became per-slot arrays with a scalar ftq_idx; the slot
              is the array index. Supersession restated per entry and
              slot. Section 2.4 successor PC selection added. History
              checkpoint and RAS snapshot confirmed block granular,
              with the one-RAS-operation-per-block argument recorded
              in section 9. FE-10, FE-11, TD-FE-5, and FE-U9 added.
              ITTAGE raw/final split removed (single-stage target at
              p2; the p2/p3 split was a conventional LUT-plus-offset
              artifact not present in Pacino). Section 10 slot model
              corrected: the two slots are the branch fields of one
              32-byte FTB block, not two fixed PC ranges; G8/G17 is
              the TAGE/ITTAGE bundle split and does not govern the
              FTB (ftb_decisions.md 2.1, 2.3). Intro line, FE-10, and
              FE-11 propagated to the branch-field model; FE-11
              restated to the RAS-operation basis.

  2026-08-09  PA-direct correction, session-064. Three corrections
              carried from
              ftq_bpu_interfaces.md section 10.
              Section 2.2 and section 9: the RAS top of stack is read
              at p0, not p1. ras.sv declares ras_tos_addr_p0 and
              ras_tos_valid_p0; the cluster registers the value and
              applies it at p1. Section 1 stage list updated to match.
              Section 3.1: the per-predictor redirect port group was
              removed. No predictor declares a redirect port
              (INFRA-011, all 140 ports). Rewritten to the
              cluster-derived, stage-named groups bpu_redir_p2 and
              bpu_redir_p3, with the one-quantity comparison, the p1
              operand definition, the p3 comparison basis and the
              branch_id qualification. FE-4 restated and FE-12 added.
              Section 4.2: bp_loop_meta_t replaced by lp_pred_t
              (TD#106, BP-092); ftb_pred_meta_t added to the nested
              member list. TD-FE-3 reference to <pred>_redir_tgt_<pN>
              retargeted to bp_redirect_t.target_pc.
              Also updated: section 2.1 for the BP-091 loop_pred
              dual-slot retrofit; section 2.4 and 4.1 for
              bpu_pred_pft_p1 and bp_ftq_slot_t.pos; section 10 for
              the BP-086 uBTB block model; FE-U1, FE-U3 and FE-U9
              sharpened.

  2026-08-19  Section 4.3 corrected. It stated that the fast-path
              entry is read by "every redirecting predictor's
              cluster-boundary comparison", contradicting FE-4 and
              section 3.1 of this document and section 6 of
              ftq_bpu_interfaces.md, all three of which state that
              bp_cluster does not read the FTQ. The sentence
              predates the session-064 FE-4 rewrite and was the only
              statement bearing on fast-path read-port count.
              Rewritten to the three real readers, all of them the
              FTQ itself: fetch every cycle, the redirect apply
              path, and resolution.

  2026-08-19  bp_ftq_entry_t gains pft_addr, the block fall-through,
              VA_WIDTH and block scalar. Sections 2.4 and 4.1
              updated. The successor selection of 2.4 is re-evaluated
              on every redirect and its not-taken arm is
              bpu_pred_pft_p1, which is present only in the p1 cycle,
              so the value must be held in the entry. Applied to
              bp_structs_pkg.sv and checked in tb_bp_pkg.sv. Entry
              width 182b -> 222b. All 47 bpu targets green.

  2026-08-19  TD-FE-2 RESOLVED. Section 4.2.1 added: the
              bp_ftq_meta_t overload scheme. Two-arm packed union,
              u.cond {tage, sc, lp} against u.ind {ittage}, with ftb
              and a wr_br_type discriminant held outside it. Arm
              selection, four write rules and three read rules
              stated; the p3 SC write must be suppressed on the
              indirect arm or it corrupts ITTAGE state. 420b -> 280b
              per slot, slow path 53,760b -> 35,840b. Section 7.2
              fan-out re-keyed from bp_ftq_slot_t.br_type to
              bp_ftq_meta_t.wr_br_type, and the stale sentence in
              4.1 corrected. TD-FE-6 opened: the p2 FTB
              classification reaches no FTQ-facing port, which is
              both a prerequisite for this scheme and a pre-existing
              defect in the 7.2 fan-out. FE-13 added.

  2026-08-19  TD-FE-6 CLOSED, and the TD-FE-2 record restaged around
              it. Section 2.5 added: the p2 and p3 slot correction
              groups, delivered in bp_cluster.sv, which carry the FTB
              classification and the in-block positions into the
              fast-path entry on EVERY prediction rather than only on
              a redirect. Section 4.1 and section 7.2 returned to
              keying update fan-out on bp_ftq_slot_t.br_type, which
              is now correct. FE-13 restated to the slot correction
              group. Section 4.2.1 restaged: the union is DEFINED AND
              DEFERRED, a storage optimization with no other
              dependency, and its wr_br_type discriminant is dropped
              -- it was proposed while the fast-path br_type was
              stale and is redundant now. 280b -> 277b per slot,
              slow path 35,456b, FTQ 49,664b. tb_bp_cluster group I,
              24 checks, sim_bp_cluster 973 -> 997, all 47 targets
              green in this session.

  2026-08-19  ftq_backend_interfaces.md written: resolution,
              redirect and commit. FE-U2 closed for the FTQ side.
              TD-FE-7 opened -- bp_cluster has no history-rollback
              input, so a backend mispredict cannot restore the GHR
              and PHR pointers. Third of the four FTQ interfaces;
              only ftq_icache remains, and it is a decision rather
              than a specification.
  2026-08-20  TD-FE-8 CLOSED, one generation bit on the IFU path,
              toggled per allocation. FTQ module decomposition
              recorded in ftq_decisions.md 7: several modules, a
              purely structural ftq.sv top, partitioned by the rule
              that every piece of state has exactly one owner.

  2026-08-20  TD-FE-1 closed in full: its three deferred entry
              fields decided in ftq_entry_formats.md 4, two added
              as flop vectors and one rejected. TD-FE-8 opened for
              the in-flight predecode writeback race.

  2026-08-20  TD-FE-7 CLOSED by BP-102. bp_cluster gains
              ftq_rollback_val and ftq_rollback_idx with priority
              over its own p2/p3 arms; bp_history unchanged. The
              index form was taken over the pointer-value form and
              ftq_decisions.md 3.2, which was written for the value
              form, was corrected. tb_bp_cluster group J, 30 checks,
              sim_bp_cluster 1765 -> 1795, all 47 targets green in
              that session.

  2026-09-15  session-069. FE-16 CORRECTED. Its first revision put
              the L1I outside the front end, contradicting
              icache_decisions.md L1I-2, which predates it. L1I-2
              is the ruling: the L1I is inside the front end top,
              a sibling of the IFU, not inside the IFU. The point
              is that the cache is SELF CONTAINED, which physical
              design needs, not that it sits elsewhere. FE-15 and
              FE-17 follow; FE-U10 closes on the same reasoning,
              putting the ITLB inside and the shared L2 TLB out.


  2026-09-17  session-070. FE-19 added: VA_WIDTH is 41 and the high
              bits of a backend-formed redirect PC are checked before
              the address narrows. H is mandatory through Sha, MMU-20
              makes the G-stage Sv39x4, and Shvsatpa requires vsatp
              to support Bare because Svbare requires it of satp, so
              a V=1 vsatp.MODE=Bare fetch PC is a 41-bit guest
              physical address. Legality within 41 bits stays with
              the ITLB, which holds V and vsatp.MODE; the front end
              does not evaluate it.

              TD-FE-3 reversed. It called 39 the floor, computed
              against a 40-bit sign-extended Sv39 address. The floor
              is 40 as addr[40:1], and reaching it is an encoding
              change rather than a width trim. TD#122.

  2026-09-19  session-071. Conventions and section 10 define the
              PREDICTION block (32 bytes, one FTQ entry) and the
              FETCH block (64 bytes, the L1I line the IFU reads) as
              separate things; "fetch block" had been used for the
              32-byte unit throughout, including FE-10 and FE-U8.
              Section 9: the RAS snapshot is written at p2 for every
              valid block (ftq_bpu_interfaces.md 4c). Section 12:
              the "2, 7.1" entry no longer quotes text bp_arb_spec
              does not contain; "2, 7.2" added for the RAS p0 read;
              the 4.4 producer entry now covers 6.2. The 2026-08-09
              history entry was labelled INFRA-012, a task that did
              not exist then; it was a PA-direct correction.

  2026-09-20  session-072. 2.1: the p1 mux keys on lp_pred_is_loop,
              not an LP valid, which does not exist; the LP supplies
              direction only. 12: the LP no-SRAM departure from
              bp_arb_spec.md 2 and 5.2 added. FE-U4 no longer
              deferred to the completed TAGE/ITTAGE sessions.

  2026-09-20  session-072, second pass. 3.3 and 9: spec_pop_addr swept to
              ras_pop_addr_p2, and 9 no longer identifies the p0
              TOS read with the 3.3 entry.

  2026-09-20  session-072, third pass. FE-19: the legality
              enumeration carried two regimes and attributed the
              sign-extension rule to all of V=0; V=0 with
              satp.MODE=Bare is physical and bounded by pa_bits.
              The ITTAGE zero-extend is stated as binding
              predictions, not architectural addresses.

  2026-09-20  session-072. D18: the rollback index is FTQ_IDX_BITS = 6,
              not 7; 7 is FTQ_PTR_BITS.

  2026-09-20  session-072. E5: the registry pointer names section 15 and
              the issue-order numbering. E9: the zero-extension
              paragraph moved clear of the "Both are caught"
              clause. E11: SPDX header added. E12: the history
              section's split fences merged.

  2026-09-20  session-072. D16: FE-U8 cites ftq_entry_formats.md 2
              instead of the retired section 4.1. E17: section 6's
              registry sentence matches the Overview. E18: the
              pft_addr sentence has its verb back.

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

  2026-10-01  session-074. Conventions: one prediction block per
              cycle, TD#133. FE-19: the ITTAGE stores VA[40:1]
              since BP-111 (TD#132); the 38-bit pin and the
              zero-extension paragraph are retired. FE-U11 no
              longer names TD#122 as its carrier.

  2026-10-07  session-075, rulings (Jeff). 7.2: rows for
              direct call, indirect call, return-call and no
              branch; RETURN_CALL does not train ITTAGE, closing
              FE-U9. FE-U1 closed: a return the uBTB misses is
              corrected at p2. 15.4a: FE-20, the csr, config and
              maintenance input groups; FE-21, the L1I from its
              emitted path.

  2026-10-07  session-075, after BP-118. 7.2: as built the
              return-call row is not met (TD#152) and only the FTB
              and RAS train in the top (TD#151). FE-20: the config
              group as the RTL has it. FE-21: the emitted port names
              and fe_top built.

  2026-10-07  session-075, after BP-119. 7.2: every row built;
              the ruling that a branch its FTQ entry does not hold
              is placed at resolution and trains every predictor of
              its row. FE-20: sc_enable also goes to the FTQ.

  2026-10-08  session-076, PA-direct correction recording BP-121.
              2.4: per-slot successors chained (D5, D15). 7.2: the
              loop predictor reads before it writes (ruled after
              BP-121, TD#169). FE-10: p1 slots in position order
              (D12). FE-14: the squash as built (D8, D9).

  2026-10-09  session-076, recording BP-122. 3.2: the LP's p2
              re-read is a direction source at p2. 3.3: a trusted
              LP outranks SC, TAGE and FTB (ruled). 7.2: built.
              2.1: the p1 LP direction is an early guess.

  2026-10-09  session-076, ruling (Jeff). FE-17: the uncached group
              is gone (IFU-21 reversed); the maintenance path from
              commit is part of the backend group.

  2026-10-09  session-077, rulings (Jeff). FE-17 and FE-U10: the
              translation group goes to the page table walker,
              outside the top; there is no L2 TLB (MMU-1 reversed).
              FE-20: the walker's CSRs are its own group.

  2026-10-09  session-077, after BP-123, rulings (Jeff). FE-15 and
              15.2: the L1I instance is the pacino copy. FE-17: the
              commit-to-IFU maintenance path built. FE-21 superseded
              by CG-D1. The front-end units list no longer calls the
              L1I emitted rather than written. 15.2 and FE-17 name
              the L1I's l2-side port `mem` (FE-21), not up_i.

  2026-10-15  session-080, after DOC-002. FE-17: the fe_top outputs
              no group names.

  2026-10-17  session-081, after BP-138. 10: a jump no slot carries
              ends the block at the jump PC (D1, provisional).

  2026-10-19  session-081, after BP-139. 10: a branch no slot carries
              ends the block at its PC (option A). 7.2: item C.

  2026-10-19  session-081, after BP-140. 10: the cut is a backstop.

  2026-10-19  session-081, after DOC-007. 10: FD-23 re-pointed at the
              split; w_jmp_cut_p2 is read by nothing.
ftq_entry_formats.md

planning/arch/ftq_entry_formats.md on GitHub

FTQ Entry Formats

 FILE:    ftq_entry_formats.md
 SOURCE:  bp_structs_pkg.sv, fe_decisions.md sections 4.1 and 4.2
 STATUS:  DRAFT
 UPDATED: 2026-10-08
 CONTACT: Jeff Nye

The layout of the two FTQ entry structures. This file is the SOLE prose home for them. bp_cluster.md and fe_decisions.md each carried a copy until 2026-08-19; both now point here.

bp_structs_pkg.sv is the reference. Where this file and the package disagree, the package wins and this file is wrong.

Behaviour -- lifetime, read rates, checkpoint, allocation -- is ftq_decisions.md. The ports that carry these structures across the BPU boundary are ftq_bpu_interfaces.md.

Both structures follow the package array-direction convention: packed-struct dimensions descend, [NUM_PRED_SLOTS-1:0]; port dimensions ascend, [0:NUM_PRED_SLOTS-1].


1. Two paths

The FTQ entry is stored in two SRAMs, both indexed by the FTQ entry index. The fast path (bp_ftq_entry_t, section 2) is read every cycle. The slow path (bp_ftq_meta_t, section 3) is read only at update. The two are separated so the every-cycle read does not carry the width of the update-only metadata.

  fast path   bp_ftq_entry_t   228b   x 64 entries        14,592b
  slow path   bp_ftq_meta_t    425b   x 2 slots x 64      54,400b
                                                          -------
                                                          68,992b

The slow-path figure is the unpacked layout. Section 3.1 defines an overload that takes it to 278b per slot and 35,584b, which is defined and deferred.


2. Fast path: bp_ftq_entry_t

bp_ftq_entry_t is read every cycle. It is written at p1, its slots are rewritten at p2 and p3 ON EVERY PREDICTION rather than only on a redirect (fe_decisions.md 2.5 and FE-13, ftq_bpu_interfaces.md 4a, ftq_decisions.md 2), its RAS snapshot is rewritten at p2 for every valid block (ftq_bpu_interfaces.md 4c, session-071), and the entry is freed at commit. This read "written at p1 and rewritten by redirect"; session-070.

Two more writers rewrite a slot. Predecode writes the slot of a branch it finds on a structural mispredict (ftq_ifu W1). And ftq_resolve writes a PLACED slot when it accepts the resolution of a branch the entry did not hold (section 3.1, after R2), through the ftq_entry placement port rsv_wr_*, added by BP-119. The placement write is last in ftq_entry's write order, so it overrides a predecode write to the same entry in the same cycle.

SINCE BP-121 (D2) ftq_resolve writes EVERY resolved slot, mapped or placed (rsv_wr_val; since BP-139 a placement into an occupied slot only as section 3.1 ITEM C says), and ftq_entry clears the slots above a resolved end, the position of a taken or mispredicted resolution (rsv_wr_end). The entry then holds what executed rather than what was predicted, which the commit walk relies on (ftq_decisions.md 5.4). Before it, a resolution of an already-mapped slot did not write the entry and slots after a taken or mispredicted branch were not cleared, so the walk committed calls that never executed and missed return-calls predicted not taken (TD#161).

Block scalar fields, one per entry:

pc            41     prediction block start PC, VA_WIDTH
pft_addr      41     block fall-through address, VA_WIDTH
branch_id      6     FTQ entry index, FTQ_IDX_BITS
ras                  bp_ras_snapshot_t: TOSR, TOSW, BOS, 4 bits each
ghist_ptr      8     GHR circular buffer pointer snapshot
phist_ptr      5     PHR circular buffer pointer snapshot
valid          1     entry valid

Per-slot fields, bp_ftq_slot_t[NUM_PRED_SLOTS-1:0]:

slot_valid     1     this slot carries a predicted branch
target        41     predicted target for this slot, VA_WIDTH
br_type        3     bp_br_type_e
taken          1     predicted direction
pos            4     in-block branch position, FTB_BR_POS_BITS,
                     counted from the block start
pred_src       3     predictor that supplied this slot
                     not currently used, see TD-FE-4
confidence     4     saturating counter, FTQ_CONF_BITS

The per-slot array is declared inside bp_ftq_entry_t: one entry holds one prediction block and all its slots.

br_type is per slot and selects the predictor update set at resolution (fe_decisions.md 7.2). It is written at p1 from the uBTB view and CORRECTED at p2 by the slot correction group of fe_decisions.md 2.5, which carries the FTB classification. Before that group existed the field kept the p1 value for the entry's whole life (TD-FE-6).

pos locates the branch inside the fetch bundle. It addresses two-byte positions, so a 32-byte block has sixteen of them. RVA23 mandates the C extension and a branch may begin at any 2-byte boundary, so a coarser position could not tell two RVC branches in one aligned word apart. It is counted from the block START, as on every port; the FTB and the uBTB store positions region-relative and convert at their own boundary (ftb_decisions.md 4.6, session-071). The cluster also uses it to form the branch PC reported to bp_history: block START plus pos << POS_OFFSET_BITS -- not the 32-byte-aligned base, which bp_cluster.sv used until BP-110 removed it (TD#125, closed) -- which is two bytes per position at the values in bp_defines_pkg.sv (BP-092a, rescaled by BP-099). Stated as the shift rather than a literal multiplier so it cannot drift from the position width again.

The history pointers and RAS snapshot are block scalar (ftq_decisions.md 3.1, fe_decisions.md 9). The RAS snapshot is initialised at p1 from bpu_pred_ras_p1 and OVERWRITTEN at p2 for every valid block from bpu_blk_ras_p2, the state after both slots' operations (ftq_bpu_interfaces.md 4c, ras_decisions.md 4.2). No restore reads the p1 value. Session-071, ruled.

pft_addr WAS A p1 VALUE THAT NOTHING CORRECTED, until BP-118 (below); this read "IS A p1 VALUE AND, AS BUILT, NOTHING CORRECTS IT". Written once from bpu_pred_pft_p1, and the p2/p3 groups of ftq_bpu_interfaces.md 4a carry bp_ftq_slot_t only. On a uBTB miss the p1 value is the FULL block end, so the very case this field exists for -- re-deriving the successor after a redirect rewrites a slot -- is the case where it is stale.

THE FIX IS RULED, session-075 (Jeff), TD#113, and BUILT by BP-118: the 4c block-scalar group gains bpu_blk_pft_p2, and the FTQ rewrites pft_addr from it for every valid p2 block, as it rewrites ras from bpu_blk_ras_p2. The value is the not-taken term of the cluster's own p2 successor. ftq_bpu_interfaces.md 4c is the owner; no second field is added here. BP-118.

A THIRD WRITER, AT RESOLUTION. Since BP-121 (D3, TD#164, ruled session-075) ftq_resolve rewrites pft_addr when it accepts the resolution of a taken jump (rsv_wr_pft) with the resolved fall-through, which the resolution's is_rvc makes formable. The same value goes to the FTB on ftb_upd_pft_addr_u0, so the FTB learns the resolved block end rather than its own prediction. The RAS commit return address is read from this field (ftq_bpu_interfaces.md 4c names it as a reader), so it now reads the resolved value.

pft_addr is block scalar as well: it is the address fetched after this block when no slot in it is taken, one value per entry. It is written at p1 from bpu_pred_pft_p1 (TD#108) and is the not-taken arm of the successor selection of fe_decisions.md 2.4. It is stored rather than re-derived because that selection is re-evaluated whenever a redirect rewrites a slot, so the value is needed after p1 and cannot be recovered from the rest of the entry.


3. Slow path: bp_ftq_meta_t

bp_ftq_meta_t is stored in a separate, wider SRAM, read only on post-execute update and never on the prediction path.

It holds the state each predictor needs to train and cannot recompute at resolution. The field list is maintained in bp_structs_pkg.sv. The struct nests one metadata block per predictor: tage_pred_meta_t, sc_pred_meta_t, lp_pred_t, ittage_pred_meta_t, and ftb_pred_meta_t.

The loop member is lp_pred_t, the same type loop_pred outputs. TD#106 retired bp_loop_meta_t, which carried the same thirteen fields in a different declaration order with two spelled differently; the cluster's field-by-field map went with it (BP-092).

The metadata is per slot, carried [NUM_PRED_SLOTS-1:0]. Each slot produces its own provider indices, counter snapshots, and allocation targets.

bp_ftq_meta_t is written at p2 for the predictors that finalize there, and at p3 for the SC, to the entry index and slot the prediction occupies.

3.1 Overload scheme (TD-FE-2, resolved)

DEFINED HERE, DEFERRED TO IMPLEMENTATION. The scheme below is settled and is a STORAGE optimization only. Nothing else in the design depends on it, so bp_ftq_meta_t may be built with its five members unpacked and collapsed to the union later. Doing so preserves the disjointness of the p2 and p3 write groups, which the union narrows to a single arm.

The predictor metadata blocks are mutually exclusive by branch type. TAGE, SC and the loop predictor train only on conditional branches; ITTAGE trains only on indirect branches. No branch is both. Storing all four unpacked therefore holds 147 bits per slot that no resolution can ever read.

The four are overlaid in one union region with two arms. The FTB block stays OUTSIDE the union: every branch type that forms an update at all updates the FTB, so it is common to both arms.

  bp_ftq_meta_t                                       278b
    ftb          ftb_pred_meta_t         7b   [277:271]
    u            union                 271b   [270:0]

  u.cond                                271b
    tage         tage_pred_meta_t       79b   [270:192]
    sc           sc_pred_meta_t        112b   [191:80]
    lp           lp_pred_t              80b   [79:0]

  u.ind                                 271b
    rsvd                               124b   [270:147]
    ittage       ittage_pred_meta_t    147b   [146:0]

Per slot 278b against 425b unpacked. The slow-path array falls from 54,400b to 35,584b and the FTQ from 68,992b to 50,176b, a 30% reduction. The union is slow-path only, so VA_WIDTH does not reach it.

THE UNION ABSORBS THE SESSION-073 ITTAGE WIDENING FOR FREE. The two extra bits on each of ittage_prm_tgt and ittage_alt_tgt take the block from 143b to 147b, which grows into u.ind's reserved field and leaves the arm at 271b, set by u.cond. The 278b and 35,584b figures are unchanged by it. That is why the widening costs 512 bits in the unpacked layout and nothing here.

DISCRIMINANT. bp_ftq_slot_t.br_type in the fast-path entry. It is the FTB classification once the fe_decisions.md 2.5 slot correction group has written it, and the FTQ already reads the fast-path entry at resolution for pc (fe_decisions.md 7.2), so the arm costs no field and no extra access. An earlier draft of this section carried a wr_br_type copy inside bp_ftq_meta_t; it was proposed while bp_ftq_slot_t.br_type was still the stale p1 value and is redundant now that TD-FE-6 is closed.

ARM SELECTION.

  COND                            ->  u.cond
  INDIRECT_NONRET, INDIRECT_CALL  ->  u.ind
  RETURN, DIRECT_CALL,
  DIRECT_UNC, NO_BRANCH           ->  no arm; u is not written
  RETURN_CALL                     ->  not decided, see below

RETURN_CALL was missing from this table until session-070. It was added to bp_br_type_e in session-069 for the JALR that pops then pushes (ras_decisions.md 2, dcd_decisions.md DCD-11a), taking the enum to eight encodings while this table still listed seven.

It pops and pushes the RAS. Neither touches this metadata, so on that alone it would write nothing, like RETURN. What is not settled is whether it ALSO trains ITTAGE at resolution, the way INDIRECT_CALL does. If it does, it writes the ITTAGE half; if not, it writes nothing. fe_decisions.md FE-U9 owns that question.

Nothing here contradicts anything: RETURN_CALL consults only the RAS, so "RAS and ITTAGE are never both consulted" still holds.

INDIRECT_CALL takes the indirect arm because it updates ITTAGE for the target (FE-U9, session-061). Its RAS push reads the fast-path snapshot, not the metadata.

WRITE RULES.

  W1  The p2 write always writes ftb. It writes tage and lp of
      u.cond, or ittage of u.ind, per the arm selection above.
  W2  The p3 write writes sc of u.cond and ONLY when the arm is
      u.cond. On any other arm the p3 write to the union region is
      SUPPRESSED. sc occupies [191:80] and ittage occupies [142:0],
      so an unsuppressed p3 write would corrupt ITTAGE training
      state. No placement of the two arms avoids the overlap:
      ittage is wider than lp and than tage.
  W3  Within u.cond the p2 fields (tage, lp) and the p3 field (sc)
      are disjoint bit ranges, so those two writes still require no
      merge. The disjointness that held across the whole struct
      before the union holds only within an arm after it.
  W4  The cluster continues to present all five metadata blocks on
      the flat ports of ftq_bpu_interfaces.md 7.1 and 7.2. The
      overlay is performed by the FTQ as it writes the SRAM. The
      cluster does not carry the union type.

READ RULES.

  R1  At resolution the FTQ reads br_type from the fast-path entry
      and decodes the union arm from it.
  R2  When that br_type disagrees with the resolved branch type in
      bp_update_t, the metadata describes a different predictor set
      than the branch that executed. Form the uBTB and FTB updates
      only: both derive from the resolved facts and from ftb, which
      lies outside the union. Suppress the TAGE, SC, LP and ITTAGE
      updates -- their payload types embed metadata that was never
      captured for this branch type. The FTB update corrects the
      stored classification, so the next occurrence selects the
      right arm.

R2 applies only to a branch that maps to a slot of its entry. It is reachable whenever an FTB entry is stale or aliased.

THE UNMAPPED RESOLUTION. A resolution of a live entry that maps to no slot is not only the stale or aliased case: it is the ordinary first execution of any conditional branch or JALR the FTB does not yet hold, because the p2 correction carries only what the FTB returned and predecode writes a slot only on a structural mispredict. RULED session-075 (Jeff), built by BP-119: ftq_resolve places it in a slot of the entry in program order (the ftq_ifu W1 rule: the lowest free slot, or the slot at or after its position, which can displace a stored later branch), and trains it like a mapped branch: the FTB (allocating on a miss), the uBTB, and TAGE, SC, LP and ITTAGE from the placed slot's metadata. R2 does not apply to a placed branch. The placed slot is written into the entry only when the resolution is accepted, so a held resolution is placed again when presented again. Before this ruling the unmapped resolution formed no update at all.

ITEM C, A PLACEMENT INTO AN OCCUPIED SLOT (ruled by Jeff 2026-10-18, built by BP-139; it replaces the BP-119 ruling for this case, at both slot counts). When the slot a resolution is placed in holds a valid branch (at another position, since the resolution did not map), the slot's metadata describes that other branch: form the uBTB and FTB updates only and suppress TAGE, SC, LP and ITTAGE, as R2 does. A placement into a free slot trains as above. ftq_resolve reports it on rsv_plc_occ.

THE WRITE (BP-139, PROVISIONAL). A placement into an occupied slot is written into the entry only when the placed branch is a taken call, return or return-call (the commit walk must see it), or when it ends the executed block (taken or mispredicted) and the occupant is at a later position (the occupant is then off the path). Otherwise the occupant keeps its slot and maps when it resolves later. An occupant earlier than a placed taken call or return loses its slot.


4. Per-entry fetch status

The two fields deferred by ftq_ifu_interfaces.md 8 item 3. They were held back because the policy that reads them was FE-U7, which ftq_decisions.md 5 resolved.

  wb_rcvd   1   the IFU has written this entry's block back
  fault     1   fetch of this block terminated on a fault
  gen       1   generation tag, toggled on allocation (4.4)

The third field named in that item, request-issued, IS NOT ADDED. fetch_ptr already says which entries have been issued: every entry behind it has, every entry at or ahead of it has not (ftq_decisions.md 5.1). A per-entry bit would be a second encoding of one pointer, free to disagree with it.

4.1 Not in either SRAM

THESE ARE FLOPS, three vectors FTQ_DEPTH deep, 192 bits total. They are NOT members of bp_ftq_entry_t and not members of bp_ftq_meta_t. Three reasons, and the third is decisive:

  • The writeback arrives at an arbitrary time relative to the fetch read. Setting a bit inside the fast-path entry would be a read-modify-write of an SRAM that is already read every cycle.
  • The commit walk and the next-PC hold test these ACROSS entries. A flop vector is readable whole; an SRAM is readable one index at a time.
  • A redirect rewind squashes every entry after an index (ftq_decisions.md 5.5) and must clear their status in ONE cycle. In flops that is a masked clear. In SRAM it is a walk, and the walk would have to finish before those indices could be reallocated.

The entry totals of section 1 are therefore unchanged. Fast path 228b, slow path 425b per slot, 68,992b together; these 192 bits sit outside both. This read 421b and 68,480b, the figures before BP-111 (TD#132); section 1 already carried the current ones. Session-075.

4.2 Write and clear
  W1  wb_rcvd and fault CLEAR when the entry is allocated at p1,
      and gen TOGGLES. Allocation is the only producer of a fresh
      entry, so this is the one place a stale bit could otherwise
      survive a wrap.
  W2  wb_rcvd SETS on ifu_ftq_pdwb_val naming this index AND
      carrying a matching gen. A writeback failing the gen test is
      dropped entirely (4.4).
  W3  fault SETS on ifu_ftq_fault_val naming this index. The
      writeback carries both, so W2 and W3 can fire together.
  W4  A redirect rewind clears both for every entry it squashes,
      in the same cycle it moves the pointer
      (ftq_decisions.md 5.5).
  W4a W4 OUTRANKS W2 AND W3 IN ONE CYCLE. A writeback or fault set
      naming an index the same cycle's squash covers does not land.
      The one stale writeback ftq_ifu_interfaces.md 6.1 bounds
      arrives in exactly that cycle, with its generation still
      matching. Found and fixed by BP-118 through the front-end
      top; ftq_status_assert S1 fired. Session-075.

ifu_ftq_fault_pos is NOT stored. The fault code is not carried at all -- the architectural exception travels with the instruction stream to the backend, which is where it is taken (ftq_ifu_interfaces.md 6). The FTQ needs only to know that the block ended early.

4.3 Readers
  R1  fault holds the next-PC request. The FTQ stops requesting
      past a faulting block rather than predicting into a stream
      that will not be fetched (ftq_decisions.md 4.5 hold
      conditions).
  R2  fault does NOT hold commit. The entry frees normally; the
      trap is taken in the backend, which redirects the FTQ
      through the ordinary RC_TRAP path.
  R3  wb_rcvd qualifies the predecode redirect. An entry derives
      at most one, and only from its own writeback
      (ftq_ifu_interfaces.md 6). A second writeback naming an
      entry that already has the bit set derives NO redirect.
  R3a A SECOND WRITEBACK IS LEGAL, NOT A PROTOCOL VIOLATION. One
      arriving with wb_rcvd already set and gen[K] unchanged passes
      6.1 X3, is accepted and sets status. IT DERIVES NEITHER A
      REDIRECT NOR A FIELD REWRITE. Section 7 applies W1 and W2
      only on ifu_ftq_mis_val, and the rewrite and the redirect
      are ONE EVENT (ftq_ifu_assert I5): a rewrite without a flush
      would change the entry's successor while the old successor
      is still being fetched. So a mispredict reported on a second
      writeback is dropped whole, and the backend redirect remains
      the correctness backstop.

      NO DOCUMENTED PATH PRODUCES ONE SINCE BP-117. This rule was
      written for the W3 refetch: a predecode redirect on K flushed
      at K, so K was fetched twice by design. Since BP-117 a
      predecode redirect flushes at K+1 (ftq_ifu_interfaces.md 7
      W3, TD#146) and K is not refetched. The rule and I4 stay as
      the defined response if a second writeback ever arrives.
      Session-075.

      This rule first said "W1 and W2 apply to the fields as for
      any writeback", which would have split the rewrite from the
      redirect. Corrected session-073 after BP-114 reported the
      conflict. R3 previously called this case a violation, which
      was what W3 then required on every predecode redirect. Ruled
      session-073, TD#140.

Assertion I4 follows R3a: a second writeback on a set wb_rcvd is LEGAL, is accepted, and must not derive a redirect. BP-114 found the property already held the no-redirect half -- only its comment and message called the refetch writeback a violation -- and added the acceptance half, both proven by mutation. I4 is in ftq_ifu_assert.sv. TD#140 closed.

R3 is the reason wb_rcvd exists at all. Deallocation does not need it: 5.3 frees on commit only, and ftq_ifu_interfaces.md 7 already states the FTQ does not need the writeback to free an entry.

4.4 The in-flight writeback -- TD-FE-8, CLOSED

W1 clears both bits at allocation, which handles a stale bit surviving a wrap. It does NOT handle a writeback IN FLIGHT when the entry is squashed and its index reallocated: that writeback arrives after the new allocation cleared the bits, and sets them on the WRONG use of the index.

ftq_decisions.md 5.6 solves the same problem for CLUSTER responses with a four-deep in-flight shadow. That mechanism does not transfer: it works because the cluster's stage registers advance unconditionally, so the shadow shifts in lockstep. IFU latency is neither fixed nor bounded -- an ICache miss makes it arbitrary -- so there is no stage count to shadow.

ftq_ifu_interfaces.md 5 says the IFU discards whatever it holds for flushed entries, which covers everything except a writeback already presented in the flush cycle. Whether that race is real depends on the IFU's flush timing, which is not specified.

CLOSED by ftq_ifu_interfaces.md 6.1: one generation bit, ftq_ifu_gen out with the request and ifu_ftq_pdwb_gen back on the writeback, TOGGLED each time the entry is allocated. A writeback whose tag does not match is dropped entirely.

The bit is held here, beside wb_rcvd and fault:

  gen       1   generation, toggled on allocation

so section 4 is three flop vectors, 192 bits, not two. Allocation writes it and the IFU path reads it; nothing else does.

A TOGGLE rather than the pointer's wrap bit, because a rewind can reallocate an index within one wrap and a wrap-derived value would not discriminate there. One bit is sufficient because the flush of ftq_ifu_interfaces.md 5 bounds the stale writebacks in flight to one per flush; the reasoning, and what would invalidate it, is in 6.1.

The 5.6 rejection of carried wrap bits does not apply: it was rejected because it would have widened FTQ_IDX_BITS at every bp_cluster port and in three predictor metadata structs. The IFU path touches none of those.


5. Document History

  2026-08-19  Created. Sections 4.1, 4.2 and 4.2.1 moved here whole
              from fe_decisions.md, and the duplicate layout deleted
              from bp_cluster.md. No content changed in the move.
              Section 1 added: the two-path summary and the storage
              totals. Numbering: fe_decisions 4.1 -> section 2,
              4.2 -> section 3, 4.2.1 -> section 3.1.

  2026-08-19  FTB_BR_POS_BITS 3 -> 4. bp_ftq_slot_t.pos widens, so
              the slot is 56b and the entry 224b; ftb_pred_meta_t
              gains a bit in jmp_pos, so bp_ftq_meta_t is 421b.
              Fast path 14,336b, slow path 53,888b, FTQ 68,224b.
              Section 3.1's overload figures restated: 278b per
              slot, 35,584b, FTQ 49,920b.

  2026-08-20  Section 4 added: the per-entry fetch status fields
              wb_rcvd and fault, closing the remainder of TD-FE-1.
              request-issued deliberately NOT added -- fetch_ptr
              already carries it. Both are FLOPS outside either
              SRAM; 4.1 gives the three reasons. TD-FE-8 opened in
              4.4 for the in-flight writeback race, which 5.6's
              shadow cannot cover because IFU latency is unbounded.
              Section 4 Document History renumbered to 5; nothing
              referenced it. TD-FE-8 CLOSED the same day: a third
              flop vector, gen, toggled on allocation and carried
              on the IFU path. Section 4 is 192 bits, not 128.

  2026-08-21  Section 2: recorded that pft_addr is a p1 value with
              no correction path, found by BP-107 (W1). The fix is a
              p2 port in ftq_bpu_interfaces.md 4, not a field here.

  2026-08-21  Section 2 said the branch PC is block base plus
              position times FOUR. POS_OFFSET_BITS is 1, so it is
              times two; BP-099 rescaled it and this sentence was
              not propagated. Restated as `pos << POS_OFFSET_BITS`.

  2026-08-21  Cross-reference repair. No content change. 4.2 W4 and
              4.3 R1 cited "5.5" and "4.5" unqualified. Both are
              ftq_decisions.md sections. This file has no 4.5, and
              its own section 5 is this history, so an unqualified
              number resolved to the wrong document. Both qualified.

  2026-09-17  session-070. VA_WIDTH 40 -> 41 (TD#122, fe_decisions.md
              FE-19). pc, pft_addr and the per-slot target are the
              three fields that carry it. Block scalars 112 -> 114,
              slot 56 -> 57, bp_ftq_entry_t 224 -> 228, fast-path
              array 14,336 -> 14,592, total 68,224 -> 68,480.
              bp_ftq_meta_t is predictor metadata only and carries
              no VA_WIDTH field -- ITTAGE targets are
              IT_MAX_TGT_WIDTH, unchanged -- so 421b and the
              slow-path array are untouched, and so is the 278b
              union proposal. TD#122 tracks the RTL.
  2026-09-22  session-073. 4.3: R3 no longer calls the W3 refetch's
              writeback a protocol violation, and R3a states what
              it does instead. R3's bound -- one predecode
              redirect per entry -- is unchanged and is what stops
              a refetch loop. Assertion I4 corrected by BP-114 and
              TD#140 closed. R3a's "W1 and W2 apply" corrected
              after BP-114: the second writeback derives neither a
              redirect nor a rewrite, since the two are one event.

  2026-09-22  session-073. IT_MAX_TGT_WIDTH 38 -> 40 (TD#132,
              ruled by Jeff; ftq_bpu_interfaces.md 5.2 and
              ittage_table_entry_formats.md). ittage_pred_meta_t
              carries two targets per slot, so it goes 143b ->
              147b, bp_ftq_meta_t 421b -> 425b, the slow-path
              array 53,888b -> 54,400b and the FTQ total 68,480b
              -> 68,992b. The fast path is untouched: no ITTAGE
              target reaches it. The 3.1 union absorbs the
              widening into u.ind's reserved field, so the 278b
              scheme is unchanged and stays DEFERRED (Jeff,
              session-073): it is a storage optimization with no
              dependants, and unpacked is the more forgiving
              layout while the design is still moving.

  2026-09-19  session-071. Section 2: the RAS snapshot is
              overwritten at p2 for every valid block
              (ftq_bpu_interfaces.md 4c); pft_addr named in the
              paragraph that had begun "IT IS A p1 VALUE" directly
              under the RAS sentence; pos is start-relative and the
              branch PC is block START plus pos (TD#125). "Fetch
              block" replaced by "prediction block".

  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. E25: UPDATED brought to the session date.

  2026-10-06  session-075, after BP-117. 4.3 R3a: a second writeback
              is still legal and derives nothing, but no documented
              path produces one since a predecode redirect flushes at
              K+1. 4.1: the slow-path and total figures brought to
              425b and 68,992b, matching section 1. Section 2: the
              TD#113 fix for pft_addr is ruled, bpu_blk_pft_p2 on
              the 4c group; unbuilt.

  2026-10-07  session-075, after BP-118. Section 2: the TD#113 fix
              is built. 4.2 W4a: the squash outranks a same-cycle
              writeback or fault set.

  2026-10-07  session-075, after BP-119. Section 2: the predecode
              and placement writers, the placement last in write
              order. 3.1: the unmapped resolution is the first
              execution of a branch the entry does not hold; it is
              placed and trained, R2 applying only to a mapped
              branch (ruled, Jeff).

  2026-10-08  session-076, PA-direct correction recording BP-121.
              Section 2: every resolution writes its slot and the
              slots above a resolved end are cleared (D2); pft_addr
              is rewritten at the resolution of a taken jump (D3,
              TD#164); the aligned-base note brought to BP-110;
                            the "IS A p1 VALUE" heading brought to BP-118.

  2026-10-19  session-081, after BP-139. Section 2: an occupied
              placement is written only as 3.1 says. 3.1: item C
              and the placed-slot write (provisional).
ftq_bpu_interfaces.md

planning/interfaces/ftq_bpu_interfaces.md on GitHub

FTQ to BPU Interface

 FILE:    ftq_bpu_interfaces.md
 SOURCE:  fe_decisions.md, bpu_port_inventory.md (INFRA-011),
          bp_structs_pkg.sv, bp_cluster.sv
 STATUS:  DRAFT
 UPDATED: 2026-10-15
 CONTACT: Jeff Nye

Specifies the signals crossing the FTQ/BPU boundary and the routing from that boundary to the ports each predictor declares.

fe_decisions.md is the theory of operation. This file is the port specification. The RTL port declaration is the reference for every port named here. Where fe_decisions.md or bp_structs_pkg.sv disagrees with the RTL, section 10 states the correction the other file needs.


1. Scope

Covered: - prediction request from FTQ into the cluster - prediction results out of the cluster - redirects, derived at the cluster boundary - prediction metadata out of the cluster - updates from FTQ into each predictor - history checkpoint and rollback - configuration and status sidebands

Not covered:
- IFU to FTQ -- ftq_ifu_interfaces.md. TD-FE-1 is CLOSED; this
  read "(TD-FE-1, unspecified)". Session-070.
- EXE to FTQ resolution -- ftq_backend_interfaces.md
- predictor internals
- RAM arbitration (bp_arb_spec.md)

2. Conventions

Predictor ports are named as declared in the RTL. The eight modules do not share one naming convention. This file uses each module's actual port names and does not propose renaming.

Naming variance present in the shipped RTL, recorded so a reader is not surprised by it:

  tage, ittage, sc     <pred>_<signal>_<stage>, slot as unpacked
                       [0:NUM_PRED_SLOTS-1] after the port name
  ras                  same form, no queue-status ports
  ubtb                 slot as packed [NUM_PRED_SLOTS-1:0] on the
                       type
  loop_pred            per-slot since BP-091; prediction output
                       named pred_p1, update ports keep a p0 suffix
  ftb                  flat ports, no structs, no slot dimension
  bp_history           no stage suffixes, literal [1:0] and [2]
                       dimensions

Cluster-boundary signals defined in this file and not present in any shipped RTL are marked NEW. Everything else names a declared port.

Array direction follows the package convention: packed-struct dimensions descend, [NUM_PRED_SLOTS-1:0]; port dimensions ascend, [0:NUM_PRED_SLOTS-1].

Internal cluster nets carry a w_ prefix. Stage registers carry an r_ prefix with the stage in the suffix.

Stage labels are p0/p1/p2/p3 for prediction and u0/u1 for update.


3. Prediction request: FTQ to BPU

The FTQ drives one prediction request per cycle into the cluster.

  ftq_pred_val_p0                          request valid
  ftq_pred_pc_p0    [VA_WIDTH-1:0]         prediction block start PC
  ftq_pred_idx_p0   [FTQ_IDX_BITS-1:0]     allocated FTQ index

The FTQ index is presented at p0 so the cluster can carry it into the predictor input structs, which hold it as branch_id.

The cluster qualifies the request with the prediction-queue status of the queued predictors before presenting it to any of them, so all eight stay in lockstep and no prediction is dropped. The FTQ must not present a request while a pq_not_full output is low; the cluster has no request-ready output.

Nor may the FTQ present a request while any of the cluster's RAM init readies is low (the RAM Init Interface sections of tage_, ittage_ and sc_interfaces.md; ftq_decisions.md 4.5 H5). They are inputs of the FTQ, built by BP-137:

  tage_rdy      from bp_cluster (tage)
  ittage_rdy    from bp_cluster (ittage)
  sc_ready      from bp_cluster (sc)

Cluster routing of the request:

Destination Port Notes
ubtb pred_pc_p0 scalar PC
loop_pred pred_pc_p0 per slot
loop_pred pred_valid_p0 per slot
ftb pred_pc_p0 scalar PC
ftb pred_valid_p0 request valid
tage tage_pred_val_p0 per-slot bit vector
tage tage_pred_inp_p0 tage_pred_inp_t per slot
ittage ittage_pred_val_p0 per-slot bit vector
ittage ittage_pred_inp_p0 ittage_pred_inp_t/slot

tage_pred_inp_t and ittage_pred_inp_t each carry pc and branch_id. The cluster builds one per slot from the request.

Every slot of loop_pred.pred_pc_p0 is driven from the one request PC. There is no slot-1 PC at p0; the per-slot dimension is a shape, the same way the cluster drives sc.inp_pc_p2 per slot from a single staged p2 copy.

ubtb has no request-valid port. It presents an output every cycle.

sc takes no p0 request. It is driven from the TAGE p2 result (section 5.3).

RAS presents its top of stack at p0; see section 5.4.


4. Initial prediction: p1

ubtb and loop_pred produce the p1 prediction. Neither is a redirect source.

  ubtb.pred_p1       ubtb_pred_t [NUM_PRED_SLOTS-1:0]   out
  ubtb.blk_p1        ubtb_blk_t                         out
  loop_pred.pred_p1  lp_pred_t   per slot               out

ubtb_blk_t carries the entry hit and the reconstructed fall-through address. The hit is reported once per lookup; a slot's own valid bit says only whether that slot carries a branch.

lp_pred_t carries the loop table snapshot, including lp_hit, lp_pred_is_loop, and lp_pred_taken. It carries no target: the loop predictor supplies a direction only, and the target comes from the uBTB entry when the loop predictor wins.

loop_pred is per-slot as of BP-091 and its prediction output is named pred_p1. TD#105 is closed.

The p1 selection mux is cluster logic, per slot:

  lp_pred_is_loop set   ->  loop_pred supplies the direction
  else ubtb slot valid  ->  ubtb supplies the slot
  else                  ->  slot carries no prediction

There is no slot-0 exception to this rule.

THE LOOP PREDICTOR ONLY OVERRIDES THE DIRECTION OF A SLOT THE uBTB SUPPLIED. It carries no target, so when lp_pred_is_loop is set and the uBTB slot is not valid, the slot carries no prediction. Ruled session-075 (Jeff). bp_cluster.sv did not: with the uBTB slot absent it made the slot a taken conditional to address 0. Fixed by BP-118; the loop arm now requires the uBTB slot valid.

A uBTB RETURN takes its target from the registered RAS top of stack rather than from the uBTB entry.

Producer alignment. ubtb.pred_p1 is combinational from pred_pc_p0 and is therefore valid in the p0 cycle; loop_pred's output is registered and is valid in the p1 cycle. The cluster registers the uBTB result once so both describe the same request when the selection mux reads them.

Cluster output to the FTQ at p1:

  bpu_pred_val_p1                                 NEW
  bpu_pred_idx_p1  [FTQ_IDX_BITS-1:0]             NEW
  bpu_pred_slot_p1 bp_ftq_slot_t
                     [0:NUM_PRED_SLOTS-1]         NEW
  bpu_pred_ras_p1  bp_ras_snapshot_t              NEW
  bpu_pred_pft_p1  [VA_WIDTH-1:0]                 NEW

The FTQ writes these into the entry it allocates at p1.

bp_ftq_entry_t.ras IS WRITTEN AT p2, BY SECTION 4c. The RAS pushes and pops at p2 (ras_decisions.md 1.1) and the entry must hold the POST-operation snapshot (ras_decisions.md 4.2, ras_interfaces.md IC-RAS-08).

bpu_pred_ras_p1 only INITIALISES the field at allocate, and nothing restores from that value: every entry that survives reaches p2, and the 4c write overwrites it unconditionally. The port is kept because removing it is an RTL change for no functional gain.

RULED session-071 (Jeff). This section said the field "IS NOT WRITTEN FROM THIS GROUP" and, a paragraph later, that bpu_pred_ras_p1 initialises it, and left the p2 port unnamed (flagged session-070).

Allocation is unconditional: an entry is allocated for every prediction block, including one the p1 predictors miss, so a later stage has an entry to correct.

bpu_pred_pft_p1 is the block fall-through: the address the front end fetches after this block when no slot in the block is taken. One value per prediction, not one per slot, and qualified by bpu_pred_val_p1 -- it carries no valid of its own. TD#108.

It is the p1 view of the fall-through and is exactly the not-taken term the cluster already uses when it forms each slot's p1 successor for the section 6 redirect comparison: blk_p1.pft_addr on a uBTB hit, and the LOOKUP PC plus FTB_BLOCK_BYTES on a miss, where blk_p1.pft_addr reads zero. Not the block-aligned PC: blocks are unaligned and a miss does not resync the stream (ftq_decisions.md 4.7, bp_cluster.md Block width). Corrected session-069. It is not the FTB pftAddr of section 5.1, which arrives at p2.

AND THAT IS A DEFECT, NOT ONLY A DISTINCTION. bp_ftq_entry_t.pft_addr is written ONCE at p1 from this port and no later port can correct it: the 4a slot correction groups carry bp_ftq_slot_t only, and pft_addr is a block scalar. So the entry keeps the p1 view for its whole life, and on a uBTB MISS that view is the LOOKUP PC plus FTB_BLOCK_BYTES -- a full 32-byte block from wherever it started. When the FTB then terminates the block at a branch earlier in it, or corrects a block end the uBTB missed (FE-13), the entry is wrong and stays wrong.

Two consumers are affected, and they are not equally forgiving:

  • THE RAS RETURN ADDRESS. ras_decisions.md 8 names the FTB fallThroughAddr as the source of the pushed return address and says the RAS does not compute PC+2 or PC+4 itself. The FTQ has no field holding it, so a block terminated by a call pushes an address past the call. Cost is prediction accuracy on the matching return.
  • THE NOT-TAKEN SUCCESSOR. ftq_entry_formats.md 2 stores this field precisely so the successor can be re-derived after a redirect rewrites a slot -- which is the case where the p1 value is stale. Cost here is a FETCH ADDRESS, not an accuracy loss.

THE FIX IS A p2 PORT, not a new entry field. Adding a separate ret_addr patches the RAS symptom and leaves the successor wrong. The p2 block-scalar group carries the corrected fall-through and rewrites the block scalar: bpu_blk_pft_p2, section 4c, ruled session-075 and built by BP-118. Found by BP-107 (W1); the RAS half was confirmed against ras_decisions.md 8 at Jeff's instruction.

The FTQ writes it into the allocated entry as bp_ftq_entry_t.pft_addr. The port is present only in the p1 cycle and the FTQ re-evaluates the block successor on every redirect (fe_decisions.md 2.4), so the not-taken arm is read back from the entry rather than resampled from the cluster.


4a. Slot correction: p2 and p3

The p1 group of section 4 is the uBTB and loop-predictor view. The FTB classifies the block at p2 and supplies each branch field's in-block position. The cluster republishes its view of every slot at p2, and again at p3 with the SC direction applied.

  bpu_slot_val_p2                                 NEW
  bpu_slot_idx_p2  [FTQ_IDX_BITS-1:0]             NEW
  bpu_slot_p2      bp_ftq_slot_t
                     [0:NUM_PRED_SLOTS-1]         NEW
  bpu_slot_val_p3                                 NEW
  bpu_slot_idx_p3  [FTQ_IDX_BITS-1:0]             NEW
  bpu_slot_p3      bp_ftq_slot_t
                     [0:NUM_PRED_SLOTS-1]         NEW

Same type as bpu_pred_slot_p1. The FTQ overwrites the slot description of the named entry with the latest group received.

bpu_slot_val_p2 is r_val_p2 & ftb_valid_p2: the cluster has a corrected view only when the FTB answered. bpu_slot_val_p3 is r_val_p3 & r_ftb_ans_p3: gated the same way, on the FTB having answered that block at p2.

TD#161, found by BP-120, CLOSED by BP-121 (D1, D2). bpu_slot_val_p3 was r_val_p3, so when the FTB missed at p2 the p3 write overwrote the p1 slots with an empty view and the FTQ presented a block that was not its predecessor's successor: a stream error. Gating p3 alone broke the commit walk, which depended on the p3 write. BP-121 fixed that dependence as well: every resolution now writes its slot and clears the slots above a resolved end (ftq_entry_formats.md 2), and the backend commits an entry only after its resolutions are accepted (ftq_backend_interfaces.md 10 A7).

THIS IS NOT A REDIRECT AND IS NOT GATED ON ONE. A redirect fires only when the p2 successor differs from the p1 successor. The case that matters most does not qualify: a conditional the uBTB missed and the FTB found, predicted not taken. Both views end the block at the same address, no redirect fires, and the entry would otherwise keep br_type NO_BRANCH and pos zero -- so section 7.2 would form no update and no predictor would ever be trained on that branch. TD-FE-6, FE-13.

Field sources at p2:

Field Source
slot_valid FTB conditional field valid, or jump placement
br_type FTB classification, w_br_type_p2
taken TAGE when its branch_id matches, else FTB
target section 3.3 target table by branch type
pos ftb_br0_pos_p2 / ftb_br1_pos_p2, or
ftb_jmp_pos_p2 for the jump slot
pred_src the arm that supplied the target
confidence zero, FE-U3

p3 changes taken, and pred_src to PRED_SC when SC actually moved the direction. SC corrects direction, not branch type, so br_type, pos and target pass through the p2 to p3 register unchanged.


4b. No p1 port carries the block start PC

bp_ftq_entry_t.pc is the prediction block start and the entry is written at p1, but NO PORT IN THIS SECTION CARRIES IT: the group has the slots, the RAS snapshot and the fall-through. The value exists only as the ftq_pred_pc_p0 the FTQ issued a cycle earlier, so THE FTQ MUST STAGE ITS OWN REQUEST to write its own entry.

This is not an omission to fix by adding a port -- the cluster would be echoing back a value the FTQ gave it. It is recorded because a reader sizing the p1 group from this section alone will conclude the entry can be written from it, and it cannot. BP-107 publishes ftq_npc's r_next_pc, which already holds that value one cycle on, so it costs no state; see ftq_decisions.md 7.5.

Widening ftq_shadow by VA_WIDTH per stage would also work and is worse: it carries for four stages something only one stage needs.


4c. Block-scalar correction: p2

The 4a groups carry bp_ftq_slot_t only. A block scalar of the entry that is not known until p2 needs its own group. RULED session-071 (Jeff). BUILT BY BP-118, session-075, the RAS half included: until then no bpu_blk_* port existed on either side and the entry kept the p1 snapshot, though this section and fe_decisions.md 9 described the p2 write as built.

  bpu_blk_val_p2                                  NEW
  bpu_blk_idx_p2   [FTQ_IDX_BITS-1:0]             NEW
  bpu_blk_ras_p2   bp_ras_snapshot_t              NEW
  bpu_blk_pft_p2   [VA_WIDTH-1:0]                 NEW   TD#113

bpu_blk_val_p2 is r_val_p2: EVERY valid p2 block, whether or not the FTB answered and whether or not the block operated on the RAS. It is not bpu_slot_val_p2, which also requires ftb_valid_p2.

bpu_blk_ras_p2 is ras_snapshot_p2[NUM_PRED_SLOTS-1], the pointer state after both slots' operations (ras_interfaces.md IC-RAS-08). A block with no call or return presents the unchanged state. The FTQ writes it into bp_ftq_entry_t.ras of the named entry unconditionally.

WHY EVERY BLOCK. Gating the write on a RAS operation, or on the FTB answering, leaves the p1 initial value in the entry. That value is taken before this block's own p2 operation and, in a moving stream, can predate the previous block's as well, so a restore from a block with no RAS operation would drop that push or pop. The p2 write is the only one a restore can rely on.

The index is subject to the stale-response drop of ftq_decisions.md 4.6, through the shadow of 5.6 at its p2 stage, like every other indexed response.

DEFERRED, TD#149, session-075 (Jeff): THE p3 REPAIR. ras_decisions.md 1 and 1.2 and IC-RAS-11 repair the speculative stack at p3 when the p3 view of a slot differs from the p2 operation applied, which happens when SC reverses an earlier slot and so changes which later slot is reachable (FE-11). The snapshot written here is then the pre-repair state, and a later restore to this entry restores a slightly wrong stack. The RAS is a predictor, so the cost is accuracy, not correctness. The fix, if measurement asks for it, is a p3 snapshot write. Raised session-071; this read OPEN. MEASURED by BP-121: no return mispredict after warm-up is attributable to it (PROJECT_STATUS TD#149). Left open. Since BP-121 the p3 repair runs when SC changes reachability (ras_decisions.md 1, TD#166), which it did not before.

bpu_blk_pft_p2 IS THE CORRECTED FALL-THROUGH, TD#113. It is the same not-taken address the cluster uses as the not-taken term of its p2 successor when it forms the section 6 p2 redirect comparison: the FTB fall-through when the FTB answers, and the p1 value carried forward when it does not. The FTQ writes it into bp_ftq_entry_t.pft_addr of the named entry, unconditionally, under bpu_blk_val_p2, exactly as it writes bpu_blk_ras_p2. RULED session-075 (Jeff). Built by BP-118: the net is w_pft_p2 in bp_cluster.sv, w_ftb_valid_p2 ? w_ftb_pft_addr_p2 : r_pft_p1_p2. SINCE BP-121 (D3, TD#164), for a block ending at its jump the p2 fall-through is the jump PC plus 2 or 4 (w_jmp_ft_p2), not the FTB's shared pftAddr (ftb_interfaces.md IC-FTB-03). The expression above is as BP-118 built it. AS BUILT by BP-121 (read by BP-122): w_pft_p2 is r_pft_p1_p2 when the FTB did not answer, else the PC of the first branch the FTB reports that no slot carries, r_pc_p2 + (w_cut_pos_p2 << POS_OFFSET_BITS) (w_cut_p2, BP-139 option A, fe_decisions.md 10; BP-138's w_jmp_cut_p2 was the jump case), else w_jmp_ft_p2 when the FTB holds a jump visible from this start, else ftb_pft_addr_p2; w_jmp_ft_p2 = r_pc_p2 + (ftb_jmp_pos_p2 << POS_OFFSET_BITS) + (ftb_jmp_rvc_p2 ? 2 : 4), which is also the RAS push address.

ONE SOURCE FOR BOTH. Because the value written into the entry and the value the p2 redirect comparison reads are the same net, the entry's not-taken successor and the cluster's decision about whether the block end moved cannot disagree. A separate derivation for the entry would let them.

FOUR READERS, not the two section 4 names. BP-118 found every one reads pft_addr and now sees the corrected value: the fetch successor ftq_ifu_next_pc and the predecode W3 successor, both in ftq_ifu.sv (the successor selection of fe_decisions.md 2.4); the RAS commit return address in ftq_entry.sv (ras_decisions.md 8); and the FTB update fall-through in ftq_resolve.sv, which section 4 did not name. ftq_npc's p1 successor reads bpu_pred_pft_p1, not the entry.

This read that the field "joins this group when TD#113 is built; it is not specified here". Section 4's TD#113 text, and the TD#113 row, place the fix in "the p2 group"; this section is that group. Session-075.


5. Late predictions: p2 and p3

5.1 FTB

ftb declares 42 flat ports. The p2 outputs the cluster consumes:

  ftb_valid_p2       ftb_hit_p2        ftb_way_p2
  ftb_br0_valid_p2   ftb_br0_pos_p2    ftb_br0_taken_p2
  ftb_br0_conf_p2    ftb_br0_target_p2
  ftb_br1_valid_p2   ftb_br1_pos_p2    ftb_br1_taken_p2
  ftb_br1_conf_p2    ftb_br1_target_p2
  ftb_jmp_valid_p2   ftb_jmp_pos_p2    ftb_jmp_target_p2
  ftb_is_call_p2     ftb_is_ret_p2     ftb_is_jalr_p2
  ftb_jmp_rvc_p2
  ftb_pft_addr_p2    ftb_fastpath_p2 [1:0]

ftb_jmp_rvc_p2 was added by BP-121 (TD#164), with the update input ftb_upd_jmp_rvc_u0; the port count above predates both.

br0 maps to slot 0 and br1 to slot 1 at the cluster boundary. That mapping is PROGRAM ORDERED as of IC-FTB-16: the update path fills br0 with the earlier branch, so slot 0 is the block's first branch and slot 1 its second. The FTB is not internally slot-split: one lookup supplies both branch fields of one 32-byte block (ftb_decisions.md 2.1, 2.3). ftb_fastpath_p2 is already a per-slot vector, bit 0 for br0 and bit 1 for br1.

ftb_pft_addr_p2 is the fall-through address used when a slot's direction resolves not-taken.

The block's single jump field is placed in the lowest prediction slot carrying no valid conditional field. The jump is the block-terminating branch, so lowest-free-slot placement is program order.

ftb declares no FTQ index port. The cluster tracks the index positionally through the p0 to p2 pipeline.

ftb_hit_p2 and ftb_way_p2 are the carried writeWay scheme (IC-FTB-10): they are captured at predict and returned to the FTB on the update port as ftb_upd_hit_u0 and ftb_upd_way_u0, so the FTB does not re-look-up the tag. They travel through the FTQ; see section 7.

5.2 TAGE and ITTAGE
  tage_pred_rdy_p2    [NUM_PRED_SLOTS-1:0]        out
  tage_pred_meta_p2   tage_pred_meta_t per slot   out
  ittage_pred_rdy_p2  [NUM_PRED_SLOTS-1:0]        out
  ittage_pred_meta_p2 ittage_pred_meta_t per slot out

TAGE supplies direction: tage_pred_meta_t.tage_pred_tkn. ITTAGE supplies a target: ittage_pred_meta_t.ittage_prm_tgt or ittage_alt_tgt, selected by ittage_using_primary. ittage_hit clear means the FTB target stands.

THE FIELD HOLDS VA[40:1] AND THERE IS NO EXTENSION RULE. RULED session-073 (Jeff): IT_MAX_TGT_WIDTH is 40, so the field carries every bit of the target except bit 0, which is always zero on a 2-byte-granular ISA. The cluster reconstructs by appending that bit: {stored, 1'b0}. Nothing is inferred, so no rule can be wrong. TD#132 tracks the RTL.

WHY THE FIELD WIDENED. It was 38 bits, pinned session-070, with the missing bits 40:39 supplied by extension. No extension rule works. A V=1 fetch PC is a 41-bit guest physical address, zero extended, and sign extension corrupts any GPA with bit 38 set; but zero extension gives bits 40:39 = 00, and a V=0 Sv39 kernel address needs them set. Worse, a wrong entry is STICKY: the update writes back the same VA[38:1] the entry already holds, so no mispredict can correct it, and while it hits it overrides the FTB jump target. Kernel indirect branches stop being predicted at all.

The alternatives are in misc/prop1.md, which proposed supplying the two bits from the branch PC instead. That is free but makes one stored entry mean different targets under different lookup PCs, and needs a companion change in the FTQ update path to avoid training entries it cannot represent. Jeff ruled for storage: +2 bits x 2048 entries x the TWO PER-SLOT RAM COPIES = 8,192 bits in the ITTAGE array (measured by BP-111: 226,304 -> 234,496 bits), plus 4 bits per slot of FTQ metadata, in exchange for an entry that means one thing and no rule with an exception.

FE-19 still holds: predictor storage may mispredict where an architectural address may not. It permitted the narrow field; it did not require it.

Both metadata structs carry branch_id. Every p2 and p3 comparison is qualified by branch_id equal to the FTQ index held in the matching stage register, so a queued or back-pressured response cannot be compared against the wrong entry. The redirect logic therefore assumes no fixed predictor latency.

5.3 SC

sc consumes the TAGE p2 result directly:

  tage_pred_rdy_p2   in   from tage
  tage_pred_meta_p2  in   from tage

The TAGE p2 result fans out to both the FTQ boundary comparison and the sc input.

sc history and PC inputs, driven by the cluster:

  inp_pc_p2        [VA_WIDTH-1:1]     per slot   TD#91
  sc_phr_p2        [9:0]              scalar     TD#92
  sc_t1_idx_fh_p2  [SC_MAX_FH-1:0]    scalar
  sc_t2_idx_fh_p2  [SC_MAX_FH-1:0]    scalar
  sc_t3_idx_fh_p2  [SC_MAX_FH-1:0]    scalar

sc does not take bp_folded_hist_t. The cluster slices the three SC folds and the low 10 bits of tage_phr out of the struct and drives them as separate ports.

ALL FIVE are staged p0 to p2 by the cluster. The three folds were connected live to bp_history until BP-090; because bp_history advances whenever a branch is predicted, the live folds at p2 described history newer than the block SC was indexing. Same class of signal as the PC and the phr, same staging. TAGE and ITTAGE take bp_folded_hist_t whole at their own p0 request and stage internally; only SC takes sliced folds.

sc p3 output:

  sc_pred_rdy_p3   [NUM_PRED_SLOTS-1:0]     out
  sc_pred_meta_p3  sc_pred_meta_t per slot  out

sc_pred_meta_t.sc_pred_tkn is the final direction for the slot; sc_override records whether SC changed the TAGE direction.

5.4 RAS
  ras_tos_addr_p0     [VA_WIDTH-1:0]    per slot  out
  ras_tos_valid_p0    logic             per slot  out
  ras_pred_val_p2     logic             per slot  in
  ras_br_type_p2      bp_br_type_e      per slot  in
  ras_fall_through_p2 [VA_WIDTH-1:0]    per slot  in
  ras_pop_addr_p2     [VA_WIDTH-1:0]    per slot  out
  ras_pop_valid_p2    logic             per slot  out
  ras_snapshot_p2     bp_ras_snapshot_t per slot  out
  ras_pred_val_p3     logic             per slot  in
  ras_br_type_p3      bp_br_type_e      per slot  in
  ras_p2_keep         see ras_interfaces.md     in   BP-121

Since BP-121: ras_fall_through_p2 carries the call PC plus 2 or 4, not the FTB fall-through (TD#164); ras_pred_val_p3 is qualified by p3 reachability, not the registered p2 value (TD#166); and ras_p2_keep stops a squashed block at p2 from operating the RAS (D8). ras_interfaces.md is the home of each.

The top of stack is presented at p0. The push or pop executes at p2 once ras_br_type_p2 carries the FTB classification.

RETURN_CALL IS ONE OF THEM, session-069; BUILT BY BP-119 (TD#152 closed). Before BP-119, bp_br_type_e had seven names, the cluster's p2 classification tested is_ret first and never formed it, and 3'b111 trained the FTB as a plain jump and never the RAS. The specification, now met: bp_br_type_e gains RETURN_CALL at 3'b111 for the JALR whose rd and rs1 are both link registers and are unequal, which the specification makes a pop followed by a push (ras_decisions.md 2, dcd_decisions.md DCD-11). One enum per slot still suffices: the case is two operations on one instruction, not two classifications. The p3 pair takes the registered p2 classification.

ras_pc_p2 was declared and unread (TD#101); BP-126 removed it from ras.sv and the cluster.

RAS p2 operations are qualified by reachability across slots: a taken branch ends the block, so a later slot is off the predicted path and must not push or pop (FE-11). One snapshot per entry is therefore sufficient. ras_snapshot_p2[NUM_PRED_SLOTS-1] reaches the FTQ on section 4c.

Restore and commit ports, section 8.


6. Redirects

No predictor declares a redirect port. The inventory confirms this across all its ports of all eight modules: 140 at INFRA-011, 141 since session-071 added ubtb's blk_p1 (bpu_port_inventory.md Coverage). Session-072.

A redirect is derived at the cluster boundary by comparing a predictor's stage output against the prediction the cluster formed at p1 and carried forward in its own stage registers (FE-4). The cluster does not read the FTQ.

  bpu_redir_p2      bp_redirect_t [0:NUM_PRED_SLOTS-1]   NEW
  bpu_redir_idx_p2  [FTQ_IDX_BITS-1:0]                   NEW
  bpu_redir_p3      bp_redirect_t [0:NUM_PRED_SLOTS-1]   NEW
  bpu_redir_idx_p3  [FTQ_IDX_BITS-1:0]                   NEW

bp_redirect_t is the per-slot payload and carries target_pc and valid. The index is scalar and sits alongside the array, since both slots occupy one FTQ entry.

The group is named by STAGE, not by predictor. p2 carries the FTB, TAGE, ITTAGE, and RAS corrections; p3 carries the SC correction.

The comparison is expressed as one quantity, the slot successor address, rather than as a taken/target pair. Both the p1 and the p2 view are reduced to the address fetched after that slot, so two not-taken views compare equal and raise no redirect.

The p1 operand is formed at p1 from the p1 view only: the slot target when taken, the uBTB fall-through on a hit, the LOOKUP PC plus FTB_BLOCK_BYTES on a miss. A stale uBTB block boundary therefore redirects at p2 rather than letting the front end fetch past a boundary the FTB had already contradicted.

The p3 comparison is against the p2-corrected value, not the raw p1 prediction, so a p3 redirect fires only when SC changes the value the cluster published at p2.

SUCCESSORS ARE CHAINED FROM THE HIGHEST SLOT DOWN, at p1, p2 and p3. The last slot's not-taken successor is the block fall-through; every lower slot's not-taken successor is the next slot's successor. A slot after a taken slot is not reachable and raises no redirect (w_reach_p2, and the same at p3, where reachability uses the SC direction). This is fe_decisions.md 2.4 applied per slot: the first taken slot ends the block. BUILT by BP-121 (D5 at p2 and p3, D15 at p1). Before it a not-taken slot's successor was the block fall-through even when a later slot was taken, and an unreachable slot could redirect: stream errors in cross, deep and ftbonly.

A redirect from a later stage supersedes an earlier redirect for the same entry index and slot. Supersession does not cross slots.


7. Prediction metadata: BPU to FTQ

The FTQ slow path (bp_ftq_meta_t) holds the state each predictor needs to train and cannot recompute at resolution. It is written at prediction time and read once at resolution to form the updates of section 8.

Without this group the update path cannot work at all: tage_upd_inp_t embeds tage_pred_meta_t, ittage_upd_inp_t embeds ittage_pred_meta_t, and sc_upd_inp_t embeds sc_pred_meta_t. Those values exist only at predict time.

The metadata finalizes at two stages, so there are two write groups. Each writes a disjoint set of bp_ftq_meta_t members, so the FTQ never has to merge.

7.1 p2 write
  bpu_meta_val_p2                                      NEW
  bpu_meta_idx_p2     [FTQ_IDX_BITS-1:0]               NEW
  bpu_meta_tage_p2    tage_pred_meta_t
                        [0:NUM_PRED_SLOTS-1]           NEW
  bpu_meta_ittage_p2  ittage_pred_meta_t
                        [0:NUM_PRED_SLOTS-1]           NEW
  bpu_meta_lp_p2      lp_pred_t
                        [0:NUM_PRED_SLOTS-1]           NEW
  bpu_meta_ftb_p2     ftb_pred_meta_t
                        [0:NUM_PRED_SLOTS-1]           NEW

The FTB classification is NOT carried here. It travels on the slot correction group of section 4a, which writes it into the fast-path entry where section 7.2 reads it.

Writes the tage, ittage, lp and ftb members of bp_ftq_meta_t for the entry named by bpu_meta_idx_p2.

The TAGE and ITTAGE metadata are the predictor outputs passed through unchanged.

The loop predictor finalizes at p1, not p2. The cluster registers its p1 result and presents it in the p2 group so the FTQ performs one slow-path write per entry rather than two. The lp member of bp_ftq_meta_t is lp_pred_t, the same type loop_pred outputs, so the cluster passes the registered result through unchanged. TD#106 retired bp_loop_meta_t, which carried the same thirteen fields in a different order; the cluster's field-by-field map went with it. See section 10, item 9.

Every slot carries its own loop snapshot. The zero drive that covered slots above 0 before the loop predictor was per-slot is gone (BP-091).

7.2 p3 write
  bpu_meta_val_p3                                      NEW
  bpu_meta_idx_p3     [FTQ_IDX_BITS-1:0]               NEW
  bpu_meta_sc_p3      sc_pred_meta_t
                        [0:NUM_PRED_SLOTS-1]           NEW

Writes the sc member of bp_ftq_meta_t for the entry named by bpu_meta_idx_p3. This is the SC predictor output passed through unchanged.

bpu_meta_val_p3 is asserted whether or not SC is enabled, so the entry's slow path is always complete. When SC is disabled the written value carries no prediction and the FTQ forms no SC update.

7.3 FTB metadata

bp_ftq_meta_t carries an ftb member of type ftb_pred_meta_t, holding the FTB state the update path needs:

  hit                              tag hit at predict
  way   [FTB_WAY_BITS-1:0]         hit way, or the PLRU victim
  jmp_pos [FTB_BR_POS_BITS-1:0]    jump field in-block position

The FTB determines the hit result and the write way at the prediction read and does not re-look-up the tag at update (IC-FTB-10). The FTQ returns them on ftb_upd_hit_u0 and ftb_upd_way_u0.

These are scalar within the entry, not per slot: the FTB indexes one entry per lookup and both slots come from it. bp_ftq_meta_t is carried per slot, so the cluster writes the same values to every slot's copy.

7.4 In-block positions

The per-branch in-block position lives in bp_ftq_slot_t.pos, in the fast-path entry, sourced from ftb_br0_pos_p2 and ftb_br1_pos_p2 and delivered on the section 4a slot correction group. Until that group existed no port carried either signal out of the cluster and this paragraph described something unbuildable (TD-FE-6). The FTQ uses it to locate the branch in the fetch bundle. NOT to order br0 against br1: br0 is always the earlier branch by fill order (ftb_decisions.md 4, IC-FTB-16). This read "to order br0 against br1". Session-070. It is used to locate the taken branch in the fetch bundle (IC-FTB-15), and returns the resolving branch's position on ftb_upd_pos_u0.

Locating a branch in the fetch bundle is every-cycle work, so the position belongs on the fast path rather than in the update-only metadata. The jump field's position travels in the metadata group (7.3), since it is one value per entry rather than one per slot.

The uBTB also produces a position on ubtb_pred_t.pos, so the p1 prediction can fill bp_ftq_slot_t.pos before the FTB result arrives.

The position addresses two-byte slots: FTB_BR_POS_BITS is $clog2(FTB_BLOCK_BYTES/2), so a 32-byte block has sixteen positions. RVA23 mandates the C extension, so a branch may begin at any 2-byte boundary and the position must resolve that. The cluster also uses the position to form the branch PC it reports to bp_history, block START plus position times two (BP-092a, section 9).

EVERY POSITION ON THESE PORTS IS MEASURED FROM THE BLOCK START. The FTB and the uBTB store positions relative to the 32-byte-aligned region and convert at their own boundary (ftb_decisions.md 4.6), so pos here, in bp_ftq_slot_t and on ftb_upd_pos_u0 is always start-relative. bp_cluster.sv forms the branch PC from the ALIGNED base, which is wrong for any block not starting on a 32-byte boundary; TD#125. This read "block base". Session-071.

7.5 Fields with no consumer

ftb_br0_conf_p2, ftb_br1_conf_p2 and ftb_fastpath_p2 are FTB outputs that no port in this specification carries. The confidence values are exposed for observability, and the fast-path bypass is not yet built at the cluster. They are recorded here so a reader does not mistake their absence for an omission.


8. Updates: FTQ to BPU

One update channel per prediction slot. The FTQ reads bp_ftq_meta_t at resolution and forms the per-predictor update payloads from bp_update_t, the resolved-branch record.

BUILT BY BP-119 (TD#151, TD#150 closed). The payloads are formed by ftq_upd_conv, a module inside the FTQ instantiated by ftq.sv (ruled session-075), so the FTQ's ports are the ones this section lists. Every payload field has a source in bp_update_t, bp_ftq_meta_t or the fast-path entry; BP-119 found none missing. The FTQ also takes sc_enable (FE-20).

Handshake. A slot's update is accepted when every predictor it trains is ready; no predictor is given a partial update. The cluster's readies are per slot and ANDed per predictor. The SC- disabled rule is unchanged.

THE SC READY IS THE SC UPDATE QUEUE'S ROOM, since BP-126 (TD#123, P-3, confirmed session-077): sc_upd_rdy is the queue's room and sc_enable, and an update the queue accepts waits there for the arbiter's grant (bp_arb_spec.md 4.5, 5.5). Until BP-126 the SC ready was the arbiter's grant and depended on the SC valid, so the FTQ presented the SC valid before it saw the ready (BP-119); that dependence is gone.

The FTB update path through ftq_ftb_sched is unchanged and is not gated by the other predictors' readies, so a resolution held for a predictor was trained into the FTB again when it was presented again (TD#157). FIXED BY BP-120: ftq_resolve keeps one flag per channel, keyed by the branch's entry index and position, set when the scheduler takes the FTB update of a resolution not yet accepted, so it is presented to the FTB once. Gating the FTB valid without state would loop through the SC grant and the scheduler's ready. A low-value update the scheduler takes and drops (FE-5a) counts as taken. MEASURED: loops 51 -> 58 mispredicts; the repeated trainings had been stepping the FTB confidence extra times.

Predictor Valid port Payload port Ready port
ubtb in ubtb_upd_t ubtb_upd_u0 none
loop_pred upd_valid_p0 upd_p0 none
ftb ftb_upd_valid_u0 15 flat ports none
tage tage_upd_val_u0 tage_upd_inp_u0 tage_upd_rdy
ittage ittage_upd_val_u0 ittage_upd_inp_u0 ittage_upd_rdy
sc sc_upd_val_u0 sc_upd_inp_u0 sc_upd_rdy
ras ras_commit_val 3 commit ports none
Notes:
- ubtb carries the valid inside `ubtb_upd_t.valid`; it has no
  separate valid port. The cluster port is ubtb_upd_u0; the ubtb
  module port it drives is upd_u0. This row read upd_u0 (DOC-002, D4).
- The ittage payload port is ittage_upd_inp_u0. This row read
  ittage_upd_inp (DOC-002, D2).
- loop_pred update ports carry a p0 suffix, not u0. They are
  per-slot as of BP-091, at both the module and the cluster
  boundary (`lp_upd_valid_p0`, `lp_upd_p0`).
- ftb update is 15 flat ports: ftb_upd_pc_u0, ftb_upd_hit_u0,
  ftb_upd_way_u0, ftb_upd_is_br_u0, ftb_upd_br_idx_u0,
  ftb_upd_taken_u0, ftb_upd_target_u0, ftb_upd_pos_u0,
  ftb_upd_is_jmp_u0, ftb_upd_jmp_target_u0, ftb_upd_is_call_u0,
  ftb_upd_is_ret_u0, ftb_upd_is_jalr_u0, ftb_upd_jmp_rvc_u0,
  ftb_upd_pft_addr_u0. ftb_upd_jmp_rvc_u0 was added by BP-121
  (TD#164), with ftb_upd_t.jmp_rvc. This read 14.
- ras update is the commit group: ras_commit_val,
  ras_commit_br_type, ras_commit_ret_addr, ras_commit_snapshot.
- ftb and ras have no slot dimension on their update ports.
- The ready ports are per slot. tage_upd_rdy_u1 and sc_upd_rdy_u1
  also exist; they are "update applied" flops (tage_interfaces.md),
  not accept readies. Corrected by BP-119.

The uBTB and FTB update field sets mirror each other, so one set of resolved facts forms both.

ubtb_upd_t carries no br_type field. The cluster rederives the resolved type from the payload's own is_br / is_jmp / is_call / is_ret / is_jalr bits, in the same arm order as ubtb.sv and the FTB classification, with is_br outranking is_jmp. A missing br_type read resolves to zero, which decodes as COND, so restoring the field instead of rederiving the type would silently classify every update as conditional and stop ITTAGE ever being updated.

Update fan-out by resolved br_type is fe_decisions.md 7.2. FOUR encodings that table does not list, not three. Three follow from what each predictor does: NO_BRANCH forms no update; DIRECT_CALL pushes RAS and updates uBTB and FTB; INDIRECT_CALL updates ITTAGE for the target and RAS for the return address. The fourth, RETURN_CALL at 3'b111, was added session-069 for the JALR that pops then pushes (ras_decisions.md 2, dcd_decisions.md DCD-11a) and its fan-out is NOT determined -- fe_decisions.md FE-U9. An earlier revision said "three encodings", written before the enum went to eight. Corrected session-070.

Each queued predictor's update valid is additionally qualified by its own queue ready, so no update is presented to a full queue. The FTQ holds the update until it is accepted.

Queue status ports, driven out of the cluster:

  tage    tage_pq_not_full, tage_upd_rdy, tage_upd_rdy_u1
  ittage  ittage_pq_not_full, ittage_upd_rdy, ittage_upd_rdy_u1
  sc      sc_uq_not_full, sc_upd_rdy, sc_upd_rdy_u1

Since BP-126 the cluster's sc_uq_not_full is the SC update queue's room with the one-cycle starvation hold, and sc_upd_rdy the queue's room (bp_arb_spec.md 4.5).

tage.sv and ittage.sv declare <pred>_pq_not_full and <pred>_uq_not_full since BP-132 applied TD#49. bp_cluster connects <pred>_uq_not_full to its own ports tage_upd_rdy and ittage_upd_rdy, which keep those names (ruled, Jeff, session-078), so the rows above are the cluster's names. This paragraph read that tage and ittage declare unprefixed pq_not_full and upd_rdy, with TD#49 not applied (DOC-002, D3). Session-080.

RAS restore, driven on redirect from the snapshot in the entry being corrected:

  ras_restore_val
  ras_restore_snapshot  bp_ras_snapshot_t

RAS flush ports ras_flush_val and ras_flush_snapshot are declared and READ BY NOTHING. They are redundant with the restore group above, which is the RAS response to a flush and to every other redirect (ras_decisions.md 4.4, CLOSED). Their presence is not an open design question; see 4.4.2 before raising one.


9. History checkpoint and rollback

The checkpoint is the GHR and PHR circular-buffer pointer pair, one per FTQ entry, held in the FTQ entry (FE-7). bp_history advances the pointers and rolls back by index.

bp_history carries no stage suffix on any port.

Driven by the cluster at p1, from the formed prediction:

  pred_taken    [NUM_PRED_SLOTS-1:0]          bit n = branch n
  pred_pc       [VA_WIDTH-1:0] [NUM_PRED_SLOTS]
                                              one per branch, after
                                              compaction
  num_branches  [PRED_CNT_BITS-1:0]           count, 0 to
                                              NUM_PRED_SLOTS

Sized by NUM_PRED_SLOTS since BP-129 (session-078); at two slots they are the former [1:0], [2] and [1:0].

bp_history indexes these by BRANCH NUMBER, not by slot number, so the cluster compacts the valid slots down before presenting them. A bundle whose only branch sits in slot 1 presents that branch at index 0.

pred_pc is the BRANCH PC, not the prediction block PC: the block START plus that branch's in-block position, TWO bytes per position (section 7.4). bp_history folds bits [3] and [2] of it into the PHR path bit. The block PC would make the path bit nearly constant, because a block start moves only when the block boundary moves. AN EARLIER REVISION gave the reason as "most block starts are fall-throughs from a 32-byte-aligned predecessor and carry 2'b00 there". Blocks are unaligned (ftq_decisions.md 4.7, ifu_decisions.md IFU-6), so a fall-through inherits its predecessor's low bits, and even from an aligned start the fall-through is 2'b00 there only when the block length is a multiple of 16 bytes. Corrected session-070, matching bp_history_decisions.md 3.2 and bp_history_interfaces.md Producer obligations. The branch PC varies by construction. See bp_history_interfaces.md, Producer obligations, and BP-092a.

Checkpoint write, at allocation:

  ckpt_wr_en                          driven at p1 allocation
  ckpt_wr_idx  [FTQ_IDX_BITS-1:0]     FTQ index

Rollback, on redirect. These are bp_history's own ports, inside the cluster:

  rollback_valid
  rollback_ckpt_idx  [FTQ_IDX_BITS-1:0]

Driven from the derived redirect and from the FTQ. When both stages redirect in the same cycle the p3 index wins, matching the supersession rule.

At the CLUSTER BOUNDARY the FTQ drives the rollback directly (TD-FE-7, added by BP-102):

  ftq_rollback_val
  ftq_rollback_idx   [FTQ_IDX_BITS-1:0]
  w_rollback_valid    = ftq_rollback_val
                      | w_any_redir_p2 | w_any_redir_p3;
  w_rollback_ckpt_idx = ftq_rollback_val ? ftq_rollback_idx
                      : (w_any_redir_p3 ? r_idx_p3 : r_idx_p2);

The FTQ arm outranks both cluster arms unconditionally: an architectural correction outranks a speculative one, so FE-3 does not decide this winner. FE-3 still orders p3 over p2 between themselves. The FTQ presents the INDEX of the entry whose end-of-block pointer state is to be restored, not the pointer values (ftq_decisions.md 3.2, ftq_backend_interfaces.md 8).

HISTORY CORRECTION, BP-121 (D14). RULED session-075 (Jeff, BP-121 decision 8), replacing bp_history_decisions.md 3.5. The rollback also carries a correction. As built (BP-121; declarations reported by BP-122):

  input logic                      ftq_rollback_corr
      -- the rollback carries a corrected bundle (backend
         RC_MISPREDICT with _self clear only)
  input logic [RB_CNT_BITS-1:0]    ftq_rollback_n
      -- number of bundle bits, 0 to 2
  input logic [RB_CORR_BITS-1:0]   ftq_rollback_tkn
      -- direction of each bit, bit 0 oldest: slots before the named
         one 0, the named one its resolved direction
  input logic [RB_CORR_BITS-1:0]   ftq_rollback_pbit
      -- path bit (pc[2] ^ pc[3]) of each branch in the bundle
  input logic [NUM_PRED_SLOTS-1:0] ftq_rollback_slot_ex
      -- slot s of the rollback entry is a conditional the backend
         mispredict executed (BP-122, for the loop predictor)
  input logic [NUM_PRED_SLOTS-1:0] ftq_rollback_slot_tkn
      -- its resolved direction (BP-122)

ftq_npc drives them for a backend redirect, from bkend_ftq_redir_pos and bkend_ftq_redir_taken (ftq_backend_interfaces.md 5); the cluster forms the same correction for its own p2 and p3 redirects, and muxes one or the other onto bp_history's rollback_corr/_n/_tkn/_pbit (bp_history_interfaces.md). bp_history restores to the named bundle's first bit, writes the corrected bits and rewrites that entry's checkpoint. The two slot inputs drive the loop predictor's restore (loop_pred_interfaces.md). The ftq top and ftq_npc drive all six; fe_top has no port change.

THE CORRECTION IS AT MOST TWO BITS at either slot count (Jeff, session-078; built by BP-130): at most one not-taken bit for a slot of the entry before the named position, then the named branch's bit. RB_CORR_BITS = 2 and RB_CNT_BITS = 2 are bp_defines_pkg's, fixed, not derived from NUM_PRED_SLOTS. At one slot a backend mispredict of a branch held in no slot carries slot 0's not-taken bit and its own. Since BP-139 such a branch is one the FTB did not report at p2 (a reported one ends the block, option A). The cluster's p2 / p3 corrections are at most NUM_PRED_SLOTS bits and are zero-extended to RB_CORR_BITS in its mux. ftq_rollback_slot_ex / _slot_tkn stay NUM_PRED_SLOTS. BP-129 had sized the three bundle ports by NUM_PRED_SLOTS and limited the correction to NUM_PRED_SLOTS bits, provisionally; BP-130 replaced that.

A rollback SUPPRESSES the checkpoint write in the same cycle: bp_history writes the checkpoint from its normal-update branch, which the rollback branch replaces. An FTQ rollback landing in the same cycle as a p1 allocation therefore drops that allocation's checkpoint write, which is consistent -- the redirect discards that block anyway.

Outputs:

  ghist_ptr       [GHIST_PTR_BITS-1:0]   current pointer
  phist_ptr       [PHIST_PTR_BITS-1:0]   current pointer
  ckpt_ghist_ptr  [GHIST_PTR_BITS-1:0]   checkpoint read
  ckpt_phist_ptr  [PHIST_PTR_BITS-1:0]   checkpoint read
  ghr_buf         [GHR_WIDTH-1:0]
  phr_buf         [PHR_WIDTH-1:0]
  folded          bp_folded_hist_t

ckpt_ghist_ptr and ckpt_phist_ptr are the pointer pair the FTQ writes into the allocated entry as that entry's checkpoint.

folded drives tage.folded_hist and ittage.folded_hist whole. sc takes sliced fields instead (section 5.3).


10. Package and document corrections required

The RTL is the reference. These are the changes other files need to match it and to match this specification.

bp_structs_pkg.sv
  1. bp_ftq_meta_t is carried per slot. The array is declared at the port, not inside the struct, per the bp_update_t convention.

  2. CLOSED, verified session-070. bp_redirect_t s2/s3 comments to p2/p3. bp_structs_pkg.sv contains no s2 or s3 label.

  3. CLOSED, verified session-070. branch_id commented "FTQ slot index". The package contains no such string; every branch_id comment reads "FTQ entry index". This was TD-FE-5, which fe_decisions.md 13 also still listed open.

  4. CLOSED, verified session-070. The uBTB index and tag comments read PC[26:7], the retired instruction-granularity indexing. No such comment remains.

  5. CLOSED, verified session-070. ubtb_pred_t.carry commented as a slot-target property. It now reads "entry fall-through".

fe_decisions.md
  1. CLOSED, PA-direct correction, session-064. Section 2.2 and section 9 placed the RAS top of stack at p1. ras.sv declares ras_tos_addr_p0 and ras_tos_valid_p0, at p0. Both corrected, and the section 1 stage list updated to match.

  2. CLOSED, PA-direct correction, session-064. Section 3.1 named redirect signals <pred>_redir_val_<pN> and <pred>_redir_tgt_<pN>, reading as a per-predictor port group. No predictor declares a redirect port. Rewritten to the cluster-derived, stage-named group of section 6, with FE-4 restated and FE-12 added.

Open items
  1. CLOSED, TD#92, BP-090. SC index fold staging. inp_pc_p2 and sc_phr_p2 were staged p0 to p2 while the three SC index folds were connected live to bp_history, which advances whenever a branch is predicted, so at p2 the live folds described a later block than the one SC was indexing. All three folds are now staged the same way as the PC and the phr. Section 5.3 records it; bp_arb_spec.md 6.1 names them among the staged inputs.

  2. CLOSED, TD#106, BP-092. lp_pred_t and bp_loop_meta_t carried the same field set under two spellings (lp_past_itr against lp_pst_itr, lp_curr_itr against lp_cur_itr) and the cluster mapped between them for the section 7.1 write. lp_pred_t survives, for consistency with the other predictor prediction types. bp_loop_meta_t is deleted from bp_structs_pkg.sv, the lp member of bp_ftq_meta_t is lp_pred_t, and the cluster's lp_to_meta() is deleted rather than rewritten. The two retired spellings disappear with the type.

  3. CLOSED, verified session-070: ftb_pred_meta_t is in bp_structs_pkg.sv. bp_ftq_meta_t gains an ftb member of a new type ftb_pred_meta_t (hit, way, jmp_pos), so the FTB carried writeWay state travels inside the struct like every other predictor's state (section 7.3).

  4. CLOSED, verified session-070: bp_structs_pkg.sv declares logic [FTB_BR_POS_BITS-1:0] pos; in bp_ftq_slot_t. bp_ftq_slot_t gains a pos field of FTB_BR_POS_BITS, the in-block instruction position of that slot's branch (section 7.4).

    Items 2, 3, 4, 5, 10 and 11 were all applied to the package and were still listed here as required. Item 1 was NOT verified session-070 and stays open.

  5. CLOSED, 2026-08-19. bp_ftq_entry_t gains a pft_addr field of VA_WIDTH, block scalar, holding the value delivered on bpu_pred_pft_p1. Applied to bp_structs_pkg.sv and checked in tb_bp_pkg.sv. Entry width 182b -> 222b AT THE TIME. It is now 228b after the BP-099 position widening and VA_WIDTH 41; ftq_entry_formats.md 1 is the sole home. Session-072.

  6. CLOSED, 2026-08-19. bp_cluster.sv gains the section 4a slot correction group, six ports, driven from the p2 classification, the FTB positions and the p2 target selection, plus a p3 stage register carrying the slot with the SC direction applied. tb_bp_cluster group I, 24 checks. sim_bp_cluster 973 -> 997, all 47 targets green. An earlier draft of this item proposed a narrower bpu_meta_brtype_p2; it carried the type but not the position, and left section 7.4 unbuildable.

  7. DEFERRED, not blocking. bp_ftq_meta_t becomes the two-arm packed union of ftq_entry_formats.md 3.1. It is a storage optimization only, 421b -> 278b per slot (this read "420b -> 277b"; ftq_entry_formats.md 3.1 is the owner and the figures moved when jmp_pos widened. Session-070). tb_bp_cluster group F3 proves that the p2 and p3 write groups touch DISJOINT members of the struct; under the union that holds only within u.cond, since sc and ittage alias, so F3 must be restated per arm when the union lands.

loop_pred
  1. CLOSED, TD#105, BP-091. loop_pred.sv was single-slot; no port carried a slot dimension. It is now per-slot on pred_pc_p0, pred_valid_p0, pred_p1, upd_p0 and upd_valid_p0, with per-slot table banks (TI6), and the pred_p0 to pred_p1 rename is applied. loop_pred.sv, tb_loop_pred.sv, loop_pred_interfaces.md and the bp_cluster instantiation were all updated. The cluster boundary ports lp_upd_valid_p0 and lp_upd_p0 gained the slot dimension in the same task.
bp_history
  1. CLOSED, BP-129 (session-078). bp_history's prediction ports are sized by NUM_PRED_SLOTS and PRED_CNT_BITS; the correction ports are RB_CORR_BITS / RB_CNT_BITS (BP-130). It read: bp_history uses literal [1:0] and [2] where other modules use NUM_PRED_SLOTS, deferred, INFRA-011.

  2. CLOSED, BP-126 (TD#102). bp_history generates the IT5 folds, in the rollback recompute and both steps, as for IT1 to IT4. It read: bp_history does not generate the ITTAGE IT5 folds; ittage.sv wires it_t5_idx_fh, tag_fh1 and tag_fh2 to outputs that are never driven, so IT5 indexes on PC alone.


11. Document history

  2026-08-02  Created, session-063. Written from fe_decisions.md,
              bpu_port_inventory.md (INFRA-011), and
              bp_structs_pkg.sv. Predictor ports named as declared;
              no renaming proposed. Redirect group named by stage,
              since no predictor declares a redirect port. RAS top
              of stack at p0 per ras.sv. Checkpoint held in the FTQ
              entry; bp_history rolls back by index. loop_pred
              described dual-slot per TD#105. bp_redirect_t arrayed
              per slot with ftq_idx removed. bp_ftq_slot_t defined.

  2026-08-02  Section 7 added: the prediction metadata write groups
              at p2 and p3, the FTB carried hit and way, and the
              in-block positions. Sections 8 through 11 renumbered.
              Section 4 updated for the reshaped uBTB interface
              (blk_p1, entry-scoped hit). Section 5 updated with the
              branch_id match rule, the jump slot placement rule and
              the RAS reachability rule. Section 6 updated with the
              successor-address comparison and the p3 comparison
              basis. Corrections 8 through 11 opened.

  2026-08-09  session-064. Section 9 pred_pc corrected:
              it is one value per BRANCH after compaction, not one
              per slot, and it is the branch PC rather than the
              fetch block PC (BP-092a). Section 10 items 6, 7, 8 and
              12 closed: the fe_decisions.md RAS-stage and
              redirect-port corrections were applied by this task,
              the SC index folds were staged by BP-090, and the
              loop_pred dual-slot retrofit landed in BP-091. Item 14
              opened for the IT5 fold gap (TD#102). Section 2, 3, 4,
              5.3, 7.1, 7.4 and 8 updated to the post-BP-091,
              post-BP-092 RTL: loop_pred per-slot throughout, the
              slot-0 exception removed from the p1 mux, the SC folds
              described as staged, the uBTB update br_type rederived
              rather than carried, and the position granularity
              stated.
  2026-08-19  Section 4a added: the p2 and p3 slot correction
              groups, delivered in bp_cluster.sv. They carry the FTB
              classification and the in-block positions into the
              fast-path entry on every prediction, not only when a
              redirect fires. Section 7.4 was describing a path no
              port provided; it is now buildable. Item 16 closed,
              item 17 opened and deferred (TD-FE-6, TD-FE-2).

  2026-08-19  Section 4 records that the FTQ stores the p1
              fall-through in bp_ftq_entry_t.pft_addr; section 10
              item 15 opened and closed for the field addition.

  2026-08-20  Section 9 gains the CLUSTER BOUNDARY rollback group,
              ftq_rollback_val / ftq_rollback_idx, added by BP-102
              and closing TD-FE-7. The priority rule and the
              same-cycle checkpoint-write suppression are recorded
              with it. The ports already listed in section 9 were
              bp_history's own, inside the cluster; that is now
              stated rather than implied.

  2026-08-21  BP-107 results. Section 4: bp_ftq_entry_t.pft_addr is
              a p1 value that NO later port can correct, because the
              4a groups carry bp_ftq_slot_t and pft_addr is a block
              scalar. On a uBTB miss it is the full block end, which
              breaks both the RAS return address (ras_decisions.md 8)
              and the not-taken successor. The fix belongs in the p2
              group, not in a new entry field. Section 4b added: no
              p1 port carries the block start PC, so the FTQ stages
              its own request to write its own entry.

  2026-08-21  Section 9 said FOUR bytes per position while section
              7.4 of this same file said two. POS_OFFSET_BITS is 1;
              two is correct, stale by BP-099. Section 9's claim
              that bp_history folds pred_pc[3] and [2] is
              unaffected -- that is a fact about pred_pc, not about
              the multiplier -- but the pos-relative identity it
              implies changes; see PROJECT_STATUS, bp_history
              decomposition.
              Also: three citations of INFRA-012, in section 10
              items 6 and 7 and in this history, were a label
              attached retroactively to the session-064 PA-direct
              corrections. No such task was ever generated or run.
              Corrected; INFRA-012 remains free.

  2026-09-19  session-071. Section 4c added: bpu_blk_val_p2,
              bpu_blk_idx_p2 and bpu_blk_ras_p2 carry the
              post-operation RAS snapshot for every valid p2 block,
              closing the port gap flagged session-070 (ruled,
              Jeff). bpu_pred_ras_p1 is initialise-only. The p3
              repair is recorded as open. 7.4 and section 9: the
              branch PC is block START plus position, and every
              position on a port is start-relative (TD#125).
              "Fetch block" replaced by "prediction block".

  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. E23: 4a now precedes 4b and 4b is an H2
              like its siblings.

  2026-10-06  session-075. 4c gains bpu_blk_pft_p2, the TD#113
              fix, ruled (Jeff): the not-taken term of the cluster's
              own p2 successor, written into pft_addr for every
              valid p2 block. Section 4 points to it. Unbuilt;
              BP-118.

  2026-10-07  session-075, rulings (Jeff). Section 4: the loop
              predictor overrides only a slot the uBTB supplied.
              4c: the p3 RAS repair deferred as TD#149.

  2026-10-07  session-075, after BP-118. 4c built, RAS half
              included, which this file described as built and was
              not; four readers of pft_addr named. Section 4: the
              loop rule was violated and is fixed. 5.4: RETURN_CALL
              is not in the enum as built, TD#152. Section 8: the
              payloads are not formed, TD#151, and the ruling for
              where.

  2026-10-07  session-075, after BP-119. 5.4: RETURN_CALL built.
              Section 8: ftq_upd_conv built; the handshake and the
              SC grant stated; Ready column corrected to the
              accept readies; the FTB double-training defect
              recorded, TD#157.

  2026-10-08  session-075, after BP-120. Section 8: TD#157 fixed and
              measured. 4a: the p3 write erases the p1 slots when
              the FTB missed, TD#161.

  2026-10-08  session-076, PA-direct correction recording BP-121.
              4a: bpu_slot_val_p3 gated on the FTB answer, TD#161
              closed (D1, D2). 4c: TD#149 measured; the p2
              fall-through of a jump block is the jump PC plus 2 or
              4 (D3). 6: successors chained from the highest slot,
              no redirect from an unreachable slot (D5, D15). 8:
              15 FTB update ports. 9: the history correction ports
              (D14), widths open. 5.1, 5.4: ftb_jmp_rvc_p2 and the
              RAS port changes noted.

  2026-10-09  session-076, recording BP-122. 4c: w_pft_p2 as built.
              9: the correction ports declared; the loop predictor's
              rollback slot bits added.

  2026-10-10  session-077, after BP-126. 5.4: ras_pc_p2 removed
              (TD#101). 8: the SC ready is the SC update queue's room,
              not the grant (TD#123, P-3); the cluster's
              sc_uq_not_full includes the queue full. 10 item 14
              closed (TD#102).

  2026-10-12  session-078, after BP-128 to BP-130. 9: the
              bp_history prediction ports sized by NUM_PRED_SLOTS
              (BP-129); the correction ports RB_CNT_BITS /
              RB_CORR_BITS and the correction at most two bits at
              either slot count (ruled, built by BP-130). 10 item 13
              closed.

  2026-10-15  session-080, after BP-137. 3: the FTQ holds its
              request on the three RAM init readies.

  2026-10-15  session-080, after DOC-002. 8: ubtb_upd_u0 and
              ittage_upd_inp_u0 in the update table; the queue status
              names as BP-132 built them.

  2026-10-17  session-081, after BP-138. 4c: w_pft_p2 is the jump PC
              when the jump is in no slot (D1).

  2026-10-19  session-081, after BP-139. 4c: w_pft_p2 is the PC of the
              first branch no slot carries (option A). 9: the
              unslotted branch is one the FTB did not report.
ftq_ifu_interfaces.md

planning/interfaces/ftq_ifu_interfaces.md on GitHub

FTQ to IFU Interface

 FILE:    ftq_ifu_interfaces.md
 SOURCE:  ftq_decisions.md, ftq_entry_formats.md, ftb_decisions.md,
          bp_defines_pkg.sv, ia_context/background/xs_ifu_ftq.md
 STATUS:  DRAFT
 UPDATED: 2026-10-09
 CONTACT: Jeff Nye

The second of the FTQ's four interfaces. BOTH SIDES ARE BUILT: the FTQ half is ftq_ifu.sv (BP-107, ftq_decisions.md 7.1) and the IFU half is rtl/core/frontend/ifu (BP-116). The RTL is the reference for the declared names. THE "NEW" TAG ON THE PORT ROWS IS HISTORICAL: it marked a port not yet declared on the IFU side, and none is now. The session-074 rulings on this boundary, the predecode flush at K+1 (7 W3) and the widened M1 (6), are built by BP-117 (TD#146).

This read that the IFU side did not exist and that rtl/core/frontend/ifu/rtl held only a .gitkeep, which was true until BP-116; session-075. Before that it read that no module on either side existed, true until BP-106/107; session-072.

Where this file departs from the XiangShan Kunminghu contract translated in ia_context/background/xs_ifu_ftq.md, section 9 says why.


1. Scope

Covered: - the fetch request, FTQ to IFU - the flush and resteer path, FTQ to IFU - the predecode writeback, IFU to FTQ - the entry fields the writeback adds to bp_ftq_entry_t

Not covered:
- IFU internals, the ICache, the ITLB
- the IFU to IBuffer path, which does not return to the FTQ
- EXE to FTQ resolution -- ftq_backend_interfaces.md. This read
  "still unspecified"; that document exists. Session-070.
- whether the FTQ drives the ICache directly; see section 8

2. Naming

Predictor-facing ports carry a pipeline-stage suffix. This document has no stage suffixes. That is a choice, not a gap: the IFU pipeline IS defined, F0 to F3 plus WB (ifu_decisions.md IFU-9), and this text read "The IFU pipeline is not defined". Session-070. Ports are named by direction:

  ftq_ifu_<signal>    FTQ  -> IFU
  ifu_ftq_<signal>    IFU  -> FTQ

If the suffixes are ever added here, record the rename here. This is a deliberate deviation, not an oversight.


3. Block sizes and granularity

Three sizes are in play and must not be collapsed.

  FTB_BLOCK_BYTES    32   the PREDICTION block. One FTQ entry
                          describes exactly one of these.
  FETCH_BLOCK_BYTES  64   the FETCH block: the unit the IFU reads
                          from the L1I, one cache line
                          (fe_decisions.md Conventions).
  FTB_BR_POS_BITS     4   in-block position, 2-byte granular, so
                          sixteen positions per prediction block.

bp_defines_pkg.sv, in the comment above FTB_BLOCK_BYTES, states that the 32 and the 64 must not be collapsed. This interface names the 32-byte prediction block: one request, one FTQ index, one entry, at most one request per cycle. The IFU reads the 64-byte line holding the block and extracts the block from it (ifu_decisions.md IFU-7, TD-IFU-7). Serving two sequential requests from one held line is IFU-internal and not visible here.

DELIVERING TWO PREDICTION BLOCKS PER CYCLE IS NOT IFU-INTERNAL. It needs two requests per cycle from the FTQ and reopens this interface; section 8, item 2. This paragraph called coalescing "an IFU-internal optimization" without that distinction, cited item 1 for it, and cited bp_defines_pkg.sv by a line number that had moved. Session-071.

GRANULARITY. Predecode and the predictor now agree. Both resolve 2-byte positions, so a predecode position and a predictor position are the same quantity and convert without loss. Until 2026-08-19 the predictor was 4-byte granular and the two differed; the two widths below are kept as separate names because they are derived from different things, not because they hold different values.

  FTQ_PD_WIDTH     FTB_BLOCK_BYTES / 2      = 16  predecode slots
  FTQ_PD_POS_BITS  $clog2(FTQ_PD_WIDTH)     =  4  predecode position
  FTB_BR_POS_BITS                           =  4  predictor position

Both are 4 bits and the conversion is the identity. FTQ_PD_WIDTH is derived from the block size and the RVC instruction granularity; FTB_BR_POS_BITS is derived from the block size and the predictor's position granularity. They coincide at the shipped geometry and a change to either must be checked against the other. Section 7 states where each is used.

Every position on this interface is measured from the BLOCK START: position 0 is the first halfword of the block. The FTB and the uBTB store positions relative to the 32-byte-aligned region, one bit wider, and convert at their own boundary, so no port anywhere carries the stored form (ftb_decisions.md 4.6). Session-071.


4. Fetch request: FTQ to IFU

Decoupled. The FTQ presents a request; the IFU accepts when its first stage is free and the ICache can take the access.

THERE ARE TWO REQUEST GROUPS, NOT ONE. The IFU runs translation as a pipeline ahead of fetch (ifu_decisions.md IFU-23a). Section 4.1 is the translation request, driven by xlate_ptr. This section is the fetch request, driven by fetch_ptr. The same entry is presented twice, on the translation port first and the fetch port later, and the two are independently flow controlled.

  ftq_ifu_req_val                              NEW
  ftq_ifu_req_rdy                              NEW   IFU -> FTQ
  ftq_ifu_start_pc    [VA_WIDTH-1:0]           NEW
  ftq_ifu_next_pc     [VA_WIDTH-1:0]           NEW
  ftq_ifu_idx         [FTQ_IDX_BITS-1:0]       NEW
  ftq_ifu_taken_val                            NEW
  ftq_ifu_taken_pos   [FTB_BR_POS_BITS-1:0]    NEW
  ftq_ifu_gen                                  NEW   TD-FE-8
  ftq_ifu_commit_ptr  [FTQ_IDX_BITS-1:0]       NEW   IFU-22

A request on this port is issued only for an entry whose translation has already been presented on 4.1. The FTQ does not enforce that; it follows from FQ-1, fetch_ptr <= xlate_ptr.

ftq_ifu_start_pc is bp_ftq_entry_t.pc, the block start.

ftq_ifu_next_pc is the block successor, selected across the slots by fe_decisions.md 2.4: the first taken slot's target, or bp_ftq_entry_t.pft_addr when no slot is taken. The IFU does not recompute it. It exists so the IFU knows where the block ends without reading the prediction, and so a prefetcher can walk ahead.

ftq_ifu_taken_val and ftq_ifu_taken_pos name the predicted taken branch, so the IFU truncates the bundle there and does not present instructions after it. Not valid means fetch the whole block.

ftq_ifu_gen is an OPAQUE TAG. The IFU stores it with the request and returns it unchanged on the writeback; it has no meaning inside the IFU and must not be decoded there. It closes TD-FE-8; the rule is section 6.1.

ftq_ifu_idx accompanies every request and returns on the writeback. It is the entry's own index, the same value carried in branch_id.

4.1 Translation request: FTQ to IFU
  ftq_ifu_xlate_val                            NEW   IFU-24
  ftq_ifu_xlate_rdy                            NEW   IFU -> FTQ
  ftq_ifu_xlate_pc    [VA_WIDTH-1:0]           NEW   IFU-24
  ftq_ifu_xlate_idx   [FTQ_IDX_BITS-1:0]       NEW   IFU-24

Driven from xlate_ptr (ftq_decisions.md 5.1), which sits between alloc_ptr and fetch_ptr. The IFU's translation pipeline accepts when its ITLB port and its translation queue can take another block.

ftq_ifu_xlate_pc is bp_ftq_entry_t.pc, the same field section 4 sends as ftq_ifu_start_pc. The entry is read twice because the two pointers reach it at different times.

ftq_ifu_xlate_idx lets the IFU tag its queue entry so the fetch request can be matched against the translation that was produced for it.

NO RESULT RETURNS ON THIS PORT. The translation lands in the IFU's own queue (IFU-25). The FTQ never sees a physical address, a PMA attribute or a translation fault; those reach it, if at all, through the predecode writeback fault fields of section 6.

WHY THE ENTRY IS PRESENTED TWICE. L1I-3 makes the L1I physically indexed with translation complete before the array is indexed. A single request group would force the IFU to translate and fetch in one pass, which serialises the ITLB ahead of the array inside the fetch pipeline. Splitting the pointer moves the translation out of that path.

The two pointers reset to the same entry, and on a redirect each moves back to the flush index if it was past it (ftq_decisions.md 5.5 R1), so the first fetch after either stalls waiting for its translation: one cycle after a p2 or p3 redirect, two after a predecode or backend redirect, where F is the redirect target block and has no content until the end of the first cycle. The cost is stated, with its sources, in ftq_decisions.md 5.1 and in IFU-27. This read "one cycle after a front-end redirect, two after a backend redirect" until session-075, which was true while predecode flushed at K; before that "usually stalls one cycle" (session-074) and "are set equal on a redirect" (session-071).

ftq_ifu_commit_ptr is DRIVEN CONTINUOUSLY, not requested. It is not part of the request handshake and carries no valid. The FTQ already holds this pointer; what is new is exporting it. BUILT by BP-114 (session-073), TD#142 closed. tb_ftq_ifu group H checks it; ftq_ifu_assert I17 restated its own assignment and was deleted by BP-116 (TD#144).

It exists for uncached fetch alone. A memory mapped device must not see a read for an instruction that is not on the committed path, so the IFU compares the index of an uncached block against this pointer and issues the bus transaction only when everything earlier has committed (ifu_decisions.md IFU-22). A cached fetch never reads it: cacheable reads are speculative by design and have no side effect. Stopping fetch is what lets the pipeline drain, but the drain takes an unknown number of cycles and the IFU cannot otherwise observe that it has finished. The FTQ cannot gate the request instead, because whether a block is uncached is learned in the IFU's translation pipeline and marked in the queue entry (ifu_decisions.md IFU-25, IFU-26), after the translation request has been handed over. This read "discovered from the PMA result at F2". Session-074.

CROSS-LINE is DERIVED, not a port. The IFU computes it from ftq_ifu_start_pc and its own line size. XiangShan carries nextlineStart because its ICache takes two line addresses per access; adding a port here would pin an ICache geometry this project has not chosen (section 8, item 1).

The request is presented in FTQ entry order. The FTQ does not issue a request for an entry it has already flushed.


5. Flush: FTQ to IFU

  ftq_ifu_flush_val                            NEW
  ftq_ifu_flush_idx   [FTQ_IDX_BITS-1:0]       NEW

Drop every in-flight fetch whose FTQ index is at or after ftq_ifu_flush_idx, and discard whatever the IFU holds for those entries. The FTQ resumes requesting from the flush index, or from where it already was if it had not reached it (ftq_decisions.md 5.5 R1). The index is K or K+1 by cause, as 5.5 R1 tabulates.

IT DOES NOT CLEAR THE IBUF. Only a backend redirect does (ibuf_decisions.md IBUF-8, ifu_ibuf_interfaces.md IB-12). A predecode redirect is truncated by the IB-2 mask in the same stage as the ibuf write, so nothing wrong arrives; a p2 or p3 redirect fires before the named entry is fetched. Clearing on either would discard valid work.

THIS FLUSHES BOTH IFU PIPELINES. The translation pipeline of 4.1 and the fetch pipeline of section 4 are flushed by this one group, and the translation queue between them (IFU-25) is emptied of every entry at or after the flush index. The FTQ moves xlate_ptr and fetch_ptr back to the flush index if they were past it and leaves them otherwise (ftq_decisions.md 5.5 R1). When they were past it, the first fetch after a flush waits for its own translation. Nothing at or after the flush index is carried across a flush on the strength of having been translated before it. This read that the FTQ "sets xlate_ptr and fetch_ptr both to the flush index", which skips unfetched entries older than it when the IFU is behind. Session-071. Section 4.1 and xlate_ptr are BUILT, BP-112, TD#127 closed.

ONE flush group, not two. XiangShan carries BpuFlushInfo with separate s2 and s3 valid-pointer pairs and leaves the consumer to apply shouldFlushByStage2 and shouldFlushByStage3. Pacino's FTQ already resolves supersession by stage order before anything leaves it (FE-3: a later stage wins for the entry and slot it names, and the FTQ does not compare targets to settle it). Exporting both stages would ask the IFU to redo a decision the FTQ has already made. The FTQ presents the resolved flush point.

Sources of a flush, all resolved by the FTQ into this one group:

  p2 redirect          bpu_redir_p2 / bpu_redir_idx_p2
  p3 redirect          bpu_redir_p3 / bpu_redir_idx_p3
  predecode redirect   section 6, derived from the writeback
  backend redirect     ftq_backend_interfaces.md (this read
                       "ftq_backend, UNSPECIFIED"; session-070)

NO REQUEST ACCOMPANIES A FLUSH. A request may be PRESENTED in the flush cycle, on section 4 or on 4.1, but it belongs to the old stream: the FTQ drives it from the pre-rewind pointer and discards the handshake, so the pointer does not advance and the entry is presented again the next cycle from the rewound pointer. THE IFU MUST IGNORE ANY REQUEST PRESENTED IN A CYCLE WHERE ftq_ifu_flush_val IS SET, on both groups. Accepting one and acting on it fetches the same entry twice under one generation tag when the pre-rewind pointer was behind the flush index, and fetches a squashed entry when it was not.

The first request of the corrected stream is the one presented the CYCLE AFTER the flush.

RULED session-073 (Jeff), TD#138. This section said the opposite -- that the flush applies first and the request accompanying it is the first fetch of the corrected stream -- which no request port has ever done and which would need a same-cycle path from the winning redirect through ftq_ptr's rewind to the entry read index and the request outputs. The behaviour as built costs nothing, since the handshake was already being discarded. tb_ftq_ptr H53-H56 pin it. BP-112 recorded the full analysis.


6. Predecode writeback: IFU to FTQ

One writeback per prediction block, after the IFU has predecoded the fetched bytes.

  ifu_ftq_pdwb_val                                  NEW
  ifu_ftq_pdwb_idx     [FTQ_IDX_BITS-1:0]           NEW
  ifu_ftq_pdwb_gen                                  NEW   TD-FE-8
  ifu_ftq_pd           ftq_pd_info_t
                         [FTQ_PD_WIDTH-1:0]         NEW
  ifu_ftq_pd_range     [FTQ_PD_WIDTH-1:0]           NEW
  ifu_ftq_cfi_val                                   NEW
  ifu_ftq_cfi_pos      [FTQ_PD_POS_BITS-1:0]        NEW
  ifu_ftq_mis_val                                   NEW
  ifu_ftq_mis_pos      [FTQ_PD_POS_BITS-1:0]        NEW
  ifu_ftq_target       [VA_WIDTH-1:0]               NEW
  ifu_ftq_fault_val                                 NEW
  ifu_ftq_fault_pos    [FTQ_PD_POS_BITS-1:0]        NEW
  ifu_ftq_uc_end                                          IFU-23b

ifu_ftq_uc_end is set with ifu_ftq_mis_val when an UNCACHED block delivered only its first instruction and would have delivered more (ifu_decisions.md IFU-23b): mis_pos names that instruction and section 7 W3U gives the successor. It is never set on a cached block. Built by BP-123 (D1) in ifu.sv, ftq.sv and ftq_ifu.sv, accepted session-077 (Jeff).

ftq_pd_info_t is per predecode slot, the shape of XiangShan's PreDecodeInfo:

  typedef struct packed {
    logic        valid;    // slot holds an instruction start
    logic        is_rvc;   // 16-bit encoding. Driven by the
                           // predecoder (BP-116); no consumer in
                           // the FTQ.
    logic [1:0]  br_type;  // 00 not CFI, 01 branch, 10 jal, 11 jalr
    logic        is_call;
    logic        is_ret;
  } ftq_pd_info_t;                                   // 6 bits

ifu_ftq_pd_range marks the slots inside the block that were actually fetched: the tail is cut short by a taken branch, by the block end, or by a fault.

ifu_ftq_cfi_val and ifu_ftq_cfi_pos name the first control-flow instruction predecode actually found. ifu_ftq_target is the target of the instruction at ifu_ftq_mis_pos when ifu_ftq_mis_val is set, and of the instruction at ifu_ftq_cfi_pos otherwise, when predecode can compute one: every direct branch and JAL. For JALR it carries no meaning and is not read. W1 writes it into the slot at mis_pos, and under M3 the first CFI can be a not-taken branch before the taken slot, so the cfi's target would be the wrong one. This read "is its target", the cfi's. Session-074, as BP-116 built it.

ifu_ftq_mis_val and ifu_ftq_mis_pos mark a STRUCTURAL mispredict predecode can prove without executing anything:

  M1  predecode found a JAL, call or not, before the predicted
      taken position, or anywhere when no taken position is
      predicted. M1 names the first such JAL. A JALR is never M1:
      its target is unknown here. Ruled session-074 (Jeff); this
      read "predicted to have no taken branch ... JAL, or a call".
      Built by BP-117, TD#146. A JAL AT the predicted taken
      position is not M1; M3 checks it
  M2  a taken slot named a position that holds no instruction start,
      or holds an instruction that is not a control transfer
  M3  the direct target computed by predecode for the TAKEN slot
      differs from ftq_ifu_next_pc. Only the taken slot's target
      reaches the IFU, so M3 checks no other slot
  M4  the predicted taken position lies outside ifu_ftq_pd_range

M1 through M4 need no execution and no register file. A CONDITIONAL branch's direction is NOT a predecode mispredict: predecode cannot know it, and TAGE and SC already own the direction.

PRIORITY. One writeback carries one mis_pos, and it names the EARLIEST failing position in the block. M1 therefore outranks M2, M3 and M4: an M1 JAL lies before the predicted taken position, it is always taken, so nothing at or after it executes, and the ibuf truncates at mis_pos (IB-2). Reporting a later failure instead would admit the instructions between the JAL and that position to the ibuf and leave the JAL to be caught by a backend redirect. M2, M3 and M4 are all findings at the taken position itself; among them the order ifu_f3.sv implements stands. Ruled session-075 (Jeff), as BP-117 built it.

ifu_ftq_fault_val and ifu_ftq_fault_pos report that fetch terminated on an instruction access fault, page fault or guest page fault at that slot. Guest page fault is a class here because H is MANDATORY in RVA23 via Sha, so pacino has two-stage translation.

The FAULT CODE IS NOT CARRIED HERE. The architectural exception travels with the instruction stream to the backend, which is where it is taken. The FTQ needs only to know that the block ended early so it stops requesting and stops predicting past it.

6.1 Stale writeback rejection -- TD-FE-8, closed

A writeback in flight when its entry is squashed and its index REALLOCATED would otherwise arrive after the new allocation cleared the status bits and set them on the wrong use of that index (ftq_entry_formats.md 4.4).

  X1  The FTQ holds one generation bit per entry, gen[FTQ_DEPTH-1:0],
      in flops beside wb_rcvd and fault (ftq_entry_formats.md 4).
  X2  Allocating entry i TOGGLES gen[i]. The fetch request for that
      entry carries the NEW value on ftq_ifu_gen.
  X3  A writeback is accepted only if ifu_ftq_pdwb_gen equals
      gen[ifu_ftq_pdwb_idx]. Otherwise it is DROPPED ENTIRELY: no
      status bit set, no predecode redirect derived, no field
      rewritten.
  X4  The IFU returns the tag unchanged and never decodes it.

A TOGGLE, not the pointer's wrap bit. A rewind can reallocate an index WITHIN one wrap, so a wrap-derived generation would not discriminate; toggling on every allocation discriminates on any reallocation, rewind or wrap.

ONE BIT IS SUFFICIENT, AND THE REASON IS A BOUND, NOT ARITHMETIC. A single bit fails if the same index is reallocated TWICE while one writeback is still outstanding, because the second toggle restores the original value. That cannot happen here: section 5 has the IFU discard everything it holds for flushed entries, so the only stale writeback that survives a redirect is one already presented in the flush cycle, and it arrives immediately -- not after two further reallocations of its index.

IF THE IFU FLUSH CONTRACT CHANGES so that a writeback can survive arbitrarily long after a flush, this width must be revisited. The bound is what makes one bit enough; the encoding does not.

The 5.6 rejection of carried wrap bits does not apply. That was rejected for widening FTQ_IDX_BITS at every bp_cluster port and in tage_pred_meta_t, sc_pred_meta_t and ittage_pred_meta_t. This bit is on the IFU path and touches none of them.

There is NO separate IFU to FTQ redirect port. The FTQ derives the redirect from the writeback, exactly as XiangShan does. A second path would let the two disagree.


7. What the writeback does to the entry

The writeback is the THIRD correction of a slot, after the p2 and p3 slot correction groups of ftq_bpu_interfaces.md 4a. It is later than both and supersedes both for the slot it names, by the same stage-order rule as FE-3.

On ifu_ftq_mis_val, the FTQ:

  W1  rewrites the named slot: slot_valid, br_type and taken from
      the predecode info, target from ifu_ftq_target when predecode
      computed one. pred_src becomes PRED_NONE -- no predictor
      supplied this, and the field is diagnostic (TD-FE-4).

      FOR A CONDITIONAL BRANCH taken keeps the entry's prediction;
      only the target is corrected. Predecode cannot know a
      conditional's direction (section 6, ifu_decisions.md IFU-18),
      so an M3 on a predicted-taken conditional corrects where it
      goes, not whether it goes. RULED session-077 (Jeff), after
      BP-124, which found W1 writing taken = 0 for it, so the
      successor became the fall-through (performance, not
      correctness: the backend corrects it). BUILT by BP-125,
      TD#174 closed: the entry's taken is the taken of the slot W1
      replaces when that slot is valid at mis_pos (under M3, the
      predicted-taken slot), else not taken; pred_src stays
      PRED_NONE and confidence 0 (D5). tb_ftq_ifu group L. No
      tb_fe_top program produces such a writeback.
  W2  writes ifu_ftq_mis_pos straight into bp_ftq_slot_t.pos. The
      two widths are equal and the conversion is the identity
      (section 3). It was a lossy shift until the position field
      was widened on 2026-08-19.
  W3  re-derives the block successor across the slots
      (fe_decisions.md 2.4) and drives ftq_ifu_flush_val with this
      entry's index, so fetch restarts from the corrected successor.
      THE INDEX DEPENDS ON THE ARM. For a p2 or p3 redirect it is
      K: K is not yet fetched and including it is required, since
      the correction changes taken_val and taken_pos, which is what
      the IFU truncates the bundle on, so a fetch issued against
      the old prediction would truncate in the wrong place. For a
      PREDECODE redirect it is K+1: K is already fetched, and its
      positions up to mis_pos are already in the ibuf (IB-2,
      IBUF-8a), which a predecode redirect does not clear (IB-12).
      Refetching K would deliver them twice.

      RULED session-074 (Jeff). This read that the index is K for
      all three, "for a predecode redirect K is already fetched,
      so including it costs nothing". BP-112 built K for all three
      (TD#126); BP-117 built the predecode arm at K+1 (TD#146).

      THIS RULE CANNOT BE KEYED ON THE REDIRECT CAUSE. ftq_npc
      drives RC_MISPREDICT with _self clear for p2, p3, predecode
      and the backend alike, so the distinction W3 needs is not on
      the bus. The FTQ resolves it internally from ftq_npc's
      arm_win, the arbitration arm that won: arms 2, 3 and 4 are
      predecode, p3 and p2. ftq_decisions.md 5.5 R1 carries the
      same note.
  W4  restores the history pointers and the RAS snapshot from this
      entry, the same restore a p2 or p3 redirect performs
      (ftq_decisions.md 3.2).
  W3U WHEN ifu_ftq_uc_end IS SET, the successor of W3 is not
      re-derived across the slots: it is start + 2 * mis_pos + the
      length of the instruction at mis_pos, 2 or 4. The next
      uncached instruction is thereby the next entry, which IFU-22
      gates at F0. Built by BP-123 (D1), accepted session-077
      (Jeff); tb_ftq_ifu K2 fails when it is ignored. As BP-124
      reported from the RTL: the writeback is a predecode redirect
      in every other respect. W1 rewrites the slot at mis_pos as
      for any predecode redirect (for the usual non-CFI first
      instruction, invalid, NO_BRANCH, not taken, and every later
      slot killed); W2 writes pos = mis_pos; the flush index is
      K+1; ftq_ifu forms the successor (w_corr_succ in
      predecode_correct) and ftq_npc selects it on arm 2.

NO PREDICTOR UPDATE IS FORMED FROM PREDECODE. Updates remain post-execute (FE-8, fe_decisions.md 7.1). A structural mispredict here is corrected in the entry; the predictors learn it when the branch resolves, and the ftq_entry_formats.md 3.1 R2 rule already handles a classification that disagrees with the resolved type. Forming an update here would give the predictors two producers in different orders and break FE-6.

The FTQ does not need the writeback to free an entry. Deallocation is FE-U7, which is RESOLVED by ftq_decisions.md 5: deallocation follows bkend_ftq_commit_idx and the entry is freed at commit (5.3). This said "remains open"; item 3 of section 8 in this same file already says FE-U7 is decided. Corrected session-070.


8. Open items

  1. ICache path. DECIDED 2026-08-19: pacino defines NO logical
     ftq_icache interface. The ICache is an INDEPENDENT MODULE
     inside the front-end top, a SIBLING of the IFU, and the IFU
     exposes the interface to it (icache_decisions.md L1I-2,
     fe_decisions.md FE-16). An earlier revision said the ICache
     is encapsulated behind the IFU; corrected session-069. The
     decision above is unaffected: independence changes the module
     hierarchy, not whether the FTQ reaches the cache directly.
     If physical design later needs the FTQ address earlier, a
     pass-through or alternative path is created in the PD phase,
     and this file does not change.

     XiangShan does drive the ICache and the prefetcher directly
     from its FTQ. The motive is PHYSICAL, and the evidence is in
     the Chisel rather than in any interface description:

       NewFtq.scala 637   // modify registers one cycle later to
                          // cut critical path
       NewFtq.scala 523   def copyNum = 5, with copied_ifu_ptr and
       NewFtq.scala 785   copied_bpu_ptr as Seq.fill(copyNum), and
                          toICachePcBundle a Vec(copyNum). Five
                          identical copies of one pointer and one PC
                          bundle: register replication against
                          fanout and wire delay, which has no
                          logical purpose.

     A secondary note in this tree, ia_context/background/
     xs_ifu_ftq.md 302-305, says the address fields feed the ICache
     the cycle before req.valid rises. That is a reading of the
     design, not a statement from it, and is cited as such.

     Pacino has no way to observe this pressure today:
     bp_cluster.md, Timing Methodology Gap, records that Verilator
     supplies no timing data and that stage intent in comments is
     verified by review alone. Deferring the question to PD is
     therefore deferring it to the first point at which it can be
     measured.

  2. FETCH_BLOCK_BYTES 64 against FTB_BLOCK_BYTES 32. Whether the
     IFU coalesces two consecutive FTQ entries into one 64-byte
     access, and what that does to ftq_ifu_req_rdy backpressure,
     is an IFU decision this file deliberately does not take.
     NARROWED session-071. Serving two requests from one held line
     is IFU-internal. Delivering two prediction blocks per cycle is
     not: the FTQ would issue two requests per cycle, fetch_ptr
     would advance by up to two, and there would be two predecode
     writebacks, so sections 4 and 6 reopen. As built the FTQ
     issues one request per cycle (ftq_ifu.sv, ftq_ptr.sv).
     CLOSED. One prediction block per cycle, ruled session-073
     (TD#133, which defers only the measurement). The IFU serves
     consecutive blocks in one line from one L1I request,
     ifu_decisions.md TD-IFU-8, session-074. This read "Still open;
     it is decided with the IFU design" until session-074.

  3. Entry fields. RESOLVED, ftq_entry_formats.md 4. FE-U7 is
     resolved (ftq_decisions.md 5), so the policy that reads them
     is settled and the fields are decidable.

     TWO of the three were added, not three. wb_rcvd and fault are
     per-entry status, held in FLOPS outside both SRAMs rather than
     as members of bp_ftq_entry_t; ftq_entry_formats.md 4.1 gives
     the reasons, of which the decisive one is that a redirect
     rewind must clear them for a RANGE of entries in one cycle.
     request-issued is NOT added: fetch_ptr already says which
     entries have been issued, and a per-entry bit would be a
     second encoding of one pointer.

     TD-FE-8 was opened against this interface and is CLOSED by
     section 6.1: one generation bit, ftq_ifu_gen out and
     ifu_ftq_pdwb_gen back, toggled per allocation.

  4. ifu_ftq_pd is 16 x 6 bits per writeback, 96 bits, plus the
     range vector. Whether the FTQ stores any of it or consumes it
     combinationally to form the correction of section 7 is an
     implementation choice. Nothing in section 7 requires storing
     it.

  5. Backpressure on the writeback. The group carries no ready. The
     FTQ must accept a writeback in the cycle it is presented,
     which is satisfiable because section 7 is a single entry
     rewrite. If the FTQ ever needs to stall it, a ready is added.

9. Departures from the XiangShan contract

  topdown_redirect   DROPPED. A structurally identical copy of the
                     redirect existing only to bucket top-down
                     performance counters. Add it with the counters
                     if they are built, not before.

  BpuFlushInfo       COLLAPSED to one group, section 5. The FTQ has
                     already resolved stage supersession (FE-3).

  nextlineStart      DROPPED from the request. Derived in the IFU;
                     carrying it pins an ICache geometry not chosen.

  PredictWidth 16    KEPT as FTQ_PD_WIDTH, but for a different
                     reason. XiangShan's 16 is its prediction width.
                     Here both are 16, and for different reasons:
                     the prediction block is 16 positions
                     (FTB_BR_POS_BITS 4, two bytes each) and 16 is
                     also the PREDECODE width, RVC granularity over
                     a 32-byte block. Two quantities that happen to
                     share a value.

  pdWb.pc vector     DROPPED. XiangShan returns the PC of every slot.
                     Every one of them is start_pc plus the slot
                     index times two; the FTQ can form any it needs.

  jalTarget          FOLDED into ifu_ftq_target. XiangShan carries a
                     separate directly-computed JAL target alongside
                     the general one. One target field, at mis_pos
                     or cfi_pos (section 6), names the same thing.

10. RVA23 compliance note

RVA23 mandates the C extension, so a branch may begin at any 2-byte boundary. FTB_BR_POS_BITS is 4, giving sixteen 2-byte positions per 32-byte block, so every branch in a block has its own position and this interface converts a predecode position to a predictor position without loss.

CLOSED 2026-08-19. The field was 3 bits until then, 4-byte granular, and two RVC branches in one aligned word shared a position. The consequences recorded here were: the entry could describe only one of the two, section 7 W2 could not recover which, the FTB and uBTB trained them as one branch with interfering directions, and the position-to-slot mapping of ftq_backend_interfaces.md 4 was ambiguous. All of that is gone.

The cost, measured: FTB entry 106 -> 110 bits per way (+8,192 bits of array), uBTB entry 100 -> 104 (+1,024), FTQ fast path 222 -> 224 bits per entry (+128) and slow path 420 -> 421 per slot (+128). 9,472 bits in all, about 3 percent of the three structures. No logic was restructured: every affected width is derived from $clog2(FTB_BLOCK_BYTES / N), and the granularity shift had already been separated from the predictor hash shift by BP-098, so POS_OFFSET_BITS rescaled from 2 to 1 on its own.

11. Document History

  2026-08-19  Created. Closes TD-FE-1. Fetch request, flush and
              predecode writeback defined against the 32-byte
              prediction block. Departures from the XiangShan
              contract recorded in section 9: topdown_redirect and
              the pdWb pc vector dropped, BpuFlushInfo collapsed to
              one resolved group, nextlineStart derived rather than
              carried, jalTarget folded. Predecode writeback forms
              no predictor update; FE-8 keeps updates post-execute.
              Section 10 records the 4-byte position granularity
              against RVA23 C.

  2026-08-19  FTB_BR_POS_BITS widened to 4, closing the section 10
              gap the same day it was written. Predecode and the
              predictor now share 2-byte position granularity, so
              section 3's mismatch text and section 7 W2's lossy
              shift are both retired: the conversion is the
              identity.

  2026-08-20  Section 8 item 3 CLOSED: the entry fields are
              ftq_entry_formats.md 4, two added and one rejected.
              Section 6.1 added, closing TD-FE-8 with one
              generation bit -- ftq_ifu_gen out, ifu_ftq_pdwb_gen
              back, toggled per allocation. One bit is sufficient
              because the flush of section 5 BOUNDS the number of
              stale writebacks in flight to one per flush; if that
              contract changes the width must be revisited.

  2026-08-21  Section 9 said the prediction block is 8 positions.
              FTB_BR_POS_BITS is 4, so it is 16, as sections 3 and
              10 of this file already said. Stale by BP-099.

  2026-08-21  Cross-reference repair. No content change. Section 7
              cited "the section 4.2.1 R2 rule", the fe_decisions.md
              numbering that was retired when that content moved
              out. It is ftq_entry_formats.md 3.1 R2.

  2026-09-19  session-071. Section 3: FETCH_BLOCK_BYTES is the
              fetch block, the L1I line the IFU reads, not a fetch
              width; delivering two prediction blocks per cycle is
              not IFU-internal; ports carry block-start positions.
              Section 5: xlate_ptr and fetch_ptr move back to the
              flush index only if past it; the index is K or K+1 by
              cause. W3 recorded as unbuilt, TD#126. Section 8 item
              2 narrowed. "Fetch block" replaced by "prediction
              block" where the 32-byte unit was meant.

  2026-09-20  session-072. ftq_pd_info_t.is_rvc marked undriven:
              no producer in DCD-7, no consumer in the FTQ.

  2026-09-20  session-072. E7: an empty code fence in section 4
              removed.

  2026-09-20  session-072. G1: the scope note records that the FTQ
              side is built (ftq_ifu.sv) and only the IFU side is
              new.

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

  2026-09-22  session-073, after BP-112. Section 4.1 and section 5's
              pointer rules are BUILT, TD#127 closed. 7 W3 is
              BUILT, TD#126 closed, with the note that the rule
              cannot be keyed on the redirect cause and is
              resolved from ftq_npc's arm_win. Section 5's
              same-cycle flush-and-request sentence RULED: no
              request accompanies a flush, and the IFU must ignore
              any request presented in a flush cycle. TD#138.

  2026-09-22  session-073, after BP-114. ftq_ifu_commit_ptr is
              BUILT, TD#142 closed.

  2026-10-01  session-074. 4.1: the stall after a redirect is one
              cycle front-end, two backend (BP-113, IFU-27).
              Section 8 item 2 CLOSED on TD#133 and TD-IFU-8. The
              TD#126 wording in 7 W3 checked: arm_win is named.

  2026-10-01  session-074, after BP-116. 6: ifu_ftq_target is the
              target at mis_pos (C4); M1 widened and JALR excluded
              (C5); M3 is the taken slot (C7); is_rvc driven. 7 W3:
              predecode flushes at K+1 (C6), TD#146. 4.1: uncached is
              marked in the translation queue; I17 citation. 2: a
              repeated paragraph removed.

  2026-10-06  session-075. Scope paragraph: the IFU side is built
              (BP-116); the NEW tag is historical. After BP-117:
              M1 and 7 W3 built, TD#146 closed; 6 gains the M1
              priority (Jeff); 4.1 latency is two cycles for a
              predecode redirect as well as a backend one.

  2026-10-09  session-077, after BP-123, ruling (Jeff). 6:
              ifu_ftq_uc_end. 7 W3U: the uncached successor. Both as
              BP-123 built them (D1, ifu_decisions.md IFU-23b).

  2026-10-10  session-077, after BP-124, ruling (Jeff). 7 W1: a
              conditional keeps the entry's taken; built by BP-125.
              7 W3U: what BP-124 reported, replacing "BP-124 reports
              it".

  2026-10-10  session-077, after BP-125. 7 W1: the conditional
              paragraph built, TD#174 closed.
ftq_backend_interfaces.md

planning/interfaces/ftq_backend_interfaces.md on GitHub

Backend to FTQ Interface

 FILE:    ftq_backend_interfaces.md
 SOURCE:  ftq_decisions.md, ftq_entry_formats.md, fe_decisions.md 7,
          ras_decisions.md 3.3 and 4.5, bp_structs_pkg.sv
 STATUS:  DRAFT
 UPDATED: 2026-10-08
 CONTACT: Jeff Nye

The third of the FTQ's four interfaces, and the last carrying real traffic. Every port here is NEW.

NOTHING IN THE BACKEND EXISTS. docs/backend/ is four-line stubs, rtl/core/dispatch/*/rtl holds no SystemVerilog, and no planning document describes the ROB, the branch units or the commit path. Every backend-side property this file relies on is therefore an ASSUMPTION, collected in section 10 rather than scattered through the text. When the backend is specified, check that list first.


1. Scope

Covered, all inbound: - branch resolution, post-execute - redirect and flush, from a mispredict or a trap - commit, which frees entries and advances the RAS commit stack

Not covered:
- the ROB, the branch units, the trap path
- what the FTQ does with a resolution once it has it; that is
  `fe_decisions.md` 7.2 and `ftq_entry_formats.md` 3.1
- instruction delivery to the backend, which is IFU to IBuffer and
  never returns through the FTQ

2. Naming

  bkend_ftq_<signal>    backend -> FTQ
  ftq_bkend_<signal>    FTQ -> backend

No stage suffixes. The backend pipeline is not defined.


3. Three events, not one

The backend tells the FTQ three different things at three different times, and they must not be collapsed:

  RESOLVE   a branch executed. Forms predictor updates. Does NOT
            free the entry and does NOT redirect by itself.
  REDIRECT  the fetch stream is wrong from some point on. Squashes
            entries, restores history and RAS, restarts fetch.
  COMMIT    an entry is architecturally retired. Frees it and
            advances the RAS commit stack.

fe_decisions.md 7.1 is explicit that updates trigger at post-execute resolution and do NOT wait for retirement, so RESOLVE and COMMIT are genuinely separate and can be many cycles apart. A mispredicting branch RESOLVEs, REDIRECTs, and later COMMITs: three events, one branch.


4. Resolution

  bkend_ftq_rsv_val   [NUM_RESOLVE_PORTS-1:0]              NEW
  bkend_ftq_rsv       ftq_resolve_t
                        [0:NUM_RESOLVE_PORTS-1]            NEW
  ftq_bkend_rsv_rdy   [NUM_RESOLVE_PORTS-1:0]              NEW
  typedef struct packed {
    logic [FTQ_IDX_BITS-1:0]    ftq_idx;   // entry that fetched it
    logic [FTB_BR_POS_BITS-1:0] pos;       // in-block position
    logic                       taken;     // resolved direction
    logic [VA_WIDTH-1:0]        target;    // resolved target
    bp_br_type_e                br_type;   // resolved type
    logic                       mispredict;
    logic                       is_rvc;    // compressed instruction
  } ftq_resolve_t;

is_rvc WAS ADDED BY BP-121 (TD#164, ruled session-075). The backend sets it when the resolved instruction is a compressed one. The FTQ uses it for the resolved fall-through of a taken jump (ftq_entry_formats.md 2) and passes it to the FTB's jump field (ftb_interfaces.md ftb_upd_jmp_rvc_u0). Its position in the packed struct is as bp_structs_pkg.sv declares it; the listing above shows the fields, not their order.

THE BACKEND NAMES A POSITION, NOT A SLOT. Prediction slots are a predictor concept: they are the two branch fields of one FTB block (FE-10), and nothing outside the BPU and the FTQ has any reason to know which field a branch landed in. The backend knows the FTQ index and the in-block position because both travelled with the instruction from the IFU (assumption A1, confirmed). The FTQ maps position to slot by matching pos against the two bp_ftq_slot_t.pos fields of the entry.

The slot array is program-ordered as of IC-FTB-16, so the mapping is monotone: the lower position is slot 0. That is a property worth having, but it does NOT let the backend carry a slot id instead. The IFU tags each instruction from its own predecode, and predecode yields a position; slot membership is FTB field bookkeeping the IFU does not hold. Tagging with a slot would mean exporting the entry's slot-to-position map into the IFU.

The mapping is EXACT. Positions are unique within an entry: FTB_BR_POS_BITS is 4, giving one position per 2-byte slot, so no two branches in a block can share one. It was ambiguous until 2026-08-19, when the field was 3 bits and two RVC branches in one aligned word collided onto a single slot.

A position that matches neither slot of a live entry is a branch the entry does not hold. It is PLACED in a slot in program order and trained (ftq_entry_formats.md 3.1, ruled session-075, built by BP-119); it is not dropped.

TWO RESOLUTIONS, ONE SLOT. Two resolution ports in one cycle can name the same slot index (in two entries), or two unmapped resolutions of one entry can be placed in the same free slot. Before BP-120 the later write won and both were reported accepted, so one update was lost (TD#158). FIXED BY BP-120: a resolution naming the slot of an OLDER resolution is held, whether or not the older is accepted that cycle, and two placements in one entry take program-order slots, the younger seeing the older's. OLDER means the entry nearer commit_ptr (wrap-aware), then the lower position, then port 0. A held resolution presents no FTB update.

bp_update_t is unchanged. It is arrayed [NUM_PRED_SLOTS-1:0] and the slot IS the array index, so once the FTQ has resolved position to slot it writes the matching element. ftq_resolve_t exists because bp_update_t has no position field and cannot acquire one without breaking FE-10.

NUM_RESOLVE_PORTS = NUM_PRED_SLOTS = 2. Not because two branches resolve per cycle in the backend -- unknown, assumption A3 -- but because the downstream capacity is two: fe_decisions.md 7.3 gives each predictor's update queue two write ports serving the two update channels. A third resolution in one cycle could not be forwarded, so it would have to be queued in the FTQ. If the backend turns out to have more than two branch units, add the queue and revisit; do not widen this port and leave the queues behind it at two.

ftq_bkend_rsv_rdy is per port. The FTQ deasserts it when it cannot accept, which is when the predictor update queues are full and FE-5 requires the update path to stall rather than drop. The backend holds valid until accepted. A resolution is never dropped for capacity.

One qualification, FE-5a: a LOW-value FTB update -- predict-time hit, correctly predicted -- may be dropped on collision rather than stalling this port. Allocations and mispredict corrections are never dropped and do stall it. ftq_decisions.md 5.7.

A resolution IS dropped, silently and correctly, when its entry has been squashed; see section 7 rule R3.


5. Redirect

  bkend_ftq_redir_val                                      NEW
  bkend_ftq_redir_idx    [FTQ_IDX_BITS-1:0]                NEW
  bkend_ftq_redir_pos    [FTB_BR_POS_BITS-1:0]             NEW
  bkend_ftq_redir_taken                                    NEW
  bkend_ftq_redir_pc     [VA_WIDTH-1:0]                    NEW
  bkend_ftq_redir_self                                     NEW
  bkend_ftq_redir_cause  ftq_redir_cause_e                 NEW
  typedef enum logic [1:0] {
    RC_MISPREDICT = 2'b00, // branch resolved against prediction
    RC_TRAP       = 2'b01, // exception or interrupt
    RC_REPLAY     = 2'b10, // pipeline replay, memory ordering
    RC_UNSPEC     = 2'b11  // no naming instruction; see below
  } ftq_redir_cause_e;

bkend_ftq_redir_pc IS THE NEXT FETCH ADDRESS, not a branch target. For RC_MISPREDICT it is the resolved target or the fall-through. For RC_TRAP it is the trap vector, which belongs to no FTQ entry and cannot be derived from one. Carrying an address rather than a "correct the entry and re-derive" instruction is what lets one group serve all three causes.

bkend_ftq_redir_self distinguishes the two flush levels. Clear means the naming instruction completed and everything after it is squashed, which is the mispredict case. Set means the naming instruction is squashed too, which is the trap case.

bkend_ftq_redir_idx and _pos locate the boundary. The FTQ squashes every entry after that index, and the entry itself when _self is set.

bkend_ftq_redir_taken is the resolved direction of the branch at _pos. ftq_npc uses _pos and _taken to form the history correction it drives with the rollback (D1; ftq_bpu_interfaces.md 9). Added by BP-121 (D14, decision 8). One bit, on fe_top and the ftq; read only on an RC_MISPREDICT with _self clear. Since BP-122 it also forms the loop predictor's rollback slot bits.

The FTQ's response:

  D1  restore the history pointers from the checkpoint held in the
      entry named by _idx (ftq_decisions.md 3.2) by driving
      ftq_rollback_val / ftq_rollback_idx on bp_cluster. The FTQ
      presents the INDEX; the cluster reads its own copy of that
      entry's checkpoint. Added by BP-102; see section 8.
      Since BP-121 the rollback also carries a history
      correction formed from _pos and bkend_ftq_redir_taken, and
      bp_history writes the corrected bits rather than keeping
      the predicted ones (bp_history_decisions.md 3.5,
      ftq_bpu_interfaces.md 9).
  D2  restore the RAS from bp_ras_snapshot_t in that entry, on
      ras_restore_val / ras_restore_snapshot, which do exist.
  D3  NOTHING ADDITIONAL FOR THE RAS. D2 is the whole of it on
      every cause, RC_TRAP included: this group carries mispredict,
      trap and replay on one port set, so a trap restores the RAS
      through the same path as any other redirect
      (ras_decisions.md 4.4).
      The ras_flush_val / ras_flush_snapshot ports exist, pass
      through bp_cluster and are read by nothing. They are
      REDUNDANT with D2, not unfinished. Do not drive them and do
      not re-open the question from their presence
      (ras_decisions.md 4.4.2).
  D4  free every squashed entry and restart allocation at the
      corrected stream.
  D5  drive the IFU flush group of ftq_ifu_interfaces.md 5, with
      flush index K+1 when _self is clear and K when it is set
      (ftq_decisions.md 5.5 R1). K's own fetch stands when it
      survives; refetching it would deliver its instructions twice.
      As built in ftq_ifu.sv. The index was unstated until
      session-071.

D1, D2 and D4 apply to RC_MISPREDICT, RC_TRAP and RC_REPLAY. They are SKIPPED on RC_UNSPEC, which names no entry to repair from; see 5.1.

The history restore is the same on all three instruction-naming causes. A trap does not un-execute the branches that already resolved in the naming block, so the checkpoint of the entry being corrected is the right state to resume from, and the trap vector is then fetched against it.

bp_history_decisions.md 3.4 stated the opposite until session-069: rollback-by-index restricted to branch mispredicts, with exceptions and interrupts reinitializing the history instead. That document has been corrected to D1. Its own checkpoint granularity rule is why the restriction could not hold: one checkpoint per accepted prediction bundle, not per branch, so the index resolves for any named entry whether or not that bundle contained a branch.

A backend redirect OUTRANKS every BPU-derived redirect and the predecode redirect, unconditionally and without comparison. Those are speculative corrections; this is architectural fact. This is the one place the stage-order rule of FE-3 does not decide the winner, and it is why the backend group is separate rather than folded into bp_redirect_t.

5.1 RC_UNSPEC -- the flush with no naming instruction

Was RC_RESERVED. DEFINED BY BP-105 rather than left spare, because it is the one redirect shape the other three causes cannot express.

RC_MISPREDICT, RC_TRAP and RC_REPLAY all name an instruction, so _idx and _pos locate it and _self says whether it survives. Some events that must restart fetch name NO instruction the FTQ tracks: reset and debug-mode entry, and any future external agent that forces a refetch.

  U1  `_idx` and `_pos` are MEANINGLESS and must not be read.
  U2  `_self` is meaningless and must not be read. RC_UNSPEC is
      unconditional: there is no naming instruction to keep.
  U3  The FTQ squashes EVERY entry, not entries after an index,
      and restarts allocation at `_pc`.
  U4  `_pc` is the next fetch address, as for every other cause.
      It is the only field RC_UNSPEC carries meaning in.
  U5  NO history or RAS restore is performed. There is no entry to
      restore from. Both structures are self-correcting from the
      committed state, so the correct behaviour is to squash and
      refetch, not to repair.

U5 is the substantive difference from D1 and D2. Every other cause repairs from an entry snapshot; this one has no snapshot and does not need one.

A CSR write or a fence that changes translation is NOT this cause. Those are instructions, they name an entry, and they redirect after themselves -- RC_REPLAY with _self clear. RC_UNSPEC is only for events outside the instruction stream.


6. Commit

  bkend_ftq_commit_val                                     NEW
  bkend_ftq_commit_idx   [FTQ_PTR_BITS-1:0]                NEW

bkend_ftq_commit_idx is a WATERMARK: the newest FTQ entry all of whose instructions have architecturally retired. The FTQ frees every entry from its deallocation pointer through that index inclusive.

A watermark rather than a count or a per-entry pulse. The backend retires up to eight instructions per cycle and those may span several FTQ entries or none, so a count would need a width nobody has chosen and a pulse would need a rate nobody has bounded. A watermark is idempotent: repeating it is harmless, and a cycle in which it does not advance costs nothing.

IT IS FTQ_PTR_BITS WIDE, NOT FTQ_IDX_BITS -- it carries the wrap generation. The idempotence promise above is what forces this. At full occupancy the value may name any of the 64 live entries OR the entry just committed, still on the port because nothing newer has retired, and 65 values do not fit in FTQ_IDX_BITS. The aliased pair demands opposite responses and neither is safe; the argument is written out at ftq_decisions.md 5.1. THIS IS NOT THE WIDENING REJECTED AT ftq_decisions.md 5.6, which was FTQ_IDX_BITS at every bp_cluster port and inside four metadata structs. This is one wire on a two-port group that is not on a critical path. Widened after BP-106 found the hole.

COMMIT IS RATE LIMITED BY THE RAS, not by the FTQ. ras_decisions.md 3.3 requires that when a call-containing block commits, the return address is pushed onto the commit stack, and 4.5 requires BOS to advance to that entry's post-op TOSR. The ras_commit_* group on bp_cluster is SCALAR: one commit operation per cycle, no slot dimension. So if the watermark jumps by more than one entry, the FTQ must walk the intervening entries one per cycle to issue their RAS commits.

That walk is bounded and safe. FE-11 guarantees at most one RAS-OPERATING INSTRUCTION per block and therefore one snapshot per entry, so one entry per cycle is one RAS commit per cycle, exactly the port's capacity. An earlier revision said "at most one RAS operation per entry"; since session-069 a single JALR may pop then push (DCD-11), two operations at one position. The conclusion is unaffected: the commit carries the entry's post-op snapshot, not a per-operation record. Corrected session-070. An entry is NOT freed before its RAS commit issues: the commit payload reads bp_ras_snapshot_t out of the entry, so freeing it first would read a slot that may already be reallocated. Commit and free are therefore ONE pointer, not two (ftq_decisions.md 5.4), and the walk is what paces both.

ras_decisions.md 4.5 also rules that a mispredict restore in the same cycle wins over commit for BOS: restore > commit > hold. The FTQ must therefore suppress the RAS commit it would have issued in a cycle where section 5 D2 fires.


7. Interaction rules

  R1  Priority in one cycle: REDIRECT first, then COMMIT, then
      RESOLVE. A redirect squashes entries a resolution in the same
      cycle may name; applying the resolution first would train a
      predictor on a squashed path.

      R1 RANKS THESE THREE AND NOTHING ELSE. It does NOT rank a
      redirect against an ALLOCATION, and it has been read that
      way twice. A prediction request presented in the redirect
      cycle is not discarded: the rewind applies first and the
      request is then allocated FROM THE REWOUND HEAD
      (ftq_decisions.md 5.2). Reading R1 as "a redirect outranks
      an allocation" is what left the redirect target written to a
      squashed entry and never fetched, TD#139, and a tb_ftq_ptr
      check cited R1 for it. Nor does R1 rank a redirect against a
      REQUEST HANDSHAKE on the IFU ports, which is TD#138 and is
      not ruled.

  R2  A commit can never name an entry a redirect squashes. Commit
      is architectural and squashed entries are speculative. If both
      arrive naming overlapping entries, the backend is broken; the
      FTQ does not arbitrate it.

  R3  A resolution naming an entry that has been squashed, or an
      entry whose allocation generation does not match, is DROPPED
      silently. This is normal traffic, not an error: a branch in
      flight when an older branch redirects will resolve after the
      squash.
      ONLY THE FIRST HALF IS BUILDABLE TODAY. `ftq_resolve_t.ftq_idx`
      is FTQ_IDX_BITS with no generation, and assumption A1 carries
      FTQ_IDX_BITS + FTB_BR_POS_BITS per in-flight instruction and
      nothing more. A resolution for a squashed entry whose index has
      been REALLOCATED INSIDE the live window is therefore
      indistinguishable from one for the new use. The live-window
      test is built; the generation test is not. Section 9 called the
      bit "FE-U7 work" and FE-U7 resolved without adding one to this
      path. Closing it costs one bit per in-flight instruction and a
      change to A1. Found by BP-107 (W2).

  R4  Resolutions are enqueued to the predictors in the order they
      arrive, not in program order. FE-6: this is an out-of-order
      machine, the update queue is a FIFO and is not reordered.

  R5  A resolution does not free its entry and does not redirect.
      Only COMMIT frees; only REDIRECT squashes.

8. The bp_cluster rollback input -- TD-FE-7, CLOSED

Until BP-102, bp_cluster.sv derived the bp_history rollback entirely from its OWN p2 and p3 redirects and offered no input by which the FTQ could request one. Section 5 D1 could not be built: a backend mispredict could restore the RAS, because ras_restore_val is an input, but NOT the GHR and PHR pointers. Every branch predicted after a backend mispredict would have indexed on history from the squashed path.

BP-102 added the two inputs and gave them priority:

  input logic                     ftq_rollback_val
  input logic [FTQ_IDX_BITS-1:0]  ftq_rollback_idx

  w_rollback_valid    = ftq_rollback_val
                      | w_any_redir_p2 | w_any_redir_p3;
  w_rollback_ckpt_idx = ftq_rollback_val ? ftq_rollback_idx
                      : (w_any_redir_p3 ? r_idx_p3 : r_idx_p2);

The FTQ arm outranks both cluster arms unconditionally and without comparison: an architectural correction outranks a speculative one. FE-3 still orders p3 over p2 between themselves.

THE INDEX FORM, not the pointer values. The checkpoint array inside bp_history and the checkpoint field of the FTQ entry are written from the same p1 allocation and are one to one against an FTQ_IDX_BITS index, so the index selects the same pair at 6 bits rather than 13 and bp_history needs no change at all. This read 7, which is FTQ_PTR_BITS, the pointer with its wrap bit; the port above is [FTQ_IDX_BITS-1:0]. Session-072. (13, not 14: ghist_ptr is 8 and phist_ptr is 5. Session-070.)

The FTQ presents the index of the entry whose END-of-block pointer state is to be restored, which is what the cluster's own arms do with r_idx_p2 / r_idx_p3. Deriving that index from bkend_ftq_redir_idx and bkend_ftq_redir_self is the FTQ's work. The cluster does not validate the index against any queue state and cannot: it does not read the FTQ.

This was the same class of defect as TD-FE-6 and was found the same way, by writing down what the FTQ would have to drive.

BP-121 ADDED A HISTORY CORRECTION to this group, on ports it writes as ftq_rollback_corr/_n/_tkn/_pbit (ftq_bpu_interfaces.md 9, which owns them). The index form above is unchanged.


9. What this makes decidable

Not decided here. Listed because this interface is the last input they were waiting on.

  FE-U7  RESOLVED by ftq_decisions.md 5, not "not decided here".
         FOUR pointers, not three: alloc_ptr, xlate_ptr, fetch_ptr
         and commit_ptr (5.1; xlate_ptr added session-069).
         ALLOCATION ADVANCES AT p0, not on the p1 prediction (5.2),
         because ftq_pred_idx_p0 leaves with the request.
         Deallocation follows bkend_ftq_commit_idx and the commit
         walk of section 6 sits between them. Full is allocation
         catching deallocation. A generation or wrap bit is
         required by rule R3 and FE-U7 did NOT add one.
         This entry read "All three pointers ... allocation
         advances on the p1 prediction". Session-070.
  G23    Checkpoint slot reclaim. The checkpoint lives in the entry,
         so it is reclaimed with the entry at commit.
  G9     FTB update arbitration. Two resolution ports feed one FTB
         update port with no slot dimension. The FTQ needs the
         scheduler; this interface fixes its input rate at two.
  FE-U2  Flush handling. Section 5 is the answer for the FTQ side.
         The RAS behaviour behind D3 is CLOSED, ras_decisions.md
         4.4: it is D2, and nothing more. BP-105 then closed the
         flush EVENT and the FTB half as well -- there is no flush
         event, FE-14. TD#96, G24 and IC-FTB-07 all closed.

10. Assumptions about the backend

Every one of these is unverifiable today. The backend does not exist.

  A1  CONFIRMED 2026-08-19. Instructions carry their FTQ index and
      in-block position from the IFU through to resolution and
      retirement: FTQ_IDX_BITS + FTB_BR_POS_BITS = 6 + 4 = 10 bits
      per in-flight instruction, and 11 since BP-121 added
      ftq_resolve_t.is_rvc (section 4, TD#164). It read 9, which
      was correct until BP-099 took FTB_BR_POS_BITS from 3 to 4
      for the C extension. Corrected session-070; the 2026-08-19 history entry
      keeps 9, which was right when written. Section 4 and section 6 both
      depend on it. XiangShan does the same (ftqPtr and ftqOffset in
      FetchToIBuffer).
  A2  Retirement is in order, so a commit watermark is meaningful.
  A3  At most two branches resolve per cycle. Section 4 sizes the
      port group to the downstream update capacity, not to a known
      backend width.
  A4  The backend can hold a resolution when ftq_bkend_rsv_rdy is
      low. If it cannot, the FTQ needs a resolution buffer and
      FE-5 has to be restated.
  A5  Exactly one redirect is presented per cycle, already
      prioritised by the backend across its own sources. The FTQ
      does not arbitrate between backend redirects.
  A6  The trap vector is supplied by the backend on
      bkend_ftq_redir_pc. The FTQ reads no CSR.
  A7  ADOPTED session-075 (Jeff, BP-121 decision 9). The backend
      commits an entry only after every resolution naming it has
      been accepted (ftq_bkend_rsv_rdy). The commit walk reads the
      entry's slots for the RAS commit (section 6), and a
      resolution not yet accepted has not yet written its slot.
      BP-121's testbench backend holds commit this way. The
      alternative, the FTQ tracking pending resolutions per entry,
      was not taken.

11. Departures from the XiangShan contract

  one redirect port   XiangShan carries redirect and
                      topdown_redirect, structurally identical, the
                      second only for performance accounting.
                      Dropped, as in ftq_ifu_interfaces.md 9.

  cause encoding      KEPT and narrowed. XiangShan's redirect
                      carries a large CfiUpdateInfo bundle. Here the
                      FTQ already holds the prediction, so the
                      redirect carries only what the FTQ cannot
                      know: where the stream went wrong, where it
                      resumes, and why.

  commit watermark    XiangShan advances a commit pointer from the
                      ROB. Same model, stated as an idempotent
                      index rather than a pointer increment.

12. Document History

  2026-10-08  session-075, after BP-120. Section 4: TD#158 fixed;
              the age rule.

  2026-10-07  session-075, after BP-119. Section 4: an unmapped
              position is placed and trained; two resolutions
              naming one slot lose an update, TD#158.

  2026-09-22  session-073, after BP-113. R1: it ranks redirect,
              commit and resolve and nothing else. It does not rank
              a redirect against an allocation, which is
              ftq_decisions.md 5.2, nor against a request
              handshake, which is TD#138.
  2026-08-19  Created. Resolution, redirect and commit defined as
              three separate events. Resolution names an in-block
              POSITION, not a prediction slot, so the backend needs
              no knowledge of the slot model; the FTQ maps position
              to slot. Port count set by the downstream update
              capacity of two, not by an unknown backend width.
              Commit is an idempotent watermark, rate limited by
              the scalar RAS commit port to one entry per cycle.
              TD-FE-7 opened: bp_cluster derives its history
              rollback only from its own p2/p3 redirects and has no
              input, so a backend mispredict cannot restore the GHR
              and PHR pointers. Six backend assumptions recorded in
              section 10; none is verifiable, the backend does not
              exist.

  2026-08-19  A1 CONFIRMED: 9 bits per in-flight instruction.
              Section 4 records that the position-to-slot mapping is
              monotone under IC-FTB-16, that a slot id still cannot
              replace the position because the IFU holds no slot
              map, and that the mapping is exact only while positions
              are unique -- which they are not at
              FTB_BR_POS_BITS = 3.

  2026-08-19  FTB_BR_POS_BITS widened to 4. The section 4
              position-to-slot mapping is now EXACT: one position
              per 2-byte slot, so no two branches in a block can
              share one. The caveat added earlier the same day is
              retired.
  2026-08-20  TD-FE-7 CLOSED by BP-102. Section 8 rewritten from
              a defect report to the built interface; section 5 D1
              no longer says the input does not exist. The index
              form was taken over the pointer-value form.
              tb_bp_cluster group J, 30 checks.

  2026-08-21  Section 7 R3: only the live-window half is buildable.
              ftq_resolve_t.ftq_idx carries no generation bit and
              assumption A1 does not carry one either, so a
              reallocated index inside the live window cannot be
              separated from the new use. Recorded by BP-107 rather
              than left as a rule the RTL silently half-implements.

  2026-08-21  Two corrections from BP-106. Section 6:
              bkend_ftq_commit_idx widened to FTQ_PTR_BITS, because
              the idempotence promise makes 65 values legal at full
              occupancy and FTQ_IDX_BITS holds 64. Also section 6:
              the sentence asking for a commit-walk pointer distinct
              from the deallocation pointer is STRUCK, with the
              "freeing may run ahead" claim it rested on. It
              contradicted ftq_decisions.md 5.4, which governs by
              ruling, session-067.

  2026-08-21  Cross-reference repair. No content change. Section 6
              cited "ras_decisions.md 211". Every other citation in
              that file is a section number and 211 is not one; the
              requirement is 3.3, Commit stack / Update. The
              companion 4.5 in the same sentence was already correct.

  2026-09-19  session-071. D5 states the IFU flush index, K+1 with
              _self clear and K with it set, matching the RTL and
              ftq_decisions.md 5.5 R1. D1 already named the entry
              the redirect names for the history restore;
              ftq_decisions.md 3.2, which used the entry before it
              when _self is set, now agrees.

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

  2026-10-08  session-076, PA-direct correction recording BP-121.
              4: ftq_resolve_t.is_rvc (TD#164). 5:
              bkend_ftq_redir_taken; D1 carries the history
              correction (decision 8). 8: the correction ports. 10:
              A1 is 11 bits; A7 adopted (decision 9).

  2026-10-09  session-076, recording BP-122. 5:
              bkend_ftq_redir_taken is one bit (as built).
dcd_decisions.md

planning/arch/dcd_decisions.md on GitHub

Decode Implementation Decisions

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

Owns the DCD-N, TD-DCD-N and DCD-UN registries.


1. Scope and reference

The RISC-V unprivileged specification is the reference for every instruction encoding, immediate format and register field named here. This document does not restate them. It contains only what the specification does not decide.

instr_decoder.sv's instruction ENCODINGS are not in scope: they are the specification's. What the specification does not decide IS in scope: the boundary of section 10a, and since session-077 the representation decode hands rename, and which encodings decode treats as illegal, section 10b. This read "instr_decoder.sv is not in scope for its instruction decode. It is Complete", which left the representation undecided; BP-123 found the decoder rejecting mandatory instructions and mapping others onto placeholders.

The RVC expander is not in scope either. Its encodings are the compressed-instruction chapter of the specification, and the project's decisions about it are placement and ordering, which belong with the stage that holds it: ifu_decisions.md IFU-1 puts it in the IFU ahead of the ibuf, and IFU-4 runs it before predecode.

The predecoder replaces predecode.sv. Its bundle view is a NEW struct, ifu_pd_pkt_t, not a redefinition of predecode_pkt_t (Jeff, session-074). The old struct stays for the built decode until decode moves to the new one, TD#143. Neither the existing module nor the existing struct constrains anything below.


2. One predecoder, two views

DCD-1  There is one predecoder. It produces two views of one
       classification.
   The block view is `ftq_pd_info_t` at each of the 16
   halfword positions of the prediction block. It goes to the FTQ
   writeback and its shape is fixed by `ftq_ifu.sv`.

   The bundle view is `ifu_pd_pkt_t`, one per instruction
   slot. It goes through the ibuf to `instr_decoder`.

The two differ in width because their consumers do. The FTQ needs an answer at every position in the block, including positions that are not instruction starts. Decode needs SLOTS of 8. The classification is computed once.

THE ARRAY WIDTH BELONGS TO THE PORT, NOT TO THE TYPE. ifu_pd_pkt_t is a per-slot struct and both ibuf ports carry an array of it: 16 wide on the write port, because the IFU does not compact (ifu_ibuf_interfaces.md IB-1, IFU-5, IBUF-3), and 8 wide on the read port into decode, where instr_decoder is [SLOTS-1:0] (IBUF-9). The ibuf is the width converter. This read "at each of the 8 decode slots", which attaches decode's width to the type and puts it against the four documents that carry 16 on the write port. Session-072.

DCD-2  Position 16, the 17th halfword of IFU-8, has no entry in
       either view. It can only be the tail of a straddling
       instruction, never a start.

3. Inputs

DCD-3  The predecoder takes both the raw halfwords and the
       expanded buffer.

IFU-4 expands before predecode, and expansion runs at every halfword position independently, so a position that is not an instruction start still produces an expanded value. That value is meaningless. The raw halfwords are what determine which positions are starts, so both are needed.


4. Instruction starts

DCD-4  A position is an instruction start if it is reached by the
       walk from the block start PC. At each start, the low two
       bits of that position's halfword give the length: not
       `2'b11` is a 16-bit instruction and the next start is one
       position later, `2'b11` is a 32-bit instruction and the
       next start is two positions later.
DCD-5  The walk begins at the block start PC supplied by the FTQ,
       which is position 0: positions count from the block start
       (ftq_ifu_interfaces.md 3) and the block is unaligned, IFU-6.
       When the block starts on the tail of a 32-bit instruction
       that began at position 15 of the previous block, the walk
       begins at position 1 (IFU-11).
   Session-074. This read "not at position 0", from before
   positions were counted from the block start, and did not
   cover a block that starts on a tail.
DCD-6  The start mask is a parallel prefix over the per-position
       lengths, not a sequential walk. Each position independently
       yields the length of an instruction starting there, and the
       mask is a scan over those lengths.

DCD-6 is stated because the obvious implementation is a loop and the obvious loop does not close timing over 16 positions.


5. Control flow classification

DCD-7  Per position the predecoder emits a 2-bit type: `2'b00`
       not a control flow instruction, `2'b01` conditional
       branch, `2'b10` JAL, `2'b11` JALR. Plus `is_call` and
       `is_ret`.

The classification runs on the expanded encodings, so only the base-ISA opcodes are recognised. The compressed forms have already become their 32-bit equivalents and are not separately decoded. That is the reason for IFU-4.

DCD-8  The classification is exact, not a hint. It distinguishes
       the three control flow classes and resolves call and
       return. There is no conservative case and nothing is
       deferred to decode.

6. Targets

DCD-9  The predecoder computes a target for conditional branches
       and for JAL, as the position's PC plus the sign-extended
       immediate of the relevant format.
DCD-10 No target is computed for JALR. The target depends on a
       register value the front end does not have. The target
       field carries no meaning for a JALR position and the FTQ
       does not read it, IFU-17.

7. Call and return

The specification's return-address-stack hints are the reference for which JAL and JALR forms push, pop, or both. x1 and x5 are the link registers and the behaviour is a function of rd and rs1.

DCD-11 `is_call` and `is_ret` are independent bits, not a single
       encoded class. The specification has one case that both
       pops and pushes, a JALR whose `rd` and `rs1` are both link
       registers and are not equal. Both bits are set for it.
DCD-11a Downstream, that pair maps to `bp_br_type_e.RETURN_CALL`,
        added session-069 (`ras_decisions.md` 2). The predecoder
        emits the two bits; the enum is formed from them where a
        single classification is required, as on
        `ras_br_type_p2`.
TD-DCD-2  CLOSED by BP-119. It asked whether the RAS, built
          before DCD-11, accepts both bits set on one instruction
          and in which order. It did not: ras.sv treated 3'b111 as
          a no-op at p2, in the p3 repair and at commit, and
          nothing upstream presented 3'b111 anyway (the cluster
          and the uBTB presented RETURN, so the stack was one
          short after each switch). BP-119 built RAS-DS1: pop,
          then push, at p2, p3 and commit.

8. Validity and range

DCD-12 A position's `valid` is set when it is an instruction
       start under DCD-4 and it lies within the fetched range.
DCD-13 `pd_range` marks the positions actually fetched. The
       range ends at the predicted taken position when the FTQ
       supplied one, and at the block end otherwise, and is cut
       short at a fault (ftq_ifu_interfaces.md 6). The block end
       is `ftq_ifu_next_pc`, the fall-through: the not-taken range
       is the positions whose address is below it, all sixteen
       when it is not within 32 bytes above the start. Session-074,
       as BP-116 built it.
DCD-14 The predecoder does not test the prediction. It reports
       what it found. The comparison against the prediction, and
       `cfi_val`, `cfi_pos`, `mis_val`, `mis_pos`, are the IFU's,
       IFU-15.

9. Faults

DCD-15 A faulting position is reported with `fault_val` and
       `fault_pos` in the block view, and with the cause, the
       faulting virtual address, and on a guest page fault the
       faulting guest physical address and its implicit-access
       kind, in the bundle view. The kind was added session-077
       (mmu_decisions.md MMU-29).

The cause field carries three causes, not two, plus none: instruction access fault, instruction page fault and instruction guest-page fault. H is mandatory in RVA23 through Sha. mmu_decisions.md MMU-16.

The two carry different things on purpose. The FTQ needs only to know the block ended early. The architectural exception travels with the instruction to the backend. This is IFU-2 and the note under IFU-20.


10. The bundle view

DCD-16 `ifu_pd_pkt_t` carries, per slot: valid, the expanded
       32-bit instruction, the start PC, the position within the
       prediction block, the FTQ index, the fault cause, the faulting
       virtual address, the faulting guest physical address, the
       implicit-access kind of that guest physical address,
       `is_rvc`, and the control flow classification of DCD-7.
       `is_vsetvl` and `needs_vtype` are REMOVED from it (TD#148):
       decode computes its own (DCD-17) and nothing read the IFU's.
       RULED session-077 (Jeff), after BP-124; REMOVED by BP-125,
       ifu_pd_pkt_t 192 -> 190 bits (T78 checks the width). The two
       paragraphs below record why they were carried.
   THE FAULTING GPA IS FAULT_GPA_WIDTH = 56 BITS, the widest
   guest physical address a walk can form (a 44-bit VS-stage
   PPN plus the page offset), so every faulting GPA is carried
   whole and none is replaced by a sentinel
   (mmu_decisions.md MMU-23, MMU-30 withdrawn). Ruled
   session-077 (Jeff); a package change, built by BP-124. For
   kind 00 the IFU fills the page offset from the faulting
   halfword's virtual address (ifu_decisions.md IFU-2a).

   THE IMPLICIT-ACCESS KIND is two bits, valid on a guest page
   fault: 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
   (itlb_ifu_interfaces.md IT-6c). The backend needs it to
   write htinst (mmu_decisions.md MMU-29). Added session-077
   (Jeff); a package change, BUILT by BP-123 as
   `logic [1:0] fault_gpa_imp`.

   `is_vsetvl` and `needs_vtype` are per-instruction and belong
   here by TD-DCD-1; the enumeration did not carry them while
   ifu_ibuf_interfaces.md 4 listed them as coming from this
   rule. `vtype_hazard` is NOT here, TD-DCD-1. Session-072.

   `needs_vtype` is set for every OP-V instruction other than
   the vsetvl configuration forms, and for every vector load
   and store. It over-marks the whole-register forms, which is
   safe for rename. Session-074, as BP-116 built it; recheck
   against decode when decode moves to ifu_pd_pkt_t, TD#143.
DCD-16a A SLOT THAT FAULTED AT FETCH carries only `valid`, the
        start PC, the FTQ index, the position and the fault fields
        (cause, faulting VA, faulting GPA and its kind). Every
        other field on it -- the instruction, `is_rvc`, the DCD-7
        classification (and, until BP-125, `is_vsetvl` and
        `needs_vtype`) -- is
        meaningless, and neither decode nor the backend may read
        it. The faulting instruction never executes, so nothing
        needs its length or class: the trap is taken from the
        fault fields. Ruled session-075 (Jeff); the IFU drives
        `is_rvc` from the faulting halfword today, which this makes
        harmless rather than wrong. Found by BP-118.

The start PC and the position are both present and are not redundant. Expansion breaks the correspondence between them, because a compressed instruction advances the PC by two and fills a whole slot.

is_rvc is present because expansion also erases the length. The backend needs it for the link address of a compressed JAL or JALR (rd = pc + 2) and for the fall-through PC of a not-taken mispredict. Added session-074 (Jeff).

TD-DCD-1  The vtype fields of the old `predecode_pkt_t` are
          `is_vsetvl`, `needs_vtype` and `vtype_hazard`. The
          first two are per-instruction and belong here. The
          third does not. `vtype_hazard` is defined as a vsetvl
          preceding a `needs_vtype` in the same bundle, and the
          bundle the predecoder sees is a prediction block while
          the bundle decode sees is 8 slots from the ibuf head.
          The ibuf regroups: one prediction block can split across
          two decode bundles and one decode bundle can draw from
          two prediction blocks. An intra-bundle property computed before
          the ibuf is wrong after it. `vtype_hazard` is computed
          in decode, DCD-17.

10a. Decode on the bundle view -- TD#143

RULED session-075 (Jeff). BUILT by BP-118. What decode does once it takes ifu_pd_pkt_t from the ibuf read port (IBUF-9) instead of predecode_pkt_t. Section 1 keeps the instruction ENCODINGS out of scope, since they are the specification's; these four rules are its boundary, which the specification does not decide. This read that section 1 keeps the instruction decode out of scope, true until section 10b (session-077).

DCD-17 `vtype_hazard` IS COMPUTED IN DECODE. For each of the 8
       decode slots it is set when an earlier valid slot in the
       same decode bundle is a vsetvl form and this slot needs
       vtype. Decode computes it from its OWN classification of
       the instruction, not from the `is_vsetvl` and `needs_vtype`
       bits in `ifu_pd_pkt_t`: decode's is exact, and the IFU's
       `needs_vtype` over-marks the whole-register forms (DCD-16).
       Closes DCD-U1.
   The ibuf stays a buffer with no knowledge of instruction
   meaning, and the decode bundle is exactly the group the
   flag describes.
DCD-18 DECODE PASSES `ifu_pd_pkt_t` THROUGH to rename unchanged,
       beside its own decode packet, plus `vtype_hazard` per slot.
       The PC, FTQ index, position, fault fields and `is_rvc`
       reach the backend this way (ftq_backend_interfaces.md A1).
       `predecode_out` and `predecode_pkt_t` are retired.
DCD-19 A SLOT CARRYING A FETCH FAULT IS NOT DECODED AS ILLEGAL.
       Its instruction bits are meaningless, and an instruction
       fetch fault takes priority over an illegal instruction
       exception. Decode passes the fault through and raises no
       illegal on that slot.
DCD-20 C AND Zcb ARE ALWAYS ENABLED. After expansion in the IFU
       decode cannot tell which compressed extension an
       instruction came from: `is_rvc` survives, the Zcb
       distinction does not. RVA23 mandates both, so `misa.C` is
       read-only 1, and decode's per-extension gating of
       compressed encodings is deleted.
TD#148  `is_vsetvl` and `needs_vtype` in `ifu_pd_pkt_t` have no
        reader once DCD-17 is built. Left in place so BP-118 needs
        no change to `bp_structs_pkg`. Removal ruled session-077
        (Jeff). CLOSED by BP-125: removed from the struct,
        ifu_predecode, ifu_f3 and every reader.
TD#155  `en_c`, `en_zcb` and `MASK_BITS` in instr_decoder lose
        their readers with the gating DCD-20 deletes. They are
        declared in decode_pkg.sv (`ext_enable_t`), so removing
        them is a package change; it narrows fe_top's ext_enable
        input and removes tb_instr_decoder's en_c=0 and en_zcb=0
        cases. CLOSED BY BP-120: removed; ext_enable_t and
        fe_top's ext_enable are 16 bits; tb_instr_decoder 654 ->
        649 checks.

As built by BP-118, a faulting slot's decode packet is valid and the instruction bits only, no illegal and no vector decode, and it neither raises nor seeds vtype_hazard. DCD-16a makes the instruction bits meaningless too; decode reads none of them.


10b. Decode representation and legality -- session-077

RULED session-077 (Jeff), from the PA's R1 to R14, after BP-123. The decoder mapped FP, AMO and CSR instructions onto placeholder operations before BP-123, and BP-123 (D4) mapped the SYSTEM fences, HLV/HLVX/HSV, WRS and FLH/FSH onto the representation already used for their class, so a backend could not tell those operations apart. Reading the decoder in session-077 also found reserved encodings in those spaces accepted, which RVA23 recommends raising illegal. BUILT by BP-124 (session-077): alu_op_t 8 bits, values 107 to 185 as DCD-22 lists them, the seven decode_pkt_t fields after is_illegal, Zvbb at 189 to 198; tb_instr_decoder 1323 checks; sim_dec_sweep 458752 encodings.

PA ADDITIONS, drafted session-077 and built by BP-124 as written: DCD-24's vector paragraph and its is_fp, is_load and is_store rule; DCD-25's zero-extended CSR address, the vtype immediates and the vsetivli AVL; DCD-33; the vector part of DCD-34; DCD-35; the operation names and order of DCD-22. Jeff accepted BP-124's decisions D1 to D9 (session-077), recorded in DCD-24, DCD-25, DCD-32 and DCD-36.

The specification references, checked session-077: a reserved encoding's behaviour is UNSPECIFIED and raising illegal-instruction is valid behaviour (unprivileged, RV32I; F chapter); RVA23 strongly recommends illegal-instruction for unimplemented opcodes (rva23-profile.adoc, RVA23U64 and RVA23S64 Recommendations); a reserved FENCE configuration SHALL be treated as FENCE (RV32I), and the unused fields of FENCE.I shall be ignored (Zifencei); Zfhmin is FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, FCVT.H.S, and with D FCVT.D.H and FCVT.H.D (zfhmin.adoc); Zfa's .H forms need Zfh, FMVH.X.D and FMVP.D.X are RV32 only, and Zfa depends on F (zfa.adoc).

DCD-21 THE PRINCIPLE (R1). `alu_op` and the decoded fields of
       `decode_pkt_t` fully identify every scalar operation, its
       operands' register files and its legality. No downstream
       unit re-decodes the instruction word for any of these.
       `instr` stays in the packet for traps (stval) and debug, not
       as a decode source. For a vector instruction `v_op_class`
       identifies the operation and `alu_op` is ALU_VEC.
DCD-22 `alu_op_t` IS 8 BITS (R2). Values 0 to 106 keep their values;
       ALU_ILL stays 63. Three are RENAMED to their exact meaning,
       values unchanged: ALU_FLD (56) -> ALU_FLOAD, ALU_FSD (57) ->
       ALU_FSTORE, ALU_CSR (49) -> ALU_CSRRW. ALU_FMADD (58) keeps
       its name and now means FMADD only. The new operations are
       appended from 107 in this order:
  ALU_VEC
  FP      ALU_FMSUB ALU_FNMSUB ALU_FNMADD
          ALU_FADD ALU_FSUB ALU_FMUL ALU_FDIV ALU_FSQRT
          ALU_FSGNJ ALU_FSGNJN ALU_FSGNJX ALU_FMIN ALU_FMAX
          ALU_FCVT_W ALU_FCVT_WU ALU_FCVT_L ALU_FCVT_LU
          ALU_FCVT_FW ALU_FCVT_FWU ALU_FCVT_FL ALU_FCVT_FLU
          ALU_FCVT_FF ALU_FMV_XF ALU_FMV_FX
          ALU_FEQ ALU_FLT ALU_FLE ALU_FCLASS
  Zfa     ALU_FLI ALU_FMINM ALU_FMAXM ALU_FROUND ALU_FROUNDNX
          ALU_FCVTMOD_W_D ALU_FLEQ ALU_FLTQ
  A       ALU_LR_W ALU_LR_D ALU_SC_W ALU_SC_D
          ALU_AMOSWAP_W ALU_AMOSWAP_D ALU_AMOADD_W ALU_AMOADD_D
          ALU_AMOXOR_W ALU_AMOXOR_D ALU_AMOAND_W ALU_AMOAND_D
          ALU_AMOOR_W ALU_AMOOR_D ALU_AMOMIN_W ALU_AMOMIN_D
          ALU_AMOMAX_W ALU_AMOMAX_D ALU_AMOMINU_W ALU_AMOMINU_D
          ALU_AMOMAXU_W ALU_AMOMAXU_D
  fences  ALU_FENCE_I ALU_CBO_INVAL ALU_CBO_CLEAN ALU_CBO_FLUSH
          ALU_CBO_ZERO ALU_SFENCE_VMA ALU_SINVAL_VMA
          ALU_SFENCE_W_INVAL ALU_SFENCE_INVAL_IR ALU_HFENCE_VVMA
          ALU_HFENCE_GVMA ALU_HINVAL_VVMA ALU_HINVAL_GVMA
  Zawrs   ALU_WRS_NTO ALU_WRS_STO
  Zicsr   ALU_CSRRS ALU_CSRRC ALU_CSRRWI ALU_CSRRSI ALU_CSRRCI
   79 operations, 107 to 185. ALU_FENCE (55) is FENCE, with
   FENCE.TSO and PAUSE, which are FENCE configurations.
DCD-23 FP PRECISION IS A FIELD (R3). `decode_pkt_t` gains
       `fp_fmt [1:0]` and `fp_src_fmt [1:0]`, encoded 2'b00 S,
       2'b01 D, 2'b10 H, 2'b11 unused. `fp_fmt` is the instruction's
       fmt field (bits 26:25) for OP-FP and the four FMA opcodes, so
       for a conversion to or from an integer, a move, a compare or
       a classify it is the precision of the FP operand, and for
       ALU_FCVT_FF the destination; for an FP load or store it is
       the width of the memory datum. `fp_src_fmt` is the source
       precision of ALU_FCVT_FF only, from instruction bits 21:20
       (rs2[1:0]). Both
       are zero for a non-FP operation. The rounding mode stays in
       `funct3`. This read "for a conversion, of the destination",
       which left FCVT.W.S and FCVT.W.D indistinguishable.
DCD-24 OPERAND REGISTER FILES (R4). `decode_pkt_t` gains `rd_is_fp`,
       `rs1_is_fp` and `rs2_is_fp`; rs3 is always an FP register.
       `uses_rd`, `uses_rs1`, `uses_rs2` and `uses_rs3` are exact
       per operation: a unary FP operation (FSQRT, FCVT_*, FMV_*,
       FCLASS, FROUND, FROUNDNX, FCVTMOD_W_D) does not use rs2, and
       FLI uses no source register; rs3 is zero for every operation
       but the four FMAs. `is_fp` means the operation executes in
       the FP unit, so an FP load or store has `is_fp` clear and
       names its FP register with `rd_is_fp` or `rs2_is_fp`
       (BP-124 D2). LR sets `is_load` only, SC `is_store` only, an
       AMO both, a CBO neither (D3). `is_csr` is set for the six
       CSR operations and for ECALL, EBREAK, SRET, MRET and WFI,
       and clear for the fences, WRS, HLV/HSV and MOP (D6).
       Accepted session-077 (Jeff).
   FOR A VECTOR INSTRUCTION these fields describe its SCALAR
   register operands only; its vector register operands are in
   `vec_decode_pkt_t`. OPIVX and OPMVX read GPR rs1; OPFVF reads
   FPR rs1; vmv.x.s, vcpop.m, vfirst.m and the vsetvl forms
   write GPR rd; vfmv.f.s writes FPR rd; vsetvl reads GPR rs1
   and rs2, vsetvli GPR rs1, vsetivli neither; a vector load or
   store reads GPR rs1, and GPR rs2 when strided. Every other
   vector instruction uses no scalar register. For every vector
   instruction `is_fp` is clear (it executes in the vector
   unit), `is_load` is set for a vector load and `is_store` for
   a vector store, and `is_branch`, `is_jump` and `is_csr` are
   clear. Added session-077 by the PA as R4's consequence for
   vector instructions, whose scalar packet set uses_rd,
   uses_rs1 and uses_rs2 for every instruction; flagged for
   Jeff.
DCD-25 IMMEDIATES THAT SIT IN A REGISTER FIELD go in `imm`, because
       decode zeroes an unused register field: the CSRRxI zimm in
       `imm[16:12]` beside the CSR address in `imm[11:0]`, for all
       six CSR operations the address ZERO-extended and `imm[31:17]`
       zero, `imm[16:12]` zero for the register forms (the decoder
       sign-extended the address as an I-type immediate); the FLI
       constant index in `imm[4:0]`; an OPIVI 5-bit immediate in
       `imm`, sign- or zero-extended as the specification defines
       for that instruction, and vror.vi's 6-bit immediate, whose
       bit 5 is instruction bit 26, in `imm[5:0]` zero-extended;
       vmv<nr>r.v's register-count field zero-extended (BP-124 D9,
       accepted); the
       vtype immediate of vsetvli (zimm[10:0]) and vsetivli
       (zimm[9:0]) in `imm[10:0]` zero-extended, reserved bits
       included, so vill can be formed downstream; and vsetivli's
       AVL, uimm[4:0], in `imm[20:16]`. The decoder zeroes rs1 for
       CSRRWI, CSRRSI and CSRRCI, losing the zimm, and would lose
       vsetivli's AVL once DCD-24 clears its uses_rs1; found
       session-077, PA additions.
DCD-26 FP LEGALITY (R5). Legal, each gated by its enable: F (en_f),
       D (en_d), Zfhmin as quoted above (en_zfhmin; the D-dependent
       pair also en_d), Zfa's .S and .D forms and FCVTMOD.W.D
       (en_zfa; the .D forms also en_d). Illegal: every other .H
       operation (Zfh is not implemented), Zfa's .H forms,
       FMVH.X.D and FMVP.D.X (RV32 only), every Q form, and
       FCVTMOD.W.D with an rm other than 001 (RTZ), which zfa.adoc
       reserves.
DCD-27 STATIC ROUNDING MODE 101 OR 110 IS ILLEGAL (R6), in every
       instruction whose encoding has an rm field. Dynamic rm with
       an invalid frm is raised at execute, not here.
DCD-28 AMO LEGALITY (R7). Legal: funct3 010 (W) and 011 (D), with
       funct5 LR 00010 (rs2 must be x0), SC 00011, AMOSWAP 00001,
       AMOADD 00000, AMOXOR 00100, AMOAND 01100, AMOOR 01000,
       AMOMIN 10000, AMOMAX 10100, AMOMINU 11000, AMOMAXU 11100.
       Every other width (Zabha) and funct5 (AMOCAS, Zacas) is
       illegal. aq and rl travel in `funct7`.
DCD-29 FENCES AND CBO (R8). MISC_MEM funct3 000 is ALU_FENCE for
       every fm, pred, succ, rs1 and rd: the specification requires
       reserved configurations to be treated as FENCE. fm, pred and
       succ travel in imm[11:0] zero-extended, a reserved
       configuration's raw fields included; the backend executes
       a reserved configuration as FENCE with fm 0000 (RV32I).
       BP-124 D4, accepted session-077 (Jeff). funct3 001
       is ALU_FENCE_I, its imm, rs1 and rd ignored as Zifencei
       requires. funct3 010 is the CBO operation of imm (0, 1, 2,
       4), any other imm illegal, and rd not x0 illegal (DCD-31).
       funct3 011 to 111 is illegal. The SYSTEM fence forms are the
       ALU_SFENCE/SINVAL/HFENCE/HINVAL operations of DCD-22.
DCD-30 WRS, HLV, CSR (R9, R10, R11). WRS.NTO and WRS.STO are their
       own operations. HLV, HLVX and HSV keep the width-exact load
       and store operations, with `is_load` or `is_store`, and set
       new packet bits `is_hlsv` (a virtual-machine access) and,
       for HLVX, `is_hlvx` (read with execute permission). The six
       CSR instructions are six operations.
DCD-31 SYSTEM RESERVED FIELDS ARE ILLEGAL (R12). rd not x0 in
       ECALL, EBREAK, MRET, SRET, WFI, WRS, the SFENCE, SINVAL,
       HFENCE and HINVAL forms and CBO; rs1 not x0 in ECALL,
       EBREAK, MRET, SRET, WFI, WRS, SFENCE.W.INVAL and
       SFENCE.INVAL.IR.
DCD-32 VECTOR RESERVED ENCODINGS ARE ILLEGAL (R13): every encoding
       that decodes to VOTHER or to the VMEM default, and any store,
       segment or not, with sumop 10000 (built by BP-124).
   EVERY OTHER RESERVED VECTOR ENCODING IS ILLEGAL TOO. RULED
   session-077 (Jeff), after BP-124, which found 24742 in its
   sweep (rule VRSV) and reported them as this rule then said.
   The classes, from the V 1.0 text BP-124 cites:
   - mew = 1 (EEW 128 and above), every load and store form
   - a unit-stride segment load or store whose lumop/sumop is
     neither 00000 nor 10000
   - a whole-register load or store with vm 0, NFIELDS other
     than 1, 2, 4 or 8, mew 1, or (store) width not 000
   - vlm.v or vsm.v with vm 0, width not 000, or mew 1
   - vsetvl with bits 29:25 not zero (bit 31 set and bit 30
     clear is vsetvl; bit 30 set is vsetivli)
   - vadc and vsbc with vm 1
   - vmv.v.v/x/i and vfmv.v.f with vs2 not v0
   - vmv.s.x and vfmv.s.f with vs2 not v0 or vm 0
   - vfmv.f.s with vs1 not 0 or vm 0; vmv.x.s with vm 0
   - vmv<nr>r.v with vm 0 or a register count other than 1, 2,
     4 or 8
   - vcompress.vm and the eight mask-logical operations with
     vm 0
   - vid.v with vs2 not v0
   - VFUNARY0 selectors 00100, 00101 and 01101 (the last is
     Zvfbfmin's vfwcvtbf16.f.f.v, not implemented)
   This read: "Other reserved vector encodings found are
   reported for a ruling, not changed." BP-124 D7 classed every
   lumop 01000 encoding as whole-register, reserved NFIELDS
   included; those fall under the third class. An illegal
   vector word carries a zero vector packet (DCD-36).

   BUILT by BP-125, TD#175 closed: a reserved memory form
   decodes as VMEM and a reserved OP-V form as VOTHER, so the
   existing illegal path applies (D3). Counts by class, each
   encoding counted under the class of its form (D2; the
   classes overlap on mew): mew 15168, segment lumop/sumop 7168,
   whole-register 236, vlm/vsm 30, vsetvl 1178, vadc/vsbc 190,
   vmv.v/vfmv.v.f 136, vmv.s.x/vfmv.s.f 144, vfmv.f.s/vmv.x.s 76,
   vmv<nr>r 66, vcompress and mask-logical 342, vid.v 2,
   VFUNARY0 6; total 24742. CORRECTED session-077: the vsetvl
   class read "bits 30:25", copied by the PA from BP-124's report
   without checking the encoding; bit 30 set is vsetivli, so
   that text would have made half the vsetivli encodings
   illegal. BP-125 built bits 29:25. Checked against
   riscv-opcodes rv_v, every other class matches its fixed
   fields.
DCD-33 ZVBB IS DECODED, one v_op_class per instruction, appended
       after VOP_VSOXSEG in this order with the values 189 to 198:
       VOP_VANDN, VOP_VBREV, VOP_VBREV8, VOP_VREV8, VOP_VCLZ,
       VOP_VCTZ, VOP_VCPOP_V (VOP_VCPOP is vcpop.m), VOP_VROL,
       VOP_VROR and VOP_VWSLL, gated by en_v, each with is_vector and
       needs_vtype set. Zvbb is mandatory in RVA23U64
       and the decoder had no entry for it, so DCD-32 would have
       made it illegal. Added session-077 by the PA; flagged for
       Jeff.
DCD-36 AN ILLEGAL PACKET carries ALU_ILL and nothing else: no
       register (uses_* clear, the fields zero), no immediate, no
       is_* flag, no FP field, and a zero vector packet, so rename
       and dispatch see only the trap. BP-124 D5, accepted
       session-077 (Jeff).
DCD-34 VERIFICATION (R14). Legality and classification are checked
       against a disassembler oracle, spike-dasm, the disassembler the
       decoder work has used, with --isa naming exactly the implemented
       extensions (every RVA23U64 and RVA23S64 mandatory extension that
       has instructions, H and Svinval among them, and no optional one).
       Directed decoder tests take each word from clang -c (RISC-V
       target, the same extension set) and confirm it with spike-dasm.
       This read "an LLVM disassembler oracle, as BP-117 checked the
       expander, with --mattr". spike-dasm and clang replaced it
       session-077 (Jeff). BP-124 found LLVM installed off PATH, in the
       embecosm toolchain under /usr/local, which the expander oracle
       uses (TD#147); this note said the system had no LLVM. BUILT by
       BP-124: sim_dec_sweep compares the decoder against
       tb/dec_dasm_oracle.txt (458752 encodings, including all eight
       LOAD-FP and STORE-FP widths), oracle_dec_sweep regenerates it
       with tb/gen_dec_dasm_oracle.py, and asm_dec_words re-checks the
       216 directed words with clang and spike-dasm (246 since BP-125).
       The out-of-repo tool path is TD#176. Since DCD-32's classes
       became illegal (BP-125) the sweep expects 208902 legal and 249850
       illegal. BP-124's Results Capture gave its totals as 233504 and
       225248; its per-space figures sum to 233644 and 225108. The sweep
       covers every funct and selector field of OP_FP, the four FMA
       opcodes, AMO, MISC_MEM, SYSTEM, and, because of DCD-32 and
       DCD-33, OP_VECTOR and the vector forms of LOAD-FP and STORE-FP.
       Each disagreement is resolved against the ratified specification
       and listed. The sweep over the vector space was added by the PA
       with DCD-33.
DCD-35 THE Zimop COMMENTS are corrected: Zicfiss, an RVA23
       expansion option this design does not implement, redefines
       some MOP encodings. decode_pkg.sv reads "(no extension
       redefines them in RVA23)" and instr_decoder.sv "no RVA23
       extension redefines them" (BP-123); both become "no
       extension this design implements redefines them; Zicfiss, an
       RVA23 option not implemented, redefines some".

11. Open

DCD-U1  CLOSED session-075 by DCD-17: decode. It asked where
        `vtype_hazard` is computed; TD-DCD-1 had excluded the
        predecoder and left the ibuf read port and decode.
DCD-U2  CLOSED session-070 by ras_decisions.md RAS-DS1: the RAS
        treats them as two operations and performs the POP FIRST,
        then the push. bp_cluster.md and ftq_bpu_interfaces.md 5.4
        agree. This asked for the order "if the RAS treats them as
        two operations"; it does, and RAS-DS1 says so. What is
        then open was TD-DCD-2, whether the BUILT RAS implemented
        it; it did not, and BP-119 built it.

12. Bindings

IFU-1     Expansion in the IFU. The RVC expander is specified
          there, not here.
IFU-3     Puts predecode in the IFU.
IFU-4     Expansion before predecode, the premise of DCD-7.
IFU-6     Unaligned block, the premise of DCD-5.
IFU-8     17 positions, the premise of DCD-2.
IFU-15    The IFU owns the prediction test, not DCD-14.
IFU-16    Satisfied by DCD-7.
IFU-17    Satisfied by DCD-10.
IFU-18    Direction is proven only for an unconditional, which
          follows from DCD-7 and is the FTQ's rule.
IBUF-2    Consumes the bundle view of DCD-16.
TD-IFU-1  Closed by DCD-16.
TD-IFU-5  Closed by this document.
IBUF-9    The 8-wide read port that sets the decode bundle of
          DCD-17.
TD#143    DCD-17 to DCD-20 built by BP-118; rvc_expander.sv
          retires in BP-119.
MMU-29    The implicit-access kind of DCD-16.
MMU-23    FAULT_GPA_WIDTH, DCD-16.

13. Document History

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

  2026-10-09  session-077, after BP-123, rulings (Jeff). Section 1:
              the representation and legality are in scope. DCD-16:
              the GPA is FAULT_GPA_WIDTH = 56; the kind is built.
              Section 10b, DCD-21 to DCD-35, from R1 to R14. DCD-24's
              vector paragraph, DCD-33 (Zvbb) and the vector part
              of DCD-34 were added by the PA and flagged.

  2026-10-09  session-077, after review of the BP-124 draft. DCD-23:
              fp_fmt is the encoding's fmt field. DCD-24: is_fp,
              is_load and is_store for vector instructions. DCD-25:
              the vtype immediates and the vsetivli AVL. DCD-26:
              FCVTMOD.W.D needs rm 001. DCD-35: the exact comment
              text. 10b lists the PA additions pending Jeff. 10a's
              scope sentence; DCD-16's "last two".

  2026-10-10  session-077, ruling (Jeff). DCD-34: the oracle is
              spike-dasm and directed words come from clang -c; the
              LLVM oracle is withdrawn, there being no LLVM on the
              system.

  2026-10-10  session-077, after BP-124, rulings (Jeff). 10b built;
              the PA additions accepted as built. BP-124's D2 to D7
              and D9 accepted: DCD-24 (FP load/store is_fp, LR/SC/AMO
              marking, is_csr, rs3), DCD-29 (the FENCE immediate),
              DCD-36 (the illegal packet). DCD-32: every reserved
              vector encoding is illegal, the VRSV classes listed;
              built by BP-125. DCD-34: built; LLVM is installed off
              PATH, so the "no LLVM" note is corrected.

  2026-10-10  session-077, ruling (Jeff). DCD-16 and TD#148:
              is_vsetvl and needs_vtype leave ifu_pd_pkt_t; removed
              by BP-125.

  2026-10-10  session-077, after BP-125. DCD-32 built, TD#175
              closed, with the per-class counts; its vsetvl class
              corrected from bits 30:25 to 29:25 (PA error). DCD-34:
              the sweep's totals. DCD-16 and TD#148: the removal
              built, 192 -> 190 bits.

Fetch Target Queue

Status: RTL complete, interim documentation

The fetch target queue, its pointers, redirect and rollback, and how it trains the predictors at commit.

Specification: ftq_decisions.md, fe_decisions.md, ftq_entry_formats.md, ftq_bpu_interfaces.md, ftq_ifu_interfaces.md, ftq_backend_interfaces.md (in the Overview above)

Related: IA tasks: BP-107, BP-112, BP-117, BP-139; Frontend demo: fd11_be_mispredict: Backend Mispredict; Frontend demo: fd21_commit: Commit

Branch Detector

Status: RTL complete, interim documentation

Predecode in the IFU, which finds the branches in a fetch block and redirects fetch when the prediction missed one.

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

Related: Blog: Memory disambiguation and pre-decode; IA task: DECODE-001; Frontend demo: fd10_pd_redirect: Predecode Redirect

Pre-Fusion Detector

Status: RTL planned. Documentation planned.

Detection of fusible instruction pairs before decode; no fusion logic is in the current frontend.