apll: add lock for apll

components/esp_hw_support/include/soc/clk_ctrl_os.h

@@ -5,6 +5,7 @@
  */
 
 #include "soc/rtc.h"
+#include "esp_err.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -37,6 +38,39 @@ void periph_rtc_dig_clk8m_disable(void);
  */
 uint32_t periph_rtc_dig_clk8m_get_freq(void);
 
+#if SOC_CLK_APLL_SUPPORTED
+/**
+ * @brief Enable APLL power if it has not enabled
+ */
+void periph_rtc_apll_acquire(void);
+
+/**
+ * @brief Shut down APLL power if no peripherals using APLL
+ */
+void periph_rtc_apll_release(void);
+
+/**
+ * @brief Calculate and set APLL coefficients by given frequency
+ * @note  Have to call 'periph_rtc_apll_acquire' to enable APLL power before setting frequency
+ * @note  This calculation is based on the inequality:
+ *        xtal_freq * (4 + sdm2 + sdm1/256 + sdm0/65536) >= SOC_APLL_MULTIPLIER_OUT_MIN_HZ(350 MHz)
+ *        It will always calculate the minimum coefficients that can satisfy the inequality above, instead of loop them one by one.
+ *        which means more appropriate coefficients are likely to exist.
+ *        But this algorithm can meet almost all the cases and the accuracy can be guaranteed as well.
+ * @note  The APLL frequency is only allowed to set when there is only one peripheral refer to it.
+ *        If APLL is already set by another peripheral, this function will return `ESP_ERR_INVALID_STATE`
+ *        and output the current frequency by parameter `real_freq`.
+ *
+ * @param expt_freq Expected APLL frequency (unit: Hz)
+ * @param real_freq APLL real working frequency [output] (unit: Hz)
+ * @return
+ *      - ESP_OK: APLL frequency set success
+ *      - ESP_ERR_INVALID_ARG: The input expt_freq is out of APLL support range
+ *      - ESP_ERR_INVALID_STATE: APLL is refered by more than one peripherals, not allowed to change its frequency now
+ */
+esp_err_t periph_rtc_apll_freq_set(uint32_t expt_freq, uint32_t *real_freq);
+#endif // SOC_CLK_APLL_SUPPORTED
+
 #ifdef __cplusplus
 }
 #endif