# Data Bus

[中文]

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

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

## Design Dimensions

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

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

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

## Four Implementations

### ringbuffer

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

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

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

### fifo

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

    esp_gmf_db_new_fifo(capacity, &db);

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

### block

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

    esp_gmf_db_new_block(num, buf_size, &db);

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

### pbuf

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

    esp_gmf_db_new_pbuf(depth, &db);

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

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

## Selection Guide

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

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

## Common Interface

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

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

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

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

## EOF and Abort Control

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

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

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

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

## API Reference

Unified interface and common types for the four implementations:

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

- `esp_gmf_new_databus.h`: Creation interfaces for the four implementations

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

### Header File

- gmf_core/data_bus/include/esp_gmf_data_bus.h

### Functions

esp_gmf_err_t esp_gmf_db_init(esp_gmf_db_config_t *db_config, esp_gmf_db_handle_t *hd)

  Initialize data bus with the given configuration.

  Parameters:

    - db_config – [in] Pointer to the configuration structure

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

    - ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_db_deinit(esp_gmf_db_handle_t handle)

  Deinitialize data bus, freeing associated resources.

  Parameters:

    handle – [in] data bus handle to deinitialize

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

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

  Read data from data bus.

  Parameters:

    - handle – [in] data bus handle

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

    - buf_len – [in] Length of the buffer

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

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

  Write data to data bus.

  Parameters:

    - handle – [in] data bus handle

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

    - buf_len – [in] Length of the data buffer

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

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

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

  Parameters:

    - handle – [in] data bus handle

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

    - wanted_size – [in] Size of data to acquire

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

  Returns:

    - ESP_GMF_IO_OK Operation successful

    - ESP_GMF_IO_FAIL Operation failed

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Release a read operation on data bus.

  Parameters:

    - handle – [in] data bus handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation successful

    - ESP_GMF_IO_FAIL Operation failed

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Acquire space to write operation on data bus.

  Parameters:

    - handle – [in] data bus handle

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

    - wanted_size – [in] Size of data to acquire

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

  Returns:

    - ESP_GMF_IO_OK Operation successful

    - ESP_GMF_IO_FAIL Operation failed

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Release a write operation on data bus.

  Parameters:

    - handle – [in] data bus handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation successful

    - ESP_GMF_IO_FAIL Operation failed

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_t esp_gmf_db_done_write(esp_gmf_db_handle_t handle)

  Mark a write operation as done on data bus.

  Parameters:

    handle – [in] data bus handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_reset_done_write(esp_gmf_db_handle_t handle)

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

  Parameters:

    handle – [in] data bus handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_reset(esp_gmf_db_handle_t handle)

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

  Parameters:

    handle – [in] data bus handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_abort(esp_gmf_db_handle_t handle)

  Abort exit the data bus.

  Parameters:

    handle – [in] data bus handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_clear_abort(esp_gmf_db_handle_t handle)

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

  Note

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

  Parameters:

    handle – [in] data bus handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

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

  Set buffer alignment for the underlying data bus implementation.

  Note

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

  Parameters:

    - handle – [in] data bus handle

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_total_size(esp_gmf_db_handle_t handle, uint32_t *buff_size)

  Get the total size of data bus buffer.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_filled_size(esp_gmf_db_handle_t handle, uint32_t *filled_size)

  Get the filled size of data bus buffer.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_available(esp_gmf_db_handle_t handle, uint32_t *available_size)

  Get the available size in data bus buffer.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_set_writer(esp_gmf_db_handle_t handle, void *holder)

  Set the writer holder for data bus.

  Parameters:

    - handle – [in] data bus handle

    - holder – [in] Pointer to the writer holder

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_writer(esp_gmf_db_handle_t handle, void **holder)

  Get the writer holder from data bus.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_set_reader(esp_gmf_db_handle_t handle, void *holder)

  Set the reader holder for data bus.

  Parameters:

    - handle – [in] data bus handle

    - holder – [in] Pointer to the reader holder

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_reader(esp_gmf_db_handle_t handle, void **holder)

  Get the reader holder from data bus.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_db_get_type(esp_gmf_db_handle_t handle, esp_gmf_data_bus_type_t *db_type)

  Get the data bus type of data bus.

  Parameters:

    - handle – [in] data bus handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

const char *esp_gmf_db_get_name(esp_gmf_db_handle_t handle)

  Get the name of data bus.

  Parameters:

    handle – [in] data bus handle

  Returns:

    - Pointer to the name of the data bus

### Structures

struct esp_gmf_data_bus_block_t

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

  Public Members

  uint8_t *buf

    Pointer to the buffer

  size_t buf_length

    Length of the buffer

  size_t valid_size

    Valid data size in the buffer

  bool is_last

    Flag indicating if the buffer is the last

struct data_bus_op_t

  Structure representing the operations of a data bus.

  Public Members

  esp_gmf_err_t (*deinit)(esp_gmf_db_handle_t handle)

    Deinitialize the data bus

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

    Read data from the data bus

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

    Write data to the data bus

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

    Acquire a block of data for reading

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

    Release a block of data after reading

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

    Acquire a block of data for writing

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

    Release a block of data after writing

  esp_gmf_err_t (*done_write)(esp_gmf_db_handle_t handle)

    Signal that writing to the data bus is done

  esp_gmf_err_t (*reset_done_write)(esp_gmf_db_handle_t handle)

    Reset the “done writing” signal

  esp_gmf_err_t (*reset)(esp_gmf_db_handle_t handle)

    Reset the data bus

  esp_gmf_err_t (*abort)(esp_gmf_db_handle_t handle)

    Abort ongoing operations

  esp_gmf_err_t (*clear_abort)(esp_gmf_db_handle_t handle)

    Clear abort flag and restore semaphores

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

    Optional alignment

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

    Get the total size of the data bus

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

    Get the filled size of the data bus

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

    Get the available size of the data bus

struct esp_gmf_data_bus_t

  Structure representing a data bus.

  Public Members

  struct data_bus_op_t op

    Operations of the data bus

  void *child

    Pointer to the child

  void *writer

    Pointer to the writer who call the write associated functions

  void *reader

    Pointer to the reader who call the read associated functions

  const char *name

    Name of the data bus

  esp_gmf_data_bus_type_t type

    Type of the data bus

  int max_item_num

    Maximum number of items

  int max_size

    Maximum size

struct esp_gmf_db_config_t

  Configuration for the database.

  Public Members

  void *child

    Pointer to the child

  const char *name

    Name of the database

  esp_gmf_data_bus_type_t type

    Type of the data bus

  int max_item_num

    Maximum number of items

  int max_size

    Maximum size

  bool safeguard

    Flag indicating if the safeguard is enabled

### Type Definitions

typedef void *esp_gmf_db_handle_t

  Handle for the data bus interface.

### Enumerations

enum esp_gmf_data_bus_type_t

  Type of data bus.

  Values:

  enumerator DATA_BUS_TYPE_BYTE

    Data bus type for byte-oriented data

  enumerator DATA_BUS_TYPE_BLOCK

    Data bus type for block-oriented data

### Header File

- gmf_core/data_bus/include/esp_gmf_new_databus.h

### Functions

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

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

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

  See LICENSE file for details.

  Parameters:

    - num – [in] Size of each item

    - item_cnt – [in] Number of items

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

  Returns:

    - 0 On success

    - < 0 Negative value if an error occurs

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

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

  Parameters:

    - num – [in] Size of each item

    - item_cnt – [in] Number of items

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

  Returns:

    - 0 On success

    - < 0 Negative value if an error occurs

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

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

  Parameters:

    - num – [in] Size of each item

    - item_cnt – [in] Number of items

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

  Returns:

    - 0 On success

    - < 0 Negative value if an error occurs

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

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

  Parameters:

    - num – [in] num Maximum number of items

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

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

  Returns:

    - 0 On success

    - < 0 Negative value if an error occurs

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

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

  Parameters:

    - size – [in] Total queue buffer size

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

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

  Returns:

    - 0 On success

    - < 0 Negative value if an error occurs

### Header File

- gmf_core/data_bus/include/esp_gmf_ringbuffer.h

### Functions

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

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

  Parameters:

    - block_size – [in] Size of each block

    - n_blocks – [in] Number of blocks

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_rb_destroy(esp_gmf_rb_handle_t handle)

  Cleanup and free all memory allocated for the ring buffer.

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_reset(esp_gmf_rb_handle_t handle)

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

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

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

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

  Parameters:

    - handle – [in] The Ringbuffer handle

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

    - wanted_size – [in] Desired size to read

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

    - ESP_GMF_IO_FAIL Invalid arguments

    - ESP_GMF_IO_TIMEOUT Operation timed out

    - ESP_GMF_IO_ABORT Operation aborted

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

  Release the read operation.

  Note

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

  Parameters:

    - handle – [in] The Ringbuffer handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

  Acquire space for write.

  Note

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

  Parameters:

    - handle – [in] The Ringbuffer handle

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

    - wanted_size – [in] Desired size to write

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

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

  Parameters:

    - handle – [in] The Ringbuffer handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

    - ESP_GMF_IO_FAIL Invalid arguments

    - ESP_GMF_IO_TIMEOUT Operation timed out

    - ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_rb_abort(esp_gmf_rb_handle_t handle)

  Abort any pending operations on the ring buffer.

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_clear_abort(esp_gmf_rb_handle_t handle)

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

  Note

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

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_rb_done_write(esp_gmf_rb_handle_t handle)

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

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_reset_done_write(esp_gmf_rb_handle_t handle)

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

  Parameters:

    handle – [in] The Ringbuffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_bytes_available(esp_gmf_rb_handle_t handle, uint32_t *available_size)

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

  Parameters:

    - handle – [in] The Ringbuffer handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_bytes_filled(esp_gmf_rb_handle_t handle, uint32_t *filled_size)

  Get the number of bytes filled in the ring buffer.

  Parameters:

    - handle – [in] The Ringbuffer handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_rb_get_size(esp_gmf_rb_handle_t handle, uint32_t *valid_size)

  Get the total size of the ring buffer.

  Parameters:

    - handle – [in] The Ringbuffer handle

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

### Type Definitions

typedef void *esp_gmf_rb_handle_t

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

  The `esp_gmf_rb_release_write` and `esp_gmf_rb_acquire_read` have blocking functionality.

  Handle to the ring buffer

### Header File

- gmf_core/data_bus/include/esp_gmf_fifo.h

### Functions

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

  Create a FIFO buffer for data blocks.

  Parameters:

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

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

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

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

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

  Set alignment for FIFO buffer.

  Note

  Should call this API before `esp_gmf_fifo_acquire_write` to get aligned buffer

  Parameters:

    - handle – [in] FIFO handle

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

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

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_destroy(esp_gmf_fifo_handle_t handle)

  Destroy the FIFO buffer and release resources.

  Parameters:

    handle – [in] FIFO handle to be destroyed

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle

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

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

  Note

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

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

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

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

  Parameters:

    - handle – [in] FIFO handle

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

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

    - ESP_GMF_IO_FAIL Invalid arguments, or wanted_size > total size

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Returned acquired block address to the specific handle.

  Note

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

  1. `esp_gmf_fifo_acquire_read` and `esp_gmf_fifo_release_read` must be called in pairs

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

  Parameters:

    - handle – [in] FIFO handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

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

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

  Note

  1. `esp_gmf_fifo_acquire_write` and `esp_gmf_fifo_release_write` must be called in pairs

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

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

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

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

  Parameters:

    - handle – [in] FIFO handle

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

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

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

  Returns:

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

    - ESP_GMF_IO_FAIL Invalid arguments, or no filled data

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Returned a previously acquired write block.

  Note

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

  1. `esp_gmf_fifo_acquire_write` and `esp_gmf_fifo_release_write` must be called in pairs

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

  Parameters:

    - handle – [in] FIFO handle

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_fifo_done_write(esp_gmf_fifo_handle_t handle)

  Indicate that writing to the FIFO is complete.

  Parameters:

    handle – [in] FIFO handle

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_reset_done_write(esp_gmf_fifo_handle_t handle)

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

  Parameters:

    handle – [in] FIFO handle

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_abort(esp_gmf_fifo_handle_t handle)

  Abort all operations on the FIFO.

  Parameters:

    handle – [in] FIFO handle

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_clear_abort(esp_gmf_fifo_handle_t handle)

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

  Note

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

  Parameters:

    handle – [in] The FIFO handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_fifo_reset(esp_gmf_fifo_handle_t handle)

  Reset the FIFO to its initial state.

  Parameters:

    handle – [in] FIFO handle

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid handle

esp_gmf_err_t esp_gmf_fifo_get_free_size(esp_gmf_fifo_handle_t handle, uint32_t *free_size)

  Get the amount of free space in the FIFO.

  Parameters:

    - handle – [in] FIFO handle

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

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_get_filled_size(esp_gmf_fifo_handle_t handle, uint32_t *filled_size)

  Get the amount of filled space in the FIFO.

  Parameters:

    - handle – [in] FIFO handle

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

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

esp_gmf_err_t esp_gmf_fifo_get_total_size(esp_gmf_fifo_handle_t handle, uint32_t *total_size)

  Get the total capacity of the FIFO.

  Parameters:

    - handle – [in] FIFO handle

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

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments

### Type Definitions

typedef void *esp_gmf_fifo_handle_t

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

  Handle for the GMF FIFO

### Header File

- gmf_core/data_bus/include/esp_gmf_block.h

### Functions

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

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

  Parameters:

    - block_size – [in] Size of each block

    - block_cnt – [in] Number of blocks

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

    - ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

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

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

  Note

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

  Parameters:

    - handle – [in] Block buffer handle from esp_gmf_block_create

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

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

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

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

esp_gmf_err_t esp_gmf_block_destroy(esp_gmf_block_handle_t handle)

  Cleanup and free all memory created by esp_gmf_block_create.

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

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

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

  Note

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

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

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

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

  Parameters:

    - handle – [in] Handle to the block buffer

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

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

    - ESP_GMF_IO_FAIL Invalid arguments, or wanted_size > total size

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Returned acquired buffer address to the specific handle.

  Note

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

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

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

  Parameters:

    - handle – [in] Handle to the block buffer

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

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

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

  Note

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

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

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

  Parameters:

    - handle – [in] Handle to the block buffer

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

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

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

  Returns:

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

    - ESP_GMF_IO_FAIL Invalid arguments, or no filled data

    - ESP_GMF_IO_ABORT Operation aborted

    - ESP_GMF_IO_TIMEOUT Operation timed out

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

  Returned acquired buffer address to the specific handle.

  Note

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

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

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

  Parameters:

    - handle – [in] Handle to the block buffer

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_block_done_write(esp_gmf_block_handle_t handle)

  Set status of writing to is done.

  Note

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

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_reset_done_write(esp_gmf_block_handle_t handle)

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

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_abort(esp_gmf_block_handle_t handle)

  Abort waiting if reading or writing is blocking.

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_clear_abort(esp_gmf_block_handle_t handle)

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

  Note

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

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_reset(esp_gmf_block_handle_t handle)

  Reset, clear all values as initial state.

  Parameters:

    handle – [in] The block handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_free_size(esp_gmf_block_handle_t handle, uint32_t *free_size)

  Get the free size of a GMF block.

  Parameters:

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_total_size(esp_gmf_block_handle_t handle, uint32_t *total_size)

  Get the total size of a GMF block.

  Parameters:

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_block_get_filled_size(esp_gmf_block_handle_t handle, uint32_t *filled_size)

  Get the filled size of a GMF block.

  Parameters:

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

### Type Definitions

typedef void *esp_gmf_block_handle_t

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

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

  Represents a handle to a block buffer

### Header File

- gmf_core/data_bus/include/esp_gmf_pbuf.h

### Functions

esp_gmf_err_t esp_gmf_pbuf_create(int capacity, esp_gmf_pbuf_handle_t *handle)

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

  Parameters:

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

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

    - ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

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

  Set default alignment for payload buffers allocated on `esp_gmf_pbuf_acquire_write`

  Note

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

  Parameters:

    - handle – [in] Pointer buffer handle

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

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

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG If handle is NULL or alignment is invalid

esp_gmf_err_t esp_gmf_pbuf_destroy(esp_gmf_pbuf_handle_t handle)

  Destroy a pointer buffer and release all associated resources.

  Parameters:

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

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

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

  Note

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

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

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

    - ESP_GMF_IO_FAIL Invalid arguments, or no filled data

    - ESP_GMF_IO_ABORT Operation aborted

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

  Returned acquired buffer to the specific pointer buffer.

  Note

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

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

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

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

  Note

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

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

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

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

  Returns:

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

    - ESP_GMF_IO_FAIL Invalid arguments, or no filled data

    - ESP_GMF_IO_ABORT Operation aborted

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

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

  Note

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

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

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

  Returns:

    - ESP_GMF_IO_OK Operation succeeded

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

    - ESP_GMF_IO_ABORT Operation aborted

esp_gmf_err_t esp_gmf_pbuf_done_write(esp_gmf_pbuf_handle_t handle)

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

  Parameters:

    handle – [in] Handle to the pointer buffer

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_reset_done_write(esp_gmf_pbuf_handle_t handle)

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

  Parameters:

    handle – [in] Handle to the pointer buffer

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_abort(esp_gmf_pbuf_handle_t handle)

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

  Parameters:

    handle – [in] Handle to the pointer buffer

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_clear_abort(esp_gmf_pbuf_handle_t handle)

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

  Note

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

  Parameters:

    handle – [in] The Pointer Buffer handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_pbuf_reset(esp_gmf_pbuf_handle_t handle)

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

  Parameters:

    handle – [in] Handle to the pointer buffer

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_free_size(esp_gmf_pbuf_handle_t handle, uint32_t *free_size)

  Get the total free size of the pointer buffer.

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_filled_size(esp_gmf_pbuf_handle_t handle, uint32_t *filled_size)

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_pbuf_get_total_size(esp_gmf_pbuf_handle_t handle, uint32_t *total_size)

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

  Parameters:

    - handle – [in] Handle to the pointer buffer

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

  Returns:

    - ESP_GMF_ERR_OK Operation successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument provided

### Type Definitions

typedef void *esp_gmf_pbuf_handle_t

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

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

  Represents a handle to a pointer buffer

Was this page helpful?

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

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