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