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 | |
Example
1 2 3 4 5 | |
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 | |
Example
1 2 3 4 5 6 7 | |
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 (
streama stream ofdevorHA_STREAM_DEFAULT,eventnull):HA_WAIT_STREAM_SYNCreserves 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'sHA_STREAM_OP_FREEallocations that the sync covered to the pool.HA_WAIT_STREAM_QUERYdoes not block: it returns the stream's sticky error if a prior op failed, elseHaSuccesswhen idle orHaStreamNotReadywhile work is pending. - Event kinds (
eventset,streamHA_STREAM_DEFAULT):HA_WAIT_EVENT_SYNCblocks until the record op has been issued to the device, then until it completes.HA_WAIT_EVENT_QUERYdoes not block:HaSuccessonce complete,HaEventNotReadywhile the record is pending. Both returnHaEventNotRecordedfor an event never recorded. - Device kind (
streamHA_STREAM_DEFAULT,eventnull):HA_WAIT_DEVICE_SYNCsynchronizes, asHA_WAIT_STREAM_SYNCdoes, every streamdevhas 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).HaDeviceNotReadyif 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 | |
Example
1 2 3 | |
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 | |
Example
1 2 3 | |