View source for The Execution Frontier

{{About message}}

= The Execution Frontier =

<blockquote>'''What this page is.''' The current leading edge of guest-facing execution: the chain that must fire for a stock guest CUDA kernel to run on the physical GPU, what has been proven about it, where it stops, how we know, and the open lines of investigation and theories. It is evidence-led: every statement carries a live observation, a decompilation finding, or a clearly labelled theory. Condensed from [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/03-execution-frontier.md <code>../docs/04-implementation/03-execution-frontier.md</code>]; the docs tree wins on disagreement.</blockquote>

Status: 2026-10-12 (source page dated 2026-10-06), tree <code>master @ 2f066727</code>. Tags: <code>[live]</code> observed; <code>[wip]</code> partial; <code>[wall]</code> current blocker; theories are labelled as such.

== 1. The chain that should fire ==

A guest CUDA launch becomes a '''method stream''' in a push buffer, referenced by a '''GPFIFO ring entry''', announced by a '''doorbell'''. The host emulation decodes it and forwards an equivalent method stream to a real channel owned by the module's resource-manager session. The hardware '''front-end''' fetches and executes the methods, the launch descriptor ('''QMD''') is materialised and read by the '''GR engine''', the grid is dispatched to the SMs, and completion is published as '''semaphores''' the guest waits on.

<pre>guest: builds launch + method stream
       GPFIFO entry + doorbell
   -&gt; host: doorbell trap, decode, rebuild forward stream,
            prewrite QMD, ring/USERD, doorbell
   -&gt; front-end: fetch GPFIFO entry (ring cursor advances)
   -&gt; front-end: execute methods (object bind, cache ops, report sem)
   -&gt; front-end: install inline QMD into the descriptor buffer
   -&gt; GR engine: read QMD through the channel's page tables
   -&gt; context switch loads the channel context (FECS/ucode)
   -&gt; GR: dispatch grid to the SMs
   -&gt; engine authors release semaphore + channel semaphore
   -&gt; host polls release, relays to guest; CUDA wakes</pre>

{| class="wikitable"
|-
! #
! Stage
! State
|-
| 1
| Guest builds launch + method stream
| <code>[live]</code> observed (stock driver, unmodified)
|-
| 2
| GPFIFO entry + doorbell
| <code>[live]</code> observed
|-
| 3
| Host decode + forward stream + QMD prewrite + ring/USERD
| <code>[live]</code> observed
|-
| 4
| Front-end fetches the ring entry
| <code>[live]</code> observed (ring cursor advances)
|-
| 5
| Front-end executes methods
| <code>[live]</code> observed (object bind, cache ops, report semaphore)
|-
| 6
| '''Inline-QMD install''' (descriptor materialised)
| <code>[wall]</code> not observed
|-
| 7
| '''Engine reads the QMD'''
| <code>[wall]</code> not observed
|-
| 8
| Context switch loads the channel context
| <code>[live]</code> context validity at dispatch is ruled in
|-
| 9
| GR dispatches the grid to the SMs
| never observed on this stack
|-
| 10
| Engine authors release + channel semaphore
| absent for forwarded launches
|-
| 11
| Host relays completion; guest wakes
| the guest waits and times out
|}

'''One-line summary:''' the guest, the emulation, the forwarding path and the front-end are live; the '''launch-descriptor install path''' (stages 6–7) is the leading edge, and with it stages 9–11.

== 2. Where the leading edge is ==

A stock guest program now reaches its kernel launch and submits it through the forwarding path. On the wire the ring entry is consumed and the front-end methods run — but the launch descriptor is never materialised, the engine never reads a QMD, no engine-authored completion appears, and the guest blocks in its synchronisation wait.

This is '''not''' a context-validity wall (ruled out at dispatch) and '''not''' a window-mapping wall for the descriptor destination (that install is accepted). The wall is the '''form of the launch method stream''': what the front-end requires in order to install the inline descriptor, and what the engine requires in order to read and dispatch it.

== 3. How we know (observables and their limits) ==

{| class="wikitable"
|-
! Observable
! What it proves
! What it does not prove
|-
| Ring entry consumed; ring cursor advances
| the front-end is alive and fetching
| nothing about the engine
|-
| Method execution on the ladder channel
| the front-end can execute the method vocabulary
| '''not''' engine execution — these signals can be front-end-authored
|-
| Descriptor buffer prewritten with a detectable sentinel
| whether the descriptor was materialised after submission
| a read does not modify memory; the sentinel detects installs, not reads
|-
| Install sentinel unchanged after submit
| the inline-install method did not run
| it does not say why
|-
| Engine-authored release word absent; poll times out
| the engine did not complete the launch
| it does not say whether the engine started
|-
| No GR fault recorded
| the engine did not raise this error
| silence is not health: a skipped launch is silent by construction
|-
| Channel instance context flag set
| the channel is context-valid at dispatch
| nothing about the descriptor path
|}

'''Consequence:''' progress on this frontier must be measured by an '''engine-authored''' signal (the release word advancing) — not by front-end signals, which we have already learned to distinguish.

== 4. What is exonerated (do not relitigate) ==

* Context validity at dispatch — the channel's context is valid when the launch is submitted (instance flag set).
* The descriptor destination window mapping — installed in the engine's table view at submit.
* Front-end fetch and control-block alignment — the entry is consumed with the host control block at offset 0.
* The shared context-buffer one-shot rule — traced to a shared per-GPU buffer already initialised in the same cycle; not the dispatch delta.
* Parenting/TSG for the fetch — both variants fetch identically.
* The copy-engine path — CE-class work, releases and fault relay are live (default off); the GR path is a separate problem.

== 5. The clear issues (ranked) ==

'''Issue A — the forwarded stream carries a verbatim guest prelude that cannot complete.''' The forwarded stream includes a verbatim copy of the guest's prelude whose inline-data writes target addresses not present in the engine's view of the channel's page tables, and the referenced data is not relocated. The shorter, proven stream shape fires its tail (channel semaphore) but still does not schedule the descriptor.

'''Issue B — the descriptor-virtualization control method is absent.''' The method that arms the inline-descriptor install path is not present in the forwarded stream. Fixing it should materialise the descriptor — falsifiable in one cycle by watching the sentinel and the engine-read signal.

'''Issue C — diagnostic hygiene.''' The sentinel placed at word 0 overlaps real descriptor fields; it must be moved to an unused word so diagnostics do not perturb what they measure.

== 6. Lines of investigation (live) ==

# '''Restore the proven launch shape''' as the baseline and '''re-add the virtualization control method''' — one variable at a time, with the install sentinel and the engine-read signal as the readout.
# '''Relocate or drop the verbatim prelude''' so inline-data writes target addresses present in the engine's view, or replace it with the host-side staging the proven shape already uses.
# '''Move the sentinel''' and re-run to confirm the readout is clean.
# '''Diff against a known-good reference''' — our own ladder dispatching a descriptor built from the same source material, or a captured working launch of the stock stack on the same GPU — converting the remaining work from inference to differential.
# '''Offline probing''' of any rule the front-end or engine is believed to require, using the firmware debugger before spending a supervised cycle ([[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]]).

== 7. Theories (labelled; not yet proven) ==

* '''T1 — the virtualization control is the gate.''' The front-end will not materialise an inline descriptor until the control method enables the install path.
* '''T2 — materialise-then-read.''' The engine only schedules a descriptor that exists in its own view; an install targeting unmapped destinations aborts silently rather than faulting.
* '''T3 — the verbatim prelude poisons the launch.''' Its refused writes leave the launch path unable to schedule the descriptor.
* '''T4 — relocation is the missing transform.''' The guest's descriptor is valid for the guest's view of memory; the forwarding path must relocate referenced data into the channel's view before install.

Each theory has a one-cycle falsifier: the install sentinel, the engine-read signal, and the engine-authored release, in that order.

== 8. Claim discipline ==

* '''Engine-authored release is the only proof of execution.''' Front-end signals are necessary but not sufficient.
* '''Silence is not health.''' No fault recorded does not mean no fault occurred.
* '''Emulator verdicts are instruction/memory-level.''' They bound behaviour, never timing or device environment.
* '''A wall is closed only by an acceptance signal''', named before the experiment.

== 9. Related pages ==

* [[Project Status|<code>Project-Status.md</code>]] — the project-level ladder.
* [[CUDA Userspace Driver|<code>CUDA-Userspace-Driver.md</code>]] — the guest-side client path.
* [[Physical GPU Backend and Guest Wiring|<code>Physical-GPU-Backend.md</code>]] — the backend the work is forwarded to.
* [[The vGSP Execution Plane (vEP)|<code>Execution-Plane.md</code>]] — the execution layer's design.
* [[Introduction to GMMU|<code>Introduction-to-GMMU.md</code>]] — page tables, QMDs and the engines.
* [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/03-execution-frontier.md <code>../docs/04-implementation/03-execution-frontier.md</code>] — the canonical, continuously-updated version with the full evidence tables.