Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: Resolve doxygen & Sphinx warnings

Browse source
This commit is contained in:
Angus Gratton 2020-01-29 09:31:14 +11:00 committed by Angus Gratton
parent 268816649c
commit 11fac8637a
38 changed files with 312 additions and 273 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h
View file

@ -439,11 +439,11 @@ typedef struct {
struct esp_ble_mesh_model {
/** Model ID */
union {
const uint16_t model_id;
struct {
uint16_t company_id;
uint16_t model_id;
} vnd;
const uint16_t model_id; /*!< 16-bit model identifier */
struct esp_ble_mesh_vnd_struct {
uint16_t company_id; /*!< 16-bit company identifier */
uint16_t model_id; /*!< 16-bit model identifier */
} vnd; /*!< Structure encapsulating a model ID with a company ID */
};
/** Internal information, mainly for persistent storage */
@ -656,7 +656,7 @@ typedef struct {
typedef struct {
union {
struct {
esp_ble_mesh_bd_addr_t addr; /*!< Device address */
esp_ble_mesh_bd_addr_t addr; /*!< Device address */
esp_ble_mesh_addr_type_t addr_type; /*!< Device address type */
};
uint8_t uuid[16]; /*!< Device UUID */

11
components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
View file

@ -31,7 +31,8 @@ extern "C" {
typedef uint8_t esp_a2d_mct_t;
/// A2DP media codec capabilities union
/** A2DP media codec capabilities union
*/
typedef struct {
esp_a2d_mct_t type; /*!< A2DP media codec type */
#define ESP_A2D_CIE_LEN_SBC (4)
@ -39,10 +40,10 @@ typedef struct {
#define ESP_A2D_CIE_LEN_M24 (6)
#define ESP_A2D_CIE_LEN_ATRAC (7)
union {
uint8_t sbc[ESP_A2D_CIE_LEN_SBC];
uint8_t m12[ESP_A2D_CIE_LEN_M12];
uint8_t m24[ESP_A2D_CIE_LEN_M24];
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];
uint8_t sbc[ESP_A2D_CIE_LEN_SBC]; /*!< SBC codec capabilities */
uint8_t m12[ESP_A2D_CIE_LEN_M12]; /*!< MPEG-1,2 audio codec capabilities */
uint8_t m24[ESP_A2D_CIE_LEN_M24]; /*!< MPEG-2, 4 AAC audio codec capabilities */
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]; /*!< ATRAC family codec capabilities */
} cie; /*!< A2DP codec information element */
} __attribute__((packed)) esp_a2d_mcc_t;

6
components/bt/host/bluedroid/api/include/api/esp_bt_defs.h
View file

@ -86,9 +86,9 @@ typedef struct {
#define ESP_UUID_LEN_128 16
uint16_t len; /*!< UUID length, 16bit, 32bit or 128bit */
union {
uint16_t uuid16;
uint32_t uuid32;
uint8_t uuid128[ESP_UUID_LEN_128];
uint16_t uuid16; /*!< 16bit UUID */
uint32_t uuid32; /*!< 32bit UUID */
uint8_t uuid128[ESP_UUID_LEN_128]; /*!< 128bit UUID */
} uuid; /*!< UUID */
} __attribute__((packed)) esp_bt_uuid_t;

27
components/driver/esp32s2/include/touch_sensor.h
View file

@ -51,22 +51,22 @@ esp_err_t touch_pad_sw_start(void);
* sleep_cycle decide the interval between each measurement.
* t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
* @param meas_timers The times of charge and discharge in each measure process of touch channels.
* The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1ms.
* @param meas_time The time of charge and discharge in each measure process of touch channels.
* The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
* Recommended typical value: Modify this value to make the measurement time around 1ms.
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_time);
/**
* @brief Get touch sensor times of charge and discharge and sleep time
* @param sleep_cycle Pointer to accept sleep cycle number
* @param meas_times Pointer to accept measurement times count.
* @param meas_time Pointer to accept measurement time count.
* @return
* - ESP_OK on success
*/
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times);
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_time);
/**
* @brief Set connection type of touch channel in idle status.
@ -196,7 +196,7 @@ uint32_t touch_pad_read_intr_status_mask(void);
/**
* @brief Enable touch sensor interrupt by bitmask.
* @param type interrupt type
* @param int_mask Pad mask to enable interrupts
* @return
* - ESP_OK on success
*/
@ -204,7 +204,7 @@ esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask);
/**
* @brief Disable touch sensor interrupt by bitmask.
* @param type interrupt type
* @param int_mask Pad mask to disable interrupts
* @return
* - ESP_OK on success
*/
@ -215,12 +215,13 @@ esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask);
* The handler will be attached to the same CPU core that this function is running on.
* @param fn Pointer to ISR handler
* @param arg Parameter for ISR
* @param int_mask Initial pad mask to enable interrupt for
* @return
* - ESP_OK Success ;
* - ESP_ERR_INVALID_ARG GPIO error
* - ESP_ERR_NO_MEM No memory
*/
esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t intr_mask);
esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t int_mask);
/**
* @brief get raw data of touch sensor.
@ -239,7 +240,7 @@ esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data);
* @brief get baseline of touch sensor.
* @note After initialization, the baseline value is the maximum during the first measurement period.
* @param touch_num touch pad index
* @param touch_value pointer to accept touch sensor value
* @param basedata pointer to accept touch sensor baseline value
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Touch channel 0 havent this parameter.
@ -331,7 +332,7 @@ esp_err_t touch_pad_denoise_disable(void);
/**
* @brief Get denoise measure value (TOUCH_PAD_NUM0).
* @param denoise value of denoise
* @param data Pointer to receive denoise value
* @return
* - ESP_OK Success
*/
@ -405,7 +406,7 @@ esp_err_t touch_pad_proximity_get_config(touch_pad_proximity_t *proximity);
* @brief Get measure count of proximity channel.
* The proximity sensor measurement is the accumulation of touch channel measurements.
* @param touch_num touch pad index
* @param proximity parameter of proximity
* @param cnt Pointer to receive proximity channel measurement count
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG parameter is NULL
@ -462,4 +463,4 @@ esp_err_t touch_pad_sleep_channel_read_proximity_cnt(uint32_t *proximity_cnt);
#ifdef __cplusplus
}
#endif
#endif

12
components/driver/include/driver/timer.h
View file

@ -331,8 +331,6 @@ esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num);
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
* @param timer_num Timer index.
*
* @return
* - None
*/
void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num) __attribute__((deprecated));
@ -341,8 +339,6 @@ void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num)
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
* @param timer_num Timer index.
*
* @return
* - None
*/
void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t timer_num);
@ -351,8 +347,6 @@ void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t tim
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
* @param timer_num Timer index.
*
* @return
* - None
*/
void timer_group_enable_alarm_in_isr(timer_group_t group_num, timer_idx_t timer_num);
@ -372,8 +366,6 @@ uint64_t timer_group_get_counter_value_in_isr(timer_group_t group_num, timer_idx
* @param timer_num Timer index.
* @param alarm_val Alarm threshold.
*
* @return
* - None
*/
void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t timer_num, uint64_t alarm_val);
@ -383,8 +375,6 @@ void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t tim
* @param timer_num Timer index.
* @param counter_en Enable/disable.
*
* @return
* - None
*/
void timer_group_set_counter_enable_in_isr(timer_group_t group_num, timer_idx_t timer_num, timer_start_t counter_en);
@ -411,8 +401,6 @@ uint32_t timer_group_get_intr_status_in_isr(timer_group_t group_num);
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
* @param intr_mask Masked interrupt.
*
* @return
* - None
*/
void timer_group_clr_intr_sta_in_isr(timer_group_t group_num, timer_intr_t intr_mask) __attribute__((deprecated));

12
components/esp32/include/esp_intr_alloc.h
View file

@ -56,7 +56,6 @@ extern "C" {
#define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
ESP_INTR_FLAG_NMI) ///< Mask for all level flags
/**@}*/
/** @addtogroup Intr_Alloc_Pseudo_Src
@ -78,16 +77,23 @@ extern "C" {
/**@}*/
// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
*/
#define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
/** Enable interrupt by interrupt number */
#define ESP_INTR_ENABLE(inum) xt_ints_on((1<<inum))
/** Disable interrupt by interrupt number */
#define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
/** Function prototype for interrupt handler function */
typedef void (*intr_handler_t)(void *arg);
/** Interrupt handler associated data structure */
typedef struct intr_handle_data_t intr_handle_data_t;
/** Handle to an interrupt handler */
typedef intr_handle_data_t* intr_handle_t ;
/**

12
components/esp32s2/include/esp_intr_alloc.h
View file

@ -56,7 +56,6 @@ extern "C" {
#define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
ESP_INTR_FLAG_NMI) ///< Mask for all level flags
/**@}*/
/** @addtogroup Intr_Alloc_Pseudo_Src
@ -78,16 +77,23 @@ extern "C" {
/**@}*/
// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
*/
#define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
/** Enable interrupt by interrupt number */
#define ESP_INTR_ENABLE(inum) xt_ints_on((1<<inum))
/** Disable interrupt by interrupt number */
#define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
/** Function prototype for interrupt handler function */
typedef void (*intr_handler_t)(void *arg);
/** Interrupt handler associated data structure */
typedef struct intr_handle_data_t intr_handle_data_t;
/** Handle to an interrupt handler */
typedef intr_handle_data_t* intr_handle_t ;
/**

1
components/esp_event/include/esp_event.h
View file

@ -302,6 +302,7 @@ esp_err_t esp_event_isr_post(esp_event_base_t event_base,
/**
* @brief Special variant of esp_event_post_to for posting events from interrupt handlers
*
* @param[in] event_loop the event loop to post to
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler

2
components/freemodbus/common/include/esp_modbus_common.h
View file

@ -114,7 +114,7 @@ typedef union {
uart_port_t port; /*!< Modbus communication port (UART) number */
uint32_t baudrate; /*!< Modbus baudrate */
uart_parity_t parity; /*!< Modbus UART parity settings */
uint16_t dummy_port;
uint16_t dummy_port; /*!< Dummy field, unused */
};
// Tcp communication structure
struct {

4
components/soc/include/hal/i2c_types.h
View file

@ -83,11 +83,11 @@ typedef struct{
union {
struct {
uint32_t clk_speed; /*!< I2C clock frequency for master mode, (no higher than 1MHz for now) */
} master;
} master; /*!< I2C master config */
struct {
uint8_t addr_10bit_en; /*!< I2C 10bit address mode enable for slave mode */
uint16_t slave_addr; /*!< I2C address for slave mode */
} slave;
} slave; /*!< I2C slave config */
};
} i2c_config_t;

19
components/soc/include/hal/touch_sensor_types.h
View file

@ -17,6 +17,7 @@
#include "soc/touch_sensor_caps.h"
#include "sdkconfig.h"
/** Touch pad channel */
typedef enum {
TOUCH_PAD_NUM0 = 0, /*!< Touch pad channel 0 is GPIO4(ESP32) */
TOUCH_PAD_NUM1, /*!< Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2) */
@ -38,6 +39,7 @@ typedef enum {
TOUCH_PAD_MAX,
} touch_pad_t;
/** Touch sensor high reference voltage */
typedef enum {
TOUCH_HVOLT_KEEP = -1, /*!<Touch sensor high reference voltage, no change */
TOUCH_HVOLT_2V4 = 0, /*!<Touch sensor high reference voltage, 2.4V */
@ -47,6 +49,7 @@ typedef enum {
TOUCH_HVOLT_MAX,
} touch_high_volt_t;
/** Touch sensor low reference voltage */
typedef enum {
TOUCH_LVOLT_KEEP = -1, /*!<Touch sensor low reference voltage, no change */
TOUCH_LVOLT_0V5 = 0, /*!<Touch sensor low reference voltage, 0.5V */
@ -56,6 +59,7 @@ typedef enum {
TOUCH_LVOLT_MAX,
} touch_low_volt_t;
/** Touch sensor high reference voltage attenuation */
typedef enum {
TOUCH_HVOLT_ATTEN_KEEP = -1, /*!<Touch sensor high reference voltage attenuation, no change */
TOUCH_HVOLT_ATTEN_1V5 = 0, /*!<Touch sensor high reference voltage attenuation, 1.5V attenuation */
@ -65,6 +69,7 @@ typedef enum {
TOUCH_HVOLT_ATTEN_MAX,
} touch_volt_atten_t;
/** Touch sensor charge/discharge speed */
typedef enum {
TOUCH_PAD_SLOPE_0 = 0, /*!<Touch sensor charge / discharge speed, always zero */
TOUCH_PAD_SLOPE_1 = 1, /*!<Touch sensor charge / discharge speed, slowest */
@ -77,12 +82,14 @@ typedef enum {
TOUCH_PAD_SLOPE_MAX,
} touch_cnt_slope_t;
/** Touch sensor initial charge level */
typedef enum {
TOUCH_PAD_TIE_OPT_LOW = 0, /*!<Initial level of charging voltage, low level */
TOUCH_PAD_TIE_OPT_HIGH = 1, /*!<Initial level of charging voltage, high level */
TOUCH_PAD_TIE_OPT_MAX,
} touch_tie_opt_t;
/** Touch sensor FSM mode */
typedef enum {
TOUCH_FSM_MODE_TIMER = 0, /*!<To start touch FSM by timer */
TOUCH_FSM_MODE_SW, /*!<To start touch FSM by software trigger */
@ -175,6 +182,7 @@ typedef enum {
TOUCH_PAD_DENOISE_CAP_MAX
} touch_pad_denoise_cap_t;
/** Touch sensor denoise configuration */
typedef struct touch_pad_denoise {
touch_pad_denoise_grade_t grade; /*!<Select denoise range of denoise channel.
Determined by measuring the noise amplitude of the denoise channel. */
@ -195,6 +203,7 @@ typedef enum {
TOUCH_PAD_SHIELD_DRV_MAX
} touch_pad_shield_driver_t;
/** Touch sensor waterproof configuration */
typedef struct touch_pad_waterproof {
touch_pad_t guard_ring_pad; /*!<Waterproof. Select touch channel use for guard pad */
touch_pad_shield_driver_t shield_driver;/*!<Waterproof. Select max equivalent capacitance for sheild pad
@ -202,6 +211,7 @@ typedef struct touch_pad_waterproof {
reading to the Touch0 reading to estimate the equivalent capacitance.*/
} touch_pad_waterproof_t;
/** Touch sensor proximity detection configuration */
typedef struct touch_pad_proximity {
touch_pad_t select_pad[SOC_TOUCH_PROXIMITY_CHANNEL_NUM]; /*!<Set touch channel number for proximity pad.
If clear the proximity channel, point this pad to `TOUCH_PAD_NUM0` */
@ -209,9 +219,10 @@ typedef struct touch_pad_proximity {
#define TOUCH_PROXIMITY_MEAS_NUM_MAX (0xFF)
} touch_pad_proximity_t;
/** Touch channel idle state configuration */
typedef enum {
TOUCH_PAD_CONN_HIGHZ = 0, /*!<Idel status of touch channel is high resistance state */
TOUCH_PAD_CONN_GND = 1, /*!<Idel status of touch channel is ground connection */
TOUCH_PAD_CONN_HIGHZ = 0, /*!<Idle status of touch channel is high resistance state */
TOUCH_PAD_CONN_GND = 1, /*!<Idle status of touch channel is ground connection */
TOUCH_PAD_CONN_MAX
} touch_pad_conn_type_t;
@ -223,6 +234,7 @@ typedef enum {
TOUCH_PAD_FILTER_MAX
} touch_filter_mode_t;
/** Touch sensor filter configuration */
typedef struct touch_filter_config {
touch_filter_mode_t mode; /*!<Set filter mode. The input to the filter is raw data and the output is the baseline value.
Larger filter coefficients increase the stability of the baseline. */
@ -253,6 +265,7 @@ typedef struct touch_filter_config {
#define TOUCH_JITTER_STEP_MAX (15)
} touch_filter_config_t;
/** Touch sensor channel sleep configuration */
typedef struct {
touch_pad_t touch_num; /*!<Set touch channel number for sleep pad.
Only one touch sensor channel is supported in deep sleep mode. */
@ -261,4 +274,4 @@ typedef struct {
bool en_proximity; /*!<enable proximity function for sleep pad */
} touch_pad_sleep_channel_t;
#endif // CONFIG_IDF_TARGET_ESP32S2
#endif // CONFIG_IDF_TARGET_ESP32S2

2
components/soc/include/hal/uart_types.h
View file

@ -136,7 +136,7 @@ typedef struct {
uint8_t rx_flow_ctrl_thresh; /*!< UART HW RTS threshold*/
union {
uart_sclk_t source_clk; /*!< UART source clock selection */
bool use_ref_tick __attribute__((deprecated));
bool use_ref_tick __attribute__((deprecated)); /*!< Deprecated method to select ref tick clock source, set source_clk field instead */
};
} uart_config_t;

132
components/vfs/include/esp_vfs.h
View file

@ -101,137 +101,137 @@ typedef struct
{
int flags; /*!< ESP_VFS_FLAG_CONTEXT_PTR or ESP_VFS_FLAG_DEFAULT */
union {
ssize_t (*write_p)(void* p, int fd, const void * data, size_t size);
ssize_t (*write)(int fd, const void * data, size_t size);
ssize_t (*write_p)(void* p, int fd, const void * data, size_t size); /*!< Write with context pointer */
ssize_t (*write)(int fd, const void * data, size_t size); /*!< Write without context pointer */
};
union {
off_t (*lseek_p)(void* p, int fd, off_t size, int mode);
off_t (*lseek)(int fd, off_t size, int mode);
off_t (*lseek_p)(void* p, int fd, off_t size, int mode); /*!< Seek with context pointer */
off_t (*lseek)(int fd, off_t size, int mode); /*!< Seek without context pointer */
};
union {
ssize_t (*read_p)(void* ctx, int fd, void * dst, size_t size);
ssize_t (*read)(int fd, void * dst, size_t size);
ssize_t (*read_p)(void* ctx, int fd, void * dst, size_t size); /*!< Read with context pointer */
ssize_t (*read)(int fd, void * dst, size_t size); /*!< Read without context pointer */
};
union {
ssize_t (*pread_p)(void *ctx, int fd, void * dst, size_t size, off_t offset);
ssize_t (*pread)(int fd, void * dst, size_t size, off_t offset);
ssize_t (*pread_p)(void *ctx, int fd, void * dst, size_t size, off_t offset); /*!< pread with context pointer */
ssize_t (*pread)(int fd, void * dst, size_t size, off_t offset); /*!< pread without context pointer */
};
union {
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset);
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset);
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset); /*!< pwrite with context pointer */
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset); /*!< pwrite without context pointer */
};
union {
int (*open_p)(void* ctx, const char * path, int flags, int mode);
int (*open)(const char * path, int flags, int mode);
int (*open_p)(void* ctx, const char * path, int flags, int mode); /*!< open with context pointer */
int (*open)(const char * path, int flags, int mode); /*!< open without context pointer */
};
union {
int (*close_p)(void* ctx, int fd);
int (*close)(int fd);
int (*close_p)(void* ctx, int fd); /*!< close with context pointer */
int (*close)(int fd); /*!< close without context pointer */
};
union {
int (*fstat_p)(void* ctx, int fd, struct stat * st);
int (*fstat)(int fd, struct stat * st);
int (*fstat_p)(void* ctx, int fd, struct stat * st); /*!< fstat with context pointer */
int (*fstat)(int fd, struct stat * st); /*!< fstat without context pointer */
};
union {
int (*stat_p)(void* ctx, const char * path, struct stat * st);
int (*stat)(const char * path, struct stat * st);
int (*stat_p)(void* ctx, const char * path, struct stat * st); /*!< stat with context pointer */
int (*stat)(const char * path, struct stat * st); /*!< stat without context pointer */
};
union {
int (*link_p)(void* ctx, const char* n1, const char* n2);
int (*link)(const char* n1, const char* n2);
int (*link_p)(void* ctx, const char* n1, const char* n2); /*!< link with context pointer */
int (*link)(const char* n1, const char* n2); /*!< link without context pointer */
};
union {
int (*unlink_p)(void* ctx, const char *path);
int (*unlink)(const char *path);
int (*unlink_p)(void* ctx, const char *path); /*!< unlink with context pointer */
int (*unlink)(const char *path); /*!< unlink without context pointer */
};
union {
int (*rename_p)(void* ctx, const char *src, const char *dst);
int (*rename)(const char *src, const char *dst);
int (*rename_p)(void* ctx, const char *src, const char *dst); /*!< rename with context pointer */
int (*rename)(const char *src, const char *dst); /*!< rename without context pointer */
};
union {
DIR* (*opendir_p)(void* ctx, const char* name);
DIR* (*opendir)(const char* name);
DIR* (*opendir_p)(void* ctx, const char* name); /*!< opendir with context pointer */
DIR* (*opendir)(const char* name); /*!< opendir without context pointer */
};
union {
struct dirent* (*readdir_p)(void* ctx, DIR* pdir);
struct dirent* (*readdir)(DIR* pdir);
struct dirent* (*readdir_p)(void* ctx, DIR* pdir); /*!< readdir with context pointer */
struct dirent* (*readdir)(DIR* pdir); /*!< readdir without context pointer */
};
union {
int (*readdir_r_p)(void* ctx, DIR* pdir, struct dirent* entry, struct dirent** out_dirent);
int (*readdir_r)(DIR* pdir, struct dirent* entry, struct dirent** out_dirent);
int (*readdir_r_p)(void* ctx, DIR* pdir, struct dirent* entry, struct dirent** out_dirent); /*!< readdir_r with context pointer */
int (*readdir_r)(DIR* pdir, struct dirent* entry, struct dirent** out_dirent); /*!< readdir_r without context pointer */
};
union {
long (*telldir_p)(void* ctx, DIR* pdir);
long (*telldir)(DIR* pdir);
long (*telldir_p)(void* ctx, DIR* pdir); /*!< telldir with context pointer */
long (*telldir)(DIR* pdir); /*!< telldir without context pointer */
};
union {
void (*seekdir_p)(void* ctx, DIR* pdir, long offset);
void (*seekdir)(DIR* pdir, long offset);
void (*seekdir_p)(void* ctx, DIR* pdir, long offset); /*!< seekdir with context pointer */
void (*seekdir)(DIR* pdir, long offset); /*!< seekdir without context pointer */
};
union {
int (*closedir_p)(void* ctx, DIR* pdir);
int (*closedir)(DIR* pdir);
int (*closedir_p)(void* ctx, DIR* pdir); /*!< closedir with context pointer */
int (*closedir)(DIR* pdir); /*!< closedir without context pointer */
};
union {
int (*mkdir_p)(void* ctx, const char* name, mode_t mode);
int (*mkdir)(const char* name, mode_t mode);
int (*mkdir_p)(void* ctx, const char* name, mode_t mode); /*!< mkdir with context pointer */
int (*mkdir)(const char* name, mode_t mode); /*!< mkdir without context pointer */
};
union {
int (*rmdir_p)(void* ctx, const char* name);
int (*rmdir)(const char* name);
int (*rmdir_p)(void* ctx, const char* name); /*!< rmdir with context pointer */
int (*rmdir)(const char* name); /*!< rmdir without context pointer */
};
union {
int (*fcntl_p)(void* ctx, int fd, int cmd, int arg);
int (*fcntl)(int fd, int cmd, int arg);
int (*fcntl_p)(void* ctx, int fd, int cmd, int arg); /*!< fcntl with context pointer */
int (*fcntl)(int fd, int cmd, int arg); /*!< fcntl without context pointer */
};
union {
int (*ioctl_p)(void* ctx, int fd, int cmd, va_list args);
int (*ioctl)(int fd, int cmd, va_list args);
int (*ioctl_p)(void* ctx, int fd, int cmd, va_list args); /*!< ioctl with context pointer */
int (*ioctl)(int fd, int cmd, va_list args); /*!< ioctl without context pointer */
};
union {
int (*fsync_p)(void* ctx, int fd);
int (*fsync)(int fd);
int (*fsync_p)(void* ctx, int fd); /*!< fsync with context pointer */
int (*fsync)(int fd); /*!< fsync without context pointer */
};
union {
int (*access_p)(void* ctx, const char *path, int amode);
int (*access)(const char *path, int amode);
int (*access_p)(void* ctx, const char *path, int amode); /*!< access with context pointer */
int (*access)(const char *path, int amode); /*!< access without context pointer */
};
union {
int (*truncate_p)(void* ctx, const char *path, off_t length);
int (*truncate)(const char *path, off_t length);
int (*truncate_p)(void* ctx, const char *path, off_t length); /*!< truncate with context pointer */
int (*truncate)(const char *path, off_t length); /*!< truncate without context pointer */
};
union {
int (*utime_p)(void* ctx, const char *path, const struct utimbuf *times);
int (*utime)(const char *path, const struct utimbuf *times);
int (*utime_p)(void* ctx, const char *path, const struct utimbuf *times); /*!< utime with context pointer */
int (*utime)(const char *path, const struct utimbuf *times); /*!< utime without context pointer */
};
#ifdef CONFIG_VFS_SUPPORT_TERMIOS
union {
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p);
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p);
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p); /*!< tcsetattr with context pointer */
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p); /*!< tcsetattr without context pointer */
};
union {
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p);
int (*tcgetattr)(int fd, struct termios *p);
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p); /*!< tcgetattr with context pointer */
int (*tcgetattr)(int fd, struct termios *p); /*!< tcgetattr without context pointer */
};
union {
int (*tcdrain_p)(void *ctx, int fd);
int (*tcdrain)(int fd);
int (*tcdrain_p)(void *ctx, int fd); /*!< tcdrain with context pointer */
int (*tcdrain)(int fd); /*!< tcdrain without context pointer */
};
union {
int (*tcflush_p)(void *ctx, int fd, int select);
int (*tcflush)(int fd, int select);
int (*tcflush_p)(void *ctx, int fd, int select); /*!< tcflush with context pointer */
int (*tcflush)(int fd, int select); /*!< tcflush without context pointer */
};
union {
int (*tcflow_p)(void *ctx, int fd, int action);
int (*tcflow)(int fd, int action);
int (*tcflow_p)(void *ctx, int fd, int action); /*!< tcflow with context pointer */
int (*tcflow)(int fd, int action); /*!< tcflow without context pointer */
};
union {
pid_t (*tcgetsid_p)(void *ctx, int fd);
pid_t (*tcgetsid)(int fd);
pid_t (*tcgetsid_p)(void *ctx, int fd); /*!< tcgetsid with context pointer */
pid_t (*tcgetsid)(int fd); /*!< tcgetsid without context pointer */
};
union {
int (*tcsendbreak_p)(void *ctx, int fd, int duration);
int (*tcsendbreak)(int fd, int duration);
int (*tcsendbreak_p)(void *ctx, int fd, int duration); /*!< tcsendbreak with context pointer */
int (*tcsendbreak)(int fd, int duration); /*!< tcsendbreak without context pointer */
};
#endif // CONFIG_VFS_SUPPORT_TERMIOS

15
docs/build_docs.py
View file

@ -31,9 +31,6 @@ DXG_WARN_LOG = "doxygen-warning-log.txt"
DXG_SANITIZED_LOG = "doxygen-warning-log-sanitized.txt"
DXG_KNOWN_WARNINGS = os.path.join(os.environ["IDF_PATH"], "docs", "doxygen-known-warnings.txt")
SANITIZE_FILENAME_REGEX = re.compile("[^:]*/([^/:]*)(:.*)")
SANITIZE_LINENUM_REGEX = re.compile("([^:]*)(:[0-9]+:)(.*)")
LogMessage = namedtuple("LogMessage", "original_text sanitized_text")
languages = LANGUAGES
@ -238,6 +235,10 @@ def call_build_docs(entry):
return sphinx_call(*entry, buildername="html")
SANITIZE_FILENAME_REGEX = re.compile("[^:]*/([^/:]*)(:.*)")
SANITIZE_LINENUM_REGEX = re.compile("([^:]*)(:[0-9]+:)(.*)")
def sanitize_line(line):
"""
Clear a log message from insignificant parts
@ -273,6 +274,14 @@ def check_docs(language, target, log_file, known_warnings_file, out_sanitized_lo
for known_line in k:
known_messages.append(known_line)
if "doxygen" in known_warnings_file:
# Clean a known Doxygen limitation: it's expected to always document anonymous
# structs/unions but we don't do this in our docs, so filter these all out with a regex
# (this won't match any named field, only anonymous members -
# ie the last part of the field is is just <something>::@NUM not <something>::name)
RE_ANONYMOUS_FIELD = re.compile(r".+:line: warning: parameters of member [^:\s]+(::[^:\s]+)*(::@\d+)+ are not \(all\) documented")
all_messages = [msg for msg in all_messages if not re.match(RE_ANONYMOUS_FIELD, msg.sanitized_text)]
# Collect all new messages that are not match with the known messages.
# The order is an important.
new_messages = list()

16
docs/conf_common.py
View file

@ -21,6 +21,7 @@ import os
import os.path
import re
import subprocess
from idf_extensions.util import download_file_if_missing
# build_docs on the CI server sometimes fails under Python3. This is a workaround:
sys.setrecursionlimit(3500)
@ -132,22 +133,31 @@ def update_exclude_patterns(tags):
'api-guides/esp-ble-mesh/**',
'api-guides/ulp-legacy.rst',
'api-guides/unit-tests-legacy.rst',
'api-guides/ulp_instruction_set.rst',
'api-guides/jtag-debugging/configure-wrover.rst',
'api-reference/system/himem.rst',
'api-reference/bluetooth/**',
'api-reference/peripherals/sdio_slave.rst',
'api-reference/peripherals/esp_slave_protocol.rst',
'api-reference/peripherals/mcpwm.rst',
'api-reference/peripherals/sd_pullup_requirements.rst',
'api-reference/peripherals/sdmmc_host.rst',
'api-reference/protocols/esp_serial_slave_link.rst',
'api-reference/system/ipc.rst',
'get-started-legacy/**',
'gnu-make-legacy.rst',
'hw-reference/esp32/**']:
'hw-reference/esp32/**',
]:
exclude_patterns.append(e)
if "esp32s2" not in tags:
# Exclude ESP32-only document pages so they aren't found in the initial search for .rst files
# note: in toctrees, these also need to be marked with a :esp32: filter
for e in ['hw-reference/esp32s2/**']:
for e in ['hw-reference/esp32s2/**',
'api-guides/ulps2_instruction_set.rst',
'api-reference/peripherals/temp_sensor.rst']:
exclude_patterns.append(e)
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None

1
docs/doxygen-known-warnings.txt
View file

@ -0,0 +1 @@
semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)

4
docs/en/api-guides/fatal-errors.rst
View file

@ -62,7 +62,9 @@ Behavior of panic handler is affected by two other configuration options.
- If :doc:`Core Dump <core_dump>` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis.
- If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
.. only:: esp32
- If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
If this option is enabled, the panic handler code is placed in IRAM. This allows the panic handler to run without needing to re-enable cache first. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash).

2
docs/en/api-guides/freertos-smp.rst
View file

@ -412,7 +412,7 @@ matter.
.. _floating-points:
Floating Point Arithmetic
------------------------
-------------------------
ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words,
the state of a core's FPU registers are not immediately saved when a context

10
docs/en/api-guides/lwip.rst
View file

@ -325,7 +325,15 @@ IP layer features
Limitations
^^^^^^^^^^^
- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay. Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration (as applicable) may also help.
- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay.
.. only::esp32
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration (as applicable) may also help.
.. only::esp32s2
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` project configuration may also help.
Performance Optimization
------------------------

2
docs/en/api-reference/peripherals/adc.rst
View file

@ -85,7 +85,7 @@ Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
The reading may fail due to collision with Wi-Fi, should check it.
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2`
.. only: esp32
.. only:: esp32
Reading the internal hall effect sensor::

6
docs/en/api-reference/peripherals/esp_slave_protocol.rst
View file

@ -6,12 +6,6 @@ Communication with ESP SDIO Slave
ESP SDIO slave initialization
------------------------------
.. only:: esp32s2
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard
SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification

10
docs/en/api-reference/peripherals/index.rst
View file

@ -14,17 +14,17 @@ Peripherals API
I2C <i2c>
I2S <i2s>
LED Control <ledc>
MCPWM <mcpwm>
:esp32: MCPWM <mcpwm>
Pulse Counter <pcnt>
Remote Control <rmt>
SD Pull-up Requirements <sd_pullup_requirements>
SDMMC Host <sdmmc_host>
:esp32: SD Pull-up Requirements <sd_pullup_requirements>
:esp32: SDMMC Host <sdmmc_host>
SD SPI Host <sdspi_host>
SDIO Slave <sdio_slave>
:esp32: SDIO Slave <sdio_slave>
Sigma-delta Modulation <sigmadelta>
SPI Master <spi_master>
SPI Slave <spi_slave>
Temp sensor <temp_sensor>
:esp32s2: Temp sensor <temp_sensor>
Timer <timer>
Touch Sensor <touch_pad>
UART <uart>

8
docs/en/api-reference/peripherals/sdio_slave.rst
View file

@ -4,14 +4,6 @@ SDIO Card Slave Driver
Overview
--------
.. only:: esp32s2
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
.. only:: esp32
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table.
The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run.
This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.

75
docs/en/api-reference/peripherals/sdmmc_host.rst
View file

@ -3,54 +3,47 @@ SDMMC Host Driver
Overview
--------
.. only:: esp32s2
.. note::
ESP32's SDMMC host peripheral has two slots:
{IDF_TARGET_NAME} does not have a SDMMC host peripheral.
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
.. only:: esp32
Pin mappings of these slots are given in the table below.
ESP32's SDMMC host peripheral has two slots:
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
Pin mappings of these slots are given in the table below.
.. warning::
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
.. warning::
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Supported Speed Modes

6
docs/en/api-reference/peripherals/sdspi_host.rst
View file

@ -4,7 +4,11 @@ SD SPI Host Driver
Overview
--------
The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards.
.. only:: esp32
This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
The SD SPI host driver has the following modes:

37
docs/en/api-reference/peripherals/temp_sensor.rst
View file

@ -4,30 +4,23 @@ ESP32-S2 Temperature Sensor
Overview
--------
.. only:: esp32
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
.. note::
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
ESP32 does not have a built-in temperature sensor.
.. only:: esp32s2
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
Application Example
-------------------

85
docs/en/api-reference/storage/sdmmc.rst
View file

@ -16,74 +16,79 @@ SDMMC and SD SPI host drivers (:component:`driver/include/driver/sdmmc_host.h`)
For functions used to initialize and configure:
- SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
- SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>`
.. only:: esp32
- SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
- SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>`
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands.
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands.
The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
Application Example
-------------------
Application Example
-------------------
An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
Protocol layer API
------------------
Protocol layer API
------------------
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
Using API with SD memory cards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with SD memory cards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.
2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver.
1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.
2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver.
Using API with eMMC chips
^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with eMMC chips
^^^^^^^^^^^^^^^^^^^^^^^^^
From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver.
From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver.
To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section.
To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section.
Using API with SDIO cards
^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with SDIO cards
^^^^^^^^^^^^^^^^^^^^^^^^^
Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode.
Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode.
During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card:
During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card:
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register.
2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode.
3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register.
2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode.
3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`.
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
========================================================================= ================================= =================================
Action Read Function Write Function
========================================================================= ================================= =================================
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
========================================================================= ================================= =================================
========================================================================= ================================= =================================
Action Read Function Write Function
========================================================================= ================================= =================================
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
========================================================================= ================================= =================================
SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`.
If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`.
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
.. only:: esp32
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
Combo (memory + IO) cards
^^^^^^^^^^^^^^^^^^^^^^^^^

6
docs/en/api-reference/system/system_time.rst
View file

@ -19,7 +19,7 @@ The settings for the system time source are as follows:
- High-resolution timer
- None
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_ESP32_TIME_SYSCALL` in project configuration.
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_TIME_SYSCALL` in project configuration.
RTC Clock Source
@ -35,7 +35,7 @@ The RTC timer has the following clock sources:
- ``Internal 8.5MHz oscillator, divided by 256 (~33kHz)``. Provides better frequency stability than the ``internal 150kHz RC oscillator`` at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_ESP32_RTC_CLK_SRC` in project configuration.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTC_CLK_SRC` in project configuration.
More details on wiring requirements for the ``External 32kHz crystal`` and ``External 32kHz oscillator at 32K_XP pin`` sources can be found in Section 2.1.4 *Crystal Oscillator* of `Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf#page=10>`_.
@ -130,4 +130,4 @@ Once these steps are completed, call the standard C library function ``localtime
API Reference
-------------
.. include:: /_build/inc/sntp.inc
.. include-build-file:: inc/sntp.inc

6
docs/sphinx-known-warnings.txt
View file

@ -40,6 +40,12 @@ ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t
ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
# This seems like a bug, as the field are ::model_id and ::vnd::model_id
esp_ble_mesh_defs.inc:line: WARNING: Duplicate declaration, uint16_t esp_ble_mesh_model::model_id
#
# Issue present only when building on msys2 / mingw32 START >>>
#

10
docs/zh_CN/api-guides/unit-tests-legacy.rst
View file

@ -92,14 +92,14 @@ GPIO、SPI）需要与其通信的其他设备，因此不能使用常规测试
DUT1（master）终端：
.. code:: bash
.. code::
Waiting for signal: [output high level]!
Please press "Enter" key once any board send this signal.
DUT2（slave）终端：
.. code:: bash
.. code::
Send signal: [output high level]!
@ -183,7 +183,7 @@ DUT2 终端::
当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。
.. code:: bash
.. code::
Here's the test menu, pick your combo:
(1) "esp_ota_begin() verifies arguments" [ota]
@ -230,7 +230,7 @@ DUT2 终端::
一旦选择了多设备测试用例，它会打印一个子菜单：
.. code:: bash
.. code::
Running gpio master/slave test example...
gpio master/slave test example
@ -241,7 +241,7 @@ DUT2 终端::
与多设备测试用例相似，多阶段测试用例也会打印子菜单：
.. code:: bash
.. code::
Running reset reason check for deepsleep...
reset reason check for deepsleep

6
docs/zh_CN/api-guides/unit-tests.rst
View file

@ -175,7 +175,7 @@ DUT2（slave）终端：
当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。
.. code:: bash
.. code::
Here's the test menu, pick your combo:
(1) "esp_ota_begin() verifies arguments" [ota]
@ -222,7 +222,7 @@ DUT2（slave）终端：
一旦选择了多设备测试用例，它会打印一个子菜单：
.. code:: bash
.. code::
Running gpio master/slave test example...
gpio master/slave test example
@ -233,7 +233,7 @@ DUT2（slave）终端：
与多设备测试用例相似，多阶段测试用例也会打印子菜单：
.. code:: bash
.. code::
Running reset reason check for deepsleep...
reset reason check for deepsleep

2
docs/zh_CN/api-reference/network/esp_mesh.rst
View file

@ -332,5 +332,5 @@ ESP-IDF 包含以下 ESP-MESH 示例项目：
API 参考
--------------
.. include:: /_build/inc/esp_mesh.inc
.. include-build-file:: inc/esp_mesh.inc

2
docs/zh_CN/api-reference/network/esp_now.rst
View file

@ -84,5 +84,5 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
API 参考
-------------
.. include:: /_build/inc/esp_now.inc
.. include-build-file:: inc/esp_now.inc

8
docs/zh_CN/api-reference/peripherals/index.rst
View file

@ -13,16 +13,16 @@
I2C <i2c>
I2S <i2s>
LED Control <ledc>
MCPWM <mcpwm>
:esp32: MCPWM <mcpwm>
Pulse Counter <pcnt>
Remote Control <rmt>
SDMMC Host <sdmmc_host>
:esp32: SDMMC Host <sdmmc_host>
SD SPI Host <sdspi_host>
SDIO Slave <sdio_slave>
:esp32: SDIO Slave <sdio_slave>
Sigma-delta Modulation <sigmadelta>
SPI Master <spi_master>
SPI Slave <spi_slave>
Temp sensor <temp_sensor>
:esp32s2: Temp sensor <temp_sensor>
Timer <timer>
Touch Sensor <touch_pad>
UART <uart>

3
docs/zh_CN/api-reference/peripherals/ledc.rst
View file

@ -172,4 +172,5 @@ LED PWM 改变占空比和渐变控制的实例请参照 :example:`peripherals/l
API 参考
-------------
.. include:: /_build/inc/ledc.inc
.. include-build-file:: inc/ledc.inc

3
docs/zh_CN/api-reference/peripherals/touch_pad.rst
View file

@ -156,7 +156,8 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵
API 参考
-------------
.. include-build-file:: inc/touch_pad.inc
.. include-build-file:: inc/touch_sensor.inc
.. include-build-file:: inc/touch_sensor_common.inc
GPIO 宏查找表
^^^^^^^^^^^^^^^^^^

2
docs/zh_CN/api-reference/protocols/index.rst
View file

@ -16,7 +16,7 @@
ESP-MQTT <mqtt>
Modbus slave <modbus>
Local Control <esp_local_ctrl>
ESP Serial Slave Link <esp_serial_slave_link>
:esp32: ESP Serial Slave Link <esp_serial_slave_link>
此 API 部分的示例代码在 ESP-IDF 示例工程的 :example:`protocols` 目录下提供。

8
docs/zh_CN/api-reference/storage/sdmmc.rst
View file

@ -16,7 +16,11 @@ SDMMC 主机驱动和 SD SPI 主机驱动（:component:`driver/include/driver/sd
初始化函数及配置函数：
- 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>`
.. only:: esp32
- 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>`
- 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>`
本文档中所述的 SDMMC 协议层仅处理 SD 协议相关事项，例如卡初始化和数据传输命令。
@ -94,4 +98,4 @@ API 参考
.. include-build-file:: inc/sdmmc_cmd.inc
.. include-build-file:: inc/sdmmc_types.inc
.. include-build-file:: inc/sdmmc_types.inc