gsp-phys: command-queue TX and the GSP-RM unload RPC for clean teardown

Adds a minimal msgq producer on the command queue (element layout, checksum, sequence, dma_wmb before writePtr, doorbell) and submits the UNLOADING_GUEST_DRIVER RPC so GSP-RM shuts down and sets the scratch14 handoff bit the Booter Unload gate needs. Release attempts the RPC once before quiescing when a boot ran; on-demand testing is available through the debugfs file gsp-phys-unload-rpc while the module owns the GPU. GSP-RM processor suspend is polled on the GSP mailbox.

1 files changed, 29 insertions, 9 deletions

diff --git a/docs/03-architecture/08-physical-gpu-integration.md b/docs/03-architecture/08-physical-gpu-integration.md
index 0c18e84..f4dfa68 100644
--- a/docs/03-architecture/08-physical-gpu-integration.md
+++ b/docs/03-architecture/08-physical-gpu-integration.md
@@ -202,12 +202,14 @@ event before it raises `GSP_INIT_DONE` (0x1001). **A plain release is not yet
 possible:** the Booter Unload gate requires all four secure scratch14 handoff
 bits (24–27); a
 host-driven boot sets only bit 24, and bit 27 is set by the server's shutdown
-path (host RPC `UNLOADING_GUEST_DRIVER`), which is not implemented, while the
+path (host RPC `UNLOADING_GUEST_DRIVER`; implemented in the module as the
+rung-4b command-queue TX + shutdown path and pending its first live run),
+while the
 host-side seed/unlock alternative is fuse-locked on this part. Until that RPC
-lands, a green session is left claimed with the harness `--keep` flag and
-returning the GPU to the distribution driver takes a power cycle. The
-supervised harness modes are `--boot` (the only write mode: full boot
-lifecycle), `--boot-dryrun` (zero-write staging rehearsal) and `--keep`
+has run in a live session, a green session is left claimed with the harness
+`--keep` flag and returning the GPU to the distribution driver takes a power
+cycle. The supervised harness modes are `--boot` (the only write mode: full
+boot lifecycle), `--boot-dryrun` (zero-write staging rehearsal) and `--keep`
 (leave a verified claimed session running); `--fwsec` is retired.
 
 ### 4.4 Host-side resource-manager client
@@ -321,10 +323,28 @@ per-context scheduling. Tenant policy and fairness are a later layer on top.
   executing the sequencer buffer carried in that event. Clean release is not
   yet possible: the Booter Unload gate requires all four secure scratch14
   handoff bits (24–27), a host-driven boot sets only bit 24, bit 27 is set by
-  the server's shutdown path (host RPC `UNLOADING_GUEST_DRIVER`, not
-  implemented), and host-side seed/unlock is fuse-locked on this part. The
-  live session is therefore left claimed (`--keep`) and a fresh cycle needs a
-  power cycle. See §4.3.
+  the server's shutdown path (host RPC `UNLOADING_GUEST_DRIVER`), and
+  host-side seed/unlock is fuse-locked on this part. The live session is
+  therefore left claimed (`--keep`) and a fresh cycle needs a power cycle.
+  See §4.3.
+* **Update (2026-10-01) — rung 4b implemented (build-only):** the module now
+  produces real command-queue records to GSP-RM and attempts a clean shutdown
+  on release. The producer writes the 48-byte transport element header plus
+  the 32-byte rpc header (signature `0x43505256`, header version `0x03000000`,
+  `rpc.length = 32 + payload`), an XOR-fold 64→32 checksum over the
+  zero-padded record that makes a consumer's fold read zero, an incrementing
+  sequence number, and publishes the wrap-around `writePtr` under a DMA write
+  barrier before ringing the queue-head doorbell at `0x110c00`. The shutdown
+  RPC is `UNLOADING_GUEST_DRIVER` (function 47) with `bInPMTransition=0`,
+  `bGc6Entering=0`, `newLevel=0`; the wait criterion is the GSP falcon
+  mailbox0 reading `0x80000000` (processor-suspended), bounded at 10 s. On a
+  release the RPC runs once (only when the full boot stage ran) before the
+  existing quiesce/FWSEC teardown; without a full boot the fail-safe
+  behaviour is unchanged. A write-only debugfs trigger
+  (`open-iov-vfio/gsp-phys-unload-rpc`, write "1") lets a live claimed
+  session test the shutdown without touching WPR2. All of it is inert unless
+  the full boot stage ran; the code has not yet run live, and this bullet
+  must be updated with the live outcome.
 
 ## 9. Interaction sequence (end state)