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) Stream(words []uint32, data []byte, window []byte) error
- type DeviceBackend
- func (b *DeviceBackend) Close()
- func (b *DeviceBackend) Create(kind uint32, desc []byte) (uint32, error)
- func (b *DeviceBackend) Destroy(id uint32)
- func (b *DeviceBackend) Objects() []any
- func (b *DeviceBackend) Read(id uint32, offset uint64, dst []byte) error
- func (b *DeviceBackend) Replay(words []uint32, data []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") )
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
}
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) 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.
type DeviceBackend ¶
type DeviceBackend struct {
// contains filtered or unexported fields
}
DeviceBackend is a Reader on a browser device: objects are made from wire descriptors (webgpu.DecodeDescriptor), streams run with Device.Replay and are waited for, and reads are mapAsync, getMappedRange, copy, unmap. It is the one implementation both transports (go-virtio's gpudev, the WebAssembly host module) share. The device's Quota bounds the memory and pipelines its contexts create; create it with the grant of the tenant.
func NewDeviceBackend ¶
func NewDeviceBackend(dev *webgpu.Device) *DeviceBackend
NewDeviceBackend returns a backend whose objects live on dev. webgpu's replay.js must be installed (webgpu.InstallReplay).
func (*DeviceBackend) Close ¶
func (b *DeviceBackend) Close()
Close implements Backend: it destroys what is left.
func (*DeviceBackend) Create ¶
func (b *DeviceBackend) Create(kind uint32, desc []byte) (uint32, error)
Create implements Backend.
func (*DeviceBackend) Destroy ¶
func (b *DeviceBackend) Destroy(id uint32)
Destroy implements Backend.
func (*DeviceBackend) Objects ¶
func (b *DeviceBackend) Objects() []any
Objects returns the handles the backend holds (for inspection by tests).
Source Files