Data Bus

[中文]

A data bus is the queue implementation beneath a port that carries data. Ports provide a unified acquire-release protocol; the data bus is responsible for buffer management, cross-thread synchronization, and queuing payloads between producers and consumers. GMF-Core provides four implementations - ringbuffer, fifo, block, and pbuf - targeting different copy strategies, blocking semantics, and data granularity. Elements access data through ports and do not need to be aware of the specific data bus implementation.

For ports and the acquire-release protocol, see Data Flow. For the relationship between pipelines and tasks, see GMF Pipeline and Task Scheduling.

Design Dimensions

When choosing a data bus implementation, the main considerations are how data enters the buffer, whether reads and writes need to block, and whether each transfer is a byte stream or an entire block. The following table compares the four implementations by copy strategy, blocking semantics, and data granularity; subsequent sections explain each one’s buffer source and applicable scenarios.

Dimension	ringbuffer	fifo / block	pbuf
Copy Strategy	memcpy	Zero-copy (address passing)	Zero-copy (pointer queue)
Blocking Semantics	Both read and write block	Both read and write block	Non-blocking
Data Granularity	Arbitrary bytes	Entire block	Entire block

When selecting, first determine three things: how large is the rate difference between upstream and downstream, whether data can be passed at block boundaries, and whether the caller can block when the buffer is unavailable.

Four Implementations

ringbuffer

A ringbuffer maintains a fixed-size circular buffer and reads/writes by bytes each time. acquire_read waits until data is available; acquire_write waits until space is available. Both writing in and reading out pass through the ringbuffer’s internal buffer, so each read and write involves one memcpy.

esp_gmf_db_handle_t db;
esp_gmf_db_new_ringbuffer(num, buf_size, &db);

Suitable for scenarios with large processing rate differences between upstream and downstream that require buffered decoupling. For example, when an MP3 decoder outputs PCM frame by frame and I2S consumes data at a fixed pace, the ringbuffer can absorb the burst nature of decoder output.

fifo

A fifo is a first-in-first-out queue that passes by address. acquire_write returns a free payload container; the element writes into it and enqueues it via release_write; acquire_read dequeues the filled payload from the front for downstream to read. Data is passed by address in the queue without internal memcpy.

esp_gmf_db_new_fifo(capacity, &db);

Suitable for scenarios where upstream and downstream rates are similar, access granularity is consistent, and blocking semantics are needed. A fifo does not support “reading an arbitrary number of bytes”; each acquire returns a complete data block. A fifo’s payload memory can be provided externally; to specify write-side buffer alignment, call esp_gmf_fifo_set_align() before the first acquire_write.

block

A block emphasizes “one entire block at a time” semantics. At creation, num buffers of buf_size bytes are pre-allocated; the write side obtains a free block via acquire_write, fills it, and submits it to the read side via release_write.

esp_gmf_db_new_block(num, buf_size, &db);

Suitable for whole-frame transfer (such as one video frame), fixed object sizes, and zero-copy requirements. The difference from fifo lies in buffer management: fifo’s payload memory can be provided externally, while block’s buffers are pre-allocated by the data bus at creation time.

pbuf

A pbuf is a payload pointer queue. It does not allocate buffers; it only queues payload pointers. Both acquire and release are non-blocking calls.

esp_gmf_db_new_pbuf(depth, &db);

Suitable for scenarios where data is already in a fixed memory region (such as a DMA capture buffer). The producer submits a payload pointer carrying the buffer address to pbuf; downstream then obtains the same payload pointer. Since pbuf does not block, the producer must ensure the queue does not overflow on its own.

Both block and pbuf pass data as entire payload blocks. If a downstream element needs to read by an arbitrary number of bytes, it can use the byte cache inside the element: load the acquired block payload into esp_gmf_cache, then read data at a fixed or arbitrary length via esp_gmf_cache_acquire. This preserves the zero-copy transfer of block/pbuf while converting the element’s internal access granularity to byte-level reading.

Selection Guide

Requirement Characteristics	Recommended	Buffer Source	Copy	Blocking
Byte access, large rate difference	ringbuffer	Internal circular buffer of the data bus	Yes	Yes
Arbitrary-size writes, zero-copy	fifo	Externally provided payload / buffer	No	Yes
Whole-frame data, zero-copy	block	Pre-allocated fixed blocks in the data bus	No	Yes
Direct DMA buffer passing	pbuf	Payload pointer provided by producer	No	No

Recommended selection order: first determine whether memcpy is acceptable, then determine whether reads and writes need to block, and finally determine whether data is passed in fixed blocks. When “reading by an arbitrary number of bytes” is needed, ringbuffer is typically chosen; if upstream uses block or pbuf to pass entire blocks, the element can also use the byte cache internally to achieve byte-level reading.

Common Interface

Read, write, reset, and status query operations for the data bus are provided by a unified interface in esp_gmf_data_bus.h. A port binds to one data bus at creation time and subsequently accesses it via the same acquire-release interface.

API	Function
esp_gmf_db_acquire_write	Acquire a writable payload block
esp_gmf_db_release_write	Submit the written payload to the read side
esp_gmf_db_acquire_read	Acquire a readable payload block
esp_gmf_db_release_read	Return the read payload to the write side
esp_gmf_db_reset	Clear the buffer and reset internal state
esp_gmf_db_get_total_size / esp_gmf_db_get_filled_size	Query capacity and filled bytes
esp_gmf_db_get_available	Query current writable space

Normally elements do not call these APIs directly; they access the data bus indirectly through the port’s esp_gmf_port_acquire_*. For ports and the acquire-release protocol, see Data Flow.

Some implementations also provide dedicated configuration interfaces. For example, fifo allows calling esp_gmf_fifo_set_align() before the first write-side acquire to set the buffer address alignment, useful for DMA or PSRAM cache alignment scenarios.

EOF and Abort Control

In addition to the normal read/write loop, the data bus provides four flow control interfaces to express the EOF and abort semantics.

API	Effect	Typical Scenario
esp_gmf_db_done_write()	Sets EOF; causes acquire_read to return a payload with is_done set	Data source has reached the end
esp_gmf_db_reset_done_write()	Clears EOF	Switching to a new data source, reusing the data bus
esp_gmf_db_abort()	Wakes all blocked calls, returns ESP_GMF_IO_ABORT	Emergency stop, error recovery
esp_gmf_db_clear_abort()	Only clears the abort flag; buffer data is preserved	Continue reading after error recovery

The semantic difference between done and abort: done means data has ended naturally; downstream processes remaining data and then enters the end flow. abort means immediate termination; subsequent read/write calls return ESP_GMF_IO_ABORT. Both cause the task to exit the running phase, entering FINISHED and STOPPED paths respectively (see the task scheduling section in GMF Pipeline and Task Scheduling).

The difference between clear_abort and reset: esp_gmf_db_reset() clears buffered data and resets internal state; clear_abort only clears the abort status flag. To continue processing data retained in the buffer after recovery, use clear_abort; to discard old data and start fresh, use reset.

API Reference

Unified interface and common types for the four implementations:

• esp_gmf_data_bus.h: Data bus common interface (acquire / release / done / abort / reset)

• esp_gmf_new_databus.h: Creation interfaces for the four implementations

For implementation-specific header files, consult esp_gmf_ringbuffer.h / esp_gmf_fifo.h / esp_gmf_block.h / esp_gmf_pbuf.h as needed. Normal reads and writes are completed via the data bus common interface; implementation-specific configuration interfaces are only needed when using implementation-specific features.

Header File

• gmf_core/data_bus/include/esp_gmf_data_bus.h

Functions

esp_gmf_err_t esp_gmf_db_init(esp_gmf_db_config_t *db_config, esp_gmf_db_handle_t *hd)

Initialize data bus with the given configuration.

Parameters:

• db_config – [in] Pointer to the configuration structure

• hd – [out] Pointer to store the data bus handle after initialization

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_db_deinit(esp_gmf_db_handle_t handle)

Deinitialize data bus, freeing associated resources.

Parameters:

handle – [in] data bus handle to deinitialize

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_read(esp_gmf_db_handle_t handle, void *buffer, int buf_len, int block_ticks)

Read data from data bus.

Parameters:

• handle – [in] data bus handle

• buffer – [out] Pointer to the buffer to store the read data

• buf_len – [in] Length of the buffer

• block_ticks – [in] Maximum time to wait for the read operation

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_write(esp_gmf_db_handle_t handle, void *buffer, int buf_len, int block_ticks)

Write data to data bus.

Parameters:

• handle – [in] data bus handle

• buffer – [in] Pointer to the data buffer to be written

• buf_len – [in] Length of the data buffer

• block_ticks – [in] Maximum time to wait for the write operation

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_io_t esp_gmf_db_acquire_read(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire expected data on data bus The actual valid size is stored in blk->valid_size

Parameters:

• handle – [in] data bus handle

• blk – [out] Pointer to the data bus block structure

• wanted_size – [in] Size of data to acquire

• block_ticks – [in] Maximum time to wait for the acquire operation

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_db_release_read(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Release a read operation on data bus.

Parameters:

• handle – [in] data bus handle

• blk – [in] Pointer to the data bus block structure

• block_ticks – [in] Maximum time to wait for the release operation

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_db_acquire_write(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire space to write operation on data bus.

Parameters:

• handle – [in] data bus handle

• blk – [out] Pointer to the data bus block structure

• wanted_size – [in] Size of data to acquire

• block_ticks – [in] Maximum time to wait for the acquire operation

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_db_release_write(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Release a write operation on data bus.

Parameters:

• handle – [in] data bus handle

• blk – [in] Pointer to the data bus block structure

• block_ticks – [in] Maximum time to wait for the release operation

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_t esp_gmf_db_done_write(esp_gmf_db_handle_t handle)

Mark a write operation as done on data bus.

Parameters:

handle – [in] data bus handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_reset_done_write(esp_gmf_db_handle_t handle)

Reset the status of a completed write operation on data bus.

Parameters:

handle – [in] data bus handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_reset(esp_gmf_db_handle_t handle)

Reset data bus, clearing any pending operations and resetting status.

Parameters:

handle – [in] data bus handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_abort(esp_gmf_db_handle_t handle)

Abort exit the data bus.

Parameters:

handle – [in] data bus handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_clear_abort(esp_gmf_db_handle_t handle)

Clear the abort flag and restore semaphores to allow normal operations.

Note

This function should be called when recovering from an abort state. It provides a unified interface across all data bus types. The specific recovery implementation depends on the underlying data bus type (block, ringbuffer, FIFO, or pbuf)

Parameters:

handle – [in] data bus handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_set_align(esp_gmf_db_handle_t handle, uint8_t addr_align, uint8_t size_align)

Set buffer alignment for the underlying data bus implementation.

Note

Refer to the concrete data bus type (block, fifo, pbuf, etc.) for addr_align and size_align semantics and timing requirements

Parameters:

• handle – [in] data bus handle

• addr_align – [in] Base-address alignment forwarded to the implementation

• size_align – [in] Buffer-length alignment (e.g. round-up stride) forwarded to the implementation

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_total_size(esp_gmf_db_handle_t handle, uint32_t *buff_size)

Get the total size of data bus buffer.

Parameters:

• handle – [in] data bus handle

• buff_size – [out] Pointer to store the total buffer size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_filled_size(esp_gmf_db_handle_t handle, uint32_t *filled_size)

Get the filled size of data bus buffer.

Parameters:

• handle – [in] data bus handle

• filled_size – [out] Pointer to store the filled buffer size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_available(esp_gmf_db_handle_t handle, uint32_t *available_size)

Get the available size in data bus buffer.

Parameters:

• handle – [in] data bus handle

• available_size – [out] Pointer to store the available buffer size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_set_writer(esp_gmf_db_handle_t handle, void *holder)

Set the writer holder for data bus.

Parameters:

• handle – [in] data bus handle

• holder – [in] Pointer to the writer holder

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_writer(esp_gmf_db_handle_t handle, void **holder)

Get the writer holder from data bus.

Parameters:

• handle – [in] data bus handle

• holder – [out] Pointer to store the writer holder

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_set_reader(esp_gmf_db_handle_t handle, void *holder)

Set the reader holder for data bus.

Parameters:

• handle – [in] data bus handle

• holder – [in] Pointer to the reader holder

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_reader(esp_gmf_db_handle_t handle, void **holder)

Get the reader holder from data bus.

Parameters:

• handle – [in] data bus handle

• holder – [out] Pointer to store the reader holder

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_type(esp_gmf_db_handle_t handle, esp_gmf_data_bus_type_t *db_type)

Get the data bus type of data bus.

Parameters:

• handle – [in] data bus handle

• db_type – [out] Pointer to store the data bus type

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

const char *esp_gmf_db_get_name(esp_gmf_db_handle_t handle)

Get the name of data bus.

Parameters:

handle – [in] data bus handle

Returns:

• Pointer to the name of the data bus

Structures

struct esp_gmf_data_bus_block_t

Structure representing a block of data for block-oriented data buses.

Public Members

uint8_t *buf

Pointer to the buffer

size_t buf_length

Length of the buffer

size_t valid_size

Valid data size in the buffer

bool is_last

Flag indicating if the buffer is the last

struct data_bus_op_t

Structure representing the operations of a data bus.

Public Members

esp_gmf_err_t (*deinit)(esp_gmf_db_handle_t handle)

Deinitialize the data bus

esp_gmf_err_t (*read)(esp_gmf_db_handle_t handle, uint8_t *buffer, int buf_len, int block_ticks)

Read data from the data bus

esp_gmf_err_t (*write)(esp_gmf_db_handle_t handle, uint8_t *buffer, int written_size, int block_ticks)

Write data to the data bus

esp_gmf_err_io_t (*acquire_read)(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire a block of data for reading

esp_gmf_err_io_t (*release_read)(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Release a block of data after reading

esp_gmf_err_io_t (*acquire_write)(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire a block of data for writing

esp_gmf_err_io_t (*release_write)(esp_gmf_db_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Release a block of data after writing

esp_gmf_err_t (*done_write)(esp_gmf_db_handle_t handle)

Signal that writing to the data bus is done

esp_gmf_err_t (*reset_done_write)(esp_gmf_db_handle_t handle)

Reset the “done writing” signal

esp_gmf_err_t (*reset)(esp_gmf_db_handle_t handle)

Reset the data bus

esp_gmf_err_t (*abort)(esp_gmf_db_handle_t handle)

Abort ongoing operations

esp_gmf_err_t (*clear_abort)(esp_gmf_db_handle_t handle)

Clear abort flag and restore semaphores

esp_gmf_err_t (*set_align)(esp_gmf_db_handle_t handle, uint8_t addr_align, uint8_t size_align)

Optional alignment

esp_gmf_err_t (*get_total_size)(esp_gmf_db_handle_t handle, uint32_t *size)

Get the total size of the data bus

esp_gmf_err_t (*get_filled_size)(esp_gmf_db_handle_t handle, uint32_t *filled_size)

Get the filled size of the data bus

esp_gmf_err_t (*get_available)(esp_gmf_db_handle_t handle, uint32_t *available_size)

Get the available size of the data bus

struct esp_gmf_data_bus_t

Structure representing a data bus.

Public Members

struct data_bus_op_t op

Operations of the data bus

void *child

Pointer to the child

void *writer

Pointer to the writer who call the write associated functions

void *reader

Pointer to the reader who call the read associated functions

const char *name

Name of the data bus

esp_gmf_data_bus_type_t type

Type of the data bus

int max_item_num

Maximum number of items

int max_size

Maximum size

struct esp_gmf_db_config_t

Configuration for the database.

Public Members

void *child

Pointer to the child

const char *name

Name of the database

esp_gmf_data_bus_type_t type

Type of the data bus

int max_item_num

Maximum number of items

int max_size

Maximum size

bool safeguard

Flag indicating if the safeguard is enabled

Type Definitions

typedef void *esp_gmf_db_handle_t

Handle for the data bus interface.

Enumerations

enum esp_gmf_data_bus_type_t

Type of data bus.

Values:

enumerator DATA_BUS_TYPE_BYTE

Data bus type for byte-oriented data

enumerator DATA_BUS_TYPE_BLOCK

Data bus type for block-oriented data

Header File

• gmf_core/data_bus/include/esp_gmf_new_databus.h

Functions

int esp_gmf_db_new_ringbuf(int num, int item_cnt, esp_gmf_db_handle_t *h)

Create a new ring buffer with the specified item count and size.

SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO., LTD SPDX-License-Identifier: LicenseRef-Espressif-Modified-MIT

See LICENSE file for details.

Parameters:

• num – [in] Size of each item

• item_cnt – [in] Number of items

• h – [out] Pointer to store the handle of the GMF data bus

Returns:

• 0 On success

• < 0 Negative value if an error occurs

int esp_gmf_db_new_block(int num, int item_cnt, esp_gmf_db_handle_t *h)

Create a new block buffer with the specified item count and size.

Parameters:

• num – [in] Size of each item

• item_cnt – [in] Number of items

• h – [out] Pointer to store the handle of the GMF data bus

Returns:

• 0 On success

• < 0 Negative value if an error occurs

int esp_gmf_db_new_pbuf(int num, int item_cnt, esp_gmf_db_handle_t *h)

Create a new pointer buffer (pbuf) with the specified item count and size.

Parameters:

• num – [in] Size of each item

• item_cnt – [in] Number of items

• h – [out] Pointer to store the handle of the GMF data bus

Returns:

• 0 On success

• < 0 Negative value if an error occurs

int esp_gmf_db_new_fifo(int num, int item_cnt, esp_gmf_db_handle_t *h)

Create a new FIFO buffer with the specified item count and size.

Parameters:

• num – [in] num Maximum number of items

• item_cnt – [in] Reserved for future use (currently unused)

• h – [out] Pointer to store the handle of the GMF data bus

Returns:

• 0 On success

• < 0 Negative value if an error occurs

int esp_gmf_db_new_data_queue(int size, int item_cnt, esp_gmf_db_handle_t *h)

Create a new data queue with variable-sized block records.

Parameters:

• size – [in] Total queue buffer size

• item_cnt – [in] Reserved for future use (currently unused)

• h – [out] Pointer to store the handle of the GMF data bus

Returns:

• 0 On success

• < 0 Negative value if an error occurs

Header File

• gmf_core/data_bus/include/esp_gmf_ringbuffer.h

Functions

esp_gmf_err_t esp_gmf_rb_create(int block_size, int n_blocks, esp_gmf_rb_handle_t *handle)

Create a ring buffer with total size = block_size * n_blocks.

Parameters:

• block_size – [in] Size of each block

• n_blocks – [in] Number of blocks

• handle – [out] Pointer to store the handle to the created ringbufer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_rb_destroy(esp_gmf_rb_handle_t handle)

Cleanup and free all memory allocated for the ring buffer.

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_reset(esp_gmf_rb_handle_t handle)

Reset the ring buffer, clearing all values to the initial state.

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_io_t esp_gmf_rb_acquire_read(esp_gmf_rb_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int ticks_to_wait)

Copy valid data from ring buffer to the given buffer with specific handle When the ring buffer handle cannot provide enough size, it will block for the duration specified by block_ticks. The actual valid size is stored in blk->valid_size

Parameters:

• handle – [in] The Ringbuffer handle

• blk – [out] Pointer to the data block structure to be filled

• wanted_size – [in] Desired size to read

• ticks_to_wait – [in] Maximum duration to wait for the operation to complete

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments

• ESP_GMF_IO_TIMEOUT Operation timed out

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_rb_release_read(esp_gmf_rb_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Release the read operation.

Note

It’s do nothing due to read acquire is a copy operation

Parameters:

• handle – [in] The Ringbuffer handle

• blk – [in] Pointer to the data block structure to release

• block_ticks – [in] Maximum duration to wait for the operation to complete

Returns:

• ESP_GMF_IO_OK Operation succeeded

esp_gmf_err_io_t esp_gmf_rb_acquire_write(esp_gmf_rb_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int ticks_to_wait)

Acquire space for write.

Note

It’s do nothing due to write acquire is a copy operation

Parameters:

• handle – [in] The Ringbuffer handle

• blk – [out] Pointer to the data block structure to be filled

• wanted_size – [in] Desired size to write

• ticks_to_wait – [in] Maximum duration to wait for the operation to complete

Returns:

• ESP_GMF_IO_OK Operation succeeded

esp_gmf_err_io_t esp_gmf_rb_release_write(esp_gmf_rb_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Copy the given buffer to the ring buffer with specific handle When the ring buffer handle cannot accommodate the given buffer size, it will block for the duration specified by block_ticks.

Parameters:

• handle – [in] The Ringbuffer handle

• blk – [in] Pointer to the data block structure to release

• block_ticks – [in] Maximum duration to wait for the operation to complete

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments

• ESP_GMF_IO_TIMEOUT Operation timed out

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_rb_abort(esp_gmf_rb_handle_t handle)

Abort any pending operations on the ring buffer.

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_clear_abort(esp_gmf_rb_handle_t handle)

Clear the abort flag and drain semaphores for recovery after abort.

Note

This function should be called when recovering from an abort state It clears the abort_read and abort_write flags, then drains and restores semaphore signals based on actual buffer state

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_rb_done_write(esp_gmf_rb_handle_t handle)

Set the status of writing to the ring buffer as done.

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_reset_done_write(esp_gmf_rb_handle_t handle)

Reset the status of writing to the ring buffer as not done.

Parameters:

handle – [in] The Ringbuffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_bytes_available(esp_gmf_rb_handle_t handle, uint32_t *available_size)

Get the number of bytes available for reading from the ring buffer.

Parameters:

• handle – [in] The Ringbuffer handle

• available_size – [out] Pointer to store the available size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_bytes_filled(esp_gmf_rb_handle_t handle, uint32_t *filled_size)

Get the number of bytes filled in the ring buffer.

Parameters:

• handle – [in] The Ringbuffer handle

• filled_size – [out] Pointer to store the filled size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_get_size(esp_gmf_rb_handle_t handle, uint32_t *valid_size)

Get the total size of the ring buffer.

Parameters:

• handle – [in] The Ringbuffer handle

• valid_size – [out] Pointer to store the total size

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

Type Definitions

typedef void *esp_gmf_rb_handle_t

GMF ringbuffer represents a ring buffer. The buffer size is determined by multiplying the block size with the number of blocks.Read and write operations occur on a byte-by-byte basis and do not offer direct access to the internal buffer address. Its access is thread-safe. The ‘esp_gmf_rb_acquire_read’ and ‘esp_gmf_rb_release_write’ perform read and write operations as copies, respectively. esp_gmf_rb_release_read and esp_gmf_rb_acquire_write have no practical significance.

The esp_gmf_rb_release_write and esp_gmf_rb_acquire_read have blocking functionality.

Handle to the ring buffer

Header File

• gmf_core/data_bus/include/esp_gmf_fifo.h

Functions

esp_gmf_err_t esp_gmf_fifo_create(int block_cnt, int block_size, esp_gmf_fifo_handle_t *handle)

Create a FIFO buffer for data blocks.

Parameters:

• block_cnt – [in] Number of blocks in the FIFO

• block_size – [in] Size of each block in bytes

• handle – [out] Pointer to the FIFO handle to be created

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_set_align(esp_gmf_fifo_handle_t handle, uint8_t addr_align, uint8_t size_align)

Set alignment for FIFO buffer.

Note

Should call this API before esp_gmf_fifo_acquire_write to get aligned buffer

Parameters:

• handle – [in] FIFO handle

• addr_align – [in] Byte alignment for allocated node buffers (power of two; 0 selects internal default)

• size_align – [in] Rounds each node allocation up to a multiple of this value (0 or 1 for no length rounding)

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_destroy(esp_gmf_fifo_handle_t handle)

Destroy the FIFO buffer and release resources.

Parameters:

handle – [in] FIFO handle to be destroyed

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_io_t esp_gmf_fifo_acquire_read(esp_gmf_fifo_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire a filled block from the FIFO, if there is insufficient block and block_ticks is greater than 0, the function will block until enough block becomes available.

Note

1. The wanted_size parameter is not used because the acquired block comes from the filled blocks.

1. The obtained buffer address is internal and should not be freed externally.

2. The obtained blocks must be released by esp_gmf_fifo_release_read in pairs.

3. The actual valid size is stored in blk->valid_size

Parameters:

• handle – [in] FIFO handle

• blk – [out] Pointer to the data block structure to be filled

• wanted_size – [in] Desired size to read in bytes

• block_ticks – [in] Maximum ticks to wait if the block is not available

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or wanted_size > total size

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_fifo_release_read(esp_gmf_fifo_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Returned acquired block address to the specific handle.

Note

1. The returned block MUST be acquired from esp_gmf_fifo_acquire_read to ensure proper synchronization

1. esp_gmf_fifo_acquire_read and esp_gmf_fifo_release_read must be called in pairs

2. Calling this function once makes one block available for the write operation

Parameters:

• handle – [in] FIFO handle

• blk – [in] Pointer to the data block structure to be released

• block_ticks – [in] Maximum ticks to wait if necessary

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_fifo_acquire_write(esp_gmf_fifo_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire freed block to the desired size within a specific handle If the number of the list is reach the maximum and block_ticks is greater than 0, the function will block until enough space becomes available.

Note

1. esp_gmf_fifo_acquire_write and esp_gmf_fifo_release_write must be called in pairs

1. The obtained buffer address is internal and should not be freed externally

2. The wanted_size parameter is used to specify the size of the block that can be written

3. If the freed block is not ready and the number of items in the list is below the maximum limit, a new node and buffer will be allocated for the list

4. If the obtained buffer is smaller than the wanted_size, the buffer will be reallocated to match the requested size

Parameters:

• handle – [in] FIFO handle

• blk – [out] Pointer to the data block structure to be filled

• wanted_size – [in] Desired size to write in bytes

• block_ticks – [in] Maximum ticks to wait if the block is not available

Returns:

• ESP_GMF_IO_OK Operation succeeded, or it’s done to write

• ESP_GMF_IO_FAIL Invalid arguments, or no filled data

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_fifo_release_write(esp_gmf_fifo_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Returned a previously acquired write block.

Note

1. The returned buffer MUST be acquired from esp_gmf_fifo_acquire_write to ensure proper synchronization

1. esp_gmf_fifo_acquire_write and esp_gmf_fifo_release_write must be called in pairs

2. Calling this function once makes one block available for read operations, and the count of freed blocks will be decremented by one

Parameters:

• handle – [in] FIFO handle

• blk – [in] Pointer to the data block structure to be released

• block_ticks – [in] Maximum ticks to wait if necessary

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_fifo_done_write(esp_gmf_fifo_handle_t handle)

Indicate that writing to the FIFO is complete.

Parameters:

handle – [in] FIFO handle

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_reset_done_write(esp_gmf_fifo_handle_t handle)

Reset the status of writing to the FIFO as not done.

Parameters:

handle – [in] FIFO handle

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_abort(esp_gmf_fifo_handle_t handle)

Abort all operations on the FIFO.

Parameters:

handle – [in] FIFO handle

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_clear_abort(esp_gmf_fifo_handle_t handle)

Clear the abort flag and drain semaphores for recovery after abort.

Note

This function should be called when recovering from an abort state It clears the abort_read and abort_write flags, then drains and restores semaphore signals based on actual buffer state

Parameters:

handle – [in] The FIFO handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_fifo_reset(esp_gmf_fifo_handle_t handle)

Reset the FIFO to its initial state.

Parameters:

handle – [in] FIFO handle

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_get_free_size(esp_gmf_fifo_handle_t handle, uint32_t *free_size)

Get the amount of free space in the FIFO.

Parameters:

• handle – [in] FIFO handle

• free_size – [out] Pointer to store the free size in bytes

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_get_filled_size(esp_gmf_fifo_handle_t handle, uint32_t *filled_size)

Get the amount of filled space in the FIFO.

Parameters:

• handle – [in] FIFO handle

• filled_size – [out] Pointer to store the filled size in bytes

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_get_total_size(esp_gmf_fifo_handle_t handle, uint32_t *total_size)

Get the total capacity of the FIFO.

Parameters:

• handle – [in] FIFO handle

• total_size – [out] Pointer to store the total size in bytes

Returns:

• ESP_GMF_ERR_OK Success

• ESP_GMF_ERR_INVALID_ARG Invalid arguments

Type Definitions

typedef void *esp_gmf_fifo_handle_t

The GMF FIFO Buffer is an interface designed for passing buffer addresses without generating any copies. It maintains a list whose maximum number of items is specified when creating the FIFO handle. The FIFO buffer is not allocated during initialization; instead, it is allocated when esp_gmf_fifo_acquire_write is called. This interface provides blocking operations, meaning that esp_gmf_fifo_acquire_read and esp_gmf_fifo_acquire_write will block until a buffer becomes available or the timeout occurs. The functions esp_gmf_fifo_release_read and esp_gmf_fifo_release_write must be used in pairs and cannot be invoked recursively. Additionally, the GMF FIFO buffer is thread-safe, ensuring safe concurrent access in multi-threaded environments.

Handle for the GMF FIFO

Header File

• gmf_core/data_bus/include/esp_gmf_block.h

Functions

esp_gmf_err_t esp_gmf_block_create(int block_size, int block_cnt, esp_gmf_block_handle_t *handle)

Create a block buffer with total size = block_size * block_cnt.

Parameters:

• block_size – [in] Size of each block

• block_cnt – [in] Number of blocks

• handle – [out] Pointer to store the handle to the created block buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_block_set_align(esp_gmf_block_handle_t handle, uint8_t addr_align, uint8_t size_align)

Reallocate the contiguous backing buffer so its base address meets the requested alignment.

Note

Call after esp_gmf_block_create and before any data transfer via esp_gmf_block_acquire_read or esp_gmf_block_acquire_write. This API frees the existing backing store first, then allocates a new zero-filled region (reduces peak heap versus alloc-then-free). If any payload remains in the ring (fill_size != 0), the call fails so callers do not lose data silently.

Parameters:

• handle – [in] Block buffer handle from esp_gmf_block_create

• addr_align – [in] Byte alignment for the backing store base: use 1 for legacy calloc allocation; use 0 to substitute esp_gmf_oal_get_spiram_cache_align(); values greater than 1 must be a power of two and select aligned heap allocation.

• size_align – [in] Rounds the backing store byte length up to a multiple of this value. Use 0 or 1 for no length rounding; values greater than 1 must be a power of two.

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If handle is NULL or alignment is invalid after resolution

• ESP_GMF_ERR_INVALID_STATE If the buffer is not idle (contains in-flight data)

• ESP_GMF_ERR_MEMORY_LACK If reallocation fails after the old backing store was freed; the handle has no buffer — call esp_gmf_block_destroy only, do not use acquire APIs

esp_gmf_err_t esp_gmf_block_destroy(esp_gmf_block_handle_t handle)

Cleanup and free all memory created by esp_gmf_block_create.

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_io_t esp_gmf_block_acquire_read(esp_gmf_block_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Retrieve the address of a valid data buffer from the internal buffer for reading, without performing any copying. If there is insufficient data and block_ticks is greater than 0, the function will block until enough data becomes available.

Note

1. It’s recommended to set wanted_size either equal to block_size or to ensure that the total size divided by wanted_size results in no remainder. This ensures expected behavior, particularly when reaching the end of the buffer, where the return value may not match the expected value due to the buffer’s inability to wrap from the tail to the head.

1. The obtained buffer address is internal and should not be freed externally

2. The wanted_size can’t be greater than block_size * block_cnt

3. The actual valid size is stored in blk->valid_size

Parameters:

• handle – [in] Handle to the block buffer

• blk – [out] Pointer to the data bus block structure to store the acquired data

• wanted_size – [in] Desired size of data to be acquired

• block_ticks – [in] Ticks to wait for the operation

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or wanted_size > total size

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_block_release_read(esp_gmf_block_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Returned acquired buffer address to the specific handle.

Note

1. The returned buffer MUST be acquired from esp_gmf_block_acquire_read to ensure proper synchronization

1. esp_gmf_block_acquire_read and esp_gmf_block_release_read must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

2. If the buffer address reaches the end of the internal buffer, the read pointer will be reset to the beginning of the internal buffer

Parameters:

• handle – [in] Handle to the block buffer

• blk – [in] Pointer to the data bus block structure containing the data to be released

• block_ticks – [in] Ticks to wait for the operation

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_block_acquire_write(esp_gmf_block_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire space corresponding to the desired size within a specific handle If there is insufficient space and block_ticks is greater than 0, the function will block until enough space becomes available.

Note

1. esp_gmf_block_acquire_write and esp_gmf_block_release_write must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

1. The obtained buffer address is internal and should not be freed externally

2. The wanted_size can’t be greater than block_size * block_cnt

Parameters:

• handle – [in] Handle to the block buffer

• blk – [out] Pointer to the data bus block structure to store the acquired space

• wanted_size – [in] Desired size of space to be acquired

• block_ticks – [in] Ticks to wait for the operation

Returns:

• ESP_GMF_IO_OK Operation succeeded, or it’s done to write

• ESP_GMF_IO_FAIL Invalid arguments, or no filled data

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_block_release_write(esp_gmf_block_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Returned acquired buffer address to the specific handle.

Note

1. The returned buffer MUST be acquired from esp_gmf_block_acquire_write to ensure proper synchronization

1. esp_gmf_block_acquire_write and esp_gmf_block_release_write must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

2. If the buffer address reaches the end of the internal buffer, the write pointer will be reset to the beginning of the internal buffer

Parameters:

• handle – [in] Handle to the block buffer

• blk – [in] Pointer to the data bus block structure containing the space to be released

• block_ticks – [in] Ticks to wait for the operation

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_block_done_write(esp_gmf_block_handle_t handle)

Set status of writing to is done.

Note

This function just mark the done flag, which is actually used in esp_gmf_block_release_write to ensure that the last frame of data can be read. So it will be called in esp_gmf_block_release_write only.

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_reset_done_write(esp_gmf_block_handle_t handle)

Reset the status of writing to the block buffer as not done.

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_abort(esp_gmf_block_handle_t handle)

Abort waiting if reading or writing is blocking.

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_clear_abort(esp_gmf_block_handle_t handle)

Clear the abort flag and drain semaphores for recovery after abort.

Note

This function should be called when recovering from an abort state It clears the _is_abort flag, then drains and restores semaphore signals based on actual buffer state

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_reset(esp_gmf_block_handle_t handle)

Reset, clear all values as initial state.

Parameters:

handle – [in] The block handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_free_size(esp_gmf_block_handle_t handle, uint32_t *free_size)

Get the free size of a GMF block.

Parameters:

• handle – [in] The handle to the GMF block.

• free_size – [out] Pointer to a variable where the free size will be stored.

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_total_size(esp_gmf_block_handle_t handle, uint32_t *total_size)

Get the total size of a GMF block.

Parameters:

• handle – [in] The handle to the GMF block

• total_size – [out] Pointer to a variable where the total size of the block will be stored

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_filled_size(esp_gmf_block_handle_t handle, uint32_t *filled_size)

Get the filled size of a GMF block.

Parameters:

• handle – [in] The handle to the GMF block

• filled_size – [out] Pointer to a variable where the filled size will be stored

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

Type Definitions

typedef void *esp_gmf_block_handle_t

GMF block buffer is an interface for passing buffer addresses without generating any copies. It first allocates a memory block of size block_size * block_cnt. Each time the Acquire API is called, it returns the starting address of each block, and each Acquire size recommendation is divisible by the total cache size. Acquire size also supports any value within the total size, and the recommended Acquire size that is divisible by the total has the best performance. After esp_gmf_block_acquire_write and esp_gmf_block_release_write, esp_gmf_block_acquire_read can obtain the written data.

These interfaces are thread-safe, and esp_gmf_block_acquire_write and esp_gmf_block_acquire_read also have blocking functionality.

Represents a handle to a block buffer

Header File

• gmf_core/data_bus/include/esp_gmf_pbuf.h

Functions

esp_gmf_err_t esp_gmf_pbuf_create(int capacity, esp_gmf_pbuf_handle_t *handle)

Creates a new pointer buffer with the specified capacity It simply allocates an instance without any buffer.

Parameters:

• capacity – [in] The capacity of the maximum pointer buffer

• handle – [out] Pointer to store the handle to the created pointer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_pbuf_set_align(esp_gmf_pbuf_handle_t handle, uint8_t addr_align, uint8_t size_align)

Set default alignment for payload buffers allocated on esp_gmf_pbuf_acquire_write

Note

Call before any payload allocation through esp_gmf_pbuf_acquire_write. Use align 0 to apply the internal default alignment (16 bytes). Values greater than 1 must be a power of two.

Parameters:

• handle – [in] Pointer buffer handle

• addr_align – [in] Byte alignment for new or grown payloads (0 applies internal default, typically 16)

• size_align – [in] Rounds payload allocation length up to a multiple (0 or 1 for no length rounding)

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG If handle is NULL or alignment is invalid

esp_gmf_err_t esp_gmf_pbuf_destroy(esp_gmf_pbuf_handle_t handle)

Destroy a pointer buffer and release all associated resources.

Parameters:

handle – [in] Handle to the pointer buffer to be destroyed

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_io_t esp_gmf_pbuf_acquire_read(esp_gmf_pbuf_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire valid data from the pointer buffer for reading, it consistently retrieves the filled header data.

Note

1. If called before any write operation, it will return ESP_GMF_IO_FAIL

1. esp_gmf_pbuf_acquire_read and esp_gmf_pbuf_release_read must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

2. The actual valid size is stored in blk->valid_size

Parameters:

• handle – [in] Handle to the pointer buffer

• blk – [out] Pointer to the data bus block structure to store the acquired data

• wanted_size – [in] Desired size of data to be acquired

• block_ticks – [in] Currently unused (reserved for callback compatibility)

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or no filled data

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_pbuf_release_read(esp_gmf_pbuf_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Returned acquired buffer to the specific pointer buffer.

Note

1. The returned buffer MUST be acquired from esp_gmf_pbuf_acquire_read to ensure proper synchronization

1. esp_gmf_pbuf_acquire_read and esp_gmf_pbuf_release_read must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

Parameters:

• handle – [in] Handle to the pointer buffer

• blk – [in] Pointer to the data bus block structure containing the data to be released

• block_ticks – [in] Currently unused (reserved for callback compatibility)

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_pbuf_acquire_write(esp_gmf_pbuf_handle_t handle, esp_gmf_data_bus_block_t *blk, uint32_t wanted_size, int block_ticks)

Acquire space corresponding to the desired size within a specific handle The first call requests the desired buffer, or it does so when no buffer is available.

Note

1. The allocated number of buffer is greater than given capacity, it will return ESP_GMF_IO_FAIL

1. esp_gmf_pbuf_acquire_write and esp_gmf_pbuf_release_write must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

Parameters:

• handle – [in] Handle to the pointer buffer

• blk – [out] Pointer to the data bus block structure to store the acquired space

• wanted_size – [in] Desired size of space to be acquired

• block_ticks – [in] Currently unused (reserved for callback compatibility)

Returns:

• ESP_GMF_IO_OK Operation succeeded, or it’s done to write

• ESP_GMF_IO_FAIL Invalid arguments, or no filled data

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_io_t esp_gmf_pbuf_release_write(esp_gmf_pbuf_handle_t handle, esp_gmf_data_bus_block_t *blk, int block_ticks)

Store the given buffer to filled list by the specific pointer buffer.

Note

1. The stored buffer MUST be acquired from esp_gmf_pbuf_acquire_write to ensure proper synchronization

1. esp_gmf_pbuf_acquire_write and esp_gmf_pbuf_release_write must be called in pairs, and consecutive acquisition followed by consecutive release is not allowed

Parameters:

• handle – [in] Handle to the pointer buffer

• blk – [in] Pointer to the data bus block structure containing the space to be released

• block_ticks – [in] Currently unused (reserved for callback compatibility)

Returns:

• ESP_GMF_IO_OK Operation succeeded

• ESP_GMF_IO_FAIL Invalid arguments, or the buffer does not belong to the provided handle

• ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_pbuf_done_write(esp_gmf_pbuf_handle_t handle)

Set the status of writing to the pointer buffer as done.

Parameters:

handle – [in] Handle to the pointer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_reset_done_write(esp_gmf_pbuf_handle_t handle)

Reset the status of writing to the pointer buffer as not done.

Parameters:

handle – [in] Handle to the pointer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_abort(esp_gmf_pbuf_handle_t handle)

Abort waiting until there is space for reading or writing of the pointer buffer.

Parameters:

handle – [in] Handle to the pointer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_clear_abort(esp_gmf_pbuf_handle_t handle)

Clear the abort flag and drain semaphores for recovery after abort.

Note

This function should be called when recovering from an abort state It Clears the _is_abort flag, then drains and restores semaphore signals based on actual buffer state

Parameters:

handle – [in] The Pointer Buffer handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pbuf_reset(esp_gmf_pbuf_handle_t handle)

Reset the pointer buffer, clearing all values to initial state.

Parameters:

handle – [in] Handle to the pointer buffer

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_free_size(esp_gmf_pbuf_handle_t handle, uint32_t *free_size)

Get the total free size of the pointer buffer.

Parameters:

• handle – [in] Handle to the pointer buffer

• free_size – [out] Pointer to store the total free size

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_filled_size(esp_gmf_pbuf_handle_t handle, uint32_t *filled_size)

Get the number of bytes that have filled the pointer buffer.

Parameters:

• handle – [in] Handle to the pointer buffer

• filled_size – [out] Pointer to store the filled size

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_total_size(esp_gmf_pbuf_handle_t handle, uint32_t *total_size)

Get the total size of the pointer buffer (in bytes)

Parameters:

• handle – [in] Handle to the pointer buffer

• total_size – [out] Pointer to store the total size

Returns:

• ESP_GMF_ERR_OK Operation successful

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

Type Definitions

typedef void *esp_gmf_pbuf_handle_t

GMF Pointer Buffer is an interface for passing buffer addresses without generating any copies. esp_gmf_pbuf_acquire_read is used to retrieve a filled buffer. esp_gmf_pbuf_acquire_write indicates the address of an available buffer. If no available buffer exists, a request will also be made. The maximum number of requests is specified during initialization. The esp_gmf_pbuf_acquire_read/write and esp_gmf_pbuf_release_read/writer must be used in pairs and cannot be invoked recursively.

Its interfaces do not possess blocking conditions, but they can be called safely in a multithreaded environment.

Represents a handle to a pointer buffer

---

Was this page helpful?

• Thank you! We received your feedback.
• If you have any comments, fill in Espressif Documentation Feedback Form.

• We value your feedback.
• Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.