Skip to content

Driver API: Streams & Events

Stream and event objects, stream ops, and host-side waits. See Driver API for the concepts.

Contents

Name Kind Description
ha_drv_obj_create API Create a stream or an event
ha_drv_stream_post API Enqueue one op on a stream
ha_drv_wait API Wait on or query a stream, event or device
ha_drv_obj_destroy API Destroy a stream or an event

ha_drv_obj_create

Create a stream or an event on dev.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.
kind in — HA_OBJ_STREAM or HA_OBJ_EVENT. See HaDrvObjKind.
out out — Receives the handle; pass &stream (HaStream_t) or &event (HaDrvEvent) cast to void**.

Returns — HaSuccess; HaInvalidArgument if dev/out is null or kind is unknown; HaDeviceNotReady if a reset is in progress; or the underlying stream error.

Signature · Example
1
HaError ha_drv_obj_create(HaDrvDev dev, HaDrvObjKind kind, void **out);

Example

1
2
3
4
5
HaStream_t stream = HA_STREAM_DEFAULT;
ha_drv_obj_create(dev, HA_OBJ_STREAM, reinterpret_cast<void **>(&stream));

HaDrvEvent ev = nullptr;
ha_drv_obj_create(dev, HA_OBJ_EVENT, reinterpret_cast<void **>(&ev));

ha_drv_stream_post

Queue one op on stream; it runs in sequence-number (seq) order with the stream's other ops and launches. Returns once queued, not once run. An execution failure becomes the stream's sticky error and surfaces at the next ha_drv_wait.

Event kinds: HA_STREAM_OP_RECORD_EVENT records an event at most once (a second record is HaEventInvalidArgument) and makes it the event's position for ha_drv_wait(HA_WAIT_EVENT_*) and later waits. HA_STREAM_OP_WAIT_EVENT needs a recorded event and rejects a stream waiting on its own record (HaStreamInvalidArgument, it would never complete).

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.
stream in — Stream owned by dev (from ha_drv_obj_create), or HA_STREAM_DEFAULT.
op in — Op to queue; copied, so it need not outlive the call. See HaDrvStreamOp.
out_seq out — Optional; receives the op's per-stream seq on success. Untouched on failure.

Returns — HaSuccess if queued; HaInvalidArgument if dev/op is null or op has an unknown kind or direction or a null event; HaDeviceUnsupported if dev cannot execute ops; HaDeviceNotReady if a reset is in progress; HaStreamInvalidHandle if stream is not owned by dev; HaEventInvalidHandle if the event is not a live event of dev; HaEventNotRecorded for a wait on an unrecorded event; or the stream's sticky error if a prior op failed. No seq is consumed on failure.

Signature · Example
1
HaError ha_drv_stream_post(HaDrvDev dev, HaStream_t stream, const HaDrvStreamOp *op, uint64_t *out_seq);

Example

1
2
3
4
5
6
7
HaDrvStreamOp op{HA_STREAM_OP_MEMCPY, {}};
op.memcpy = {dst, src, n, HaMemCpyDirection::DeviceToDevice};
ha_drv_stream_post(dev, HA_STREAM_DEFAULT, &op, nullptr);

HaDrvStreamOp free_op{HA_STREAM_OP_FREE, {}};
free_op.free.ptr = src;                          // returned at a sync after the preceding copy finishes
ha_drv_stream_post(dev, HA_STREAM_DEFAULT, &free_op, nullptr);

ha_drv_wait

Block on or query a stream, an event or the whole device from the host. No wait kind covers work posted after the call. To make a stream wait on an event, post HA_STREAM_OP_WAIT_EVENT instead.

  • Stream kinds (stream a stream of dev or HA_STREAM_DEFAULT, event null): HA_WAIT_STREAM_SYNC reserves the stream's next seq and blocks until every op posted before it has completed on the device; on success it also returns the stream's HA_STREAM_OP_FREE allocations that the sync covered to the pool. HA_WAIT_STREAM_QUERY does not block: it returns the stream's sticky error if a prior op failed, else HaSuccess when idle or HaStreamNotReady while work is pending.
  • Event kinds (event set, stream HA_STREAM_DEFAULT): HA_WAIT_EVENT_SYNC blocks until the record op has been issued to the device, then until it completes. HA_WAIT_EVENT_QUERY does not block: HaSuccess once complete, HaEventNotReady while the record is pending. Both return HaEventNotRecorded for an event never recorded.
  • Device kind (stream HA_STREAM_DEFAULT, event null): HA_WAIT_DEVICE_SYNC synchronizes, as HA_WAIT_STREAM_SYNC does, every stream dev has at the call — explicit streams, every thread's default stream, and default streams whose thread has exited — and returns the first error (a stream destroyed meanwhile is skipped). HaDeviceNotReady if a device reset completed meanwhile.
Parameter Direction Default Description
dev in — Device handle from ha_drv_open.
stream in — Stream handle (or HA_STREAM_DEFAULT) for the stream kinds, else HA_STREAM_DEFAULT.
event in — Event handle for the event kinds, else null.
kind in — What to wait on and whether to block. One of HA_WAIT_STREAM_QUERY, HA_WAIT_STREAM_SYNC, HA_WAIT_EVENT_QUERY, HA_WAIT_EVENT_SYNC, HA_WAIT_DEVICE_SYNC (see HaDrvWaitKind).
timeout_ms in — SYNC kinds only; a negative value waits indefinitely.
out_synced_seq out — HA_WAIT_STREAM_SYNC only, optional: the seq the sync reserved. Ops with a smaller seq are covered by it (e.g. an HA_STREAM_OP_MARKER's out_seq). Written before blocking, so it is set even when the sync fails.

Returns — HaSuccess; HaInvalidArgument if dev is null, kind is unknown, an event kind gets a stream or no event, a stream kind gets an event, or the device kind gets either; HaDeviceNotReady if a reset is in progress or raced the wait; HaStreamInvalidHandle / HaEventInvalidHandle if the object is not owned by dev; otherwise the sticky, sync or query error.

Signature · Example
1
2
HaError ha_drv_wait(HaDrvDev dev, HaStream_t stream, HaDrvEvent event, HaDrvWaitKind kind, int timeout_ms,
                    uint64_t *out_synced_seq);

Example

1
2
3
ha_drv_wait(dev, stream, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);               // one stream
ha_drv_wait(dev, HA_STREAM_DEFAULT, ev, HA_WAIT_EVENT_SYNC, -1, nullptr);          // event
ha_drv_wait(dev, HA_STREAM_DEFAULT, nullptr, HA_WAIT_DEVICE_SYNC, -1, nullptr);    // whole device

ha_drv_obj_destroy

Destroy a stream or an event owned by dev. A stream is released after the work posted to it finishes. An event's handle is invalid as soon as this is called; if it was recorded, the call first waits for the record to be issued to the device (the queued record op still uses it), then releases it.

Parameter Direction Default Description
dev in — Device handle from ha_drv_open.
kind in — HA_OBJ_STREAM or HA_OBJ_EVENT. See HaDrvObjKind.
obj in — Handle from ha_drv_obj_create (cast from HaStream_t or HaDrvEvent).

Returns — HaSuccess; HaInvalidArgument if dev is null or kind is unknown; HaDeviceNotReady if a reset is in progress (the reset frees the object); HaStreamInvalidHandle / HaEventInvalidHandle if obj is not a live object of dev; HaStreamNotReady if a recorded event's record was not issued in time, in which case the event is not released.

Signature · Example
1
HaError ha_drv_obj_destroy(HaDrvDev dev, HaDrvObjKind kind, void *obj);

Example

1
2
3
ha_drv_wait(dev, stream, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);
ha_drv_obj_destroy(dev, HA_OBJ_STREAM, stream);
ha_drv_obj_destroy(dev, HA_OBJ_EVENT, ev);  // ev is invalid from this point