# 09 — GSP/uproc firmware notes used by risc-v-gsp-rm-debugger

## 1. The microcontrollers around the GPU

From the open-iov wiki **GPU Firmware** page and the linked **NVIDIA RISC-V
Story** presentation (the project mirrors the wiki locally; the PDF is a
public RISC-V summit deck):

* **Falcon (FAst Logic CONtroller)** is NVIDIA's proprietary control
  processor, used across >15 hardware engines for over a decade. It was
  designed for flexibility, long memory latency, low area and security.
  Limits that forced a successor: small addressing range, modest performance
  (~0.67 DMIPS/MHz, ~1.4 CoreMark/MHz), no data cache, no rich OS support.
* **NV-RISCV** is NVIDIA's own implementation of a RISC-V core chosen as the
  next-generation falcon: more performance (>2× falcon claimed), wider
  addressing, TCM, vectored interrupts, security features (TZ-style), with
  area targets under 0.1 mm² at 16FF.
* The GPU hosts several of these cores: the **GSP** (GPU System Processor)
  running a rich firmware stack, plus security/boot engines (**SEC2**, ACR,
  SOE) and the **PMU** microcontroller. The RISC-V Story deck documents the
  falcon-to-RV transition and the DMA/mailbox lines between engines.

## 2. GSP application structure

The GSP firmware is an ELF64 RV64IMAC image (the TU104 570.144 `.fwimage` used
by the probe has entry `0x4009000`, 33 program headers, stripped). Its
application layer is a multi-task RTOS program:

* `_start` (hand-written assembly) sets the trap vector to an early panic
  handler, initialises the stack, pushes two zero words to help debugger
  backtracing, and calls `appMain`. The **bootloader passes arguments in
  a0–a5**: bootargs PA and VA, ELF PA and size, load base PA, and the
  write-protected region id. A re-host harness must reproduce this ABI.
* `init.c` creates the tasks and starts the RTOS; the included driver set
  covers MPU, ODP (on-demand paging), memory, and the RISC-V system library.
* The boot configuration selects `NVRISCV_PARTITION_SWITCH` variants, i.e.
  images can run under a separation-kernel partition model.

## 3. RTOS and libos layers

Two OS layers appear in the vendor snapshots:

* **SafeRTOS/NVRTOS** — the classic resident RTOS: priority scheduling,
  timers, events/signals, IPC and DMA support; ~38 KiB TCM-resident kernel;
  missing paging, task reset, capability security. Used by the GSP test
  firmware partition model.
* **LIBOS** (exokernel design, early draft) — designed to be TCM-resident
  (projected 1–6 KiB), capability-based security, round-robin scheduler,
  DMEM on-demand paging, module configuration so unused features are not
  paid for. This is the direction the GSP stack evolves toward.

**Implication for the simulator:** the scheduler is not the interesting part
for RPC accuracy; the task/dispatcher semantics are. Risc-V GSP-RM debugger's demo mirrors
that shape (mailbox → dispatcher → handler → counters), and a rehost shim
should stub the scheduler while keeping task entry points and message
handling real.

## 4. Boot and partition models

* **MP-SK/FMC** (separation kernel): images are built as partitions. One
  observed GSP test image has two partitions: a SafeRTOS first-stage
  bootloader partition (clobbered after hand-off via partition switch), and a
  high-sec test partition that reads performance counters, writes them to
  shared memory and switches back.
* **Confidential-compute skeleton**: six partition stubs — RM Proxy, RM
  (mutually exclusive with RM Proxy), SPDM, ACR, Init and Attestation — with
  the boot flow **Init → ACR → RM**. The vendor tooling side-loads images to
  a live GSP with a debug command (`nvwatch …`) for bring-up.

These models matter for portability: a new architecture may change the
partition layout or boot order, and risc-v-gsp-rm-debugger's probe is the quickest way to
see the new first-touch sequence before a device model exists.

## 5. Memory, DMA and registers

* The firmware assumes **TCM** and an MPU (protection regions are generated
  at link time); `qemu virt` has neither, so the probe loads segments into
  RAM and faults at the first register access.
* The engines exchange data over **CSB/TRANSCOM windows and mailboxes** with
  DMA into host/FB memory; the physical backend work in Open-IOV already
  models the message-queue side (status/command queues, doorbells) — that is
  the layer risc-v-gsp-rm-debugger can emulate first when R1 lands.
* The GSP kernel's start path receives its memory permissions as boot args
  from the bootloader rather than discovering them, which is why a
  re-host should pass the same structure rather than re-derive it.

## 6. How risc-v-gsp-rm-debugger models this today (and honestly, does not)

| Firmware aspect | risc-v-gsp-rm-debugger v0.1 |
|---|---|
| Task/dispatcher/state-machine logic | modelled faithfully by the demo and by rehosted code |
| RPC handler input/output behaviour | observable and recordable; schemas decode structures |
| RTOS scheduling, interrupts, partition switch | approximated / absent |
| Falcon/CSB/TCM/PMU registers | absent (probe reports first touch; R1 roadmap) |
| Boot ROM chain (FWSEC/booter/SEC2) | out of scope for the VM; the physical backend owns it |

Use the notes above when designing new rehost shims or a device model: the
goal is to keep everything *above* the register/mailbox boundary real, and to
model that boundary explicitly rather than pretend it away.