1 /* 2 * SPDX-FileCopyrightText: 2015-2021 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 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** 17 * @file PHY init parameters and API 18 */ 19 20 21 /** 22 * @brief Structure holding PHY init parameters 23 */ 24 typedef struct { 25 uint8_t params[128]; /*!< opaque PHY initialization parameters */ 26 } esp_phy_init_data_t; 27 28 /** 29 * @brief Opaque PHY calibration data 30 */ 31 typedef struct { 32 uint8_t version[4]; /*!< PHY version */ 33 uint8_t mac[6]; /*!< The MAC address of the station */ 34 uint8_t opaque[1894]; /*!< calibration data */ 35 } esp_phy_calibration_data_t; 36 37 typedef enum { 38 PHY_RF_CAL_PARTIAL = 0x00000000, /*!< Do part of RF calibration. This should be used after power-on reset. */ 39 PHY_RF_CAL_NONE = 0x00000001, /*!< Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset. */ 40 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. */ 41 } esp_phy_calibration_mode_t; 42 43 #if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN 44 /** 45 * @brief PHY init data type 46 */ 47 typedef enum { 48 ESP_PHY_INIT_DATA_TYPE_DEFAULT = 0, 49 ESP_PHY_INIT_DATA_TYPE_SRRC, 50 ESP_PHY_INIT_DATA_TYPE_FCC, 51 ESP_PHY_INIT_DATA_TYPE_CE, 52 ESP_PHY_INIT_DATA_TYPE_NCC, 53 ESP_PHY_INIT_DATA_TYPE_KCC, 54 ESP_PHY_INIT_DATA_TYPE_MIC, 55 ESP_PHY_INIT_DATA_TYPE_IC, 56 ESP_PHY_INIT_DATA_TYPE_ACMA, 57 ESP_PHY_INIT_DATA_TYPE_ANATEL, 58 ESP_PHY_INIT_DATA_TYPE_ISED, 59 ESP_PHY_INIT_DATA_TYPE_WPC, 60 ESP_PHY_INIT_DATA_TYPE_OFCA, 61 ESP_PHY_INIT_DATA_TYPE_IFETEL, 62 ESP_PHY_INIT_DATA_TYPE_RCM, 63 ESP_PHY_INIT_DATA_TYPE_NUMBER, 64 } phy_init_data_type_t; 65 #endif 66 67 /** 68 * @brief Get PHY init data 69 * 70 * If "Use a partition to store PHY init data" option is set in menuconfig, 71 * This function will load PHY init data from a partition. Otherwise, 72 * PHY init data will be compiled into the application itself, and this function 73 * will return a pointer to PHY init data located in read-only memory (DROM). 74 * 75 * If "Use a partition to store PHY init data" option is enabled, this function 76 * may return NULL if the data loaded from flash is not valid. 77 * 78 * @note Call esp_phy_release_init_data to release the pointer obtained using 79 * this function after the call to esp_wifi_init. 80 * 81 * @return pointer to PHY init data structure 82 */ 83 const esp_phy_init_data_t* esp_phy_get_init_data(void); 84 85 /** 86 * @brief Release PHY init data 87 * @param data pointer to PHY init data structure obtained from 88 * esp_phy_get_init_data function 89 */ 90 void esp_phy_release_init_data(const esp_phy_init_data_t* data); 91 92 /** 93 * @brief Function called by esp_phy_init to load PHY calibration data 94 * 95 * This is a convenience function which can be used to load PHY calibration 96 * data from NVS. Data can be stored to NVS using esp_phy_store_cal_data_to_nvs 97 * function. 98 * 99 * If calibration data is not present in the NVS, or 100 * data is not valid (was obtained for a chip with a different MAC address, 101 * or obtained for a different version of software), this function will 102 * return an error. 103 * 104 * If "Initialize PHY in startup code" option is set in menuconfig, this 105 * function will be used to load calibration data. To provide a different 106 * mechanism for loading calibration data, disable 107 * "Initialize PHY in startup code" option in menuconfig and call esp_phy_init 108 * function from the application. For an example usage of esp_phy_init and 109 * this function, see esp_phy_store_cal_data_to_nvs function in cpu_start.c 110 * 111 * @param out_cal_data pointer to calibration data structure to be filled with 112 * loaded data. 113 * @return ESP_OK on success 114 */ 115 esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t* out_cal_data); 116 117 /** 118 * @brief Function called by esp_phy_init to store PHY calibration data 119 * 120 * This is a convenience function which can be used to store PHY calibration 121 * data to the NVS. Calibration data is returned by esp_phy_init function. 122 * Data saved using this function to the NVS can later be loaded using 123 * esp_phy_store_cal_data_to_nvs function. 124 * 125 * If "Initialize PHY in startup code" option is set in menuconfig, this 126 * function will be used to store calibration data. To provide a different 127 * mechanism for storing calibration data, disable 128 * "Initialize PHY in startup code" option in menuconfig and call esp_phy_init 129 * function from the application. 130 * 131 * @param cal_data pointer to calibration data which has to be saved. 132 * @return ESP_OK on success 133 */ 134 esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t* cal_data); 135 136 /** 137 * @brief Erase PHY calibration data which is stored in the NVS 138 * 139 * This is a function which can be used to trigger full calibration as a last-resort remedy 140 * if partial calibration is used. It can be called in the application based on some conditions 141 * (e.g. an option provided in some diagnostic mode). 142 * 143 * @return ESP_OK on success 144 * @return others on fail. Please refer to NVS API return value error number. 145 */ 146 esp_err_t esp_phy_erase_cal_data_in_nvs(void); 147 148 /** 149 * @brief Enable PHY and RF module 150 * 151 * PHY and RF module should be enabled in order to use WiFi or BT. 152 * Now PHY and RF enabling job is done automatically when start WiFi or BT. Users should not 153 * call this API in their application. 154 * 155 */ 156 void esp_phy_enable(void); 157 158 /** 159 * @brief Disable PHY and RF module 160 * 161 * PHY module should be disabled in order to shutdown WiFi or BT. 162 * Now PHY and RF disabling job is done automatically when stop WiFi or BT. Users should not 163 * call this API in their application. 164 * 165 */ 166 void esp_phy_disable(void); 167 168 /** 169 * @brief Load calibration data from NVS and initialize PHY and RF module 170 */ 171 void esp_phy_load_cal_and_init(void); 172 173 #if CONFIG_MAC_BB_PD 174 /** 175 * @brief Initialize backup memory for MAC and Baseband power up/down 176 */ 177 void esp_mac_bb_pd_mem_init(void); 178 179 /** 180 * @brief Power up MAC and Baseband 181 */ 182 void esp_mac_bb_power_up(void); 183 184 /** 185 * @brief Power down MAC and Baseband 186 */ 187 void esp_mac_bb_power_down(void); 188 #endif 189 190 /** 191 * @brief Enable WiFi/BT common clock 192 * 193 */ 194 void esp_phy_common_clock_enable(void); 195 196 /** 197 * @brief Disable WiFi/BT common clock 198 * 199 */ 200 void esp_phy_common_clock_disable(void); 201 202 /** 203 * @brief Get the time stamp when PHY/RF was switched on 204 * @return return 0 if PHY/RF is never switched on. Otherwise return time in 205 * microsecond since boot when phy/rf was last switched on 206 */ 207 int64_t esp_phy_rf_get_on_ts(void); 208 209 /** 210 * @brief Update the corresponding PHY init type according to the country code of Wi-Fi. 211 */ 212 esp_err_t esp_phy_update_country_info(const char *country); 213 214 215 #if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN 216 /** 217 * @brief Apply PHY init bin to PHY 218 * @return ESP_OK on success. 219 * @return ESP_FAIL on fail. 220 */ 221 esp_err_t esp_phy_apply_phy_init_data(uint8_t *init_data); 222 #endif 223 224 /** 225 * @brief Get PHY lib version 226 * @return PHY lib version. 227 */ 228 char * get_phy_version_str(void); 229 230 #ifdef __cplusplus 231 } 232 #endif 233
