Buffers

What carries the data, and who provides it. More...

Files
file	mpipe_buffer.h
	Buffer and buffer pool APIs.

Data Structures
struct	mpipe_buffer_pool_config
	Buffer pool config structure. More...
struct	mpipe_buffer_pool
	Buffer pool structure. More...
struct	mpipe_buffer_meta
	Common buffer metadata stored in net_buf user_data. More...

Functions
static struct mpipe_buffer_meta *	mpipe_buffer_get_meta (const struct net_buf *buf)
	Get the mpipe metadata carried by a buffer.
void	mpipe_buffer_destroy (struct net_buf *buf)
	Destroy callback for net_buf.
int	mpipe_buffer_pool_configure (struct mpipe_buffer_pool *pool, const struct mpipe_structure *config)
	Configure a buffer pool.
int	mpipe_buffer_pool_set_req_config (struct mpipe_buffer_pool *pool, const struct mpipe_buffer_pool_config *cfg)
	State what a buffer pool requires of its own accord.
int	mpipe_buffer_pool_set_config (struct mpipe_buffer_pool *pool, const struct mpipe_buffer_pool_config *cfg)
	Apply a negotiated config to a buffer pool.
int	mpipe_buffer_pool_start (struct mpipe_buffer_pool *pool)
	Start a buffer pool.
int	mpipe_buffer_pool_stop (struct mpipe_buffer_pool *pool)
	Stop a buffer pool.
void	mpipe_buffer_pool_init (struct mpipe_buffer_pool *pool)
	Initialize a buffer pool.

Detailed Description

What carries the data, and who provides it.

Data travels as Zephyr net_buf buffers. mpipe adds an mpipe_buffer_meta in the buffer's user data - the pool it came from, how many bytes are valid, a timestamp, and the driver-owned buffer it wraps where there is one. That last field is what makes the path zero-copy: a frame a camera wrote reaches the display without being moved.

Buffers come from an mpipe_buffer_pool, never from a heap. A pool is a small vtable over some backing store, so a plugin can hand out buffers a driver already owns rather than copies of them, and the framework drives it through the helpers rather than calling the hooks directly.

Settling who provides the buffers

Once the format is fixed, a query runs through the graph to settle the buffer configuration - how many, how big, how aligned, and whose pool. It travels downstream to the sink, and proposals are written on the way back up, so an element always has its downstream's proposal in hand before it decides.

A proposal is either an entire pool or a bare config by value. The distinction matters for ownership: a demand may only reach a pool the proposing element still owns through mpipe_buffer_pool_set_config, whose owner is free to clamp or refuse it. Nobody writes another pool's config fields directly, and whoever starts a pool is who stops it.

The two configs a pool carries, req_config and config, are what keep one run's negotiated demands out of the next; see the fields below.

Function Documentation

mpipe_buffer_destroy()

void mpipe_buffer_destroy

(

struct net_buf *

buf

)

#include <mpipe_buffer.h>

Destroy callback for net_buf.

Automatically called when buffer reference count reaches zero.

Parameters

buf	Pointer to the net_buf to destroy.

mpipe_buffer_get_meta()

struct mpipe_buffer_meta * mpipe_buffer_get_meta ( const struct net_buf * buf )

inlinestatic

#include <mpipe_buffer.h>

Get the mpipe metadata carried by a buffer.

The metadata lives in the buffer's user data area, so the returned pointer is valid for as long as the buffer is.

Parameters

buf	Buffer to read the metadata of.

Returns

Pointer to the buffer's mpipe_buffer_meta.

mpipe_buffer_pool_configure()

int mpipe_buffer_pool_configure	(	struct mpipe_buffer_pool *	pool,
		const struct mpipe_structure *	config )

#include <mpipe_buffer.h>

Configure a buffer pool.

Parameters

pool	Pointer to the buffer pool to configure
config	Caps structure to configure the buffer pool

Returns

0 on success, negative errno on failure

mpipe_buffer_pool_init()

void mpipe_buffer_pool_init

(

struct mpipe_buffer_pool *

pool

)

#include <mpipe_buffer.h>

Initialize a buffer pool.

Parameters

pool	Pointer to the buffer pool to initialize

mpipe_buffer_pool_set_config()

int mpipe_buffer_pool_set_config	(	struct mpipe_buffer_pool *	pool,
		const struct mpipe_buffer_pool_config *	cfg )

#include <mpipe_buffer.h>

Apply a negotiated config to a buffer pool.

This is the only way a config negotiated through a buffer pool query may reach a pool: the caller hands the value over and the pool's owner validates it. An element must never write mpipe_buffer_pool::config fields of a pool it does not own.

With a mpipe_buffer_pool::set_config implementation, the pool decides: it may accept, clamp, or refuse the config. Without one, the config is copied in as given.

Parameters

pool	Pointer to the buffer pool
cfg	Negotiated config to apply

Return values

0	Success, the pool's config reflects the accepted values.
-EBUSY	The pool is started; stop it before reconfiguring.

Returns

Any negative errno the pool's set_config returns to refuse.

mpipe_buffer_pool_set_req_config()

int mpipe_buffer_pool_set_req_config	(	struct mpipe_buffer_pool *	pool,
		const struct mpipe_buffer_pool_config *	cfg )

#include <mpipe_buffer.h>

State what a buffer pool requires of its own accord.

The pool's owner calls this once, at setup, with the requirement that is true of the pool whatever it is later asked to carry: a hardware minimum buffer count, an alignment the allocator imposes, a size the application fixed. A negotiation never writes it, so it survives as the floor every run starts from - the framework restores mpipe_buffer_pool::config from it on teardown, and an element merging demands into a pool it owns has nothing of its own to remember.

mpipe_buffer_pool::config is set to the same values, so the first run starts from the requirement like every run after it.

Parameters

pool	Pointer to the buffer pool
cfg	What the pool requires

Return values

0	Success
-EBUSY	The pool is started; stop it before restating its requirement

mpipe_buffer_pool_start()

int mpipe_buffer_pool_start

(

struct mpipe_buffer_pool *

pool

)

#include <mpipe_buffer.h>

Start a buffer pool.

Parameters

pool	Pointer to the buffer pool to start

Returns

0 on success, negative errno on failure

mpipe_buffer_pool_stop()

int mpipe_buffer_pool_stop

(

struct mpipe_buffer_pool *

pool

)

#include <mpipe_buffer.h>

Stop a buffer pool.

Also restores mpipe_buffer_pool::config from mpipe_buffer_pool::req_config, which is what keeps one run's negotiated demands out of the next. It happens whether or not the pool was ever started, so a pool that was proposed and turned down is reset too.

Parameters

pool	Pointer to the buffer pool to stop

Returns

0 on success, negative errno on failure