Register and command reference

Register map

Reads of 0x000–0x038 are forwarded to the Main FSM and may insert wait states (PREADY low for the round trip — in the current RTL the answer is immediate). All other transactions are zero-wait-state.

Status word — 0x000

Error codes — 0x004

Four independent fields; the main code tells you which sub-code matters.

Fatal vs. recoverable: main codes 3 (FE), 4 (flash-guard violation), counter faults during boot, and ASCON faults during provisioning park the FSM in M_FATAL_ERROR until reset. Everything else flushes the FIFOs, pulses operation_done and returns to ready.

Debug words — 0x02C / 0x030 / 0x034

REQ_STATUS — 0x030

QSPI_STATUS — 0x034

MC_FIFO_STATUS — 0x02C

[15:0] = {backdoor_valid, fifo_flush, mfsm_flush, rx_pop, rx_push, rx_full, rx_empty, rd_fail, flush, seq_error, tx_valid, tx_wrw, tx_push, tx_pop, tx_full, tx_empty}. Intended for waveform-style debugging over APB; the strobes are single-cycle and will usually read 0.

Encrypt — write one record

One record = one 256-byte flash page = 8 B associated data + 232 B ciphertext (58 words of payload) + 16 B tag. The page address must be ≥ 0x002000 and 256-byte aligned.

#define SS1_BASE  0x01051000u   /* needs verification — see note above */
#define REG(o)    (*(volatile uint32_t*)(SS1_BASE + (o)))

int sec_encrypt(uint32_t page, const uint32_t pt[58])
{
    while (!(REG(0x000) & 1u)) ;          /* 1. wait for ready            */

    REG(0x064) = page;                     /* 2. target page address       */
    REG(0x044) = 1;                        /* 3. open the write sequence   */

    for (int i = 0; i < 58; i++)           /* 4. exactly 58 words,         */
        REG(0x068 + 4*i) = pt[i];          /*    consecutive addresses     */

    REG(0x044) = 1;                        /* 5. close → validate → start  */

    while (!(REG(0x000) & 1u)) ;          /* 6. erase+encrypt+program …   */

    return (REG(0x000) >> 4) & 1u          /* 7. error bit?                */
         ? -(int)REG(0x004) : 0;
}

Step 5 is where hardware takes over: sequence validation → tx_valid → pending-request slot → Main FSM (erase if needed, counter increment, AD write, ASCON stream, flash commit). Instead of polling, firmware may enable irq_en_3 and sleep until irq_3.

Decrypt — read one record

int sec_decrypt(uint32_t page, uint32_t pt[58])
{
    while (!(REG(0x000) & 1u)) ;          /* 1. wait for ready            */

    REG(0x048) = page;                     /* 2. request: PWDATA[23:0]     */

    while (REG(0x038) == 0) {              /* 3. poll RX_READY …           */
        if (REG(0x000) & (1u << 4))       /*    … checking the error bit: */
            return -(int)REG(0x004);       /*    auth failure ends here    */
    }

    for (int i = 0; i < 58; i++)           /* 4. each read pops one word   */
        pt[i] = REG(0x03C);

    return 0;
}

Step 3 must check the error bit while polling: after an authentication failure, the RX FIFO remains empty and RX_READY does not become 1. Firmware should also read 0x03C only after 0x038 indicates data availability; a premature pop returns 0xDEAD_BEEF and raises ERR_MC_PROTOCOL with a FIFO flush.

Observing the automatic boot

Helper-data enrollment and key reconstruction run automatically after reset — there is no APB command to start them (details). Firmware only observes:

void sec_wait_boot(void)
{
    uint32_t s;
    do { s = REG(0x000); } while (!(s & 1u));  /* ready          */
    /* s bit 2: enrolled (helper data in NVM)                    */
    /* s bit 3: key_valid (hash check passed)                    */
    /* ready remains 0 + bit 4 set → fatal boot error, read 0x004 */
}

A fatal boot (FE failure, hash mismatch, counter corruption) leaves ready = 0, busy = 0 and the code latched at 0x004 — poll 0x008 for state 46 (M_FATAL_ERROR) to distinguish it from a slow boot.

Debug / fallback key loading

For debug and recovery scenarios, firmware may load a known 128-bit key instead of using the PUF-derived key. This is an explicit debug feature: the key arrives in plaintext over APB, so the resulting security depends on controlling the firmware and bus access path.

void sec_load_debug_key(const uint32_t key[4])
{
    while (!(REG(0x000) & 1u)) ;     /* module must be ready, no open  */
                                      /* write sequence                 */
    REG(0x04C) = key[0];              /* exactly four words —           */
    REG(0x050) = key[1];              /* a 5th is ignored,              */
    REG(0x054) = key[2];              /* fewer ⇒ GO is ignored          */
    REG(0x058) = key[3];
    REG(0x05C) = 1;                   /* GO                             */
    while (!(REG(0x000) & 1u)) ;     /* ASCON loads & activates key    */
    /* REG(0x060) now reads 1 — sticky until the next reset       */
}

• Debug-key requests have higher priority than pending write/read requests (separate slot, higher priority).
• KEY_SOURCE (0x060) flips to 1 and stays there until reset.
• Records carry the key mode in their AD: a record written under the PUF key cannot be decrypted in debug-key mode, and vice versa. The AD check rejects the request with ERR_AUTH before ASCON runs.
• No hash is stored or checked for the debug key.

QSPI command trace — 0x040

A 16-entry ring that records every command the SEC core enqueues toward the flash (type + address), plus monotonic totals. Read-only observability — it never influences the data path.

Typical use: after an encrypt, select COUNTS and check "1 erase, 64 programs", or inspect the ENTRY view to confirm the erase→program order and addresses.

Performance Counter Unit — 0x150

Optional metrics block (synthesis knob PCU_ENABLE; reads return 0 when absent). Raw counts only — statistics are software's job.

NVM flash layout (W25Q64JV, 8 MB)

Record layout within a page: AD at +0x00 (2 words), ciphertext at +0x08 (58 words), tag at +0xF0 (4 words). There is no commit marker — record validity is the tag check.

Firmware checklist

• Exactly 58 words, consecutive. Any gap, repeat, or extra word inside an open write sequence makes the closing trigger fail (seq_error + flush). The payload never reaches the crypto path.
• One request at a time. Issuing a second write/read while one is pending sets sticky req_dropped (0x030[23]) and drops the new request. Check it during bring-up.
• Poll before pop. 0x03C while 0x038 = 0 → 0xDEAD_BEEF, ERR_MC_PROTOCOL, FIFO flush.
• Check the error bit while polling RX_READY. After a failed authentication, data-ready does not assert.
• Sector geometry. Writing the first page of a 4 KB sector erases all 16 pages of that sector. Lay records out sector-front-first or accept losing neighbours.
• Helper region is hardware-protected. Any application write/erase overlapping 0x000000–0x00015F trips the hardware guard → M_FATAL_ERROR.
• Key modes are separated. PUF-keyed records are unreadable in debug-key mode (AD check → ERR_AUTH), and vice versa. KEY_SOURCE is sticky until reset.
• Fatal errors require reset. Main codes 3/4, boot counter faults, and provision faults latch M_FATAL_ERROR; only rst_n recovers.
• IRQ: irq_3 pulses on operation done and request errors when the SS-control enable (irq_en_3) is set; on fatal entry it pulses continuously.