# GMF-IO

[中文]

gmf_io is the input/output component of ESP-GMF, providing concrete implementations of five types of IO: file, network, embedded flash, I2S PDM, and audio codec, all accessed through the `esp_gmf_io_t` base class. All subclasses share the same lifecycle, acquire-release protocol, URL scoring, asynchronous buffering, and done / abort / reload control; this document focuses on the differences, configuration options, and usage tips for each of the five subclasses.

The IO base class (`esp_gmf_io_t` structure and `esp_gmf_io_*` API series) is defined in gmf-core; see Data Flow for documentation.

## Feature List

- file io: reads and writes the file system based on POSIX `fopen` / `fread` / `fwrite`, supporting `/sdcard` absolute paths and `file://` scheme, with optional DMA-compatible cache for accelerating large block reads/writes

- http io: reads and writes HTTP / HTTPS resources based on `esp_http_client`, supporting Range requests, gzip decompression, event hooks, server certificates, and `crt_bundle`

- embed_flash io: reads data from a read-only embedded flash resource table; URL format `embed://group/<index>_name.ext`; suitable for firmware-embedded notification tones

- i2s_pdm io: wraps the ESP-IDF `i2s_pdm` driver channel for PDM microphone capture or PDM speaker playback

- codec_dev io: directly interfaces with `esp_codec_dev` device handles to read/write audio samples, typically for recording / playback via an on-board codec

- URL scoring: each subclass implements `get_score`; the pool can score candidate IOs by URL and automatically select the best one

- Synchronous / asynchronous two operation modes: when a buffer and task are configured, the framework automatically spawns an io_process task to decouple production and consumption; otherwise all acquire / release calls execute synchronously in the caller’s thread

- Speed monitoring: the base class can be enabled in both synchronous and asynchronous modes, providing instantaneous and average throughput in Kbps

- Reuse and switching: `esp_gmf_io_reload` switches URI without rebuilding the instance, commonly used for HLS segments and playlists

- End-of-stream and abort: unified `done` / `abort` semantics that handle the internal data bus and task accordingly

## Technical Details

### IO Position in GMF

Each gmf_io subclass is the leaf of a three-level inheritance chain: `esp_gmf_obj_t` provides common object fields (tag, cfg, new, del); `esp_gmf_io_t` defines the shared IO interface (open / seek / acquire / release / reset / reload / done / abort / speed stats) on top of it; the five subclasses in `elements/gmf_io` only implement callbacks and fill in subclass-specific configuration. The pipeline connects adjacent elements to an IO’s internal data bus via `esp_gmf_port`; neighbors read and write through the uniform port interface.

            flowchart TB
        Obj["esp_gmf_obj_t"]
        IoBase["IO Base Class (esp_gmf_io_t)"]
        IoImpl["Five IO Subclasses (file/http/embed_flash/i2s_pdm/codec_dev)"]
        Port["Data Port (esp_gmf_port)"]

        Obj --> IoBase
        IoBase --> IoImpl
        IoBase -. data bus .-> Port

In actual development, you only interact with the subclass-provided `xxx_io_cfg_t` and `esp_gmf_io_xxx_init`; all runtime control uses the base class `esp_gmf_io_*` API series. To extend a custom IO, add a subclass inheriting from `esp_gmf_io_t` and fill in the function pointer table.

### Synchronous and Asynchronous Operation Modes

The base class has two operating modes, selected by the subclass through `esp_gmf_io_cfg_t.thread.stack` and `esp_gmf_io_cfg_t.buffer_cfg.buffer_size`.

Synchronous mode: `thread.stack == 0` with no data bus configured. `acquire_read` / `release_read` / `acquire_write` / `release_write` directly execute the subclass callback in the caller’s thread. Low overhead; suitable for codec_dev, embed_flash, and i2s_pdm, where reading/writing is itself a blocking DMA or zero-copy memory access.

Asynchronous mode: `thread.stack > 0` and `buffer_size > 0`. The base class creates an `io_process` task and a block-type data bus at the `esp_gmf_io_open` stage; the task loops internally: in the read direction, it reads data from the device via `acquire_read` and submits it to the data bus via `db_release_write`; in the write direction, it retrieves data from the data bus via `db_acquire_read` and delivers it to the device via `release_write`. The application’s `esp_gmf_io_acquire_*` actually operates on the data bus, decoupled from device IO. Suitable for HTTP and file IO with variable latency that requires prefetching.

The diagram below compares the two modes in the read direction.

            flowchart TD
        subgraph sync ["Synchronous Mode"]
            User_A["Caller Thread"]
            DevA["Device acquire_read"]
            User_A -->|"direct call"| DevA
        end
        subgraph async ["Asynchronous Mode"]
            User_B["Caller Thread"]
            DbB["Block Data Bus"]
            TaskB["io_process Task"]
            DevB["Device acquire_read"]
            User_B -->|"db_acquire_read"| DbB
            TaskB -->|"read device"| DevB
            TaskB -->|"db_release_write"| DbB
        end

io_http defaults to asynchronous; other subclasses default to synchronous; the application can override as needed.

### URL Scoring and Automatic Selection

The pool supports registering multiple IOs simultaneously and uses `esp_gmf_io_get_score` to determine “which IO can handle this URL”. Scores have three levels:

- `ESP_GMF_IO_SCORE_NONE` (0): Not supported

- `ESP_GMF_IO_SCORE_STANDARD` (50): Matches scheme (`http://`, `file://`, `embed://`)

- `ESP_GMF_IO_SCORE_PERFECT` (100): Exact match (scheme + extension / dedicated IO)

Built-in scoring rules for the five subclasses:

Subclass | Matching Condition
--- | ---
io_file | URL starts with `/` or `file://` (recommended: `file:///sdcard/xxx`) → `STANDARD`
io_http | URL starts with `http://` or `https://` → `STANDARD`
io_embed_flash | URL starts with `embed://` → `STANDARD`
io_i2s_pdm / io_codec_dev | No scheme-based matching; selected directly by pool tag (`io_codec_dev`, `io_i2s_pdm`)

Custom IOs that want to take priority over the default implementation (e.g., HLS over HTTP) can return `PERFECT`.

### io_file

Based on POSIX stdio. `esp_gmf_io_file_init()` allocates an instance according to `file_io_cfg_t`; at open, the URI is obtained via `esp_gmf_io_get_uri`, supporting `/sdcard/xxx` absolute paths and `file:///sdcard/xxx` file URIs. The read direction uses `"rb"`; the write direction uses `"wb"`; the read direction writes the file size obtained from `stat` back to the base class, used for progress reporting and seek validation.

Resume from position. If the base class has a non-zero `info.pos` at the open stage, the subclass calls `fseek(SEEK_SET)` to jump to that position. Combined with the pipeline’s `seek` / application’s `esp_gmf_io_set_pos`, playback can start from a specified byte offset.

Cache configuration. `cache_size` controls the user buffer allocated by `setvbuf`. Values `<= 512` are treated as disabled; above this threshold, allocation is aligned up to 512 bytes. `cache_caps` selects the heap tag for the cache; zero defaults to `MALLOC_CAP_DMA`. On chips with PSRAM DMA support (e.g., esp32p4), it is recommended to use `MALLOC_CAP_SPIRAM | MALLOC_CAP_DMA` to save internal SRAM.

Seek and reset. `seek` directly calls `fseek(SEEK_SET)`; `reset` sets the cursor to 0. Both take effect immediately in synchronous mode; in asynchronous mode, the base class converts them to deferred processing by the task.

    file_io_cfg_t cfg = FILE_IO_CFG_DEFAULT();
    cfg.dir        = ESP_GMF_IO_DIR_READER;
    cfg.cache_size = 8 * 1024;
    cfg.cache_caps = MALLOC_CAP_SPIRAM | MALLOC_CAP_DMA;

    esp_gmf_io_handle_t io = NULL;
    esp_gmf_io_file_init(&cfg, &io);
    esp_gmf_io_set_uri(io, "/sdcard/test.mp3");

### io_http

Based on `esp_http_client`. Default asynchronous: stack 6 KiB, priority 10, core 0, data bus 20 KiB, IO block 3 KiB; override via `http_io_cfg_t.io_cfg`.

Request construction. At open, the client is established with `timeout_ms = 30000`; optionally `cert_pem` or `crt_bundle_attach`. If the base class has a non-zero `info.pos` (indicating resume), open automatically adds a `Range: bytes=<pos>-` header. 301 / 302 responses are automatically redirected with a reconnect.

Automatic gzip decompression. If the response header contains `Content-Encoding: gzip`, io_http internally decompresses using `gzip_miniz` while reading; the application receives the decompressed byte stream. Other `Content-Encoding` values are treated as unsupported and return failure.

Event hook. The application registers a callback via `http_io_cfg_t.event_handle` or `esp_gmf_io_http_set_event_callback()`; it is called at various points: before connection, during request, during response, at request end, and on track switch. A positive return value causes io_http to skip the default read/write action, suitable for implementing custom authentication, data modification, and multipart upload. Event enums are in `http_stream_event_id_t`.

reset and reload. `esp_gmf_io_http_reset()` resets HTTP state, commonly used in event callbacks to “finish the current resource and switch to the next segment”. The base class’s `esp_gmf_io_reload` reuses the existing connection after setting a new URI to reduce handshake overhead, suitable for sequential switching within the same host.

    http_io_cfg_t cfg = HTTP_STREAM_CFG_DEFAULT();
    cfg.dir               = ESP_GMF_IO_DIR_READER;
    cfg.crt_bundle_attach = esp_crt_bundle_attach;
    cfg.event_handle      = my_http_hook;
    cfg.user_data         = &app_ctx;

    esp_gmf_io_handle_t io = NULL;
    esp_gmf_io_http_init(&cfg, &io);
    esp_gmf_io_set_uri(io, "https://example.com/track.mp3");

### io_embed_flash

Reads read-only resources linked into the firmware; supports read direction only. Typical use cases include firmware-embedded notification tones, button feedback, and startup sounds.

Resource table. The context is an `embed_item_info_t` array, where each entry contains `address` and `size` fields. Set via `esp_gmf_io_embed_flash_set_context()`; `max_files` provides an upper bound, which can be larger than the actual number of entries.

URL format. `embed://<group>/<index>_<name>.<ext>`. At open, the URL is parsed to extract the last numeric segment before `_` as the index, which is used to look up `address` and `size` in the resource table. The read data is raw bytes; if encoded as mp3 / wav, a decoding element is needed.

    extern const embed_item_info_t g_my_tones[];

    embed_flash_io_cfg_t cfg = EMBED_FLASH_CFG_DEFAULT();
    cfg.max_files = ESP_MY_TONE_URL_MAX;

    esp_gmf_io_handle_t io = NULL;
    esp_gmf_io_embed_flash_init(&cfg, &io);
    esp_gmf_io_embed_flash_set_context(io, g_my_tones, ESP_MY_TONE_URL_MAX);
    esp_gmf_io_set_uri(io, "embed://tone/0_startup.mp3");

The repository provides the `mk_flash_embed_tone.py` helper script to generate the resource table and corresponding URI enum from audio files in a specified directory.

### io_i2s_pdm

Wraps the ESP-IDF `i2s_pdm` driver channel as an IO. The read/write direction is determined by `i2s_pdm_io_cfg_t.dir`; the channel handle `pdm_chan` is created by the application in advance following the ESP-IDF procedure.

At open, `i2s_channel_enable` is called to enable the channel; in the write direction, an `on_send_q_ovf` event callback is additionally registered to detect send queue overflow, and the `PDM_TX_DONE_BIT` event group bit is used to wait for the last transmission to complete at close, ensuring tail data has been sent. In the read direction, `i2s_channel_read` blocks until a payload is filled; in the write direction, `i2s_channel_write` blocks until the entire payload is written.

    i2s_chan_handle_t tx_handle = NULL;
    /* Create I2S PDM TX channel following ESP-IDF procedure */

    i2s_pdm_io_cfg_t cfg = ESP_GMF_IO_I2S_PDM_CFG_DEFAULT();
    cfg.dir      = ESP_GMF_IO_DIR_WRITER;
    cfg.pdm_chan = tx_handle;

    esp_gmf_io_handle_t io = NULL;
    esp_gmf_io_i2s_pdm_init(&cfg, &io);

### io_codec_dev

Directly uses an `esp_codec_dev` device handle as an IO. The device is bound at construction via `codec_dev_io_cfg_t.dev`; at runtime, it can be hot-swapped via `esp_gmf_io_codec_dev_set_dev()` (e.g., switching from Bluetooth back to local codec).

`acquire_read` calls `esp_codec_dev_read` to synchronously read the specified number of bytes; `release_write` calls `esp_codec_dev_write` to write the valid bytes of the payload. open / close only update state flags; hardware start/stop is handled by the application via `esp_codec_dev_open` / `esp_codec_dev_close`. codec_dev io does not perform data format conversion; input samples must be aligned to the device’s current sample rate, bit width, and channels by upstream elements (`aud_rate_cvt`, `aud_bit_cvt`, `aud_ch_cvt`).

    codec_dev_io_cfg_t cfg = ESP_GMF_IO_CODEC_DEV_CFG_DEFAULT();
    cfg.dir = ESP_GMF_IO_DIR_WRITER;
    cfg.dev = playback_handle;

    esp_gmf_io_handle_t io = NULL;
    esp_gmf_io_codec_dev_init(&cfg, &io);
    /* Switch device at runtime */
    esp_gmf_io_codec_dev_set_dev(io, new_playback_handle);

### Runtime Control

All subclasses share the same set of control interfaces, grouped by purpose into four categories.

Position and size. `esp_gmf_io_set_uri` / `get_uri` maintains the URL; `set_size` / `get_size` and `set_pos` / `update_pos` / `get_pos` maintain bytes read and total bytes. Subclasses write the total size to the base class at open (file from `stat`, http from `Content-Length`); used by the pipeline for progress reporting and seek validation.

End-of-stream and abort. `esp_gmf_io_done` marks the current data source as fully read; downstream `acquire_*` returns payloads with `is_done = true`; in asynchronous mode, it also pauses the IO task, which resumes after the application calls `esp_gmf_io_clear_done`. `esp_gmf_io_abort` is stronger: subsequent `acquire_*` / `release_*` return `ESP_GMF_IO_ABORT` directly; `esp_gmf_io_clear_abort` is needed to recover. These correspond to the two distinct semantics of “skip track” and “user stop”.

Reset and reload. `esp_gmf_io_reset` clears pos, calls the subclass reset, and resets the async task and job; the pipeline calls this automatically during `reset`. `esp_gmf_io_reload` is for seamless switching: it replaces the URI and reuses the connection and resources, saving time compared to `close + set_uri + open`.

Speed statistics. Enable via `esp_gmf_io_cfg_t.enable_speed_monitor` or `esp_gmf_io_enable_speed_monitor`; the base class accumulates transferred bytes and elapsed time during I/O and maintains instantaneous and average Kbps. Available in both synchronous and asynchronous modes; read via `esp_gmf_io_get_speed_stats` as `esp_gmf_io_speed_stats_t`, for observing network bandwidth, file read/write throughput, and similar metrics.

## Performance

The table below gives typical throughput levels and optimization directions for common configurations. Measured values are strongly dependent on file system, network, PSRAM, and codec sample rate; provided for relative comparison only.

IO | Typical Mode | Main Bottleneck | Optimization Direction
--- | --- | --- | ---
io_file | Synchronous | SD card controller / FATFS block size | Increase `cache_size` (recommended 4-16 KiB); use SPIRAM cache on chips with PSRAM DMA support
io_http | Asynchronous | TLS handshake, link bandwidth | Increase `buffer_size` (default 20 KiB) and `io_size` (default 3 KiB); set task core affinity appropriately
io_embed_flash | Synchronous | Flash read bandwidth / memcpy | Avoid too-small `wanted_size`; align with the downstream element’s `io_size`
io_i2s_pdm | Synchronous | I2S driver DMA descriptor size | Keep payload size as an integer multiple of the DMA descriptor size
io_codec_dev | Synchronous | Codec sample rate determines the hard ceiling | Align downstream elements to the codec’s sample rate / bit width / channels; avoid software conversion

## Application Examples

- `gmf_examples/basic_examples/pipeline_play_embed_music`: Reads mp3 from embed_flash, processes through `aud_dec` and effects chain, then outputs via codec_dev; covers three stages of pool registration, pipeline construction, and IO binding

The upper-level application components such as `esp_audio_simple_player` also connect file and HTTP sources through this component internally and can serve as advanced references.

## SoC Compatibility

- The behavior of `cache_caps` in io_file differs across chips:

  - esp32: use `MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT` or `MALLOC_CAP_DMA`

  - esp32sx / esp32cx: can additionally use `MALLOC_CAP_INTERNAL`

  - esp32p4 and other chips with `SOC_SDMMC_PSRAM_DMA_CAPABLE`: can use `MALLOC_CAP_SPIRAM | MALLOC_CAP_DMA` to save SRAM

- io_i2s_pdm depends on `driver/i2s_pdm.h` and is only available on SoCs with PDM support; use the corresponding I2S Std wrapper for chips without PDM support

- Enabling `crt_bundle_attach` for io_http requires `CONFIG_MBEDTLS_CERTIFICATE_BUNDLE` to be enabled

## FAQ

Q: When should asynchronous mode be enabled for an IO?

When the IO latency has noticeable jitter, or when downstream element consumption rate is sensitive to IO jitter. A typical example is HTTP audio-on-demand, where network jitter needs to be absorbed by a prefetch buffer. For stable devices like codec_dev and embed_flash, synchronous mode is sufficient; asynchronous mode would only add context switching overhead.

Q: `acquire_read` returns success but the payload’s `valid_size` is smaller than `wanted_size`?

This is normal. The end of a file, network chunking, and I2S DMA descriptor switching can all cause a single read to return less than the requested length. The caller should use `valid_size` as the actual data length and stop reading when `is_done == true`.

Q: io_http has `event_handle` configured but the callback is not triggered?

Confirm the event id is one of the five `HTTP_STREAM_*` types; also the callback must be passed in via `http_io_cfg_t` at configuration, or by calling `esp_gmf_io_http_set_event_callback()` after init. Directly modifying the configuration struct members after init does not take effect.

Q: embed_flash io returns error “No _ in file name” halfway through reading?

The URL format requires `embed://<group>/<index>_<name>.<ext>`; the index and filename are separated by an underscore. Fix the URI or resource table naming to resolve this.

Q: Can codec_dev io drive I2S directly?

No. codec_dev io only interacts with the `esp_codec_dev` handle, which internally connects to the I2S or I2S_PDM driver. To operate I2S directly, use io_i2s_pdm or another I2S subclass wrapper.

Q: seek takes a long time in asynchronous mode?

In asynchronous mode, seek aborts the current data bus, waits for the IO task to execute `fseek` / Range request at the next job boundary, then refreshes the data. The wait time depends on the IO operation the task is currently performing; if necessary, the wait limit can be adjusted via `esp_gmf_io_set_task_timeout`.

## API Reference

Header files for this component:

- `esp_gmf_io_file.h`: file io configuration and initialization

- `esp_gmf_io_http.h`: http io configuration, events, certificates, reset

- `esp_gmf_io_embed_flash.h`: embed_flash io configuration and resource table setup

- `esp_gmf_io_i2s_pdm.h`: i2s_pdm io configuration and initialization

- `esp_gmf_io_codec_dev.h`: codec_dev io configuration and device hot-swap

The base class API documentation for `esp_gmf_io.h` is in Data Flow.

### Header File

- elements/gmf_io/include/esp_gmf_io_file.h

### Functions

esp_gmf_err_t esp_gmf_io_file_init(file_io_cfg_t *config, esp_gmf_io_handle_t *io)

  Initializes the file stream I/O with the provided configuration.

  Parameters:

    - config – [in] Pointer to the file IO configuration

    - io – [out] Pointer to the file IO handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

### Structures

struct file_io_cfg_t

  File IO configurations, if any entry is zero then the configuration will be set to default values.

  Public Members

  int dir

    IO direction, reader or writer

  const char *name

    Name for this instance

  int cache_size

    Cache size for file IO operations in bytes. If size <= 512, it will be set to 0. Note: Larger cache size will improve read and write performance but consume more memory

  int cache_caps

    Cache memory capabilities, if zero then it will be set to MALLOC_CAP_DMA. Note:

    1. If chips have SOC_SDMMC_PSRAM_DMA_CAPABLE capability(such as ESP32P4), then you can set (MALLOC_CAP_SPIRAM | MALLOC_CAP_DMA) to save SRAM

    2. For ESP32, should use (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT) or MALLOC_CAP_DMA caps to malloc cache

    3. For ESP32Sxx and ESP32Cxx, can also use MALLOC_CAP_INTERNAL caps to malloc cache

  esp_gmf_io_cfg_t io_cfg

    IO configuration for task and buffer

### Macros

FILE_IO_CFG_DEFAULT()

### Header File

- elements/gmf_io/include/esp_gmf_io_http.h

### Functions

esp_gmf_err_t esp_gmf_io_http_init(http_io_cfg_t *config, esp_gmf_io_handle_t *io)

  Initialize the HTTP stream I/O with the specified configuration.

  Parameters:

    - config – [in] Pointer to an `http_io_cfg_t` structure containing the configuration settings for the HTTP I/O

    - io – [out] Pointer to a `esp_gmf_io_handle_t` where the initialized I/O object handle will be stored

  Returns:

    - ESP_GMF_ERR_OK Initialization successful

    - ESP_GMF_ERR_INVALID_ARG Invalid argument(s)

    - ESP_GMF_ERR_MEMORY_LACK Insufficient memory for initialization

esp_gmf_err_t esp_gmf_io_http_reset(esp_gmf_io_handle_t handle)

  Reset http information.

          This function can be used in event_handler of http IO.
          User can call this function to connect to next track in playlist when he/she gets `HTTP_STREAM_FINISH_TRACK` event

  Parameters:

    handle – The http IO handle

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_http_set_server_cert(esp_gmf_io_handle_t handle, const char *cert)

  Set SSL server certification.

  Note

  PEM format as string, if the client requires to verify server

  Parameters:

    - handle – The http IO handle

    - cert – Server certification

  Returns:

    - ESP_GMF_ERR_OK On success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

esp_gmf_err_t esp_gmf_io_http_set_event_callback(esp_gmf_io_handle_t handle, http_io_event_handle_t event_callback)

  Set the event handle for the HTTP IO.

  Parameters:

    - handle – The http IO handle

    - event_callback – The event callback handle

  Returns:

    - ESP_GMF_ERR_OK on success

    - ESP_GMF_ERR_INVALID_ARG Invalid argument

### Structures

struct http_stream_event_msg_t

  Stream event message.

  Public Members

  http_stream_event_id_t event_id

    Event ID

  void *http_client

    Reference to HTTP Client using by this HTTP Stream

  void *buffer

    Reference to Buffer using by the IO

  int buffer_len

    Length of buffer

  void *user_data

    User data context, from `http_io_cfg_t`

struct http_io_cfg_t

  HTTP Stream configurations Default value will be used if any entry is zero.

  Public Members

  int dir

    Type of stream

  http_io_event_handle_t event_handle

    The hook function for HTTP Stream

  void *user_data

    User data context

  const char *cert_pem

    SSL server certification, PEM format as string, if the client requires to verify server

  esp_gmf_io_cfg_t io_cfg

    IO configuration for task and buffer

  esp_err_t (*crt_bundle_attach)(void *conf)

    Function pointer to esp_crt_bundle_attach. Enables the use of certification bundle for server verification, must be enabled in menuconfig

### Macros

HTTP_STREAM_TASK_STACK

HTTP_STREAM_TASK_CORE

HTTP_STREAM_TASK_PRIO

HTTP_STREAM_RINGBUFFER_SIZE

HTTP_STREAM_BUFFER_SIZE

HTTP_STREAM_CFG_DEFAULT()

### Type Definitions

typedef int (*http_io_event_handle_t)(http_stream_event_msg_t *msg)

### Enumerations

enum http_stream_event_id_t

  HTTP Stream hook type.

  Values:

  enumerator HTTP_STREAM_PRE_REQUEST

    The event handler will be called before HTTP Client making the connection to the server

  enumerator HTTP_STREAM_ON_REQUEST

    The event handler will be called when HTTP Client is requesting data, If the function return the value (-1: ESP_GMF_ERR_FAIL), HTTP Client will be stopped If the function return the value > 0, HTTP Stream will ignore the post_field If the function return the value = 0, HTTP Stream continue send data from post_field (if any)

  enumerator HTTP_STREAM_ON_RESPONSE

    The event handler will be called when HTTP Client is receiving data If the function return the value (-1: ESP_GMF_ERR_FAIL), HTTP Client will be stopped If the function return the value > 0, HTTP Stream will ignore the read function If the function return the value = 0, HTTP Stream continue read data from HTTP Server

  enumerator HTTP_STREAM_POST_REQUEST

    The event handler will be called after HTTP Client send header and body to the server, before fetching the headers

  enumerator HTTP_STREAM_FINISH_REQUEST

    The event handler will be called after HTTP Client fetch the header and ready to read HTTP body

### Header File

- elements/gmf_io/include/esp_gmf_io_embed_flash.h

### Functions

esp_gmf_err_t esp_gmf_io_embed_flash_init(embed_flash_io_cfg_t *config, esp_gmf_io_handle_t *io)

  Initializes the embed flash stream I/O with the provided configuration.

  Parameters:

    - config – [in] Pointer to the embed flash IO configuration

    - io – [out] Pointer to the embed flash IO handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_io_embed_flash_set_context(esp_gmf_io_handle_t io, const embed_item_info_t *context, int max_num)

  Set the embed flash context This function mainly provides information about embed flash data.

  Parameters:

    - io – [in] The embed flash element handle

    - context – [in] The embed flash context

    - max_num – [in] The number of embed flash context

  Returns:

    - ESP_GMF_ERR_OK

    - ESP_GMF_ERR_FAIL

### Structures

struct embed_flash_io_cfg_t

  Espressif embed flash configurations, if any entry is zero then the configuration will be set to default values.

  Public Members

  int max_files

    IO direction, reader or writer

  const char *name

    Name for this instance

  esp_gmf_io_cfg_t io_cfg

    IO configuration for task and buffer

struct embed_item_info

  Embed information in flash.

  Public Members

  const uint8_t *address

    The corresponding address in flash

  int size

    Size of corresponding data

### Macros

EMBED_FLASH_CFG_DEFAULT()

### Type Definitions

typedef struct embed_item_info embed_item_info_t

  Embed information in flash.

### Header File

- elements/gmf_io/include/esp_gmf_io_i2s_pdm.h

### Functions

esp_gmf_err_t esp_gmf_io_i2s_pdm_init(i2s_pdm_io_cfg_t *config, esp_gmf_io_handle_t *io)

  Initializes the I2S PDM I/O with the provided configuration.

  Parameters:

    - config – [in] Pointer to the file IO configuration

    - io – [out] Pointer to the file IO handle to be initialized

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

### Structures

struct i2s_pdm_io_cfg_t

  I2S PDM IO configurations, if any entry is zero then the configuration will be set to default values.

  Public Members

  i2s_chan_handle_t pdm_chan

    I2S tx channel handler

  int dir

    IO direction, reader or writer

  const char *name

    Name for this instance

  esp_gmf_io_cfg_t io_cfg

    IO configuration for task and buffer

### Macros

ESP_GMF_IO_I2S_PDM_CFG_DEFAULT()

### Header File

- elements/gmf_io/codec_dev_io/esp_gmf_io_codec_dev.h

### Functions

esp_gmf_err_t esp_gmf_io_codec_dev_init(codec_dev_io_cfg_t *config, esp_gmf_io_handle_t *io)

  Initializes the Audio Codec Device I/O with the provided configuration.

  Parameters:

    - config – [in] Audio codec device io configuration

    - io – [out] Audio codec device io handle

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid configuration provided

    - ESP_GMF_ERR_MEMORY_LACK Failed to allocate memory

esp_gmf_err_t esp_gmf_io_codec_dev_set_dev(esp_gmf_io_handle_t io, esp_codec_dev_handle_t dev)

  Set or update the audio codec device handle for an existing I/O instance.

  Parameters:

    - io – [in] Audio codec device I/O handle

    - dev – [in] New audio codec device handle to set

  Returns:

    - ESP_GMF_ERR_OK Success

    - ESP_GMF_ERR_INVALID_ARG Invalid arguments provided

    - ESP_GMF_ERR_INVALID_STATE Invalid state

### Structures

struct codec_dev_io_cfg_t

  Audio Codec Device IO configurations, if any entry is zero then the configuration will be set to default values.

  Public Members

  esp_codec_dev_handle_t dev

    Audio Codec Device handler

  esp_gmf_io_dir_t dir

    IO direction, reader or writer

  const char *name

    Name for this instance

  esp_gmf_io_cfg_t io_cfg

    IO configuration for task and buffer

### Macros

ESP_GMF_IO_CODEC_DEV_CFG_DEFAULT()

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.