Documentation
¶
Overview ¶
Package batch is the host side of a batched GPU command stream, without a transport: the table of a guest's object ids, the creation and destruction of its objects, the replay of its streams and, for streams that read back (wire.ReadBuffer), the bounded read window.
A guest records with a remote device (webgpu.NewRemoteDevice) or a webgpu.Recorder and sends three kinds of message: create an object from a wire descriptor, destroy objects, run a stream. A transport — go-virtio's webgpu-batch frames over virtio-gpu, a WebAssembly host module — decodes its own framing and calls Context's three methods; the semantics are here once. The ids a guest uses are private to its Context and are translated (wire.Remap, wire.RemapDescriptor) to the ids the Backend returned before the Backend sees anything, so a stream can only name objects its own context created.
The package is portable: the Backend that runs the work is what needs a GPU (a browser device, a native one, or a test's recording fake).
Index ¶
- Constants
- Variables
- type Backend
- type Config
- type Context
- func (c *Context) Close()
- func (c *Context) Create(id, kind uint32, desc []byte) error
- func (c *Context) Destroy(ids ...uint32) error
- func (c *Context) Live() int
- func (c *Context) Lookup(id uint32) (uint32, bool)
- func (c *Context) Lost() error
- func (c *Context) PeakDispatchInvocations() uint64
- func (c *Context) PeakInvocations() uint64
- func (c *Context) Stream(words []uint32, data []byte, window []byte) error
- type Reader
Constants ¶
const DefaultMaxRead = 1 << 20
DefaultMaxRead is the read window a Config without MaxRead grants, 1 MiB.
Variables ¶
var ( // ErrRefused: a message the context's own state refuses (an id in use, // an unknown kind, an id not live). ErrRefused = errors.New("batch: message refused") // ErrLost: the context failed earlier and accepts nothing more. ErrLost = errors.New("batch: context lost") // ErrRead: a read-back the context refuses: no window, a buffer that is // unknown or lacks MAP_READ, a range outside the buffer or the window, // a window or reads above the quota. ErrRead = errors.New("batch: read-back refused") // ErrInvalid: the GPU refused an object the guest described: WGSL that // does not compile, a pipeline or bind group that fails WebGPU validation. // The error carries the browser's message (the WGSL line and column). ErrInvalid = errors.New("batch: the GPU refused the object") )
Errors. Every refusal wraps one; after any error the Context is lost.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend interface {
// Create makes an object of a wire kind from its descriptor (object
// references already translated) and returns the id the backend's
// replayer knows it by (nonzero).
Create(kind uint32, desc []byte) (id uint32, err error)
// Destroy releases an object Create returned.
Destroy(id uint32)
// Replay executes one stream whose ids are all ids Create returned, and
// returns once the GPU has executed it.
Replay(words []uint32, data []byte) error
// Close releases everything the backend holds for the context.
Close()
}
Backend runs a context's work. A Context has checked and translated everything it passes: ids are the ones Create returned.
type Config ¶
type Config struct {
// MaxObjects, if nonzero, bounds the guest ids: a guest id is in
// [1, MaxObjects).
MaxObjects uint32
// MaxRead bounds the read window of one stream: the window a caller
// passes, and the bytes the stream's reads return together. 0 is
// DefaultMaxRead; it is capped at wire.MaxReadWindow.
MaxRead uint32
// MaxWorkgroups bounds a Dispatch's counts per dimension; 0 is
// wire.DefaultMaxWorkgroups (WebGPU's default limit).
MaxWorkgroups uint32
// WorkgroupInvocations is the most invocations one workgroup can hold,
// the device's maxComputeInvocationsPerWorkgroup (0: 256, WebGPU's
// default). A Dispatch is counted at its workgroup counts times this.
WorkgroupInvocations uint32
// MaxDispatchInvocations bounds one Dispatch, and MaxStreamInvocations
// the Dispatches of one stream together, in invocations (0: no bound);
// see wire.CheckInvocations. A DispatchIndirect is not counted.
MaxDispatchInvocations, MaxStreamInvocations uint64
}
Config bounds a Context.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is one guest's objects on a Backend. It is not safe for concurrent use.
func (*Context) Close ¶
func (c *Context) Close()
Close forgets every object and closes the backend, which releases whatever it holds for the context.
func (*Context) Create ¶
Create makes guest object id of a wire kind from a descriptor (which is translated in place: pass a copy the caller does not keep).
func (*Context) Lookup ¶
Lookup returns the backend's id for guest object id, for a transport that gives an object more than the three messages do (virtio's BIND_RESOURCE).
func (*Context) PeakDispatchInvocations ¶ added in v0.11.0
func (*Context) PeakInvocations ¶ added in v0.11.0
PeakInvocations is the most invocations one stream of this context asked for (wire.CheckInvocations' total): what a stream quota would have to allow. PeakDispatchInvocations is the largest single Dispatch: what a dispatch quota would have to allow.
func (*Context) Stream ¶
Stream runs a guest's stream: its ids are translated in place, so words must be memory the caller owns (a copy of the guest's). Its ReadBuffer commands, checked before anything runs, are served after the replay into window, which the caller owns and the stream writes only inside; a stream that reads needs a window, and a Backend that is a Reader.
Source Files