feat(spi_flash): implement dynamic CPU frequency switching workaround for encrypted writes

This commit implements a workaround that allows ESP32-C5 to run at 240MHz CPU frequency
normally, while automatically reducing CPU frequency during encrypted flash writes to
ensure correct operation. The frequency limit is chip revision dependent:
- v1.2 and above: limited to 160MHz during encrypted writes
- v1.0 and below: limited to 80MHz during encrypted writes

Key implementation details:
- Frequency limiting is triggered automatically when esp_flash_write_encrypted() is called
- Uses start() flags (ESP_FLASH_START_FLAG_LIMIT_CPU_FREQ) to integrate with OS layer
- Works with both PM enabled and disabled configurations
- Frequency is automatically restored after encrypted write completes
- For ESP32-C5 with 120MHz flash, Flash clock and timing registers are adjusted when
  CPU frequency is reduced to 80MHz
- SPI1 timing registers are configured during frequency switching since encrypted writes
  use SPI1 and must work correctly at reduced CPU frequencies

Code improvements:
- Use SOC_MSPI_FREQ_AXI_CONSTRAINED capability macro instead of hardcoded chip checks
- Control workaround via Kconfig (CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED) instead of
  hardcoded macros
- Add comprehensive test cases covering various PM configurations and edge cases

This workaround enables ESP32-C5 applications to benefit from 240MHz CPU performance
while maintaining reliable encrypted flash write functionality.

components/esp_pm/include/esp_private/pm_impl.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2016-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2016-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -15,7 +15,6 @@
 
 #include "soc/rtc.h"
 #include "esp_pm.h"
-#include "esp_timer.h"
 #include "sdkconfig.h"
 
 #ifdef __cplusplus
@@ -26,11 +25,11 @@ extern "C" {
  * This is an enum of possible power modes supported by the implementation
  */
 typedef enum {
-    PM_MODE_LIGHT_SLEEP,//!< Light sleep
-    PM_MODE_APB_MIN,    //!< Idle (no CPU frequency or APB frequency locks)
-    PM_MODE_APB_MAX,    //!< Maximum APB frequency mode
-    PM_MODE_CPU_MAX,    //!< Maximum CPU frequency mode
-    PM_MODE_COUNT       //!< Number of items
+    PM_MODE_LIGHT_SLEEP,      //!< Light sleep
+    PM_MODE_APB_MIN,          //!< Idle (no CPU frequency or APB frequency locks)
+    PM_MODE_APB_MAX,          //!< Maximum APB frequency mode
+    PM_MODE_CPU_MAX,          //!< Maximum CPU frequency mode
+    PM_MODE_COUNT             //!< Number of items
 } pm_mode_t;
 
 /**
@@ -141,8 +140,18 @@ esp_err_t esp_pm_register_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
   */
 esp_err_t esp_pm_unregister_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
 
+
+/**
+ * @brief Initialize flash frequency limit
+ *
+ * This function initializes the flash frequency limit.
+ * @note This function is only available when CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED is enabled.
+ */
+void esp_pm_flash_freq_limit_init(void);
+
 #ifdef CONFIG_PM_PROFILING
 #define WITH_PROFILING
+#include "esp_timer.h"
 #endif
 
 #ifdef WITH_PROFILING

components/esp_pm/include/esp_private/pm_impl_freq_limit.h

@@ -0,0 +1,59 @@
+/*
+ * SPDX-FileCopyrightText: 2016-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "sdkconfig.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED
+
+/**
+ * @brief Initialize and pre-calculate forced CPU_MAX frequency configuration (private function for spi_flash)
+ *
+ * This function pre-calculates and stores the forced CPU_MAX frequency configuration
+ * based on the given frequency limit. The configuration is computed once during
+ * initialization and reused during runtime for better performance.
+ *
+ * @param limit_freq_mhz Frequency limit in MHz
+ * @note This is a private function, only for use by spi_flash component.
+ * @note Must be called during initialization before esp_pm_impl_cpu_max_freq_force().
+ * @note This function is only available when CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED is enabled and CONFIG_PM_ENABLE is enabled.
+ */
+void esp_pm_impl_cpu_max_freq_force_init(uint32_t limit_freq_mhz);
+
+/**
+ * @brief Force CPU_MAX frequency to pre-configured limit (private function for spi_flash)
+ *
+ * This function activates the pre-configured forced CPU_MAX frequency limit.
+ * When forced, all reads of CPU_MAX frequency will use the pre-configured value
+ * instead of the configured value.
+ *
+ * @note This is a private function, only for use by spi_flash component.
+ * @note The forced frequency configuration must be pre-calculated during initialization.
+ * @note This function is only available when CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED is enabled and CONFIG_PM_ENABLE is enabled.
+ */
+void esp_pm_impl_cpu_max_freq_force(void);
+
+/**
+ * @brief Unforce CPU_MAX frequency (private function for spi_flash)
+ *
+ * This function removes the forced CPU_MAX frequency, allowing the configured
+ * value to be used again.
+ * @note This is a private function, only for use by spi_flash component.
+ * @note This function is only available when CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED is enabled and CONFIG_PM_ENABLE is enabled.
+ */
+void esp_pm_impl_cpu_max_freq_unforce(void);
+
+#endif // CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED
+
+#ifdef __cplusplus
+}
+#endif