数据总线

[English]

数据总线（data bus）是数据端口（port）下层承载数据的队列实现。数据端口提供统一的 acquire-release 协议，数据总线负责缓冲区管理、跨线程同步，以及生产者与消费者之间的数据载体（payload）排队。GMF-Core 提供 ringbuffer、fifo、block、pbuf 四种实现，分别面向不同的拷贝策略、阻塞语义和数据粒度。处理单元（element）通过数据端口访问数据，不需要直接感知具体数据总线实现。

数据端口与 acquire-release 协议见数据流转，处理链（pipeline）与执行线程（task）的关系见 GMF 处理链与任务调度。

设计维度

选择数据总线实现时，主要看数据如何进入缓冲区、读写是否需要等待，以及每次传递的是字节流或整块数据。下表先按拷贝策略、阻塞语义和数据粒度对四种实现做对比，后文再分别说明各自的缓冲区来源与适用场景。

维度	ringbuffer	fifo / block	pbuf
拷贝策略	有 memcpy	零拷贝（按地址传递）	零拷贝（指针队列）
阻塞语义	读写均阻塞	读写均阻塞	非阻塞
数据粒度	任意字节	整块	整块

选型时需要先判断三件事：上下游速率差异有多大，数据是否能按整块边界传递，调用方是否允许在缓冲不可用时等待。

四种实现

ringbuffer

ringbuffer 维护一个固定大小的循环缓冲区，每次按字节读写。acquire_read 会等待到有数据可读，acquire_write 会等待到有空间可写。数据写入和读出都会经过 ringbuffer 内部缓冲区，因此每次读写各有一次 memcpy。

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

适合上下游处理速率差异较大、需要缓冲解耦的场景。例如 MP3 解码器按帧输出 PCM，而 I2S 按固定节奏消费数据时，ringbuffer 可以吸收解码输出的突发性。

fifo

fifo 是按地址传递的先进先出队列。acquire_write 返回一块空闲数据载体容器，处理单元写入后通过 release_write 入队；acquire_read 从队首取出已填充的数据载体供下游读取。数据在队列中按地址传递，不经过内部 memcpy。

esp_gmf_db_new_fifo(capacity, &db);

适合上下游速率相近、访问粒度一致、需要阻塞语义的场景。fifo 不支持”任意字节数读取”，每次 acquire 获取的是完整数据块。fifo 的数据载体可以来自外部提供的内存；需要指定写侧缓冲区对齐时，可在首次 acquire_write 前调用 esp_gmf_fifo_set_align() 设置对齐值。

block

block 强调”一次一整块”的语义。创建时预分配 num 块 buf_size 字节的缓冲区；写侧通过 acquire_write 获取空闲块，填充后通过 release_write 提交给读侧。

esp_gmf_db_new_block(num, buf_size, &db);

适合整帧传递（如一帧视频）、对象大小固定、需要零拷贝的场景。与 fifo 的区别在缓冲区管理：fifo 的数据载体内存可由外部提供，block 的缓冲区由数据总线创建时预分配。

pbuf

pbuf 是数据载体指针队列。它不分配缓冲区，只排队数据载体指针，acquire 和 release 都是非阻塞调用。

esp_gmf_db_new_pbuf(depth, &db);

适合数据已经位于固定内存区（例如 DMA 采集缓冲区）的场景。生产者把带有缓冲区地址的数据载体指针提交给 pbuf，下游随后获取同一数据载体指针。由于 pbuf 不阻塞，生产者必须自行保证队列不溢出。

block 与 pbuf 都按整块数据载体传递。如果下游处理单元需要按任意字节数读取，可以在处理单元内部使用字节缓存（cache）：先把 acquire 到的整块数据载体加载进 esp_gmf_cache，再通过 esp_gmf_cache_acquire 按固定长度或任意长度取出数据。这样既保留 block / pbuf 的零拷贝传递方式，又把处理单元内部的访问粒度转换为字节级读取。

选择指南

需求特征	推荐实现	缓冲区来源	拷贝	阻塞
字节存取，速率差异大	ringbuffer	数据总线内部循环缓冲区	是	是
任意大小写入、零拷贝	fifo	外部提供的数据载体 / buffer	否	是
整帧数据、零拷贝	block	数据总线内部固定块	否	是
DMA 缓冲区直接传递	pbuf	生产者提供的数据载体指针	否	否

选型顺序建议为：先确定是否能接受 memcpy，再确定读写是否需要阻塞，最后判断数据是否按固定块传递。需要”按任意字节数读”时通常选择 ringbuffer；如果上游使用 block 或 pbuf 传递整块数据，也可以在处理单元内部配合字节缓存完成字节级读取。

公共接口

数据总线的读写、复位、状态查询等操作由 esp_gmf_data_bus.h 提供统一接口。数据端口在创建时绑定其中一种数据总线，后续通过同一组 acquire-release 接口访问。

API	作用
`esp_gmf_db_acquire_write`	申请一块可写数据载体
`esp_gmf_db_release_write`	提交写完的数据载体给读侧
`esp_gmf_db_acquire_read`	申请一块可读数据载体
`esp_gmf_db_release_read`	归还读完的数据载体给写侧
`esp_gmf_db_reset`	清空缓冲、重置内部状态
`esp_gmf_db_get_total_size` / `esp_gmf_db_get_filled_size`	查询容量与已填充字节数
`esp_gmf_db_get_available`	查询当前可写空间

通常处理单元不直接调用这些 API，而是通过数据端口的 esp_gmf_port_acquire_* 间接访问。数据端口与 acquire-release 协议见数据流转。

部分实现还提供专用配置接口。例如 fifo 可在首次写侧 acquire 前调用 esp_gmf_fifo_set_align() 设置缓冲区地址对齐值，用于 DMA 或 PSRAM cache 对齐场景。

流结束与中止控制

除了正常的读写循环，数据总线还提供四个流控接口，用来表达 EOF 与中止两种语义。

API	影响	典型场景
`esp_gmf_db_done_write()`	置 EOF，让 `acquire_read` 返回带 `is_done` 的数据载体	数据源读到末尾
`esp_gmf_db_reset_done_write()`	清除 EOF	切换到新数据源、复用数据总线
`esp_gmf_db_abort()`	唤醒所有阻塞调用，返回 `ESP_GMF_IO_ABORT`	紧急停止、错误恢复
`esp_gmf_db_clear_abort()`	仅清 abort 标志，缓冲区数据保留	错误恢复后继续读写

done 与 abort 的语义差别在于：done 表示数据自然结束，下游处理完剩余数据后进入结束流程；abort 表示立即中止，后续读写调用返回 ESP_GMF_IO_ABORT。两者都让执行线程退出 running 阶段，分别进入 FINISHED 与 STOPPED 路径（详见 GMF 处理链与任务调度的执行线程调度章节）。

clear_abort 与 reset 的差别在于：esp_gmf_db_reset() 会清空缓冲数据并重置内部状态，clear_abort 只清除 abort 状态位。若恢复后仍要继续处理缓冲区中保留的数据，使用 clear_abort；若需要丢弃旧数据并重新开始，使用 reset。

API 参考

四种实现的统一接口与公共类型：

esp_gmf_data_bus.h：数据总线公共接口（acquire / release / done / abort / reset）
esp_gmf_new_databus.h：四种实现的创建接口

具体实现的头文件按需查阅 esp_gmf_ringbuffer.h / esp_gmf_fifo.h / esp_gmf_block.h / esp_gmf_pbuf.h。常规读写通过数据总线公共接口完成；只有使用实现专属配置接口时，才需要查看具体实现头文件。

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.

参数:

db_config – [in] Pointer to the configuration structure
hd – [out] Pointer to store the data bus handle after initialization

返回:

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.

参数:

handle – [in] data bus handle to deinitialize

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

handle – [in] data bus handle

返回:

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.

参数:

handle – [in] data bus handle

返回:

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.

参数:

handle – [in] data bus handle

返回:

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.

参数:

handle – [in] data bus handle

返回:

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.

备注

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)

参数:

handle – [in] data bus handle

返回:

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.

备注

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

参数:

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

返回:

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.

参数:

handle – [in] data bus handle
buff_size – [out] Pointer to store the total buffer size

返回:

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.

参数:

handle – [in] data bus handle
filled_size – [out] Pointer to store the filled buffer size

返回:

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.

参数:

handle – [in] data bus handle
available_size – [out] Pointer to store the available buffer size

返回:

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.

参数:

handle – [in] data bus handle
holder – [in] Pointer to the writer holder

返回:

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.

参数:

handle – [in] data bus handle
holder – [out] Pointer to store the writer holder

返回:

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.

参数:

handle – [in] data bus handle
holder – [in] Pointer to the reader holder

返回:

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.

参数:

handle – [in] data bus handle
holder – [out] Pointer to store the reader holder

返回:

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.

参数:

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

返回:

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.

参数:

handle – [in] data bus handle

返回:

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.

参数:

num – [in] Size of each item
item_cnt – [in] Number of items
h – [out] Pointer to store the handle of the GMF data bus

返回:

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.

参数:

num – [in] Size of each item
item_cnt – [in] Number of items
h – [out] Pointer to store the handle of the GMF data bus

返回:

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.

参数:

num – [in] Size of each item
item_cnt – [in] Number of items
h – [out] Pointer to store the handle of the GMF data bus

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

handle – [in] The Ringbuffer handle

返回:

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.

参数:

handle – [in] The Ringbuffer handle

返回:

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

参数:

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

返回:

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.

备注

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

参数:

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

返回:

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.

备注

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

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

handle – [in] The Ringbuffer handle

返回:

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.

备注

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

参数:

handle – [in] The Ringbuffer handle

返回:

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.

参数:

handle – [in] The Ringbuffer handle

返回:

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.

参数:

handle – [in] The Ringbuffer handle

返回:

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.

参数:

handle – [in] The Ringbuffer handle
available_size – [out] Pointer to store the available size

返回:

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.

参数:

handle – [in] The Ringbuffer handle
filled_size – [out] Pointer to store the filled size

返回:

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.

参数:

handle – [in] The Ringbuffer handle
valid_size – [out] Pointer to store the total size

返回:

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.

参数:

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

返回:

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.

备注

Should call this API before esp_gmf_fifo_acquire_write to get aligned buffer

参数:

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)

返回:

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.

参数:

handle – [in] FIFO handle to be destroyed

返回:

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.

备注

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

The obtained buffer address is internal and should not be freed externally.
The obtained blocks must be released by esp_gmf_fifo_release_read in pairs.
The actual valid size is stored in blk->valid_size

参数:

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

返回:

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.

备注

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

esp_gmf_fifo_acquire_read and esp_gmf_fifo_release_read must be called in pairs
Calling this function once makes one block available for the write operation

参数:

handle – [in] FIFO handle
blk – [in] Pointer to the data block structure to be released
block_ticks – [in] Maximum ticks to wait if necessary

返回:

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.

备注

1. esp_gmf_fifo_acquire_write and esp_gmf_fifo_release_write must be called in pairs

The obtained buffer address is internal and should not be freed externally
The wanted_size parameter is used to specify the size of the block that can be written
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
If the obtained buffer is smaller than the wanted_size, the buffer will be reallocated to match the requested size

参数:

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

返回:

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.

备注

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

esp_gmf_fifo_acquire_write and esp_gmf_fifo_release_write must be called in pairs
Calling this function once makes one block available for read operations, and the count of freed blocks will be decremented by one

参数:

handle – [in] FIFO handle
blk – [in] Pointer to the data block structure to be released
block_ticks – [in] Maximum ticks to wait if necessary

返回:

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.

参数:

handle – [in] FIFO handle

返回:

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.

参数:

handle – [in] FIFO handle

返回:

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.

参数:

handle – [in] FIFO handle

返回:

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.

备注

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

参数:

handle – [in] The FIFO handle

返回:

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.

参数:

handle – [in] FIFO handle

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

备注

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.

参数:

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.

返回:

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.

参数:

handle – [in] The block handle

返回:

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.

备注

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.

The obtained buffer address is internal and should not be freed externally
The wanted_size can’t be greater than block_size * block_cnt
The actual valid size is stored in blk->valid_size

参数:

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

返回:

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.

备注

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

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
If the buffer address reaches the end of the internal buffer, the read pointer will be reset to the beginning of the internal buffer

参数:

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

返回:

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.

备注

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

The obtained buffer address is internal and should not be freed externally
The wanted_size can’t be greater than block_size * block_cnt

参数:

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

返回:

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.

备注

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

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
If the buffer address reaches the end of the internal buffer, the write pointer will be reset to the beginning of the internal buffer

参数:

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

返回:

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.

备注

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.

参数:

handle – [in] The block handle

返回:

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.

参数:

handle – [in] The block handle

返回:

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.

参数:

handle – [in] The block handle

返回:

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.

备注

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

参数:

handle – [in] The block handle

返回:

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.

参数:

handle – [in] The block handle

返回:

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.

参数:

handle – [in] The handle to the GMF block.
free_size – [out] Pointer to a variable where the free size will be stored.

返回:

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.

参数:

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

返回:

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.

参数:

handle – [in] The handle to the GMF block
filled_size – [out] Pointer to a variable where the filled size will be stored

返回:

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.

参数:

capacity – [in] The capacity of the maximum pointer buffer
handle – [out] Pointer to store the handle to the created pointer buffer

返回:

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

备注

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.

参数:

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)

返回:

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.

参数:

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

返回:

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.

备注

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

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
The actual valid size is stored in blk->valid_size

参数:

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)

返回:

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.

备注

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

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

参数:

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)

返回:

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.

备注

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

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

参数:

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)

返回:

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.

备注

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

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

参数:

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)

返回:

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.

参数:

handle – [in] Handle to the pointer buffer

返回:

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.

参数:

handle – [in] Handle to the pointer buffer

返回:

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.

参数:

handle – [in] Handle to the pointer buffer

返回:

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.

备注

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

参数:

handle – [in] The Pointer Buffer handle

返回:

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.

参数:

handle – [in] Handle to the pointer buffer

返回:

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.

参数:

handle – [in] Handle to the pointer buffer
free_size – [out] Pointer to store the total free size

返回:

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.

参数:

handle – [in] Handle to the pointer buffer
filled_size – [out] Pointer to store the filled size

返回:

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)

参数:

handle – [in] Handle to the pointer buffer
total_size – [out] Pointer to store the total size

返回:

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

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。