diff --git a/components/app_update/include/esp_ota_ops.h b/components/app_update/include/esp_ota_ops.h index ba07c013d9..ece5275db3 100644 --- a/components/app_update/include/esp_ota_ops.h +++ b/components/app_update/include/esp_ota_ops.h @@ -327,9 +327,9 @@ typedef enum { /** * @brief Revokes the old signature digest. To be called in the application after the rollback logic. * - * Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1). - * When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N. - * After successfully booting the OTA app should call this function to revoke Key #N-1. + * Relevant for Secure boot v2 on ESP32-S2, ESP32-S3, ESP32-C3 where upto 3 key digests can be stored (Key \#N-1, Key \#N, Key \#N+1). + * When key \#N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key \#N-1 & Key \#N. + * After successfully booting the OTA app should call this function to revoke Key \#N-1. * * @param index - The index of the signature block to be revoked * diff --git a/components/esp_eth/include/esp_eth_mac.h b/components/esp_eth/include/esp_eth_mac.h index db462728a1..be23792d2d 100644 --- a/components/esp_eth/include/esp_eth_mac.h +++ b/components/esp_eth/include/esp_eth_mac.h @@ -411,7 +411,7 @@ typedef struct { /** * @brief Create ESP32 Ethernet MAC instance * -* @param config: Ethernet MAC configuration +* @param config: Ethernet MAC configuration * * @return * - instance: create MAC instance successfully diff --git a/components/esp_https_server/include/esp_https_server.h b/components/esp_https_server/include/esp_https_server.h index efe726e9e7..75720bd1ce 100644 --- a/components/esp_https_server/include/esp_https_server.h +++ b/components/esp_https_server/include/esp_https_server.h @@ -25,7 +25,7 @@ typedef enum { * @brief Callback data struct, contains the ESP-TLS connection handle */ typedef struct esp_https_server_user_cb_arg { - const esp_tls_t *tls; + const esp_tls_t *tls; /*!< ESP-TLS connection handle */ } esp_https_server_user_cb_arg_t; /** diff --git a/components/esp_hw_support/include/esp_mac.h b/components/esp_hw_support/include/esp_mac.h index f0efddfc2f..e700b72ffe 100644 --- a/components/esp_hw_support/include/esp_mac.h +++ b/components/esp_hw_support/include/esp_mac.h @@ -139,7 +139,7 @@ esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type); * address, then the first octet is XORed with 0x4 in order to create a different * locally administered MAC address. * - * @param mac base MAC address, length: 6 bytes/8 bytes. + * @param local_mac base MAC address, length: 6 bytes/8 bytes. * length: 6 bytes for MAC-48 * 8 bytes for EUI-64(used for IEEE 802.15.4) * @param universal_mac Source universal MAC address, length: 6 bytes. diff --git a/components/esp_lcd/include/esp_lcd_panel_io.h b/components/esp_lcd/include/esp_lcd_panel_io.h index 7b99bde3f1..57f27ac96a 100644 --- a/components/esp_lcd/include/esp_lcd_panel_io.h +++ b/components/esp_lcd/include/esp_lcd_panel_io.h @@ -134,6 +134,10 @@ typedef struct { */ esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io); +/** + * @brief Panel IO configuration structure, for I2C interface + * + */ typedef struct { uint32_t dev_addr; /*!< I2C device address */ esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done; /*!< Callback invoked when color data transfer has finished */ @@ -145,7 +149,7 @@ typedef struct { struct { unsigned int dc_low_on_data: 1; /*!< If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa */ unsigned int disable_control_phase: 1; /*!< If this flag is enabled, the control phase isn't used */ - } flags; + } flags; /*!< Extra flags to fine-tune the I2C device */ } esp_lcd_panel_io_i2c_config_t; /** @@ -223,7 +227,7 @@ typedef struct { unsigned int swap_color_bytes: 1; /*!< Swap adjacent two color bytes */ unsigned int pclk_active_neg: 1; /*!< The display will write data lines when there's a falling edge on WR signal (a.k.a the PCLK) */ unsigned int pclk_idle_low: 1; /*!< The WR signal (a.k.a the PCLK) stays at low level in IDLE phase */ - } flags; + } flags; /*!< Panel IO config flags */ } esp_lcd_panel_io_i80_config_t; /** diff --git a/components/esp_lcd/include/esp_lcd_panel_rgb.h b/components/esp_lcd/include/esp_lcd_panel_rgb.h index 95dfb6ba4f..f821a75883 100644 --- a/components/esp_lcd/include/esp_lcd_panel_rgb.h +++ b/components/esp_lcd/include/esp_lcd_panel_rgb.h @@ -66,7 +66,7 @@ typedef struct { unsigned int de_idle_high: 1; /*!< The de signal is high in IDLE state */ unsigned int pclk_active_neg: 1; /*!< Whether the display data is clocked out at the falling edge of PCLK */ unsigned int pclk_idle_high: 1; /*!< The PCLK stays at high level in IDLE phase */ - } flags; + } flags; /*!< LCD RGB timing flags */ } esp_lcd_rgb_timing_t; /** @@ -106,7 +106,7 @@ typedef struct { unsigned int disp_active_low: 1; /*!< If this flag is enabled, a low level of display control signal can turn the screen on; vice versa */ unsigned int relax_on_idle: 1; /*!< If this flag is enabled, the host won't refresh the LCD if nothing changed in host's frame buffer (this is usefull for LCD with built-in GRAM) */ unsigned int fb_in_psram: 1; /*!< If this flag is enabled, the frame buffer will be allocated from PSRAM preferentially */ - } flags; + } flags; /*!< LCD RGB panel configuration flags */ } esp_lcd_rgb_panel_config_t; /** diff --git a/components/esp_lcd/include/esp_lcd_panel_vendor.h b/components/esp_lcd/include/esp_lcd_panel_vendor.h index dde8be68d3..2503adeb7e 100644 --- a/components/esp_lcd/include/esp_lcd_panel_vendor.h +++ b/components/esp_lcd/include/esp_lcd_panel_vendor.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -22,8 +22,8 @@ typedef struct { unsigned int bits_per_pixel; /*!< Color depth, in bpp */ struct { unsigned int reset_active_high: 1; /*!< Setting this if the panel reset is high level active */ - } flags; - void *vendor_config; /* vendor specific configuration, optional, left as NULL if not used */ + } flags; /*!< LCD panel config flags */ + void *vendor_config; /*!< vendor specific configuration, optional, left as NULL if not used */ } esp_lcd_panel_dev_config_t; /** diff --git a/components/esp_netif/include/esp_netif_ip_addr.h b/components/esp_netif/include/esp_netif_ip_addr.h index 25b877d359..57f10999b3 100644 --- a/components/esp_netif/include/esp_netif_ip_addr.h +++ b/components/esp_netif/include/esp_netif_ip_addr.h @@ -81,25 +81,37 @@ extern "C" { #define ESP_IP4ADDR_INIT(a, b, c, d) { .type = ESP_IPADDR_TYPE_V4, .u_addr = { .ip4 = { .addr = ESP_IP4TOADDR(a, b, c, d) }}}; #define ESP_IP6ADDR_INIT(a, b, c, d) { .type = ESP_IPADDR_TYPE_V6, .u_addr = { .ip6 = { .addr = { a, b, c, d }, .zone = 0 }}}; +/** + * @brief IPv6 address + * + */ struct esp_ip6_addr { - uint32_t addr[4]; - uint8_t zone; + uint32_t addr[4]; /*!< IPv6 address */ + uint8_t zone; /*!< zone ID */ }; +/** + * @brief IPv4 address + * + */ struct esp_ip4_addr { - uint32_t addr; + uint32_t addr; /*!< IPv4 address */ }; typedef struct esp_ip4_addr esp_ip4_addr_t; typedef struct esp_ip6_addr esp_ip6_addr_t; +/** + * @brief IP address + * + */ typedef struct _ip_addr { union { - esp_ip6_addr_t ip6; - esp_ip4_addr_t ip4; - } u_addr; - uint8_t type; + esp_ip6_addr_t ip6; /*!< IPv6 address type */ + esp_ip4_addr_t ip4; /*!< IPv4 address type */ + } u_addr; /*!< IP address union */ + uint8_t type; /*!< ipaddress type */ } esp_ip_addr_t; typedef enum { diff --git a/components/esp_netif/include/esp_netif_types.h b/components/esp_netif/include/esp_netif_types.h index cc7a37b9c4..ee6b92a3b2 100644 --- a/components/esp_netif/include/esp_netif_types.h +++ b/components/esp_netif/include/esp_netif_types.h @@ -112,6 +112,11 @@ typedef struct { esp_ip6_addr_t ip; /**< Interface IPV6 address */ } esp_netif_ip6_info_t; + +/** + * @brief Event structure for IP_EVENT_GOT_IP event + * + */ typedef struct { int if_index; /*!< Interface index for which the event is received (left for legacy compilation) */ esp_netif_t *esp_netif; /*!< Pointer to corresponding esp-netif object */ @@ -164,6 +169,10 @@ typedef enum esp_netif_ip_event_type { // 3) network stack specific config (esp_netif_net_stack_ifconfig_t) -- no publicly available // +/** + * @brief ESP-netif inherent config parameters + * + */ typedef struct esp_netif_inherent_config { esp_netif_flags_t flags; /*!< flags that define esp-netif behavior */ uint8_t mac[6]; /*!< initial mac address for this interface */ @@ -185,19 +194,23 @@ typedef struct esp_netif_config esp_netif_config_t; */ typedef void * esp_netif_iodriver_handle; +/** + * @brief ESP-netif driver base handle + * + */ typedef struct esp_netif_driver_base_s { - esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); - esp_netif_t *netif; + esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); /*!< post attach function pointer */ + esp_netif_t *netif; /*!< netif handle */ } esp_netif_driver_base_t; /** * @brief Specific IO driver configuration */ struct esp_netif_driver_ifconfig { - esp_netif_iodriver_handle handle; - esp_err_t (*transmit)(void *h, void *buffer, size_t len); - esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer); - void (*driver_free_rx_buffer)(void *h, void* buffer); + esp_netif_iodriver_handle handle; /*!< io-driver handle */ + esp_err_t (*transmit)(void *h, void *buffer, size_t len); /*!< transmit function pointer */ + esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer); /*!< transmit wrap function pointer */ + void (*driver_free_rx_buffer)(void *h, void* buffer); /*!< free rx buffer function pointer */ }; typedef struct esp_netif_driver_ifconfig esp_netif_driver_ifconfig_t; @@ -212,9 +225,9 @@ typedef struct esp_netif_netstack_config esp_netif_netstack_config_t; * @brief Generic esp_netif configuration */ struct esp_netif_config { - const esp_netif_inherent_config_t *base; - const esp_netif_driver_ifconfig_t *driver; - const esp_netif_netstack_config_t *stack; + const esp_netif_inherent_config_t *base; /*!< base config */ + const esp_netif_driver_ifconfig_t *driver; /*!< driver config */ + const esp_netif_netstack_config_t *stack; /*!< stack config */ }; /** diff --git a/components/esp_phy/include/esp_phy_init.h b/components/esp_phy/include/esp_phy_init.h index ec68213950..efefd114d4 100644 --- a/components/esp_phy/include/esp_phy_init.h +++ b/components/esp_phy/include/esp_phy_init.h @@ -14,7 +14,8 @@ extern "C" { #endif /** - * @file PHY init parameters and API + * @file + * init parameters and API */ @@ -34,6 +35,10 @@ typedef struct { uint8_t opaque[1894]; /*!< calibration data */ } esp_phy_calibration_data_t; +/** + * @brief PHY calibration mode + * + */ typedef enum { PHY_RF_CAL_PARTIAL = 0x00000000, /*!< Do part of RF calibration. This should be used after power-on reset. */ PHY_RF_CAL_NONE = 0x00000001, /*!< Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset. */ @@ -223,6 +228,10 @@ int64_t esp_phy_rf_get_on_ts(void); /** * @brief Update the corresponding PHY init type according to the country code of Wi-Fi. + * + * @param country country code + * @return ESP_OK on success. + * @return esp_err_t code describing the error on fail */ esp_err_t esp_phy_update_country_info(const char *country); diff --git a/components/freertos/include/freertos/queue.h b/components/freertos/include/freertos/queue.h index 05ca7de454..5070b76e79 100644 --- a/components/freertos/include/freertos/queue.h +++ b/components/freertos/include/freertos/queue.h @@ -1398,9 +1398,6 @@ BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION; BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; -/**@}*/ -/** @endcond */ - /** * @cond !DOC_EXCLUDE_HEADER_SECTION * queue. h diff --git a/components/freertos/include/freertos/task.h b/components/freertos/include/freertos/task.h index 125a924d06..88b2730933 100644 --- a/components/freertos/include/freertos/task.h +++ b/components/freertos/include/freertos/task.h @@ -392,7 +392,7 @@ typedef enum * example, to create a privileged task at priority 2 the uxPriority parameter * should be set to ( 2 | portPRIVILEGE_BIT ). * - * @param pvCreatedTask Used to pass back a handle by which the created task + * @param pxCreatedTask Used to pass back a handle by which the created task * can be referenced. * * @return pdPASS if the task was successfully created and added to a ready @@ -538,7 +538,7 @@ typedef enum * * @param uxPriority The priority at which the task will run. * - * @param pxStackBuffer Must point to a StackType_t array that has at least + * @param puxStackBuffer Must point to a StackType_t array that has at least * ulStackDepth indexes - the array will then be used as the task's stack, * removing the need for the stack to be allocated dynamically. * @@ -2368,7 +2368,7 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION; * notification value at that index being updated. ulValue is not used and * xTaskNotifyIndexed() always returns pdPASS in this case. * - * pulPreviousNotificationValue - + * @param pulPreviousNotificationValue - * Can be used to pass out the subject task's notification value before any * bits are modified by the notify function. * @@ -2532,6 +2532,10 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, * requested from an ISR is dependent on the port - see the documentation page * for the port in use. * + * @param pulPreviousNotificationValue - + * Can be used to pass out the subject task's notification value before any + * bits are modified by the notify function. + * * @return Dependent on the value of eAction. See the description of the * eAction parameter. * @@ -2778,11 +2782,10 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, * @endcond * \ingroup TaskNotifications */ -#define xTaskNotifyGive( xTaskToNotify ) \ - xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL ) - +#define xTaskNotifyGive( xTaskToNotify ) \ + xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) /** * @cond !DOC_EXCLUDE_HEADER_SECTION * task. h diff --git a/components/hal/include/hal/adc_types.h b/components/hal/include/hal/adc_types.h index f5efb1d427..dc07531e0b 100644 --- a/components/hal/include/hal/adc_types.h +++ b/components/hal/include/hal/adc_types.h @@ -121,7 +121,7 @@ typedef struct { struct { uint16_t data: 12; /*!