Documentation
¶
Overview ¶
Package wgpubatch is the wire protocol of the private "webgpu-batch" virtio-gpu context type: guest programs send go-gfx/webgpu Recorder streams to a host that replays them on WebGPU, as Venus does for Vulkan. It defines the capset id, the capset blob a host returns from GET_CAPSET, and the frame that rides as the opaque payload of SUBMIT_3D. Guest and host both import it; it has no GOOS constraint.
The Recorder stream inside a STREAM message, and the descriptor inside a CREATE message, belong to go-gfx/webgpu: this package carries them as opaque words and bytes and never interprets them (one implementation per format).
Status: no host implements this protocol yet. Everything here is checked offline (unit tests and fuzzing) only. See docs/WEBGPU.md.
References: virtio spec device-types/gpu/description.tex :523-545 (capsets), :727-750 (CTX_CREATE.context_init), :764-766 (SUBMIT_3D); Linux virtgpu_kms.c:92-112 and virtgpu_drv.h:59 (capset id range).
Index ¶
Constants ¶
const ( CapsSize = 40 // capset version 1 CapsSizeV2 = 64 // capset version 2 FrameHeaderSize = 16 MessageHeaderSize = 8 )
Sizes on the wire, in bytes.
const ( MsgCreate uint32 = 1 // id, kind, descriptor MsgDestroy uint32 = 2 // ids MsgStream uint32 = 3 // one go-gfx/webgpu Recorder submit MsgBindResource uint32 = 4 // id, resource_id, offset, size )
Message types.
const ( FeatureShaderF16 uint32 = 1 << 1 // "shader-f16" FeatureSubgroups uint32 = 1 << 2 // "subgroups" )
Capset feature bits of the adapter's optional WebGPU features (version 2): granted when the adapter has them and the host enables them on the device. "timestamp-query" is never granted.
const CapsVersion = 2
CapsVersion is the capset blob version this package encodes: 2 appended the adapter's features and limits (Caps.Limits). Frames stay at Version.
const CapsetID uint32 = 30
CapsetID is the capset id of the webgpu-batch context type, carried in the low 8 bits of CTX_CREATE.context_init. The spec reserves no private range; 30 is the highest id Linux guests record correctly (virtgpu_kms.c shifts an int: ids >= 31 corrupt capset_id_mask) and far from the allocated 1..10. See docs/WEBGPU.md, "Capset id".
const FeatureRing uint32 = 1 << 0
FeatureRing is the capset feature bit of the shared-memory ring transport (v2, designed, not implemented).
const Magic uint32 = 0x42504757
Magic opens both the capset blob and every frame: "WGPB" little-endian.
const MaxRings = 64
MaxRings is the number of ring_idx values virtio allows per context (description.tex:289, 0..63 inclusive).
const Version = 1
Version is the protocol version this package encodes and decodes.
Variables ¶
var ErrEncode = errors.New("wgpubatch: cannot encode")
ErrEncode is wrapped by every encoding error.
var ErrFrame = errors.New("wgpubatch: malformed")
ErrFrame is wrapped by every decoding error.
Functions ¶
This section is empty.
Types ¶
type BindResource ¶
BindResource exposes part of a virtio resource attached to the context as an upload or readback window of a guest buffer.
type Caps ¶
type Caps struct {
Version uint32 // capset version, >= 1; Device and the adapter feature bits are carried from 2
StreamVersion uint32 // go-gfx/webgpu Recorder stream version replayed
MaxFrame uint32 // largest SUBMIT_3D payload accepted, bytes
MaxObjects uint32 // live guest objects per context; ids are 1..MaxObjects-1
MaxRings uint32 // timelines per context, <= MaxRings
Features uint32 // FeatureRing, FeatureShaderF16, FeatureSubgroups ...
MaxMemory uint64 // buffer and texture bytes per context
Device DeviceLimits // version 2
}
Caps is the capset blob (GET_CAPSET, capset CapsetID, version 1 or 2).
func DecodeCaps ¶
DecodeCaps reads a capset blob. A longer blob is accepted (a later version may append fields); the reserved word is ignored.
type Create ¶
Create is a CREATE message: a guest-numbered object of a go-gfx/webgpu kind, with its descriptor (opaque here).
type DeviceLimits ¶ added in v0.10.0
type DeviceLimits struct {
MaxStorageBufferBindingSize uint64
MaxComputeWorkgroupStorageSize uint32
MaxComputeInvocationsPerWorkgroup uint32
MaxComputeWorkgroupsPerDimension uint32
MaxStorageBuffersPerShaderStage uint32
}
DeviceLimits are the WebGPU limits of the device a host grants, from capset version 2 on, so that a guest picks kernel variants without an adapter to ask. Zero means "not reported" (a version 1 blob).
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder builds one frame. Methods record the first error and ignore later calls; Frame returns it. Reset reuses the memory.
func NewEncoder ¶
NewEncoder returns an Encoder whose frames stay within maxFrame bytes (Caps.MaxFrame).
func (*Encoder) BindResource ¶
func (e *Encoder) BindResource(r BindResource)
BindResource appends a BIND_RESOURCE message.
type Message ¶
Message is one decoded message; Payload aliases the frame.
func Decode ¶
Decode checks a frame and splits it into messages. The host must copy the frame out of guest memory before calling it: Payloads alias b. Each payload's own layout is checked by the Parse functions, which a host calls next; Decode already rejects unknown types and ids out of range so that a frame either decodes whole or not at all.
func (Message) BindResource ¶
func (m Message) BindResource(lim Limits) (BindResource, error)
BindResource parses a BIND_RESOURCE payload. The host still checks the range against the resource it names, which only it knows.
Source Files