Documentation
¶
Overview ¶
Package batchsink is the guest side of the host module wasi_webgpu_batch (package gpubatch): a webgpu.ReadSink over its four imports, so that a wasip1 Go program writes against the go-gfx/webgpu API unchanged.
s, err := batchsink.Open() // caps + context_create
dev := s.Device("my-container") // a webgpu remote device on the sink
... CreateBuffer, NewRecorder, Dispatch, ReadBuffer, Submit ...
The sink batches. Object creations and destructions are not sent when they happen: they are appended to the frame being built (go-virtio/gpu's wgpubatch.Encoder) and travel with the next Submit, which appends its stream and crosses into the host once, with the read window the stream's ReadBuffer commands fill. One Submit is one crossing; a frame that would exceed the host's max_frame is sent early, so a program that uploads weights in chunks pays one crossing per chunk.
Errors the host reports lose the context (the host releases what it held); every later call returns the same error.
Outside GOOS=wasip1 the package builds and Open returns ErrUnavailable; tests drive a Sink over any host with NewSink.
Index ¶
- Constants
- Variables
- type Errno
- type Error
- type ErrorReporter
- type Host
- type Sink
- func (s *Sink) Caps() wgpubatch.Caps
- func (s *Sink) Close() error
- func (s *Sink) Create(id uint32, kind wire.Kind, desc []byte) error
- func (s *Sink) Destroy(id uint32) error
- func (s *Sink) Device(label string) *webgpu.Device
- func (s *Sink) Err() error
- func (s *Sink) Flush() error
- func (s *Sink) Raw(frame, window []byte) error
- func (s *Sink) Submit(words []uint32, data []byte) error
- func (s *Sink) SubmitRead(words []uint32, data []byte, window []byte) error
- func (s *Sink) Submits() int
Constants ¶
const MaxRead = 1 << 20
MaxRead is the host's read window per submit (gpubatch.DefaultLimits).
Variables ¶
ErrUnavailable: there is no wasi_webgpu_batch module here (not a wasip1 program).
Functions ¶
This section is empty.
Types ¶
type Errno ¶
type Errno uint32
Errno is the host module's result code (gpubatch.Errno).
const ( Success Errno = 0 InvalidArgument Errno = 1 Denied Errno = 2 // no gpu capability: run --gpu Unsupported Errno = 3 // no GPU here, or only a fallback adapter TooLarge Errno = 4 QuotaExceeded Errno = 5 Refused Errno = 6 // the frame or stream was refused; the context is lost ContextLost Errno = 7 Timeout Errno = 8 // a submit overran its time budget; the device is destroyed and the grant revoked Fault Errno = 9 Failed Errno = 10 InvalidShader Errno = 11 // WGSL that does not compile, or an object WebGPU rejects; the context is lost, Error.Msg says why Revoked Errno = 12 // an earlier submit overran its budget: no GPU for the rest of the container's life Reserved Errno = 13 // the guest used the bind group the host reserves for its loop budget (group 3); the context is lost Unbounded Errno = 15 // the host cannot bound the module's loops, so it did not run it; the context is lost, the grant is kept Truncated Errno = 14 // a shader hit the host's loop budget and was cut: its results are partial; the context is lost and the grant revoked )
Errno values of wasi_webgpu_batch.
type Error ¶
type Error struct {
Op string
Errno Errno
// Msg is the host's message for the failure (last_error): for
// InvalidShader, the WGSL compiler's text with line and column.
Msg string
}
Error is a host error.
type ErrorReporter ¶ added in v0.9.0
ErrorReporter is implemented by a Host that can say why its last call failed (the wasi_webgpu_batch import last_error). A Sink asks it after a failed submit and puts the message in the Error.
type Host ¶
type Host interface {
Caps(buf []byte) Errno
ContextCreate() (ctx uint32, e Errno)
// Submit sends a frame; the host fills read before returning.
Submit(ctx uint32, frame, read []byte) Errno
ContextDestroy(ctx uint32) Errno
}
Host is the four imports of wasi_webgpu_batch, over Go slices.
type Sink ¶
type Sink struct {
// contains filtered or unexported fields
}
Sink is a webgpu.ReadSink on one host context.
func Open ¶
Open returns ErrUnavailable: only a wasip1 program has the host module. NewSink drives a Sink over any Host.
func (*Sink) Caps ¶
Caps is what the host granted: frame and object limits, the GPU memory quota, the optional features (wgpubatch.FeatureShaderF16, FeatureSubgroups) and the device limits.
func (*Sink) Close ¶
Close sends what is pending and destroys the host context. The Sink is unusable afterwards.
func (*Sink) Create ¶
Create implements webgpu.RemoteSink: the creation travels with the next Submit (or Flush).
func (*Sink) Device ¶
Device returns a go-gfx/webgpu device that records into the sink, with the checks and the GPU memory quota of the host's grant applied at the call.
func (*Sink) Raw ¶
Raw sends frame as it is, with a read window, bypassing the encoder: for tools and tests that must send a frame the encoder would not build. Pending messages are sent first.
func (*Sink) Submit ¶
Submit implements webgpu.RemoteSink: one crossing, which returns once the GPU has executed the stream.
func (*Sink) SubmitRead ¶
SubmitRead implements webgpu.ReadSink: Submit, then the stream's ReadBuffer commands have filled window (at most MaxRead bytes).
Source Files