QCORE-C1 Developer Guide

Register-level programming guide for the QCORE-C1 chiplet covering the MMIO register map, DMA configuration, interrupt handling, and firmware development for bare-metal, RTOS, and Linux environments.

Register Map Overview #

The QCORE-C1 exposes a 64KB MMIO register space accessible through the QLI management sideband interface or JTAG debug port. All registers are 32-bit aligned with little-endian byte ordering.

System Control Registers #

Operation Dispatch #

ML-KEM operations are submitted through the Kyber FSM registers. A command-response model is used: write the operation parameters, write the command register to trigger, then poll (or wait for interrupt) until completion.

// ML-KEM-768 Key Generation — register-level example
// 1. Select parameter set
write_reg(0x0400, 0x00000003);    // KYBER_PARAM = ML-KEM-768 (k=3)

// 2. Set output buffer address (SRAM-relative)
write_reg(0x0408, 0x00002000);    // KYBER_PK_ADDR  = public key output
write_reg(0x040C, 0x00004000);    // KYBER_SK_ADDR  = secret key output

// 3. Provide seed (32 bytes via KYBER_SEED registers 0x0420–0x043F)
for (int i = 0; i < 8; i++)
    write_reg(0x0420 + i*4, seed[i]);

// 4. Trigger KeyGen
write_reg(0x0404, 0x00000001);    // KYBER_CMD = KEYGEN

// 5. Wait for completion
while (!(read_reg(0x0410) & 0x01))  // KYBER_STATUS.done
    ;  // Or use interrupt

// 6. Read result status
uint32_t status = read_reg(0x0410);
// Bit 0: done, Bit 1: error, Bits 7:4: error code

DMA Engine #

The DMA engine transfers data between the QLI interface and internal SRAM without CPU intervention. It supports scatter-gather descriptor rings for efficient bulk key exchange operations.

Interrupt Controller #

Firmware Development #

Bare-Metal

For bare-metal environments, the libqcore C library provides direct register access through memory-mapped I/O. The library includes a complete ML-KEM API, DMA management, and interrupt handling. The library has no external dependencies and compiles with any C99 compiler.

// Bare-metal ML-KEM-768 example (C)
#include <libqcore/qcore.h>
#include <libqcore/mlkem.h>

int main(void) {
    qcore_t *dev = qcore_init(QCORE_BASE_ADDR);

    // Generate keypair
    mlkem_keypair_t kp;
    mlkem_keygen(dev, MLKEM_768, &kp);

    // Encapsulate
    mlkem_encaps_result_t enc;
    mlkem_encaps(dev, MLKEM_768, kp.pk, &enc);

    // Decapsulate
    uint8_t ss[32];
    mlkem_decaps(dev, MLKEM_768, enc.ct, kp.sk, ss);

    // Verify
    assert(memcmp(enc.ss, ss, 32) == 0);
    qcore_zeroize(dev);  // Wipe key material
    return 0;
}

Linux Kernel Driver

A Linux kernel module (qcore_c1.ko) is available that exposes the QCORE-C1 as a character device (/dev/qcore0) with ioctl commands for ML-KEM operations. The driver supports multi-process access with per-context key isolation and integrates with the Linux Crypto API (AF_ALG) for transparent application-layer use.

RTOS Integration

The libqcore library is RTOS-agnostic. For FreeRTOS, Zephyr, or ThreadX environments, register the QCORE-C1 interrupt handler and use the provided semaphore-based completion API for non-blocking operation dispatch.