Targets, devices and pairings#

A learning system in Alpha never names a GPU in its model or learner. It meets a device in exactly one place: a pairing, which names one system and one device profile and asks a compiler-checked question, does this device supply everything this build demands? This page explains the three pieces, where each lives, and what happens when the answer is no.

The three pieces#

Device facts live in the profile, requirements live in the system, and admission compares the two. A pairing never restates a fact; if it did, the comparison could not fail.

Target packages#

The host CPU targets are part of the compiler itself: alpha build --target x86_64-linux (the default) and --target aarch64-linux. AArch64 emits through the direct lowering lane only, so it needs --direct. A target name the compiler knows but cannot emit is refused with what it is missing, and an unknown name is refused as unknown; both exit with status 4.

Hopper (sm_90) has no architecture package yet. The H100 appears as a RunPod card profile, and its instruction lowering currently lives in the bootstrap compiler.

Device profiles#

A device enters Alpha as a profile, not as assumptions inside a system. Every fact in a profile carries its evidence:

• Architectural: taken from an ISA manual, a datasheet or a driver header, which the profile cites.
• Measured: established by a recorded run on the device, which the profile cites.
• Modelled: computed from a checked model.

A fact nobody has established is absent, never guessed from a neighbouring device. Safety facts that a checker relies on (register limits, barrier rules) are kept apart from performance estimates, which only rank candidates.

On the Linux/NVIDIA platform these are NvidiaEvidence values (Architectural, Measured, Modelled) attached to NvidiaSupply records: a name, an amount and its evidence. The RTX 3070 and RTX 3090 profiles in Platform.RunPod.Nvidia.SM86 supply, for example:

The DGX Spark profile (Platform.DGXSpark.Profile) records one measured machine. It deliberately sets the SM86 command-stream capabilities to zero, so any build that demands an Ampere command stream is refused on it rather than run.

The Hardware page lists every device with its current status and evidence.

Admission: demands against supplies#

A build computes its demands from what it actually contains. Platform.Linux.Nvidia.Compatibility defines them:

• nvidiaPlanDemands derives instruction-set, registers-per-thread, threads-per-block, shared-bytes-per-block and video-memory-bytes from the plan's device regions.
• nvidiaHostDemands adds the host's needs: the driver-branch its ioctl layouts are written for, the compute-class, and unified-memory when the host uses UVM.

Each demand has a kind (ABI, feature or resource), a bound (exactly, or at least) and an amount. nvidiaCompatibilityRefusal demands supplies walks the demands in order and returns the name of the first one the supplies do not meet; an empty name means the device is admitted.

The refusals are themselves tested. Proof.CoppeliusCompatibility shows a profile without unified memory refused as unified-memory, a profile without shared-bytes-per-block refused by that name, and an sm_89 build on an Ampere profile refused as instruction-set. The compatibility-contract gate adds executed mutants that drop UVM, shrink memory and change the driver branch.

A pairing, read end to end#

Coppelius.Build.RTX3090 pairs the Coppelius system with the RTX 3090 profile:

1. It imports the profile (Platform.RunPod.Nvidia.SM86) and the system's derived host (Coppelius.Build.NativeHost).
2. coppeliusRTX3090CompatibilityRefusal applies nvidiaCompatibilityRefusal to the system's demands and the card's supplies.
3. coppeliusRTX3090ExactTargetAccepted requires three things at once: no refusal, an exact product and memory match, and SM86 capability admission.
4. It builds the target plan: target identity, the command schedule, the output name, and the artifact root RTX3090Artifact.alpha.

Other systems follow the same shape: one module per device beside the system's build (RTX3070.alpha, RTX3090.alpha, RTX4090.alpha, GB10Artifact.alpha).

When admission fails, the derived host produces no bytes, and the build refuses an empty artifact. There is no partial executable, no warning-and-continue, and no fallback to another device or to the CPU.

The derived host#

The program that drives the GPU from the CPU side is not written by hand. A system's Build/NativeHost.alpha declares:

• its memory layout (command queues, command buffers, semaphores, program, data buffers);
• the per-card host target;
• the launch-table recipes the host fills at start-up;
• a typed request schedule (submit, repeat, read, write, reissue);
• the host-side scalars its learner needs;
• the contracts the host must meet, and its compatibility demands.

Platform.Linux.Nvidia.PlanHost and PlanHostRequest then derive the program from that declaration:

• the whole channel protocol: open the card, create the driver objects and the channel, ring the doorbell, wait on fences;
• a self-check that hashes the running executable against its manifest;
• the request record, recipe expansion and the schedule.

Coppelius.Build.NativeHost is the template. A new platform gets its own plan host beside this one, not a copy inside a system.

Adding a device or a target#

1. Write the profile first. Every fact is architectural, measured or modelled, with its source. Measure the ceilings (sustained bandwidth, peak throughput per numeric format, launch and transfer overhead) with small probes built by the Alpha compiler, and commit the run records under tests/observability/import/<device>/.
2. Bring a checked model before kernels. A realization is tested by running it on its target's checked model under reference/target-models/checked/<target>/ (for example SM86.MachineModel, SM86.WarpModel). No build closure may include these models; they exist to be checked against.
3. Add a target package beside the existing ones. It owns encoders, command streams and its plan host, and it must not leak into model or learning semantics.
4. Pair a system with it. Write the per-device build module, and let admission decide.

Missing target support, an unknown ABI, a shape mismatch or an unavailable lowering is a compile error. Alpha does not substitute a CPU path, a framework or a vendor runtime for a missing GPU operation. The Strix Halo bring-up plan (docs/CHLOE-STRIX-HALO-BRINGUP.md) shows the staging for a new vendor.

Read next#

• Hardware: every device, its status and its evidence.
• Hybrid hosts and multiple GPUsDistributed · explanationHybrid hosts and multiple GPUsOne executable per role and target, x86-64 and AArch64 participants, binding a GPU by UUID, unequal devices, and memory admission across processes.: several devices, hosts and instruction sets in one run.
• Anatomy of a learning systemBuild · explanationAnatomy of a learning systemA system taken apart: model, learner, run policy and pairing, the build directory, and how to build, run and test it.: what a system is made of before it meets a device.
• Evidence and statusEvaluate · analysisEvidence and statusHow to read checked, run and measured claims, and what each one does not establish.: what checked, run and measured each establish.