Build and execute a DAG of audio processing nodes. More...

Collaboration diagram for Audio graph engine:

Modules
	Audio device node factories
	Hardware-backed source and sink node factories for the audio graph.

	Audio node types and built-in factories
	Core types for audio nodes, formats, buffers, and built-in processor node factories.

Data Structures
struct	ove_audio_edge
	Directed connection between two nodes in the audio graph. More...

struct	ove_audio_graph_stats
	Runtime diagnostic counters for an audio graph. More...

struct	ove_audio_graph
	Audio processing graph instance. More...

Macros
#define	OVE_AUDIO_GRAPH_MAX_NODES 16
	Maximum number of nodes in a single audio graph.

#define	OVE_AUDIO_GRAPH_MAX_EDGES 16
	Maximum number of edges in a single audio graph.

#define	OVE_AUDIO_GRAPH_STORAGE_BYTES(nodes, frames, channels, sample_bytes) ((size_t)(nodes) * (size_t)(frames) * (size_t)(channels) * (size_t)(sample_bytes))
	Conservative upper-bound byte count for graph buffer storage.

#define	OVE_AUDIO_GRAPH_DEFINE(name, nodes, frames, channels, sample_bytes)
	Declare named static storage for an audio graph and its buffers.

Enumerations
enum	ove_audio_graph_state { OVE_AUDIO_GRAPH_IDLE , OVE_AUDIO_GRAPH_READY , OVE_AUDIO_GRAPH_RUNNING }
	Lifecycle state of an audio graph. More...

Functions
int	ove_audio_graph_init (struct ove_audio_graph *g, unsigned int frames_per_period)
	Initialise an audio graph.

void	ove_audio_graph_deinit (struct ove_audio_graph *g)
	Release all resources held by an audio graph.

int	ove_audio_graph_add_node (struct ove_audio_graph g, const struct ove_audio_node_ops ops, void ctx, const char name, enum ove_audio_node_type type)
	Register a new node in the graph.

int	ove_audio_graph_connect (struct ove_audio_graph *g, unsigned int from, unsigned int to)
	Connect two nodes with a directed edge.

int	ove_audio_graph_set_buf_storage (struct ove_audio_graph g, void storage, size_t size)
	Provide caller-owned storage for inter-node audio buffers.

int	ove_audio_graph_build (struct ove_audio_graph *g)
	Validate and compile the graph.

int	ove_audio_graph_start (struct ove_audio_graph *g)
	Start the audio graph.

int	ove_audio_graph_stop (struct ove_audio_graph *g)
	Stop the audio graph.

int	ove_audio_graph_process (struct ove_audio_graph *g)
	Execute one processing cycle (app-driven mode).

int	ove_audio_graph_get_stats (const struct ove_audio_graph g, struct ove_audio_graph_stats stats)
	Retrieve a snapshot of graph runtime statistics.

Detailed Description

Build and execute a DAG of audio processing nodes.

The audio graph engine models audio processing as a directed acyclic graph (DAG) of typed nodes connected by edges:

Source nodes produce audio (hardware input, file, generator).
Processor nodes transform audio (DSP, format conversion, gain).
Sink nodes consume audio (hardware output, file, observer).

The graph is static: configured at init, validated at build time via topological sort and format propagation, then started. Changes require stop, reconfigure, restart.

Execution modes:

Sink-driven: hardware DMA/callback triggers graph processing.
App-driven: caller pumps one cycle via ove_audio_graph_process().

Requires CONFIG_OVE_AUDIO.

Macro Definition Documentation

◆ OVE_AUDIO_GRAPH_STORAGE_BYTES

#define OVE_AUDIO_GRAPH_STORAGE_BYTES	(	nodes,
		frames,
		channels,
		sample_bytes
	)	((size_t)(nodes) * (size_t)(frames) * (size_t)(channels) * (size_t)(sample_bytes))

Conservative upper-bound byte count for graph buffer storage.

Computes the worst-case storage required for inter-node audio buffers: every non-sink node produces one buffer of frames × channels × sample_bytes. Used by ove_audio_graph_create and OVE_AUDIO_GRAPH_DEFINE to size a zero-heap static backing array.

◆ OVE_AUDIO_GRAPH_DEFINE

#define OVE_AUDIO_GRAPH_DEFINE	(	name,
		nodes,
		frames,
		channels,
		sample_bytes
	)

Value:

    static uint8_t name##_buf[OVE_AUDIO_GRAPH_STORAGE_BYTES(                             \
        (nodes), (frames), (channels), (sample_bytes))] __attribute__((aligned(4))); \
    static struct ove_audio_graph name

Declare named static storage for an audio graph and its buffers.

Mirrors OVE_THREAD_DEFINE / OVE_QUEUE_DEFINE: emits two file-scope static objects: the ove_audio_graph instance named name, and a byte array named name##_buf sized via OVE_AUDIO_GRAPH_STORAGE_BYTES. Pair with ove_audio_graph_init and ove_audio_graph_set_buf_storage when the application wants explicit control:

OVE_AUDIO_GRAPH_DEFINE(g, 2, 512, 1, 2);
 
ove_audio_graph_init(&g, 512);
ove_audio_graph_set_buf_storage(&g, g_buf, sizeof(g_buf));

Applications that do not need this level of control should prefer ove_audio_graph_create, which allocates and attaches storage in one step.

Enumeration Type Documentation

◆ ove_audio_graph_state

enum ove_audio_graph_state

Lifecycle state of an audio graph.

See also: ove_audio_graph_build, ove_audio_graph_start, ove_audio_graph_stop

Enumerator
OVE_AUDIO_GRAPH_IDLE	Initial state; nodes may be added and connected.
OVE_AUDIO_GRAPH_READY	Build succeeded; graph may be started.
OVE_AUDIO_GRAPH_RUNNING	Graph is actively processing audio.

Function Documentation

◆ ove_audio_graph_init()

int ove_audio_graph_init	(	struct ove_audio_graph *	g,
		unsigned int	frames_per_period
	)

Initialise an audio graph.

Sets up internal state and records the processing period size. Must be called before any other graph function.

Parameters

[in]	g	Graph instance to initialise.
[in]	frames_per_period	Number of audio frames processed per cycle.

Returns: 0 on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_deinit

◆ ove_audio_graph_deinit()

void ove_audio_graph_deinit ( struct ove_audio_graph * g )

Release all resources held by an audio graph.

Stops the graph (if running), tears down each node, and frees the heap-allocated inter-node buffer block. Caller-supplied buffer storage registered via ove_audio_graph_set_buf_storage is left intact.

Parameters

[in] g Initialised graph instance.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_init

◆ ove_audio_graph_add_node()

int ove_audio_graph_add_node	(	struct ove_audio_graph *	g,
		const struct ove_audio_node_ops *	ops,
		void *	ctx,
		const char *	name,
		enum ove_audio_node_type	type
	)

Register a new node in the graph.

Appends a node entry to the graph's node table. Nodes may only be added while the graph is in the OVE_AUDIO_GRAPH_IDLE state.

Parameters

[in]	g	Graph instance.
[in]	ops	Vtable providing the node implementation.
[in]	ctx	Opaque context pointer forwarded to every vtable call.
[in]	name	Human-readable node name for diagnostics.
[in]	type	Role of the node: source, processor, or sink.

Returns: Non-negative node index on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_connect, ove_audio_graph_build

◆ ove_audio_graph_connect()

int ove_audio_graph_connect	(	struct ove_audio_graph *	g,
		unsigned int	from,
		unsigned int	to
	)

Connect two nodes with a directed edge.

Adds an edge from the node at index from to the node at index to. Both nodes must already be registered. Edges may only be added while the graph is in the OVE_AUDIO_GRAPH_IDLE state.

Parameters

[in]	g	Graph instance.
[in]	from	Index of the upstream (producer) node.
[in]	to	Index of the downstream (consumer) node.

Returns: 0 on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_add_node, ove_audio_graph_build

◆ ove_audio_graph_set_buf_storage()

int ove_audio_graph_set_buf_storage	(	struct ove_audio_graph *	g,
		void *	storage,
		size_t	size
	)

Provide caller-owned storage for inter-node audio buffers.

Must be called after ove_audio_graph_init and before ove_audio_graph_build. When set, ove_audio_graph_build uses this buffer instead of calling calloc, and ove_audio_graph_deinit will not free it. This is the only way to build a graph under CONFIG_OVE_ZERO_HEAP. Use OVE_AUDIO_GRAPH_STORAGE_BYTES to size the backing array.

Parameters

[in]	g	Graph instance in the `OVE_AUDIO_GRAPH_IDLE` state.
[in]	storage	Pointer to caller-owned memory (≥ `size` bytes).
[in]	size	Size of `storage` in bytes; must be large enough to cover every non-sink node's output buffer.

Returns: 0 on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: OVE_AUDIO_GRAPH_STORAGE_BYTES

◆ ove_audio_graph_build()

int ove_audio_graph_build ( struct ove_audio_graph * g )

Validate and compile the graph.

Performs a topological sort, propagates audio formats from sources to sinks by calling each node's configure callback, allocates the inter-node audio buffers, and transitions the graph to OVE_AUDIO_GRAPH_READY.

Parameters

[in] g Graph instance in the OVE_AUDIO_GRAPH_IDLE state.

Returns: 0 on success, negative error code on failure (e.g. cycle detected, format mismatch, or buffer allocation failure).

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_start

◆ ove_audio_graph_start()

int ove_audio_graph_start ( struct ove_audio_graph * g )

Start the audio graph.

Calls each node's start callback in topological order and transitions the graph to OVE_AUDIO_GRAPH_RUNNING. The graph must be in the OVE_AUDIO_GRAPH_READY state.

Parameters

[in] g Built graph instance.

Returns: 0 on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_build, ove_audio_graph_stop

◆ ove_audio_graph_stop()

int ove_audio_graph_stop ( struct ove_audio_graph * g )

Stop the audio graph.

Calls each node's stop callback in reverse topological order and transitions the graph back to OVE_AUDIO_GRAPH_READY.

Parameters

[in] g Running graph instance.

Returns: 0 on success, negative error code on failure.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_start

◆ ove_audio_graph_process()

int ove_audio_graph_process ( struct ove_audio_graph * g )

Execute one processing cycle (app-driven mode).

Calls each node's process callback in topological order, passing inter-node buffers along the edges. Intended for test or offline use; in sink-driven mode the hardware callback drives processing instead.

Parameters

[in] g Graph instance in OVE_AUDIO_GRAPH_READY or OVE_AUDIO_GRAPH_RUNNING state.

Returns: 0 on success, OVE_ERR_NOT_SUPPORTED if the graph has not been built, or another negative error code if any node reports an error.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_start

◆ ove_audio_graph_get_stats()

int ove_audio_graph_get_stats	(	const struct ove_audio_graph *	g,
		struct ove_audio_graph_stats *	stats
	)

Retrieve a snapshot of graph runtime statistics.

Copies the current diagnostic counters from the graph into the caller-supplied stats structure. Valid in any state once ove_audio_graph_init has succeeded.

Parameters

[in]	g	Graph instance.
[out]	stats	Pointer to a caller-allocated structure that will receive the statistics snapshot.

Returns: 0 on success, OVE_ERR_INVALID_PARAM if g or stats is NULL.

Note: Requires CONFIG_OVE_AUDIO.

See also: ove_audio_graph_stats

Modules

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OVE_AUDIO_GRAPH_STORAGE_BYTES

◆ OVE_AUDIO_GRAPH_DEFINE

Enumeration Type Documentation

◆ ove_audio_graph_state

Function Documentation

◆ ove_audio_graph_init()

◆ ove_audio_graph_deinit()

◆ ove_audio_graph_add_node()

◆ ove_audio_graph_connect()

◆ ove_audio_graph_set_buf_storage()

◆ ove_audio_graph_build()

◆ ove_audio_graph_start()

◆ ove_audio_graph_stop()

◆ ove_audio_graph_process()

◆ ove_audio_graph_get_stats()