esp_board_periph.h

[English]

Header File

Functions

esp_err_t esp_board_periph_init(const char *name)

Initialize a peripheral by name. 

    This function initializes a peripheral with reference counting support. If the peripheral
    is already initialized, it increments the reference count instead of reinitializing
    The peripheral is only actually initialized when the reference count reaches 1
    Peripherals are found by matching type and role from the handle list
参数:

name – [in] Peripheral name to initialize

返回:

  • ESP_OK On success

  • ESP_ERR_NO_MEM If memory allocation fails for list entry

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral descriptor not found

  • ESP_BOARD_ERR_PERIPH_NO_HANDLE If no matching handle found for type/role

  • ESP_BOARD_ERR_PERIPH_NO_INIT If no init function is available

  • Others Error codes from peripheral-specific initialization

esp_err_t esp_board_periph_get_handle(const char *name, void **periph_handle)

Get peripheral handle by name. 

    Retrieves the peripheral handle for a given peripheral name
    The peripheral is automatically initialized if it is not initialized
参数:

  • name – [in] Peripheral name

  • periph_handle – [out] Pointer to store the peripheral handle

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name or periph_handle is NULL

  • ESP_BOARD_ERR_PERIPH_NO_HANDLE If peripheral initialized failed or no handle found

esp_err_t esp_board_periph_get_name_by_handle(void *periph_handle, const char **name)

Get peripheral name by handle. 

    Retrieves the peripheral name for a given peripheral handle
    Searches through all initialized peripherals to find the matching handle
参数:

  • periph_handle – [in] Peripheral handle to search for

  • name – [out] Pointer to store the peripheral name

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If periph_handle or name is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If no peripheral found with the given handle

esp_err_t esp_board_periph_ref_handle(const char *name, void **periph_handle)

Get reference peripheral handle by name. 

    Retrieves the peripheral handle for a given peripheral name
    The peripheral is automatically initialized if it is not initialized
    Increases the reference count for the peripheral
参数:

  • name – [in] Peripheral name

  • periph_handle – [out] Pointer to store the peripheral handle

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name or periph_handle is NULL

  • ESP_BOARD_ERR_PERIPH_NO_HANDLE If peripheral initialized failed or no handle found

esp_err_t esp_board_periph_unref_handle(const char *name)

Unreference peripheral handle by name. 

    Decreases the reference count for the peripheral
    The peripheral is only actually deinitialized when the reference count reaches 0
参数:

name – [in] Peripheral name

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral list entry not found

  • ESP_BOARD_ERR_PERIPH_NO_INIT If no deinit function is available

  • Others Error codes from peripheral-specific deinitialization

esp_err_t esp_board_periph_get_config(const char *name, void **config)

Get peripheral configuration by name.

参数:

  • name – [in] Peripheral name

  • config – [out] Pointer to store the configuration

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name or config is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral configuration not found

  • ESP_BOARD_ERR_PERIPH_NOT_SUPPORTED If peripheral has no configuration

esp_err_t esp_board_periph_init_custom(const char *name, esp_board_periph_init_func init, esp_board_periph_deinit_func deinit)

Initialize peripheral with custom functions. 

    Associates custom init and deinit functions with a peripheral and initializes it
    This allows runtime configuration of peripheral behavior. If the peripheral
    is already initialized, only the functions are updated
参数:

  • name – [in] Peripheral name

  • init – [in] Initialization function pointer

  • deinit – [in] Deinitialization function pointer

返回:

  • ESP_OK On success

  • ESP_ERR_NO_MEM If memory allocation fails for list entry

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If any parameter is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral descriptor not found

  • ESP_BOARD_ERR_PERIPH_NO_HANDLE If no matching handle found for type/role

  • ESP_BOARD_ERR_PERIPH_INIT_FAILED If initialization fails

esp_err_t esp_board_periph_deinit(const char *name)

Deinitialize a peripheral by name. 

    Decrements the reference count for a peripheral. The peripheral is only actually
    deinitialized when the reference count reaches 0. If the peripheral is not
    initialized, this function returns success
参数:

name – [in] Peripheral name to deinitialize

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral list entry not found

  • ESP_BOARD_ERR_PERIPH_NO_INIT If no deinit function is available

  • Others Error codes from peripheral-specific deinitialization

esp_err_t esp_board_periph_show(const char *name)

Show peripheral information. 

    Displays detailed information about peripherals. If name is NULL, shows
    information for all peripherals. Otherwise, shows information for the
    specified peripheral including type, role, handle status, and reference count
参数:

name – [in] Peripheral name (NULL for all peripherals)

返回:

  • ESP_OK On success

  • ESP_BOARD_ERR_PERIPH_NOT_FOUND If specific peripheral not found (when name is not NULL)

esp_err_t esp_board_periph_init_all(void)

Initialize all peripherals. 

    Iterates through all peripheral descriptors and initializes each peripheral
    Continues initializing even if some peripherals fail, but logs errors

备注

Peripheral initialization follows the order defined in board_peripherals.yaml

返回:

  • ESP_OK On success (always returns ESP_OK, errors are logged)

esp_err_t esp_board_periph_deinit_all(void)

Deinitialize all peripherals. 

    Iterates through all peripheral list entries and deinitializes each peripheral
    Continues deinitializing even if some peripherals fail, but logs errors
返回:

  • ESP_OK On success (always returns ESP_OK, errors are logged)

Structures

struct esp_board_periph_desc

Structure representing a peripheral descriptor.

Public Members

const struct esp_board_periph_desc *next

Pointer to next peripheral descriptor

const char *name

Peripheral name

const char *type

Peripheral type

esp_board_periph_role_t role

Peripheral role

const char *format

Peripheral format

const void *cfg

Peripheral configuration data

int cfg_size

Size of configuration data

int id

Peripheral ID extracted from name (e.g., 48 from gpio48, 0 from iic0)

struct esp_board_periph_entry

Structure representing a peripheral entry.

Public Members

struct esp_board_periph_entry *next

Pointer to next peripheral entry

const char *type

Peripheral type

esp_board_periph_role_t role

Peripheral role

esp_board_periph_init_func init

Peripheral initialization function

esp_board_periph_deinit_func deinit

Peripheral deinitialization function

struct esp_board_periph_list

Structure representing a peripheral list entry.

Public Members

struct esp_board_periph_list *next

Pointer to next peripheral list entry

const char *name

Peripheral name

const char *type

Peripheral type

esp_board_periph_role_t role

Peripheral role

void *periph_handle

Peripheral-specific handle

uint8_t ref_count

Reference count

Macros

PERIPHERAL_EXTRA_FUNC_REGISTER(name, extra_func)

Type Definitions

typedef esp_err_t (*esp_board_periph_init_func)(void *cfg, int cfg_size, void **periph_handle)

Function pointer type for peripheral initialization.

typedef esp_err_t (*esp_board_periph_deinit_func)(void *periph_handle)

Function pointer type for peripheral deinitialization.

typedef struct esp_board_periph_desc esp_board_periph_desc_t

Structure representing a peripheral descriptor.

typedef struct esp_board_periph_entry esp_board_periph_entry_t

Structure representing a peripheral entry.

typedef struct esp_board_periph_list esp_board_periph_list_t

Structure representing a peripheral list entry.

此文档对您有帮助吗？