CSR — tpb_xt_local_reg

Scope. The per-engine *_LOCAL_REG control aperture every TPB engine points at. This is the register file firmware drives to release run-stall and start/stop the embedded NX (Tensilica) control core and the eight Q7 sequencer cores, to set up the SoC↔Q7 address-translation windows, program the 4D tensor-replace descriptor, and drive the HW-decode breakpoint/debug machinery. This page opens the Part-13 CSR sub-lane and is the bitfield-level companion to the address-side view in tpb-pool.

Provenance. Every offset / reset / bit-range below is read directly from the shipped register-description schema csrs/tpb/tpb_xt_local_reg.json (binary-derived CSR JSON, 55 641 bytes, Cayman / NC-v3 arch-regs tree). The page default is [HIGH · OBSERVED]; claims that depart from it carry an explicit HIGH/MED/LOW × OBSERVED/INFERRED/CARRIED tag.

1. Regfile metadata

Read from .RegFile of tpb_xt_local_reg.json.

The 64 KiB SizeInBytes is the same 0x10000 that tpb-pool reserves for TPB_0_POOL_LOCAL_REG at SoC-absolute 0x2803060000 (slot +0x3060000 off the 0x2800000000 cluster pseudo-base). For the POOL engine the q7-bundle doorbell therefore lands at 0x2803060000 + 0x3000 + 0x0 = 0x2803063000, which is exactly the boot doorbell cited by #900.

Addressing model

The schema nests RegFile → RegistersBundleArrays[] → Registers[] → BitFields[]. A register's AddressOffset is relative to its bundle's AddressOffset; for an indexed bundle (ArraySize > 1) the per-instance base advances by the bundle's BundleSizeInBytes stride:

abs_byte_off(reg, i) = bundle.AddressOffset
                     + i * bundle.BundleSizeInBytes      // i in 0 .. ArraySize-1
                     + reg.AddressOffset

BitFields[].Position is either a single bit "N" or an inclusive range "hi:lo". Reset values live in BitFields[].ResetValue (hex string), not in any Reset key.

GOTCHA (extraction). The reset key is literally ResetValue. A naive .Reset lookup returns null for every field and will make you think the whole file is reset-less — it is not. All non-zero resets quoted on this page (0x1, 0xFF, 0x1FFF, 0x10, 0xb2924, the CAM byte selectors) come from ResetValue.

2. Bundle map

The file declares 7 bundle-arrays, 55 registers, 84 bitfields. Every AccessType (register and bitfield) is RW; every SpecialAccess is None — there are no RO/WO fields in this block, even the field literally named reserved.

Each array span is verified to fit inside its 0x1000-aligned reserved window (window ends at 0x2000 + 40*0x1C = 0x245C; tensor_replace ends at 0x5000 + 32*0x20 = 0x5400).

QUIRK. Bundle strides do not pack tightly to the register footprint. general reserves 0x20 per instance for a single 4-byte register; window reserves 0x1C for 7 registers (a perfect fit); tensor_replace reserves 0x20 for only 0x10 of registers, leaving 0x10 dead per slot. Always compute instance bases from BundleSizeInBytes, never from the register count.

3. Bundle nx — embedded NX control core (base 0x0000, 1 instance)

The single Tensilica NX core that runs the engine's control firmware. This is the boot path: at reset the core is held in run-stall and FW releases it.

4. Bundle q7 — eight sequencer cores (base 0x3000, 1 instance)

The eight Q7 sequencer cores live behind a single bundle instance whose release_run_stall carries one bit per core ([7:0], reset 0xFF ⇒ all 8 stalled). This is the CSR-level confirmation of NUM_POOL_CORES = 8. The base 0x3000 is the anchor every sibling page cites.

4.1 Run-stall / start-stop sequence

The host boot path for a Q7 core is: set the entry PC, clear the stall bit, assert start. The reset state is "all 8 cores held in RunStallOnReset, neither started"; FW clears one stall bit at a time so individual cores can be brought up independently. Cross-link boot-reset. [HIGH · INFERRED — register semantics OBSERVED, ordering INFERRED from field descriptions]

/* tpb_xt_local_reg q7 bundle, base = LOCAL_REG + 0x3000.
 * Release one Q7 sequencer core out of RunStallOnReset and start it.
 * `base` is the SoC-absolute LOCAL_REG of the engine (e.g. POOL = 0x2803060000),
 * so the q7 bundle is at base + 0x3000.
 * release_run_stall.run_stall is [7:0], reset 0xFF (all 8 stalled). */
static void q7_release_and_start(volatile uint32_t *base, unsigned core /*0..7*/)
{
    volatile uint32_t *q7 = base + (0x3000u / 4);   /* word-indexed */

    /* 1. (caller has already loaded the Q7 entry PC via its IRAM/start_addr.) */

    /* 2. Clear THIS core's stall bit: read-modify-write 0xFF -> bit cleared.
     *    Each bit gates one core's RunStallOnReset; writing 0 releases it. */
    uint32_t stall = q7[0x0u / 4];          /* release_run_stall @ +0x0 */
    stall &= ~(1u << core);                  /* drop bit `core` */
    q7[0x0u / 4] = stall;

    /* 3. Assert start_ctrl.ctrl = 1: declares start_addr valid, exits Halt,
     *    begins execution. start_ctrl is a single [0] bit @ +0x4. */
    q7[0x4u / 4] = 1u;                        /* start_ctrl.ctrl */

    /* 4. (optional) poll run_state_<core> @ +0x8 + core*4 for liveness. */
    /*    volatile uint32_t st = q7[(0x8u + core*4u) / 4]; */
}

GOTCHA. release_run_stall is a bitmask — a blind *reg = 0 releases all eight cores at once. To bring up one core, read-modify-write so the other seven stay stalled. The NX bundle's release_run_stall (§3) is a single [0] bit, so for NX write 0 is unambiguous.

NOTE. run_state_<n> is [31:0] and the schema describes it only as a status word — its encoding is not enumerated here (no enum in the JSON). Treat it as opaque; poll for change, not for a specific value. [MED · OBSERVED]

5. Bundle window — SoC↔Q7 address-translation windows (base 0x2000, 40 instances, stride 0x1C)

40 address-remap windows. Each window is {control, mask, match, replace} and selects a requester class (any / NX-only / Q7-only / a single selected Q7) and a 40-bit match/mask page key that, on hit, substitutes a relocated address. This is the LOCAL_REG side of the windows documented end-to-end in soc-q7-translation-windows.

Per-window register layout (relative offsets; instance i base = 0x2000 + i*0x1C):

QUIRK (split fields, page-aligned). mask/match are 40-bit keys presented as bits [39:20] only: *_lo holds [31:20] and *_hi holds [39:32]. The low 20 bits are implicitly 0 — windows match on 1 MiB-aligned (2^20) pages, so there is no [19:0] field. replace is the 64-bit substitute split as replace_lo[31:20] + replace_hi = [63:32]. The bit ranges are taken verbatim from Position; do not assume contiguous 32-bit lo/hi halves.

5.1 Program one translation window

/* tpb_xt_local_reg window bundle, base = LOCAL_REG + 0x2000, stride 0x1C.
 * Program window `w` to remap a Q7-issued page (mask/match) to `replace`.
 * mask/match cover bits [39:20]; replace covers [63:20] in the same split.
 * Low 20 bits are page-implicit-zero (1 MiB granularity). */
static void window_program(volatile uint32_t *base, unsigned w /*0..39*/,
                           uint64_t match40, uint64_t mask40, uint64_t replace64,
                           int q7_only, int single_q7 /* -1 = any, else 0..7 */)
{
    volatile uint32_t *win = base + ((0x2000u + w * 0x1Cu) / 4);

    /* 1. Disable the window first (window_valid must be 0 during reconfig). */
    win[0x00u / 4] = 0u;                                 /* control = 0 */

    /* 2. mask  : lo = bits[31:20], hi = bits[39:32]. */
    win[0x04u / 4] = (uint32_t)( mask40 & 0xFFF00000ull);            /* mask_lo  [31:20] */
    win[0x08u / 4] = (uint32_t)((mask40 >> 32) & 0xFFull);           /* mask_hi  [39:32] */

    /* 3. match : same split. */
    win[0x0Cu / 4] = (uint32_t)( match40 & 0xFFF00000ull);           /* match_lo [31:20] */
    win[0x10u / 4] = (uint32_t)((match40 >> 32) & 0xFFull);          /* match_hi [39:32] */

    /* 4. replace: lo = bits[31:20], hi = bits[63:32] (26-bit field). */
    win[0x14u / 4] = (uint32_t)( replace64 & 0xFFF00000ull);         /* replace_lo [31:20] */
    win[0x18u / 4] = (uint32_t)((replace64 >> 32) & 0x03FFFFFFull);  /* replace_hi [63:32] */

    /* 5. Finally build control and set window_valid LAST. */
    uint32_t ctrl = 1u;                                  /* window_valid = 1 */
    if (q7_only)        ctrl |= (1u << 2);               /* q7_dedicated */
    if (single_q7 >= 0) ctrl |= (1u << 3)                /* single_q7_enable */
                              | ((uint32_t)(single_q7 & 0x7) << 4); /* single_q7_select */
    win[0x00u / 4] = ctrl;
}

GOTCHA (valid-bit ordering). The window_valid description is explicit: clear it before touching any other window state, set it only after mask / match / replace are fully written. Writing control first (or never clearing it) lets the remap fire on a half-programmed key.

6. Bundle tensor_replace — 4D strided-replace descriptor (base 0x5000, 32 instances, stride 0x20)

32 instances of a 4D tensor descriptor. Each descriptor packs two 16-bit subfields per 32-bit register across four registers: per-axis step size (X/Y/Z/W) and per-axis element count (X/Y/Z/W).

Per-instance layout (relative offsets; instance i base = 0x5000 + i*0x20):

NOTE. The eight logical subfields (step_size_*, num_elem_*) are packed into four registers, not eight; the 0x10‥0x1F tail of each 0x20 slot is unused. Steps and counts are uint16.

6.1 Program one tensor-replace descriptor

/* tpb_xt_local_reg tensor_replace bundle, base = LOCAL_REG + 0x5000, stride 0x20.
 * Pack a 4D (X,Y,Z,W) strided descriptor `d` (0..31): per-axis 16-bit step + count. */
static inline uint32_t pack16(uint16_t lo, uint16_t hi)
{
    return (uint32_t)lo | ((uint32_t)hi << 16);
}

static void tensor_replace_program(volatile uint32_t *base, unsigned d /*0..31*/,
                                   const uint16_t step[4] /*x,y,z,w*/,
                                   const uint16_t num[4]  /*x,y,z,w*/)
{
    volatile uint32_t *t = base + ((0x5000u + d * 0x20u) / 4);
    t[0x0u / 4] = pack16(step[0], step[1]);  /* dim_0: step_x | step_y */
    t[0x4u / 4] = pack16(step[2], step[3]);  /* dim_1: step_z | step_w */
    t[0x8u / 4] = pack16(num[0],  num[1]);   /* dim_2: num_x  | num_y  */
    t[0xCu / 4] = pack16(num[2],  num[3]);   /* dim_3: num_z  | num_w  */
}

7. Bundle hw_decode — HW instruction-decode + breakpoint/KDB debug (base 0x4000, 1 instance)

Configures the HW instruction-decode path (vs the instruction FIFO) and the full KDB breakpoint surface: instruction breakpoints, two opcode-instance counters (IC0/IC1), two address breakpoints, single-step, and immediate pause. Cross-link the CAM programming side in hw-decode-cam-programming and the debugger driver in uarch-debugger.

NOTE (reset asymmetry). Three breakpoint_ctrl enables reset to 1 (breakpoint_instr_enable, breakpoint_profile_table_enable, ucode_force_pause_enable) — the breakpoint engine is armed at reset; the triggers (*_valid, immediate_pause) reset to 0. The CAM-search byte selectors default to the identity sequence {0,1,2,3}, and hw_decode_flush_cntr resets to 0x10 cycles.

QUIRK. iram_block_size_mask is 17 bits ([18:2]) — not a clean power-of-two field — and resets to 0x1FFF (13 set bits). It masks the cache block index out of the IRAM address so rtl can reconstruct the PC. Do not assume it spans the whole register.

7.1 Arm an address breakpoint

/* hw_decode bundle, base = LOCAL_REG + 0x4000.
 * Arm breakpoint slot 0 to pause HW-decode after a 64-bit instruction address. */
static void hw_decode_break_at(volatile uint32_t *base, uint64_t addr)
{
    volatile uint32_t *hd = base + (0x4000u / 4);

    hd[0x18u / 4] = (uint32_t)(addr & 0xFFFFFFFFu);          /* breakpoint_addr0_lo */
    hd[0x1Cu / 4] = (uint32_t)(addr >> 32);                  /* breakpoint_addr0_hi */

    uint32_t ctl = hd[0x4u / 4];                             /* breakpoint_ctrl */
    ctl |= (1u << 0)        /* breakpoint_instr_enable (already 1 at reset) */
         | (1u << 4);       /* breakpoint_addr0_valid: enable addr-0 check  */
    hd[0x4u / 4] = ctl;
    /* On hit, HW-decode pauses at the sync_stage; resume via the debugger. */
}

8. Bundle notific — SW-queue mapping + timestamp (base 0x6000, 1 instance)

Maps each Q7 sequencer's generated notifications to a SW queue number and sets the timestamp increment.

GOTCHA. sw_queue_num0 maps only Q7_0‥Q7_3 (four 4-bit nibbles). There is no sw_queue_num1 register in this block — the upper four cores Q7_4‥Q7_7 are not mapped here (handled elsewhere, or a schema omission). Do not assume an 8-core nibble array. [MED · OBSERVED]

9. Bundle general — scratch local registers (base 0x1000, 60 instances, stride 0x20)

60 instances at 0x1000 + i*0x20 (lr[0]@0x1000 ‥ lr[59]@0x1760); one register per 0x20 slot, the remaining 0x1C is unused.

10. Interrupt control summary

Two separate interrupt apertures, one per core domain.

The Q7 intr_ctrl packs all 8 cores' enables into one 32-bit register (core c → bits [4c+3 : 4c]); each core then has its own intr_info_<c> metadata word. [HIGH · OBSERVED for the 4-bit-per-core layout; the exact 4 source meanings are not enumerated in the JSON — MED · INFERRED]

/* Enable all 4 interrupt sources for Q7 core `c` (0..7). */
static void q7_enable_intr(volatile uint32_t *base, unsigned c)
{
    volatile uint32_t *q7 = base + (0x3000u / 4);
    uint32_t en = q7[0x28u / 4];             /* q7.intr_ctrl @ +0x28 */
    en |= (0xFu << (4u * c));                 /* 4 bits for core c */
    q7[0x28u / 4] = en;
}

11. Per-generation applicability

Compared against the sibling arch-regs trees shipped in the customop library. [HIGH · OBSERVED for cayman/mariana/mariana_plus/maverick; v2/V1 INFERRED]

The four added bundles on v4/v5 are atomic-op apertures appended after notific, each ArraySize=64 with a single value[31:0] register:

NOTE (per-gen). All five core control surfaces this page documents — the NX/Q7 run-stall release, the 40 translation windows, the 4D tensor-replace descriptor, the HW-decode/breakpoint block, and the notification mapping — are byte-identical across cayman/mariana/mariana_plus/maverick at the same offsets (nx@0x0000, window@0x2000, q7@0x3000, hw_decode@0x4000, tensor_replace@0x5000, notific@0x6000). The v4/v5 delta is additive only (the 0x8000-region atomic apertures inside the previously-RESERVED upper half of the same 0x10000 aperture). A Cayman reimplementation that ignores the atomic region is forward-compatible for the control path. [HIGH · OBSERVED for v3/v4/v5; v2/V1 INFERRED — not shipped]

CORRECTION — "7 bundles / 55 regs / 84 fields" is Cayman-only. That count is often quoted as the layout. It is exact for Cayman, but the v4/v5 arch-regs trees ship 11 bundles / 59 regs / 88 fields — the four atomic_* apertures at 0x8000‥0x8FFF are missed by any survey that does not cross-check the maverick/mariana trees. All offsets, resets, and field positions outside those four bundles are unchanged.

12. Cross-references

• Boot / reset sequencing (when FW clears run-stall): boot-reset
• SoC↔Q7 translation windows (the window bundle, full address view): soc-q7-translation-windows
• HW-decode CAM programming (the profile_cam_search_vector / breakpoint CAM): hw-decode-cam-programming
• SEQ uarch-debugger (drives breakpoint_* / breakpoint_step): uarch-debugger
• Address-side view (LOCAL_REG placement, the 0x2803063000 doorbell): tpb-pool

Appendix A — full register map (offset / name / width / access)

All 55 Cayman registers, absolute byte offsets (instance 0 for indexed bundles). Every register is 32-bit RW.

Schema cross-check. 8 (nx) + 1 (general) + 7 (window) + 19 (q7) + 14 (hw_decode) + 4 (tensor_replace) + 2 (notific) = 55 registers, 84 bitfields — matches the JSON exactly.