# 数据总线

[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.

  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`

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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.

  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`

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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

  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`

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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

  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

  参数:

    - 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

此文档对您有帮助吗？

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

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