plugin-gpu

Placement	compiled-in (in-process)
Source	github.com/opencharly/plugin-gpu/candy/plugin-gpu
Version	2026.182.0001
Candy	plugin-gpu

This plugin is listed in charly/charly.yml’s compiled_plugins:, so its providers are compiled into the charly binary and register in-process.

Providers

The reserved words this plugin serves:

• gpu — verb class

What it does

GPU/VFIO HOST-DETECTION plugin (cutover C11) — the sysfs/exec probing charly core formerly held in charly/devices.go: NVIDIA-usable-via-CDI detection (nvidia-smi + CDI-spec/nvidia-ctk reachability), AMD-GPU + GFX-version detection (amdgpu DRM + KFD topology), VFIO passthrough readiness (IOMMU groups, per-function PCI scan, display-class GPU + IOMMU-group members), host-device auto-detection (device_patterns glob + real-GPU render-node pick), user-scope CDI-spec generation, and the RLIMIT_MEMLOCK + /dev/vfio group-access passthrough-readiness probes.

Carved out of charly core behind thin in-core resolve+Invoke shims (originally DetectGPU / DetectAMDGPU / DetectVFIO / DetectHostDevices / EnsureCDI / MemlockLimitBytes / VfioGroupAccessible + detectAMDGFXVersion, in charly/gpu_shim.go). K5 seam-death + K-wave 2 cone R3 shrank that set to just DetectVFIO — the operator-dropped GPU-host-DETECTION exception leg (gpu_allocate.go’s bedGPUPrereqMissing, reached via the check-bed-gpu-prereq seam); DetectHostDevices/EnsureCDI relocated to candy/plugin-deploy-pod (detect_devices.go) as peer InvokeProvider verb:gpu dispatches. Every OTHER former core caller (charly doctor, the arbiter, charly vm gpu, the pod config/start/shell paths) peer-InvokeProviders verb:gpu directly. The detection RESULT types (VFIOReport/VFIOGpu/VFIOPCIDevice/DetectedDevices) live in package spec, read directly by every consumer (no core alias).

Compiled-in (an in-proc inprocProvider): the deploy/config hot paths call the shims many times, and MemlockLimitBytes must read charly’s OWN process RLIMIT_MEMLOCK — both require in-process placement. The three static data tables (device_patterns / gpu_vendors / pci_class_labels) are this plugin’s OWN embed now (data.go/data.yml) — plugin-gpu is the only actual detection consumer, so it is the one data source (R3), not charly-core; no caller threads them through spec.GpuProbeInput any more.

The DRIVER-SWITCH (vfio<->nvidia rebind) now ALSO lives here (cutover C9, 1B): switchGPUDriverMode / gpuSwitchModeTolerant / groupInMode / currentGPUMode / gpuDisplayDriver / gpuWedgeDetected / ensureCDIRoot + the switch-plan DRY-RUN, served over verb:gpu’s OpRun DRIVER-SWITCH actions (spec.GpuSwitchInput/GpuSwitchReply) beside the C11 detection actions. Every DRIVER-SWITCH consumer dispatches verb:gpu directly — charly vm gpu (candy/plugin-vm’s vm_gpu_shim.go), the arbiter (candy/plugin-preempt’s holder_dispatch.go), and plugin-gpu’s own switch legs — there is no in-core driver-switch shim left. Auto-allocation (gpu_allocate.go) STAYS core: it is a host-side VmSpec/LibvirtDomain orchestrator consuming the DetectVFIO shim — no dep to shed.

The R10 witness: charly vm gpu status/list/plan exit 0 host-side on a GPU-less host (DetectGPU/DetectVFIO + the switch-plan DRY-RUN dispatch through verb:gpu); the vfio<->nvidia FLIP itself stays gated by the cachyos GPU beds (functionality, not externalization).

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/gpu.cue

// plugin-gpu's OWN self-contained CUE schema — the plugin's declaration
// surface, served over Describe exactly like every other plugin's schema
// (there is no schema-less plugin):
//
//  1. SERVE over Describe — the host splices `base ++ plugin` at the load gate
//     (registerPluginUnitSchema), so the plugin's declarations travel WITH it and
//     a self-contained schema that will not splice is a LOUD load failure.
//  2. DOCUMENT — `charly docs generate` renders this plugin's page from its
//     providers + this schema + the candy `description:`.
//
// verb:gpu's authored input is NOT a plugin_input: callers resolve the word and Invoke
// OpRun with a structured spec.GpuProbeInput (detection) or spec.GpuSwitchInput
// (driver switch), so this schema DOCUMENTS the verb contract (no #*Input def).
// SELF-CONTAINED: it references no base def, so it compiles STANDALONE (the property
// that lets the SDK compile it serve-side).
#GpuPlugin: {
  // The capability word the plugin serves.
  verb: "gpu"

  // What the verb does, in one line (the public-docs surface): detect host GPU /
  // VFIO state and switch the NVIDIA driver binding.
  contract: string & !=""
}

---

See also the candy reference for this candy’s install surface.