1 /* 2 * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 #include <stdint.h> 9 #include <stdbool.h> 10 #include "esp_err.h" 11 #include "zephyr_compat.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * @file 19 * init parameters and API 20 */ 21 22 23 /** 24 * @brief Structure holding PHY init parameters 25 */ 26 typedef struct { 27 uint8_t params[128]; /*!< opaque PHY initialization parameters */ 28 } esp_phy_init_data_t; 29 30 /** 31 * @brief PHY enable or disable modem 32 */ 33 typedef enum { 34 PHY_MODEM_WIFI = 1, /*!< PHY modem WIFI */ 35 PHY_MODEM_BT = 2, /*!< PHY modem BT */ 36 PHY_MODEM_IEEE802154 = 4, /*!< PHY modem IEEE802154 */ 37 PHY_MODEM_MAX, /*!< Don't use it. Used by ESP_PHY_MODEM_COUNT_MAX */ 38 } esp_phy_modem_t; 39 40 /** 41 * @brief Opaque PHY calibration data 42 */ 43 typedef struct { 44 uint8_t version[4]; /*!< PHY version */ 45 uint8_t mac[6]; /*!< The MAC address of the station */ 46 uint8_t opaque[1894]; /*!< calibration data */ 47 } esp_phy_calibration_data_t; 48 49 /** 50 * @brief PHY calibration mode 51 * 52 */ 53 typedef enum { 54 PHY_RF_CAL_PARTIAL = 0x00000000, /*!< Do part of RF calibration. This should be used after power-on reset. */ 55 PHY_RF_CAL_NONE = 0x00000001, /*!< Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset. */ 56 PHY_RF_CAL_FULL = 0x00000002 /*!< Do full RF calibration. Produces best results, but also consumes a lot of time and current. Suggested to be used once. */ 57 } esp_phy_calibration_mode_t; 58 59 #if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN 60 /** 61 * @brief PHY init data type 62 */ 63 typedef enum { 64 ESP_PHY_INIT_DATA_TYPE_DEFAULT = 0, 65 ESP_PHY_INIT_DATA_TYPE_SRRC, 66 ESP_PHY_INIT_DATA_TYPE_FCC, 67 ESP_PHY_INIT_DATA_TYPE_CE, 68 ESP_PHY_INIT_DATA_TYPE_NCC, 69 ESP_PHY_INIT_DATA_TYPE_KCC, 70 ESP_PHY_INIT_DATA_TYPE_MIC, 71 ESP_PHY_INIT_DATA_TYPE_IC, 72 ESP_PHY_INIT_DATA_TYPE_ACMA, 73 ESP_PHY_INIT_DATA_TYPE_ANATEL, 74 ESP_PHY_INIT_DATA_TYPE_ISED, 75 ESP_PHY_INIT_DATA_TYPE_WPC, 76 ESP_PHY_INIT_DATA_TYPE_OFCA, 77 ESP_PHY_INIT_DATA_TYPE_IFETEL, 78 ESP_PHY_INIT_DATA_TYPE_RCM, 79 ESP_PHY_INIT_DATA_TYPE_NUMBER, 80 } phy_init_data_type_t; 81 #endif 82 83 /** 84 * @brief Get PHY init data 85 * 86 * If "Use a partition to store PHY init data" option is set in menuconfig, 87 * This function will load PHY init data from a partition. Otherwise, 88 * PHY init data will be compiled into the application itself, and this function 89 * will return a pointer to PHY init data located in read-only memory (DROM). 90 * 91 * If "Use a partition to store PHY init data" option is enabled, this function 92 * may return NULL if the data loaded from flash is not valid. 93 * 94 * @note Call esp_phy_release_init_data to release the pointer obtained using 95 * this function after the call to esp_wifi_init. 96 * 97 * @return pointer to PHY init data structure 98 */ 99 const esp_phy_init_data_t* esp_phy_get_init_data(void); 100 101 /** 102 * @brief Release PHY init data 103 * @param data pointer to PHY init data structure obtained from 104 * esp_phy_get_init_data function 105 */ 106 void esp_phy_release_init_data(const esp_phy_init_data_t* data); 107 108 /** 109 * @brief Function called by esp_phy_load_cal_and_init to load PHY calibration data 110 * 111 * This is a convenience function which can be used to load PHY calibration 112 * data from NVS. Data can be stored to NVS using esp_phy_store_cal_data_to_nvs 113 * function. 114 * 115 * If calibration data is not present in the NVS, or 116 * data is not valid (was obtained for a chip with a different MAC address, 117 * or obtained for a different version of software), this function will 118 * return an error. 119 * 120 * @param out_cal_data pointer to calibration data structure to be filled with 121 * loaded data. 122 * @return ESP_OK on success 123 */ 124 esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t* out_cal_data); 125 126 /** 127 * @brief Function called by esp_phy_load_cal_and_init to store PHY calibration data 128 * 129 * This is a convenience function which can be used to store PHY calibration 130 * data to the NVS. Calibration data is returned by esp_phy_load_cal_and_init function. 131 * Data saved using this function to the NVS can later be loaded using 132 * esp_phy_store_cal_data_to_nvs function. 133 * 134 * @param cal_data pointer to calibration data which has to be saved. 135 * @return ESP_OK on success 136 */ 137 esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t* cal_data); 138 139 /** 140 * @brief Erase PHY calibration data which is stored in the NVS 141 * 142 * This is a function which can be used to trigger full calibration as a last-resort remedy 143 * if partial calibration is used. It can be called in the application based on some conditions 144 * (e.g. an option provided in some diagnostic mode). 145 * 146 * @return ESP_OK on success 147 * @return others on fail. Please refer to NVS API return value error number. 148 */ 149 esp_err_t esp_phy_erase_cal_data_in_nvs(void); 150 151 /** 152 * @brief Enable PHY and RF module 153 * 154 * PHY and RF module should be enabled in order to use WiFi or BT. 155 * Now PHY and RF enabling job is done automatically when start WiFi or BT. Users should not 156 * call this API in their application. 157 * 158 * @param modem the modem to call the phy enable. 159 */ 160 void esp_phy_enable(esp_phy_modem_t modem); 161 162 /** 163 * @brief Disable PHY and RF module 164 * 165 * PHY module should be disabled in order to shutdown WiFi or BT. 166 * Now PHY and RF disabling job is done automatically when stop WiFi or BT. Users should not 167 * call this API in their application. 168 * 169 * @param modem the modem to call the phy disable. 170 */ 171 void esp_phy_disable(esp_phy_modem_t modem); 172 173 /** 174 * @brief Enable BTBB module 175 * 176 * BTBB module should be enabled in order to use IEEE802154 or BT. 177 * Now BTBB enabling job is done automatically when start IEEE802154 or BT. Users should not 178 * call this API in their application. 179 * 180 */ 181 void esp_btbb_enable(void); 182 183 /** 184 * @brief Disable BTBB module 185 * 186 * Dsiable BTBB module, used by IEEE802154 or Bluetooth. 187 * Users should not call this API in their application. 188 * 189 */ 190 void esp_btbb_disable(void); 191 192 /** 193 * @brief Load calibration data from NVS and initialize PHY and RF module 194 */ 195 void esp_phy_load_cal_and_init(void); 196 197 /** 198 * @brief Initialize backup memory for Phy power up/down 199 */ 200 void esp_phy_modem_init(void); 201 202 /** 203 * @brief Deinitialize backup memory for Phy power up/down 204 * Set phy_init_flag if all modems deinit on ESP32C3 205 */ 206 void esp_phy_modem_deinit(void); 207 208 #if CONFIG_MAC_BB_PD 209 /** 210 * @brief Initialize backup memory for MAC and Baseband power up/down 211 */ 212 void esp_mac_bb_pd_mem_init(void); 213 214 /** 215 * @brief Deinitialize backup memory for MAC and Baseband power up/down 216 */ 217 void esp_mac_bb_pd_mem_deinit(void); 218 219 /** 220 * @brief Power up MAC and Baseband 221 */ 222 void esp_mac_bb_power_up(void); 223 224 /** 225 * @brief Power down MAC and Baseband 226 */ 227 void esp_mac_bb_power_down(void); 228 #endif 229 230 /** 231 * @brief Enable WiFi/BT common clock 232 * 233 */ 234 void esp_phy_common_clock_enable(void); 235 236 /** 237 * @brief Disable WiFi/BT common clock 238 * 239 */ 240 void esp_phy_common_clock_disable(void); 241 242 /** 243 * @brief Get the time stamp when PHY/RF was switched on 244 * @return return 0 if PHY/RF is never switched on. Otherwise return time in 245 * microsecond since boot when phy/rf was last switched on 246 */ 247 int64_t esp_phy_rf_get_on_ts(void); 248 249 /** 250 * @brief Update the corresponding PHY init type according to the country code of Wi-Fi. 251 * 252 * @param country country code 253 * @return ESP_OK on success. 254 * @return esp_err_t code describing the error on fail 255 */ 256 esp_err_t esp_phy_update_country_info(const char *country); 257 258 259 #if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN 260 /** 261 * @brief Apply PHY init bin to PHY 262 * @return ESP_OK on success. 263 * @return ESP_FAIL on fail. 264 */ 265 esp_err_t esp_phy_apply_phy_init_data(uint8_t *init_data); 266 #endif 267 268 /** 269 * @brief Get PHY lib version 270 * @return PHY lib version. 271 */ 272 char * get_phy_version_str(void); 273 274 /** 275 * @brief Set PHY init parameters 276 * @param param is 1 means combo module 277 */ 278 void phy_init_param_set(uint8_t param); 279 280 /** 281 * @brief Wi-Fi RX enable 282 * @param enable True for enable wifi receiving mode as default, false for closing wifi receiving mode as default. 283 */ 284 void phy_wifi_enable_set(uint8_t enable); 285 286 #if CONFIG_ESP_PHY_RECORD_USED_TIME 287 /** 288 * @brief Get phy used time from different modem 289 * @param used_time pointer of variable to get used time, in microseconds 290 * @param modem modem type 291 * @return ESP_ERR_INVALID_ARG on incorrect modem type. 292 */ 293 esp_err_t phy_query_used_time(uint64_t *used_time, esp_phy_modem_t modem); 294 295 /** 296 * @brief Clear phy used time for different modem 297 * @param modem modem type 298 * @return ESP_ERR_INVALID_ARG on incorrect modem type. 299 */ 300 esp_err_t phy_clear_used_time(esp_phy_modem_t modem); 301 #endif 302 303 #ifdef __cplusplus 304 } 305 #endif 306
