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