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 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 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 // protocol version, >= 1
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 ...
MaxMemory uint64 // buffer and texture bytes per context
}
Caps is the capset blob (GET_CAPSET, capset CapsetID, version 1).
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 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