mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-31 14:22:14 +00:00
106 lines
5.3 KiB
C
106 lines
5.3 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include "esp_err.h"
|
|
#include "hal/gpio_types.h"
|
|
#include "driver/i3c_master_types.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Configuration structure for I3C master bus
|
|
*
|
|
* This structure defines the configuration parameters for the I3C master bus,
|
|
* including GPIO pins, clock source, queue depth, interrupt priority, and other options.
|
|
*/
|
|
typedef struct {
|
|
gpio_num_t sda_io_num; /*!< GPIO number of I3C SDA signal, pulled-up internally */
|
|
gpio_num_t scl_io_num; /*!< GPIO number of I3C SCL signal, pulled-up internally */
|
|
i3c_master_clock_source_t clock_source; /*!< Clock source of I3C master bus */
|
|
size_t trans_queue_depth; /*!< Depth of internal transfer queue, increase this value can support more transfers pending in the background, only valid in asynchronous transaction. (Typically max_device_num * per_transaction)*/
|
|
size_t max_transfer_size; /*!< Maximum transfer size in one transaction, in bytes. This decides the number of DMA nodes will be used for each transaction */
|
|
size_t dma_burst_size; /*!< DMA burst size, in bytes */
|
|
int intr_priority; /*!< I3C interrupt priority, if set to 0, driver will select the default priority (1,2,3). */
|
|
struct {
|
|
uint32_t enable_internal_pullup : 1; /*!< Enable internal pullups. Note: This is not strong enough to pullup buses under high-speed frequency. Recommend proper external pull-up if possible */
|
|
uint32_t enable_internal_opendrain : 1; /*!< Pull-Push mode on I3C SCL/SDA pins by default. Set true if open-drain mode is needed */
|
|
uint32_t use_dma : 1; /*!< Use dma transaction. Set to 1 to enable the use of DMA for handling data transfers, which can improve performance for large transactions. */
|
|
uint32_t enable_async_trans : 1; /*!< Enable asynchronous transactions, allowing the master to perform other tasks while a transaction is in progress. Only works when `use_dma` is set as true. */
|
|
} flags; /*!< I3C master config flags */
|
|
} i3c_master_bus_config_t;
|
|
|
|
/**
|
|
* @brief Create a new I3C master bus.
|
|
*
|
|
* This function initializes a new I3C master bus with the provided configuration.
|
|
*
|
|
* @param[in] bus_config Pointer to the I3C master bus configuration structure.
|
|
* @param[out] ret_bus_handle Pointer to the location where the handle of the newly created bus will be stored.
|
|
*
|
|
* @return
|
|
* - ESP_OK: Bus created successfully.
|
|
* - ESP_ERR_INVALID_ARG: Invalid configuration or parameters.
|
|
* - ESP_ERR_NO_MEM: Memory allocation failed.
|
|
*/
|
|
esp_err_t i3c_new_master_bus(const i3c_master_bus_config_t *bus_config, i3c_master_bus_handle_t *ret_bus_handle);
|
|
|
|
/**
|
|
* @brief Deletes an I3C master bus and releases associated resources.
|
|
*
|
|
* This function deinitializes and deletes the specified I3C master bus instance. It ensures
|
|
* that all resources allocated for the bus are properly released. The caller must ensure
|
|
* that no active operations are ongoing on the bus before invoking this function.
|
|
*
|
|
* @param bus_handle Handle to the I3C master bus to be deleted. This handle must have been
|
|
* previously obtained from a successful bus initialization.
|
|
*
|
|
* @return
|
|
* - `ESP_OK`: The bus was successfully deleted.
|
|
* - `ESP_ERR_INVALID_ARG`: The provided `bus_handle` is invalid (e.g., null or uninitialized).
|
|
*/
|
|
esp_err_t i3c_del_master_bus(i3c_master_bus_handle_t bus_handle);
|
|
|
|
/**
|
|
* @brief Wait for all pending I3C transactions done
|
|
*
|
|
* @param[in] bus_handle I3C bus handle
|
|
* @param[in] timeout_ms Wait timeout, in ms. Specially, -1 means to wait forever.
|
|
* @return
|
|
* - ESP_OK: Flush transactions successfully
|
|
* - ESP_ERR_INVALID_ARG: Flush transactions failed because of invalid argument
|
|
* - ESP_ERR_TIMEOUT: Flush transactions failed because of timeout
|
|
*/
|
|
esp_err_t i3c_master_bus_wait_all_done(i3c_master_bus_handle_t bus_handle, int timeout_ms);
|
|
|
|
/**
|
|
* @brief Toggle between synchronous and asynchronous transfer modes for the I3C master bus.
|
|
*
|
|
* This function allows switching the I3C master bus between synchronous and asynchronous
|
|
* transfer modes. It ensures that the necessary preconditions are met before making the switch:
|
|
* - If switching to asynchronous mode, it requires that the async memory has been initialized.
|
|
* - If switching to synchronous mode, it verifies that no pending transactions are in the queue.
|
|
*
|
|
* @param[in] bus_handle Handle to the I3C master bus.
|
|
* @param[in] async_mode Boolean value indicating the target mode:
|
|
* - `true` for asynchronous mode.
|
|
* - `false` for synchronous mode.
|
|
*
|
|
* @return
|
|
* - ESP_OK: The mode was successfully toggled.
|
|
* - ESP_ERR_INVALID_ARG: Invalid input arguments.
|
|
* - ESP_ERR_INVALID_STATE: Cannot switch to synchronous mode due to pending transactions.
|
|
*/
|
|
esp_err_t i3c_master_toggle_transfer_async_mode(i3c_master_bus_handle_t bus_handle, bool async_mode);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|