phy_init: reduce the amount of hardwired logic, add coexist init

components/esp32/include/esp_phy_init.h

@@ -20,6 +20,14 @@
 extern "C" {
 #endif
 
+/**
+ * @file PHY init parameters and API
+ */
+
+
+/**
+ * @brief Structure holding PHY init parameters
+ */
 typedef struct {
 	uint8_t param_ver_id;                   /*!< init_data structure version */
 	uint8_t crystal_select;                 /*!< 0: 40MHz, 1: 26 MHz, 2: 24 MHz, 3: auto */
@@ -129,8 +137,11 @@ typedef struct {
 	uint8_t reserved[23];                   /*!< reserved for future expansion */
 } esp_phy_init_data_t;
 
+/**
+ * @brief Opaque PHY calibration data
+ */
 typedef struct {
-    uint8_t opaque[1904];                   /*!< opaque calibration data */
+    uint8_t opaque[1904];                   /*!< calibration data */
 } esp_phy_calibration_data_t;
 
 typedef enum {
@@ -140,29 +151,97 @@ typedef enum {
 } esp_phy_calibration_mode_t;
 
 /**
+ * @brief Get PHY init data
  *
- * @param mode
- * @return
+ * If "Use a partition to store PHY init data" option is set in menuconfig,
+ * This function will load PHY init data from a partition. Otherwise,
+ * PHY init data will be compiled into the application itself, and this function
+ * will return a pointer to PHY init data located in read-only memory (DROM).
+ *
+ * If "Use a partition to store PHY init data" option is enabled, this function
+ * may return NULL if the data loaded from flash is not valid.
+ *
+ * @note Call esp_phy_release_init_data to release the pointer obtained using
+ * this function after the call to esp_wifi_init.
+ *
+ * @return pointer to PHY init data structure
  */
-esp_err_t esp_phy_init(esp_phy_calibration_mode_t mode);
-
-#ifndef CONFIG_ESP32_STORE_PHY_CALIBRATION_DATA_IN_NVS
+const esp_phy_init_data_t* esp_phy_get_init_data();
 
 /**
- *
- * @param cal_data
- * @return
+ * @brief Release PHY init data
+ * @param data  pointer to PHY init data structure obtained from
+ *              esp_phy_get_init_data function
  */
-esp_err_t esp_phy_store_cal_data(const esp_phy_calibration_data_t* cal_data);
+void esp_phy_release_init_data(const esp_phy_init_data_t* data);
 
 /**
+ * @brief Function called by esp_phy_init to load PHY calibration data
  *
- * @param out_cal_data
- * @return
+ * This is a convenience function which can be used to load PHY calibration
+ * data from NVS. Data can be stored to NVS using esp_phy_store_cal_data_to_nvs
+ * function.
+ *
+ * If calibration data is not present in the NVS, or
+ * data is not valid (was obtained for a chip with a different MAC address,
+ * or obtained for a different version of software), this function will
+ * return an error.
+ *
+ * If "Initialize PHY in startup code" option is set in menuconfig, this
+ * function will be used to load calibration data. To provide a different
+ * mechanism for loading calibration data, disable
+ * "Initialize PHY in startup code" option in menuconfig and call esp_phy_init
+ * function from the application. For an example usage of esp_phy_init and
+ * this function, see do_phy_init function in cpu_start.c
+ *
+ * @param out_cal_data pointer to calibration data structure to be filled with
+ *                     loaded data.
+ * @return ESP_OK on success
  */
-esp_err_t esp_phy_load_cal_data(esp_phy_calibration_data_t* out_cal_data);
+esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t* out_cal_data);
+
+/**
+ * @brief Function called by esp_phy_init to store PHY calibration data
+ *
+ * This is a convenience function which can be used to store PHY calibration
+ * data to the NVS. Calibration data is returned by esp_phy_init function.
+ * Data saved using this function to the NVS can later be loaded using
+ * esp_phy_store_cal_data_to_nvs function.
+ *
+ * If "Initialize PHY in startup code" option is set in menuconfig, this
+ * function will be used to store calibration data. To provide a different
+ * mechanism for storing calibration data, disable
+ * "Initialize PHY in startup code" option in menuconfig and call esp_phy_init
+ * function from the application.
+ *
+ * @param cal_data pointer to calibration data which has to be saved.
+ * @return ESP_OK on success
+ */
+esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t* cal_data);
+
+/**
+ * @brief Initialize PHY module
+ *
+ * PHY module should be initialized in order to use WiFi or BT.
+ * If "Initialize PHY in startup code" option is set in menuconfig,
+ * this function will be called automatically before app_main is called,
+ * using parameters obtained from esp_phy_get_init_data.
+ *
+ * Applications which don't need to enable PHY on every start up should
+ * disable this menuconfig option and call esp_phy_init before calling
+ * esp_wifi_init or bt_controller_init. See do_phy_init function in
+ * cpu_start.c for an example of using this function.
+ *
+ * @param init_data  PHY parameters. Default set of parameters can
+ *                   be obtained by calling esp_phy_get_default_init_data
+ *                   function.
+ * @param mode  Calibration mode (Full, partial, or no calibration)
+ * @param[inout] calibration_data
+ * @return ESP_OK on success.
+ */
+esp_err_t esp_phy_init(const esp_phy_init_data_t* init_data,
+        esp_phy_calibration_mode_t mode, esp_phy_calibration_data_t* calibration_data);
 
-#endif // CONFIG_ESP32_STORE_PHY_CALIBRATION_DATA_IN_NVS
 
 #ifdef __cplusplus
 }