Data Flow

[中文]

This document describes how data flows between elements, covering payload fields and ownership, the port acquire-release protocol, how IO connects at the head and tail of a pipeline, and the byte cache.

For element lifecycle, port attributes, capability description, and runtime methods, see GMF Elements. For pipeline orchestration, task scheduling, lifecycle, and control interfaces, see GMF Pipeline and Task Scheduling. For the four data bus implementations and their selection, see Data Bus. For the overall architecture and object relationships, see GMF-Core Overview.

Payload and Port

Each element exposes only two data interfaces externally: an input port and an output port. Data is passed between ports as esp_gmf_payload_t; elements are not responsible for buffer allocation or cross-thread synchronization, and only need to read and write data following an acquire-release protocol.

The complete data flow in a single process call is shown below, using a Decoder -> Resample pipeline as an example.

        sequenceDiagram
    participant T as Task
    participant E as resample
    participant IP as in_port
    participant OP as out_port
    participant D as Downstream

    T->>+E: process()
    E->>+IP: acquire_in(size)
    IP-->>-E: input payload in
    E->>+OP: acquire_out(size)
    OP-->>-E: output payload out
    Note over E: Process input and generate output
    E->>OP: release_out(out)
    OP->>D: Submit output payload
    E->>IP: release_in(in)
    E-->>-T: ok
    

The sequence above contains two rules. First, the payload returned by acquire_in remains owned by the current element until release_in is called; the port maintains the validity of this data via reference counting or the underlying implementation, so the element does not need to handle cross-thread synchronization itself. Second, release_out submits the output payload. For block-type ports, the submission typically does not copy data, but hands the payload to the downstream input port or the underlying data queue, so one piece of data can traverse the entire pipeline without intermediate copies.

acquire-release is the fundamental protocol of the GMF-Core data path. The following sections detail the payload and port.

Payload

Fields

esp_gmf_payload_t is defined in esp_gmf_payload.h with the following fields.

Field	Type	Meaning
buf	uint8_t*	Pointer to the data buffer
buf_length	size_t	Total buffer length
valid_size	size_t	Length of valid data in the buffer
is_done	bool	End-of-stream flag; set to 1 for the last data block, triggers the pipeline to enter FINISHED
pts	uint64_t	Presentation timestamp, used for audio/video synchronization
needs_free	uint8_t	1-bit field indicating whether buf should be automatically freed when the payload is destroyed
meta_flag	uint8_t	7-bit field; currently defines ESP_GMF_META_FLAG_AUD_RECOVERY_PLC to mark audio frames recovered via packet loss concealment

Lifecycle and Ownership

In element code, a payload appears as an esp_gmf_payload_t * pointer. Ownership belongs to the current element during acquire-release; after release, it is returned to port and data bus management. Three rules apply when using payloads:

• Do not free manually: Payloads acquired from a port are managed by the port; elements can only read and write buf content and must not call esp_gmf_payload_delete.

• valid_size is set by the writer: After acquiring an output payload, the element writes data and fills valid_size with the actual number of bytes written; downstream uses this to determine how much valid data there is.

• acquire and release must be paired: Even if an error occurs during processing, release must still be called; otherwise the port enters a leaked state and subsequent calls will exhaust the buffers.

In the less common scenario where an element allocates its own payload (typically a source IO element), it can explicitly create one with esp_gmf_payload_new() or esp_gmf_payload_new_with_len() and release it with esp_gmf_payload_delete() when no longer referenced. For PSRAM cache alignment, use esp_gmf_payload_realloc_aligned_buf().

is_done and pts

is_done is the signal for the pipeline to naturally transition from RUNNING to FINISHED. When an IO element reads to the end of the file, it sets is_done to 1 and sends it with the payload; downstream elements process the end-marked payload in turn and trigger close level by level.

pts is the presentation timestamp, typically filled by the source element. Intermediate elements update it as needed or pass it through directly. Elements near the playback end use it for audio/video synchronization.

Port

Direction and Type

Each port is defined by two attributes.

Direction: ESP_GMF_PORT_DIR_IN indicates an input port (reads payloads from upstream); ESP_GMF_PORT_DIR_OUT indicates an output port (writes payloads to downstream). Each element has one input port and one output port.

Type: Byte type and block type, corresponding to two data exchange strategies.

• ESP_GMF_PORT_TYPE_BYTE (byte type) allows the element to read and write any number of bytes; the framework handles internal copying and splicing as needed. Suitable for scenarios requiring precise fixed-length access, such as a decoder parsing protocol headers.

• ESP_GMF_PORT_TYPE_BLOCK (block type) accesses one entire block at a time, without copying; only buffer addresses are passed between ports. Suitable for processing an entire video frame or bulk PCM, with higher performance but lower configurability.

acquire-release Protocol

A port exposes four APIs used in pairs to form the acquire-release access protocol. The complete signature of acquire_in as an example:

esp_gmf_err_io_t esp_gmf_port_acquire_in(
    esp_gmf_port_handle_t   handle,
    esp_gmf_payload_t     **load,
    uint32_t                wanted_size,
    int                     wait_ticks);

The four parameters:

• handle is the input port handle.

• load is an output parameter; after the call returns, *load points to a payload ready for reading.

• wanted_size is the data length the element wants to obtain. For source IOs or ports bound to a data bus, the underlying implementation prepares data according to this value; for payloads already submitted to the input port by an upstream element, the port returns the current payload directly, and the actual valid length is based on (*load)->valid_size.

• wait_ticks is the wait timeout in system ticks. ESP_GMF_MAX_DELAY means wait indefinitely; 0 means return immediately.

The return type is esp_gmf_err_io_t:

Return Code	Value	Meaning
ESP_GMF_IO_OK	>= 0	Success; the value indicates the actual number of bytes read
ESP_GMF_IO_FAIL	-1	Operation failed
ESP_GMF_IO_TIMEOUT	-2	Wait timed out
ESP_GMF_IO_ABORT	-3	Actively aborted by esp_gmf_db_abort or a task stop

Template for element code handling return values:

esp_gmf_payload_t *in_load = NULL;
esp_gmf_err_io_t ret = esp_gmf_port_acquire_in(in_port, &in_load, 1024, ESP_GMF_MAX_DELAY);
if (ret == ESP_GMF_IO_ABORT) {
    return ESP_GMF_JOB_ERR_ABORT;
} else if (ret < 0) {
    return ESP_GMF_JOB_ERR_FAIL;
}
/* Use in_load->buf, in_load->valid_size */

The four APIs work in pairs:

• Read side: acquire_in gets a readable payload; the element consumes it and calls release_in to return it.

• Write side: acquire_out gets a writable payload; the element fills it and calls release_out to submit it.

The typical call order in process is: acquire_in first to get the input, then acquire_out to prepare the output buffer, after processing call release_out to submit to downstream, and finally release_in to return the input. Acquiring the output before processing allows waiting in advance if downstream is blocked, avoiding discovering an unavailable output port only after processing is complete.

acquire and release must be paired, even if an error occurs during processing. The framework provides several helper macros to simplify error paths:

ESP_GMF_PORT_ACQUIRE_IN_CHECK(TAG, ret, err, goto ACQ_FAIL);
ESP_GMF_PORT_RELEASE_IN_CHECK(TAG, ret, err, goto REL_FAIL);

These macros consolidate the return value check and error branch into a single line.

Shared Buffer Management

GMF provides two mechanisms to reduce memory usage and avoid unnecessary data copies.

Reference Counting

For bypass or in-place processing elements, the same payload can be passed directly to downstream elements or user applications. Each additional consumer increments the port’s ref_count; the corresponding release_in / release_out decrements it. When the count reaches zero, the port invokes the underlying release callback to reclaim the buffer. Sharing is controlled by the port’s is_shared flag, which can be enabled or disabled via esp_gmf_port_enable_payload_share() (shared by default).

        flowchart LR
    Source --> Bypass
    Bypass --> User
    Bypass --> Downstream["Downstream Element"]
    

The same data is shared throughout this flow without extra copies.

Buffer Reuse (AB Buffer)

For elements that produce new output data, the framework reuses payload buffers across elements via is_shared. For a pipeline A → B → C:

A → B → C

• A outputs Buffer A.

• B uses Buffer A as input and writes to Buffer B.

• After B completes, Buffer A can be reclaimed and reallocated.

• C uses Buffer B as input; its output can reuse the freed Buffer A.

As data flows through the pipeline, Buffer A and Buffer B alternate in reuse. Even with many elements in the chain, two working buffers are typically sufficient, significantly reducing memory consumption.

At initialization, elements declare constraints on their input and output ports, such as port type, alignment requirements, and recommended data size per acquire. Port attributes are part of the element configuration; for the complete description, see GMF Elements.

The data queue corresponding to a port is managed by the data bus. GMF-Core provides four data buses (ringbuffer / fifo / block / pbuf); a port binds to one of them at creation time, and the interface seen by element code is completely identical. For the trade-offs between the four implementations and flow control interfaces, see Data Bus.

External IO

An external IO (esp_gmf_io_t) is a special element at the head and tail of a pipeline, handling reading and writing of external data sources such as files, networks, and codecs. In addition to the basic open / acquire / release / close, asynchronous mode is supported: an io_process task writes data to an internal data bus while the caller reads from the buffer, smoothing rate fluctuations such as HTTP downloads; transfer rates are available via esp_gmf_io_speed_stats_t as instantaneous and average Kbps. Advanced control interfaces for switching data sources, interruption recovery, and similar scenarios are also provided.

Synchronous and Asynchronous Modes

An IO is configured at creation via esp_gmf_io_cfg_t to select its operating mode.

Synchronous mode: thread.stack = 0 and no buffer_cfg configured. esp_gmf_io_acquire_read executes the underlying IO operation (such as fread) directly in the calling thread context. Advantages are low latency and small memory footprint; the disadvantage is that the caller must tolerate potentially long blocking from IO operations (such as network reads).

Asynchronous mode: thread.stack > 0 and buffer_cfg.buffer_size configured. The framework internally creates an io_process task that independently performs the underlying IO operation and caches data to the data bus. When the user calls acquire_read, it actually reads from the data bus, decoupled from the underlying IO. This mode is suitable for “reading a fixed number of bytes” or “large production/consumption rate differences,” such as when a decoder needs a stable byte stream but network download is bursty.

esp_gmf_io_cfg_t cfg = {
    .thread = {
        .stack = 4 * 1024,
        .prio  = 5,
        .core  = 0,
    },
    .buffer_cfg = {
        .io_size     = 4096,   /* Size of each underlying IO read */
        .buffer_size = 16 * 1024,
        .read_filter = NULL,
    },
    .enable_speed_monitor = true,
};

URL Scoring Strategy

The get_score of esp_gmf_io_t is used to obtain the match score, enabling the pool to find the best-matching IO among multiple registered IOs. The pool function esp_gmf_pool_get_io_tag_by_url iterates all registered IOs’ get_score and returns the one with the highest score. Three scoring levels:

Score	Value	Meaning
ESP_GMF_IO_SCORE_NONE	0	IO does not support this URL
ESP_GMF_IO_SCORE_STANDARD	50	Protocol prefix matches, e.g., http:// is handled by the HTTP IO
ESP_GMF_IO_SCORE_PERFECT	100	Both protocol and file extension match, or a specialized IO with high-priority matching

Custom IOs implementing get_score can return any intermediate value to distinguish priority among multiple candidate IOs.

Seamless Reload and Reset

esp_gmf_io_reload() reopens an existing IO with a new URI without destroying the underlying connection. Primarily for scenarios like HLS segments where “multiple segments are downloaded continuously from the same host,” reusing the HTTP connection to avoid repeated handshake overhead. Internally, the reload clears the data_bus EOF flag, clears the abort flag, and calls the IO’s reload callback to reopen the new URI. reload must be called after the previous read has completed.

esp_gmf_io_reset() performs a more comprehensive cleanup: clears position and file size to zero, calls the IO’s reset callback, resets the task, and reloads the IO process job. Commonly used for corresponding IO cleanup after a pipeline reset.

Done / Abort Control

The IO layer’s done and abort control interfaces correspond one-to-one with the data bus, but in asynchronous mode they also additionally manage the IO task’s hold state.

• esp_gmf_io_done() marks EOF: aborts the asynchronous IO’s data bus and holds the task; downstream acquire will get a payload with is_done set. The caller must call esp_gmf_io_clear_done() to release the held task before switching to the next data source, otherwise the subsequent IO will not advance.

• esp_gmf_io_abort() immediately aborts the current operation: data bus abort, task hold; all acquire / release return ESP_GMF_IO_ABORT. The paired esp_gmf_io_clear_abort() restores normal operation.

Typical flow for switching tracks in a playlist:

/* Current track finished */
esp_gmf_io_done(io_handle);

/* Wait for the pipeline to finish processing remaining payloads */
...

/* Switch to the next track */
esp_gmf_io_set_uri(io_handle, next_uri);
esp_gmf_io_clear_done(io_handle);
/* Pipeline continues running without rebuilding */

Custom Payload Processing

The read_filter callback in esp_gmf_io_buffer_cfg_t allows inserting custom processing after the IO reads raw data and before it is written to the data bus. Common uses include decryption, byte-order conversion, and protocol de-encapsulation. Callback signature:

esp_gmf_err_t (*read_filter)(esp_gmf_io_handle_t obj,
                              void *payload,
                              uint32_t wanted_size,
                              int block_ticks);

The payload’s buf and valid_size can be modified in-place within the callback.

Speed Monitoring

After setting enable_speed_monitor to true in esp_gmf_io_cfg_t, the framework maintains current and average transfer speeds (Kbps), which can be retrieved via esp_gmf_io_get_speed_stats() as esp_gmf_io_speed_stats_t. The monitor can also be dynamically toggled at runtime with esp_gmf_io_enable_speed_monitor(). Commonly used for network condition monitoring and adaptive transfer rate.

Byte Cache

A block-type port returns an entire block per acquire, but elements such as decoders often need to “read exactly N bytes from the data stream.” The esp_gmf_cache module provides byte-level caching:

esp_gmf_cache_handle_t cache;
esp_gmf_cache_new(1024, &cache);

/* After each block payload is acquired, load it into cache */
esp_gmf_cache_load(cache, in_load->buf, in_load->valid_size);

/* Then read by any number of bytes */
int read;
esp_gmf_cache_acquire(cache, 7, out_buf, &read);
esp_gmf_cache_release(cache, 7);

The byte cache internally maintains an expandable sliding buffer. An element can continuously load bytes from multiple payloads into the cache, then read data of any desired length; even if a single read spans the boundary of two payloads, the cache returns the data continuously from its internal buffer. A typical use case is audio decoders parsing protocol or frame headers.

API Reference

Core header files covered in this document:

• esp_gmf_payload.h: Payload structure and lifecycle

• esp_gmf_port.h: Port configuration and access APIs

• esp_gmf_cache.h: Byte cache

• esp_gmf_io.h: Public interfaces for IO objects

Header File

• gmf_core/include/esp_gmf_payload.h

Functions

esp_gmf_err_t esp_gmf_payload_new(esp_gmf_payload_t **instance)

Create a new payload instance without buffer.

Parameters:

instance – [out] Pointer to store the newly created payload instance

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Not enough memory to create the payload instance

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_payload_new_with_len(uint32_t buf_length, esp_gmf_payload_t **instance)

Create a new payload instance and buffer by specified buffer length.

Parameters:

• buf_length – [in] Length of the payload buffer

• instance – [out] Pointer to store the newly created payload instance

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Not enough memory to create the payload instance

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_payload_copy_data(esp_gmf_payload_t *src, esp_gmf_payload_t *dest)

Copy data and done flag from one payload instance to another.

Parameters:

• src – [in] Source payload instance

• dest – [out] Destination payload instance

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_payload_realloc_buf(esp_gmf_payload_t *instance, uint32_t new_length)

Reallocate the buffer of a payload instance to the specified length Unlike realloc，the original valid data in the buffer was not copied to the new buffer.

Parameters:

• instance – [in] Payload instance to reallocate the buffer for

• new_length – [in] New length for the payload buffer

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Not enough memory to reallocate the buffer

• ESP_GMF_ERR_INVALID_ARG Invalid instance or new_length is zero

esp_gmf_err_t esp_gmf_payload_realloc_aligned_buf(esp_gmf_payload_t *instance, uint8_t align, uint32_t new_length)

Reallocate the buffer of a payload instance to the specified length with specified byte alignment Behavior same as esp_gmf_payload_realloc_buf with an additional alignment request Unlike realloc，the original valid data in the buffer was not copied to the new buffer.

Parameters:

• instance – [in] Payload instance to reallocate the buffer for

• align – [in] Byte alignment for the new payload buffer

• new_length – [in] New length for the payload buffer

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Not enough memory to reallocate the buffer

• ESP_GMF_ERR_INVALID_ARG Invalid instance or new_length is zero

esp_gmf_err_t esp_gmf_payload_realloc_buffer_with_separate_alignment(esp_gmf_payload_t *instance, uint8_t addr_align, uint8_t size_align, uint32_t new_length)

Reallocate the payload buffer with separate address and length alignment.

Note

Unlike realloc, the original valid data in the buffer is not copied to the new buffer. addr_align 0 substitutes esp_gmf_oal_get_spiram_cache_align(); use 1 for natural heap alignment (calloc). When size_align is greater than 1, it must be a power of two; the allocated byte length is rounded up to a multiple of size_align. Use 0 or 1 for size_align to keep new_length unchanged.

Parameters:

• instance – [in] Payload instance to reallocate the buffer for

• addr_align – [in] Byte alignment of the buffer base address

• size_align – [in] Byte alignment used to round up the requested buffer length

• new_length – [in] Minimum usable length for the payload buffer

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_MEMORY_LACK Not enough memory to reallocate the buffer

• ESP_GMF_ERR_INVALID_ARG Invalid instance, new_length is zero, or invalid alignment

esp_gmf_err_t esp_gmf_payload_set_done(esp_gmf_payload_t *instance)

Set the done flag for a payload instance.

Parameters:

instance – [in] Payload instance to set as done

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_payload_clean_done(esp_gmf_payload_t *instance)

Clean the done flag for a payload instance.

Parameters:

instance – [in] Payload instance to clean the done status for

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

void esp_gmf_payload_delete(esp_gmf_payload_t *instance)

Delete a payload instance, if needs_free is set free associated resources.

Parameters:

instance – [in] Payload instance to delete

Structures

struct esp_gmf_payload_t

Structure representing a payload in GMF.

Public Members

uint8_t *buf

Pointer to the payload buffer

size_t buf_length

Length of the payload buffer

size_t valid_size

Size of valid data in the payload buffer

bool is_done

Flag indicating if this payload buffer marks the end of the stream

uint64_t pts

Presentation time stamp

uint8_t needs_free

Flag indicating if the payload buffer needs to be freed by esp_gmf_payload_delete or not

uint8_t meta_flag

Meta flag for the payload

Macros

ESP_GMF_META_FLAG_AUD_RECOVERY_PLC

The meta flag for the current payload.

The current frame is recovered through the packet loss concealment (PLC) mechanism

Header File

• gmf_core/include/esp_gmf_port.h

Functions

esp_gmf_err_t esp_gmf_port_init(esp_gmf_port_config_t *cfg, esp_gmf_port_handle_t *out_result)

Initialize a GMF port with the given configuration.

Parameters:

• cfg – [in] Pointer to the configuration structure

• out_result – [out] Pointer to store the result handle after initialization

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_MEMORY_LACK Memory allocate failed

esp_gmf_err_t esp_gmf_port_deinit(esp_gmf_port_handle_t handle)

Deinitialize a GMF port.

Parameters:

handle – [in] The handle of the port to be deinitialized

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_set_payload(esp_gmf_port_handle_t handle, esp_gmf_payload_t *load)

Set the self payload for the specific port.

Parameters:

• handle – [in] The handle of the port

• load – [in] Pointer to the payload structure

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_clean_payload_done(esp_gmf_port_handle_t handle)

Clean the payload done status of a GMF port.

Parameters:

handle – [in] The handle of the port

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_enable_payload_share(esp_gmf_port_handle_t handle, bool enable)

Enables or disables shared payload for the specified port.

Parameters:

• handle – [in] The port handle to enable or disable payload sharing on

• enable – [in] Set to true to enable payload sharing, or false to disable it

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument provided

esp_gmf_err_t esp_gmf_port_reset(esp_gmf_port_handle_t handle)

Reset the port payload and variable of self payload.

Parameters:

handle – [in] The handle of the port

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_set_wait_ticks(esp_gmf_port_handle_t handle, int wait_ticks_ms)

Set the wait ticks for the specific port.

Parameters:

• handle – [in] The handle of the port

• wait_ticks_ms – [in] Number of milliseconds to wait

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_set_reader(esp_gmf_port_handle_t handle, void *reader)

Set the esp_gmf_port_acquire_in and esp_gmf_port_release_in caller for the specific port.

Parameters:

• handle – [in] The handle of the port

• reader – [in] Pointer to the reader

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_set_writer(esp_gmf_port_handle_t handle, void *writer)

Set the esp_gmf_port_acquire_out and esp_gmf_port_acquire_out caller for the specific port.

Parameters:

• handle – [in] The handle of the port

• writer – [in] Pointer to the writer

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_add_last(esp_gmf_port_handle_t head, esp_gmf_port_handle_t io_inst)

Add a GMF port to the end of the list.

Parameters:

• head – [in] The head of the port list

• io_inst – [in] The port instance to be added

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_port_del_at(esp_gmf_port_handle_t *head, esp_gmf_port_handle_t io_inst)

Delete a GMF port from the list.

Parameters:

• head – [inout] A pointer to the head of the port list

• io_inst – [in] The port instance to be deleted

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_io_t esp_gmf_port_acquire_in(esp_gmf_port_handle_t handle, esp_gmf_payload_t **load, uint32_t wanted_size, int wait_ticks)

Acquire the expected valid data into the specified payload, regardless of whether the payload is NULL or not If writer of port is valid, the payload from the previous element stored on the port payload pointer is fetched If the *load pointer is NULL, a new payload will be allocated before calling the acquire operation The actual valid size is stored in load->valid_size

Parameters:

• handle – [in] The handle of the port

• load – [inout] Pointer to store the acquired payload

• wanted_size – [in] Size of the payload to be acquired

• wait_ticks – [in] Number of ticks to wait, in milliseconds

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_port_release_in(esp_gmf_port_handle_t handle, esp_gmf_payload_t *load, int wait_ticks)

Call the release operation or clean the payload pointer of the port.

Parameters:

• handle – [in] The handle of the port

• load – [in] Pointer to the payload to be released

• wait_ticks – [in] Number of ticks to wait

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_port_acquire_out(esp_gmf_port_handle_t handle, esp_gmf_payload_t **load, uint32_t wanted_size, int wait_ticks)

Acquire the buffer of the expected size into the specified payload, If the reader of the port is valid, store the provided or allocated payload to the input port of the next element If reader pointer is NULL, prepare a payload if *load is invalid before calling the acquire operation The actual valid size is stored in load->valid_size

Parameters:

• handle – [in] The handle of the port

• load – [inout] Pointer to store the acquired payload

• wanted_size – [in] Size of the payload to be acquired

• wait_ticks – [in] Number of ticks to wait, in milliseconds

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_port_release_out(esp_gmf_port_handle_t handle, esp_gmf_payload_t *load, int wait_ticks)

Call the release operation or clean the payload pointer of the port.

Parameters:

• handle – [in] The handle of the port

• load – [in] Pointer to the payload to be released

• wait_ticks – [in] Number of ticks to wait

Returns:

• ESP_GMF_IO_OK Operation successful

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

static inline void *NEW_ESP_GMF_PORT(uint8_t dir, uint8_t type, void *acq, void *release, void *del, void *ctx, int length, int ticks_ms)

static inline void *NEW_ESP_GMF_PORT_IN_BYTE(void *acq, void *release, void *del, void *ctx, int length, int ticks_ms)

static inline void *NEW_ESP_GMF_PORT_OUT_BYTE(void *acq, void *release, void *del, void *ctx, int length, int ticks_ms)

static inline void *NEW_ESP_GMF_PORT_IN_BLOCK(void *acq, void *release, void *del, void *ctx, int length, int ticks_ms)

static inline void *NEW_ESP_GMF_PORT_OUT_BLOCK(void *acq, void *release, void *del, void *ctx, int length, int ticks_ms)

Structures

struct esp_gmf_port_io_ops_t

Structure defining the I/O operations of a GMF port.

Public Members

port_acquire acquire

Function pointer for acquiring data

port_release release

Function pointer for releasing data

port_free del

Function pointer for freeing the port

struct esp_gmf_port_attr_t

Structure defining the attributes of a GMF port.

Public Members

uint8_t buf_addr_aligned

Byte-align the address of the buffer

uint8_t buf_size_aligned

Byte-align the length of the buffer

uint8_t dir

Port direction

uint8_t type

Port type

struct esp_gmf_port_

Structure representing a GMF port The usage of the port in linked elements is as follows.

+———+ +—————+ +——-—+ | In Port +–—> First Element +-—> Out Port | +———+ +—-—+—-—+ +——-—+ | v +———+ +—-—+—-—+ +——-—+ | In Port +–—> More Element +-—> Out Port | +———+ +—-—+—-—+ +——-—+ | v +———+ +—-—+—-—+ +——-—+ | In Port +–—> Last Element +-—> Out Port | +———+ +—————+ +——-—+

Public Members

struct esp_gmf_port_ *next

Pointer to the next port

void *writer

Acquire out functions caller with the port

void *reader

Acquire in functions caller with the port

esp_gmf_port_io_ops_t ops

I/O operations of the port

esp_gmf_port_attr_t attr

Port attributes

int data_length

Data length of the payload

void *ctx

User context for the port

int wait_ticks

Timeout for port operations

esp_gmf_payload_t *payload

Payload pointer to be set

uint8_t is_shared

Payload is shared to the next element port or not, 1 for shared (default), 0 for dedicated

esp_gmf_payload_t *self_payload

Self payload of the port

struct esp_gmf_port_ *ref_port

Pointer to the reference port

int8_t ref_count

Reference count indicating the number of active references

struct esp_gmf_port_config_

Structure defining the configuration of a GMF port.

Public Members

uint8_t dir

Direction of the port

uint8_t type

Type of data handled by the port

esp_gmf_port_io_ops_t ops

I/O operations of the port

void *ctx

User context associated with the port

int data_length

Data length of the port

int wait_ticks

Timeout for port operations

Macros

ESP_GMF_PORT_CHECK(log_tag, ret, ret_value, action, format, ...)

ESP_GMF_PORT_ACQUIRE_IN_CHECK(TAG, ret, ret_value, action)

ESP_GMF_PORT_ACQUIRE_OUT_CHECK(TAG, ret, ret_value, action)

ESP_GMF_PORT_RELEASE_IN_CHECK(TAG, ret, ret_value, action)

ESP_GMF_PORT_RELEASE_OUT_CHECK(TAG, ret, ret_value, action)

ESP_GMF_PORT_DIR_IN

Definition the direction of a GMF port (input or output)

Input port

ESP_GMF_PORT_DIR_OUT

Output port

ESP_GMF_PORT_TYPE_BYTE

Definition the bit mask for the type of data handled by a GMF port (byte or block)

• A byte-type port transfers values by copying data byte by byte. Users must allocate memory, which means data transmission involves copying. This type of port allows convenient access to arbitrary byte lengths

• A block-type port transfers data by passing memory addresses. The memory used by the user is provided by another source, so data transmission does not involve copying. However, accessing arbitrary byte lengths is less flexible and may require data concatenation Bit0 for the byte type of GMF port

ESP_GMF_PORT_TYPE_BLOCK

Bit1 for the block type of GMF port

Type Definitions

typedef struct esp_gmf_port_ *esp_gmf_port_handle_t

Handle to a GMF port.

typedef esp_gmf_err_io_t (*port_acquire)(void *handle, esp_gmf_payload_t *load, uint32_t wanted_size, int wait_ticks)

Function pointer type for acquiring data from a port.

typedef esp_gmf_err_io_t (*port_release)(void *handle, esp_gmf_payload_t *load, int wait_ticks)

Function pointer type for releasing data from a port.

typedef void (*port_free)(void *p)

Function pointer type for freeing a port.

typedef struct esp_gmf_port_ esp_gmf_port_t

Structure representing a GMF port The usage of the port in linked elements is as follows.

+———+ +—————+ +——-—+ | In Port +–—> First Element +-—> Out Port | +———+ +—-—+—-—+ +——-—+ | v +———+ +—-—+—-—+ +——-—+ | In Port +–—> More Element +-—> Out Port | +———+ +—-—+—-—+ +——-—+ | v +———+ +—-—+—-—+ +——-—+ | In Port +–—> Last Element +-—> Out Port | +———+ +—————+ +——-—+

typedef struct esp_gmf_port_config_ esp_gmf_port_config_t

Structure defining the configuration of a GMF port.

Header File

• gmf_core/include/esp_gmf_cache.h

Functions

static inline esp_gmf_err_t esp_gmf_cache_new(uint32_t len, esp_gmf_cache_t **handle)

Create a new GMF cache instance.

Parameters:

• len – [in] The size of the cache buffer to allocate

• handle – [out] Pointer to the cache handle to be initialized

Returns:

• ESP_GMF_ERR_OK Success, cache is initialized

• ESP_GMF_ERR_INVALID_ARG If handle is NULL

• ESP_GMF_ERR_MEMORY_LACK If memory allocation fails

static inline esp_gmf_err_t esp_gmf_cache_delete(esp_gmf_cache_t *handle)

Delete a GMF cache instance and free associated memory.

Parameters:

handle – [in] Pointer to the cache handle

Returns:

• ESP_GMF_ERR_OK Success, cache is deleted

• ESP_GMF_ERR_INVALID_ARG If handle is NULL

static inline esp_gmf_err_t esp_gmf_cache_reset(esp_gmf_cache_t *handle)

Reset a GMF cache instance to its initial state This function clears all cached data and resets the cache state, but preserves the allocated buffer memory.

Parameters:

handle – [in] Pointer to the cache handle

Returns:

• ESP_GMF_ERR_OK Success, cache is reset

• ESP_GMF_ERR_INVALID_ARG If handle is NULL

static inline esp_gmf_err_t esp_gmf_cache_ready_for_load(esp_gmf_cache_t *handle, bool *is_ready)

Check if the cache is ready to load new data If the return is_ready is true, esp_gmf_cache_load can be called to load a new payload.

Parameters:

• handle – [in] Pointer to the cache handle

• is_ready – [out] Pointer to a boolean flag indicating whether new data can be loaded

Returns:

• ESP_GMF_ERR_OK Success, is_ready is set

• ESP_GMF_ERR_INVALID_ARG If handle or is_ready is NULL

static inline esp_gmf_err_t esp_gmf_cache_load(esp_gmf_cache_t *handle, const esp_gmf_payload_t *load_in)

Load new payload data into the cache Call esp_gmf_cache_ready_for_load before use to check if it is ready to load a new payload.

Parameters:

• handle – [in] Pointer to the cache handle

• load_in – [in] Pointer to the payload data to be loaded

Returns:

• ESP_GMF_ERR_OK Success, payload is loaded

• ESP_GMF_ERR_INVALID_ARG If handle or load_in is NULL

• ESP_GMF_ERR_INVALID_STATE If previous data has not been consumed

static inline esp_gmf_err_t esp_gmf_cache_acquire(esp_gmf_cache_t *handle, uint32_t expected_size, esp_gmf_payload_t **load_out)

Acquire a data chunk of the expected size from the cache.

Note

• This function must be used in conjunction with esp_gmf_cache_release

• The expected_size should match the internal buffer length

• If expected_size exceeds the current buffer length, the buffer will be reallocated

Parameters:

• handle – [in] Pointer to the cache handle

• expected_size – [in] The requested data size in bytes

• load_out – [out] Pointer to store the acquired payload data

Returns:

• ESP_GMF_ERR_OK Data successfully acquired

• ESP_GMF_ERR_INVALID_ARG If handle or load_out is NULL

• ESP_GMF_ERR_MEMORY_LACK Insufficient memory to allocate a new buffer

• ESP_GMF_ERR_NOT_ENOUGH Cached data size less than expected size

static inline esp_gmf_err_t esp_gmf_cache_release(esp_gmf_cache_t *handle, esp_gmf_payload_t *load)

Release the payload data previously acquired with esp_gmf_cache_acquire

Note

The filled portion of the buffer is cleared only if its size equals the buffer length

Parameters:

• handle – [in] Pointer to the cache handle

• load – [in] Pointer to the payload data to be released

Returns:

• ESP_GMF_ERR_OK Payload data successfully released

• ESP_GMF_ERR_INVALID_ARG If either handle or load is NULL

static inline esp_gmf_err_t esp_gmf_cache_get_cached_size(esp_gmf_cache_t *handle, int *filled)

Get the total amount of cached data.

Parameters:

• handle – [in] Pointer to the cache handle

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

Returns:

• ESP_GMF_ERR_OK Success, filled is set

• ESP_GMF_ERR_INVALID_ARG If handle or filled is NULL

Structures

struct esp_gmf_cache_t

This GMF payload cache module is designed to cache a data block of a specified size. Each call to acquire returns this fixed-size block. If the acquired data is smaller than the expected size, new data must be loaded. When sufficient data is available, release clears the cached block. It is commonly used in scenarios where an element can only process a fixed data size, but the input data length is variable. For example, if an element requires exactly 1350 bytes per processing cycle but receives input of varying lengths, you can create a cache with esp_gmf_cache_new(1350, out_handle), and the element can then fetch data using esp_gmf_cache_acquire

Structure representing a cache for GMF payloads

Public Members

uint8_t *buf

Pointer to the cache buffer

uint32_t buf_len

Total allocated size of the cache buffer

uint32_t buf_filled

Amount of data currently stored in the buffer

esp_gmf_payload_t origin_load

Original payload from which data is copied

esp_gmf_payload_t load

Current payload structure for acquiring data

Header File

• gmf_core/include/esp_gmf_io.h

Functions

esp_gmf_err_t esp_gmf_io_init(esp_gmf_io_handle_t handle, esp_gmf_io_cfg_t *cfg)

Initialize a I/O handle with the given configuration If the stack size is greater than 0, a GMF task is created with the process job registered.

Parameters:

• handle – [in] GMF I/O handle to initialize

• cfg – [in] Pointer to the configuration structure

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_MEMORY_LACK Insufficient memory to perform the job registration

• ESP_GMF_ERR_FAIL Failed to create thread

esp_gmf_err_t esp_gmf_io_deinit(esp_gmf_io_handle_t handle)

Deinitialize a GMF I/O handle, freeing associated resources.

Parameters:

handle – [in] GMF I/O handle to deinitialize

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_enable_speed_monitor(esp_gmf_io_handle_t handle, bool enabled)

Enable or disable speed monitor for an I/O.

Parameters:

• handle – [in] I/O handle

• enabled – [in] true to enable, false to disable

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_speed_stats(esp_gmf_io_handle_t handle, esp_gmf_io_speed_stats_t *stats)

Get speed statistics for an I/O.

Parameters:

• handle – [in] I/O handle

• stats – [out] Pointer to store speed statistics

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_score(esp_gmf_io_handle_t handle, const char *url, int *score)

Evaluate how well the IO matches a given URL The score ranges from ESP_GMF_IO_SCORE_NONE to ESP_GMF_IO_SCORE_PERFECT:

• ESP_GMF_IO_SCORE_NONE: No match (The IO does not support this URL).

• ESP_GMF_IO_SCORE_STANDARD: Standard match (e.g., matching the URL scheme like “http://” or “file://”).

• ESP_GMF_IO_SCORE_PERFECT: Perfect match (e.g., matching both scheme and file extension, or high priority specialized IO).

Parameters:

• handle – [in] GMF I/O handle

• url – [in] URL to evaluate

• score – [out] Pointer to store the calculated score

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_NOT_SUPPORT The IO does not support scoring

esp_gmf_err_t esp_gmf_io_open(esp_gmf_io_handle_t handle)

Open the specific I/O handle, run the thread if it is valid.

Parameters:

handle – [in] GMF I/O handle to open

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_seek(esp_gmf_io_handle_t handle, uint64_t seek_byte_pos)

Seek to a specific byte position in the specific I/O handle If the IO thread is invalid, the IO’s seek function is called directly (synchronous). If the IO thread is valid, the seek is deferred to the IO task: the seek position is stored and the data bus is aborted to wake up the task. The IO task will process the seek at the beginning of its next iteration. The caller will block and wait for the IO task to complete the seek operation.

Parameters:

• handle – [in] GMF I/O handle

• seek_byte_pos – [in] Byte position to seek to

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_NOT_SUPPORT Not support

• Others Indicating failure

esp_gmf_err_t esp_gmf_io_close(esp_gmf_io_handle_t handle)

Close a GMF I/O handle If the IO task is active, this function will block and wait up to task_timeout_ms for the task to finish If both prev_close and thread are valid, they will be called before executing the IO close operation.

Parameters:

handle – [in] GMF I/O handle to close

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_io_t esp_gmf_io_acquire_read(esp_gmf_io_handle_t handle, esp_gmf_payload_t *load, uint32_t wanted_size, int wait_ticks)

Acquire read access to the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• load – [out] Pointer to store the acquired payload

• wanted_size – [in] Desired payload size

• wait_ticks – [in] Timeout value in ticks, in milliseconds

Returns:

• ESP_GMF_IO_OK Operation successful (check load->is_done to see if IO is done)

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_io_release_read(esp_gmf_io_handle_t handle, esp_gmf_payload_t *load, int wait_ticks)

Release read access to the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• load – [in] Pointer to the payload to release

• wait_ticks – [in] Timeout value in ticks

Returns:

• ESP_GMF_IO_OK Operation successful (check load->is_done to see if IO is done)

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_io_acquire_write(esp_gmf_io_handle_t handle, esp_gmf_payload_t *load, uint32_t wanted_size, int wait_ticks)

Acquire write access to the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• load – [out] Pointer to store the acquired payload

• wanted_size – [in] Desired payload size

• wait_ticks – [in] Timeout value in ticks, in milliseconds

Returns:

• ESP_GMF_IO_OK Operation successful (check load->is_done to see if IO is done)

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_io_t esp_gmf_io_release_write(esp_gmf_io_handle_t handle, esp_gmf_payload_t *load, int wait_ticks)

Release write access to the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• load – [in] Pointer to the payload to release

• wait_ticks – [in] Timeout value in ticks

Returns:

• ESP_GMF_IO_OK Operation successful (check load->is_done to see if IO is done)

• ESP_GMF_IO_FAIL Operation failed or invalid arguments

• ESP_GMF_IO_ABORT Operation aborted

• ESP_GMF_IO_TIMEOUT Operation timed out

esp_gmf_err_t esp_gmf_io_set_info(esp_gmf_io_handle_t handle, esp_gmf_info_file_t *info)

Set information for the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• info – [in] Pointer to the file information structure

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_info(esp_gmf_io_handle_t handle, esp_gmf_info_file_t *info)

Get information from the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• info – [out] Pointer to store the file information

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_set_uri(esp_gmf_io_handle_t handle, const char *uri)

Set the URI for the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• uri – [in] Pointer to the URI string

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_MEMORY_LACK Memory allocation failed

esp_gmf_err_t esp_gmf_io_get_uri(esp_gmf_io_handle_t handle, char **uri)

Get the URI from the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• uri – [out] Pointer to store the URI string

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_set_pos(esp_gmf_io_handle_t handle, uint64_t byte_pos)

Set the byte position for the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• byte_pos – [in] Byte position to set

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_update_pos(esp_gmf_io_handle_t handle, uint64_t byte_pos)

Update the byte position for the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• byte_pos – [in] Byte position to update

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_pos(esp_gmf_io_handle_t handle, uint64_t *byte_pos)

Get the current byte position from the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• byte_pos – [out] Pointer to store the current byte position

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_set_size(esp_gmf_io_handle_t handle, uint64_t total_size)

Set the total size for the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• total_size – [in] Total size to set

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_size(esp_gmf_io_handle_t handle, uint64_t *total_size)

Get the total size from the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

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

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_get_db_filled_size(esp_gmf_io_handle_t handle, uint32_t *filled_size)

Get the filled size in the data bus of the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

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

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_NOT_SUPPORT Operation not supported, the I/O instance does not have a configured data bus

esp_gmf_err_t esp_gmf_io_get_type(esp_gmf_io_handle_t handle, esp_gmf_io_type_t *type)

Get the I/O type of the specific I/O handle.

Parameters:

• handle – [in] GMF I/O handle

• type – [out] Pointer to store the I/O type

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_reset(esp_gmf_io_handle_t handle)

Reset IO will do reset the position and size, call the reset function if it is valid, then reset the task and reload IO process job.

Parameters:

handle – [in] GMF I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_reload(esp_gmf_io_handle_t handle, const char *uri)

Reload Io with a URI. Used primarily for seamless transitions (e.g., Hls segments) Reload is specailly designed to optimized download efficiency This function is used to avoid reconnection which is time-consuming when download sequential urls from same host If the IO has an io_process task, this function will reset the done_write (EOF) flag of data_bus and rerun the task.

Note

This function should be called after the current IO operation (e.g., reading the resource) has finished.

Parameters:

• handle – [in] GMF I/O handle

• uri – [in] Pointer to the URI string

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

• ESP_GMF_ERR_NOT_SUPPORT Not support

• Others Indicating failure

esp_gmf_err_t esp_gmf_io_done(esp_gmf_io_handle_t handle)

Mark an I/O as done, cause the esp_gmf_io_acquire_* / esp_gmf_io_release_* input parameter(load) to have the is_done flag set If the IO has an io_process task, this function will abort the data_bus and hold the task.

Note

Typical usage: when the current data source has been fully consumed (e.g. end of a track in a playlist), call this function to signal downstream consumers that no more data is available. The IO task will be held and stop producing data until esp_gmf_io_clear_done is called. Caller MUST call esp_gmf_io_clear_done before reusing the IO for the next data source, otherwise the IO task remains permanently held and will not process any further data.

Parameters:

handle – [in] GMF I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_clear_done(esp_gmf_io_handle_t handle)

Clear the done flag for an I/O, then esp_gmf_io_acquire_* / esp_gmf_io_release_* will operate normally Reset the position to 0 If the IO has an io_process task, this function will reset the data_bus and release the held task.

Note

Typical usage: after esp_gmf_io_done has been called and the caller is ready to start a new data source (e.g. switching to the next track), call this function to clear the done state, reset position to 0, and release the held IO task so it can resume producing data. This function should only be called after esp_gmf_io_done; calling it without a prior done has no effect.

Parameters:

handle – [in] GMF I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_abort(esp_gmf_io_handle_t handle)

Mark an I/O as aborted, then esp_gmf_io_acquire_* / esp_gmf_io_release_* will return ESP_GMF_IO_ABORT If the IO has an io_process task, this function will abort the data_bus and hold the task.

Note

Typical usage: when the IO operation needs to be interrupted immediately (e.g. user-initiated stop, network error recovery, or switching to a different URI). All ongoing and subsequent acquire/release calls will return ESP_GMF_IO_ABORT until esp_gmf_io_clear_abort is called. The IO task will be held and stop producing/consuming data. Caller MUST call esp_gmf_io_clear_abort to restore normal operation, otherwise the IO remains permanently in the aborted state and the task stays held.

Parameters:

handle – [in] GMF I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_clear_abort(esp_gmf_io_handle_t handle)

Clear the abort flag for an I/O, then esp_gmf_io_acquire_* / esp_gmf_io_release_* will operate normally If the IO has an io_process task, this function will clear abort on the data_bus and release the held task.

Note

Typical usage: after esp_gmf_io_abort has been called and the error condition has been resolved (e.g. network reconnected, new URI set), call this function to clear the abort state and release the held IO task so it can resume processing data. This function should only be called after esp_gmf_io_abort; calling it without a prior abort has no effect.

Parameters:

handle – [in] GMF I/O handle

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_set_task_timeout(esp_gmf_io_handle_t handle, int32_t timeout_ms)

Set the timeout for internal IO task operation.

Parameters:

• handle – [in] GMF I/O handle

• timeout_ms – [in] Timeout in milliseconds

Returns:

• ESP_GMF_ERR_OK On success

• ESP_GMF_ERR_INVALID_ARG Invalid argument

Structures

struct esp_gmf_io_buffer_cfg_t

Buffer configuration for GMF I/O.

Public Members

size_t io_size

Each time io size in bytes

size_t buffer_size

Buffer size in bytes

esp_gmf_err_t (*read_filter)(esp_gmf_io_handle_t obj, void *payload, uint32_t wanted_size, int block_ticks)

Read filter callback function

struct esp_gmf_io_speed_stats_t

Structure representing I/O speed statistics.

Public Members

uint64_t total_bytes

Total bytes

uint64_t last_total_bytes

Last total bytes count for interval calculation

uint64_t total_time_ms

Total time in milliseconds

uint64_t last_total_time_ms

Last update total time in milliseconds

uint32_t current_speed_kbps

Current speed in Kbps

uint32_t average_speed_kbps

Average speed in Kbps

struct esp_gmf_io_cfg_t

Configuration structure for a GMF I/O.

Public Members

esp_gmf_task_config_t thread

Task configuration

esp_gmf_io_buffer_cfg_t buffer_cfg

Buffer configuration

bool enable_speed_monitor

Enable speed monitor

struct esp_gmf_io_

Structure representing a GMF I/O.

Public Members

struct esp_gmf_obj_ parent

Parent object

esp_gmf_err_t (*get_score)(esp_gmf_io_handle_t obj, const char *url, int *score)

Get score callback function

esp_gmf_err_t (*open)(esp_gmf_io_handle_t obj)

Open callback function

esp_gmf_err_t (*seek)(esp_gmf_io_handle_t obj, uint64_t data)

Seek callback function

esp_gmf_err_t (*close)(esp_gmf_io_handle_t obj)

Close callback function

esp_gmf_err_t (*reset)(esp_gmf_io_handle_t obj)

Reset callback function

esp_gmf_err_t (*reload)(esp_gmf_io_handle_t obj, const char *uri)

Reload callback function Previous close callback function For some block IO instances, this function can be called before the close operation

esp_gmf_err_io_t (*acquire_read)(esp_gmf_io_handle_t handle, void *payload, uint32_t wanted_size, int block_ticks)

Acquire read callback function

esp_gmf_err_io_t (*release_read)(esp_gmf_io_handle_t handle, void *payload, int block_ticks)

Release read callback function

esp_gmf_err_io_t (*acquire_write)(esp_gmf_io_handle_t handle, void *payload, uint32_t wanted_size, int block_ticks)

Acquire write callback function

esp_gmf_err_io_t (*release_write)(esp_gmf_io_handle_t handle, void *payload, int block_ticks)

Release write callback function

esp_gmf_task_handle_t task_hd

Task handle

esp_gmf_db_handle_t data_bus

Data bus handle for buffer

esp_gmf_data_bus_block_t db_block

Data bus block for data bus read/write operation

esp_gmf_io_speed_stats_t *speed_stats

Speed statistics for this I/O (dynamically allocated when enabled)

void *evt_group

Event group for IO control synchronization

esp_gmf_io_dir_t dir

I/O direction

esp_gmf_io_type_t type

I/O type

esp_gmf_info_file_t attr

File attribute

uint64_t seek_pos

Pending seek position (ESP_GMF_IO_SEEK_POS_INVALID = no pending seek)

uint8_t _is_done

Flag indicating if a done signal has been received

uint8_t _is_abort

Flag indicating if an abort signal has been received

uint8_t _is_hold

Flag indicating if the IO task should hold itself

int32_t task_timeout_ms

Timeout for internal IO task operation (default 1000 ms)

Macros

ESP_GMF_IO_SCORE_NONE

No match (The IO does not support this URL)

ESP_GMF_IO_SCORE_STANDARD

Standard match (e.g., matching the URL scheme)

ESP_GMF_IO_SCORE_PERFECT

Perfect match (e.g., matching both scheme and extension)

Type Definitions

typedef void *esp_gmf_io_handle_t

This GMF I/O abstraction can operate in two modes depending on configuration:

    1) Asynchronous I/O (data_bus + task configured)
    When the I/O is configured with a data bus (buffer configured) and a task (thread stack > 0 in esp_gmf_io_cfg_t), the framework
    creates an internal `io_process` task. That task is responsible for driving the data flow between the actual underlying I/O
    (open/seek/close callbacks) and the data bus. In this mode, user-facing APIs such as `esp_gmf_io_acquire_*` / `esp_gmf_io_release_*`
    interact with the data bus (buffered I/O). The task performs blocking or non-blocking reads/writes against the real I/O device and
    pushes/pulls data through the data bus. This model is suitable when the element needs fixed-size transfers or when decoupling
    the producer/consumer timing is desired.

    2) Synchronous I/O (no data_bus and no task)
    If no data bus and no task are configured, the I/O operates in synchronous mode: calls to `esp_gmf_io_acquire_*` / `esp_gmf_io_release_*`
    invoke the I/O driver's callbacks directly and perform actual I/O in the caller's context. Use this mode when the element can safely
    perform I/O on the caller thread or when buffering is not needed.

Handle to a GMF I/O

typedef struct esp_gmf_io_ esp_gmf_io_t

Structure representing a GMF I/O.

Enumerations

enum esp_gmf_io_dir_t

Enumeration for the direction of a GMF I/O (none, reader, writer)

Values:

enumerator ESP_GMF_IO_DIR_NONE

No direction

enumerator ESP_GMF_IO_DIR_READER

Reader direction

enumerator ESP_GMF_IO_DIR_WRITER

Writer direction

enum esp_gmf_io_type_t

Enumeration for the type of data handled by a GMF I/O (byte or block)

Values:

enumerator ESP_GMF_IO_TYPE_BYTE

Byte type

enumerator ESP_GMF_IO_TYPE_BLOCK

Block type

---

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.