Initial Esp32c3 Support (#5060)

tools/sdk/esp32c3/include/esp_pm/include/esp32/pm.h

@@ -0,0 +1,42 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#include "soc/rtc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * @brief Power management config for ESP32
+ *
+ * Pass a pointer to this structure as an argument to esp_pm_configure function.
+ */
+typedef struct {
+    int max_freq_mhz;   /*!< Maximum CPU frequency, in MHz */
+    int min_freq_mhz;   /*!< Minimum CPU frequency to use when no locks are taken, in MHz */
+    bool light_sleep_enable;        /*!< Enter light sleep when no locks are taken */
+} esp_pm_config_esp32_t;
+
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp32c3/pm.h

@@ -0,0 +1,42 @@
+// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#include "soc/rtc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * @brief Power management config for ESP32C3
+ *
+ * Pass a pointer to this structure as an argument to esp_pm_configure function.
+ */
+typedef struct {
+    int max_freq_mhz;   /*!< Maximum CPU frequency, in MHz */
+    int min_freq_mhz;   /*!< Minimum CPU frequency to use when no locks are taken, in MHz */
+    bool light_sleep_enable;        /*!< Enter light sleep when no locks are taken */
+} esp_pm_config_esp32c3_t;
+
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp32s2/pm.h

@@ -0,0 +1,42 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#include "soc/rtc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * @brief Power management config for ESP32
+ *
+ * Pass a pointer to this structure as an argument to esp_pm_configure function.
+ */
+typedef struct {
+    int max_freq_mhz;   /*!< Maximum CPU frequency, in MHz */
+    int min_freq_mhz;   /*!< Minimum CPU frequency to use when no locks are taken, in MHz */
+    bool light_sleep_enable;        /*!< Enter light sleep when no locks are taken */
+} esp_pm_config_esp32s2_t;
+
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp32s3/pm.h

@@ -0,0 +1,42 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#include "soc/rtc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * @brief Power management config for ESP32
+ *
+ * Pass a pointer to this structure as an argument to esp_pm_configure function.
+ */
+typedef struct {
+    int max_freq_mhz;   /*!< Maximum CPU frequency, in MHz */
+    int min_freq_mhz;   /*!< Minimum CPU frequency to use when no locks are taken, in MHz */
+    bool light_sleep_enable;        /*!< Enter light sleep when no locks are taken */
+} esp_pm_config_esp32s3_t;
+
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp_pm.h

@@ -0,0 +1,184 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+#include "sdkconfig.h"
+#if CONFIG_IDF_TARGET_ESP32
+#include "esp32/pm.h"
+#elif CONFIG_IDF_TARGET_ESP32S2
+#include "esp32s2/pm.h"
+#elif CONFIG_IDF_TARGET_ESP32S3
+#include "esp32s3/pm.h"
+#elif CONFIG_IDF_TARGET_ESP32C3
+#include "esp32c3/pm.h"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Power management constraints
+ */
+typedef enum {
+    /**
+     * Require CPU frequency to be at the maximum value set via esp_pm_configure.
+     * Argument is unused and should be set to 0.
+     */
+    ESP_PM_CPU_FREQ_MAX,
+    /**
+     * Require APB frequency to be at the maximum value supported by the chip.
+     * Argument is unused and should be set to 0.
+     */
+    ESP_PM_APB_FREQ_MAX,
+    /**
+     * Prevent the system from going into light sleep.
+     * Argument is unused and should be set to 0.
+     */
+    ESP_PM_NO_LIGHT_SLEEP,
+} esp_pm_lock_type_t;
+
+/**
+ * @brief Set implementation-specific power management configuration
+ * @param config pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the configuration values are not correct
+ *      - ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported,
+ *        or if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_configure(const void* config);
+
+
+/**
+ * @brief Opaque handle to the power management lock
+ */
+typedef struct esp_pm_lock* esp_pm_lock_handle_t;
+
+
+/**
+ * @brief Initialize a lock handle for certain power management parameter
+ *
+ * When lock is created, initially it is not taken.
+ * Call esp_pm_lock_acquire to take the lock.
+ *
+ * This function must not be called from an ISR.
+ *
+ * @param lock_type Power management constraint which the lock should control
+ * @param arg argument, value depends on lock_type, see esp_pm_lock_type_t
+ * @param name arbitrary string identifying the lock (e.g. "wifi" or "spi").
+ *             Used by the esp_pm_dump_locks function to list existing locks.
+ *             May be set to NULL. If not set to NULL, must point to a string which is valid
+ *             for the lifetime of the lock.
+ * @param[out] out_handle  handle returned from this function. Use this handle when calling
+ *                         esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release.
+ *                         Must not be NULL.
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NO_MEM if the lock structure can not be allocated
+ *      - ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg,
+        const char* name, esp_pm_lock_handle_t* out_handle);
+
+/**
+ * @brief Take a power management lock
+ *
+ * Once the lock is taken, power management algorithm will not switch to the
+ * mode specified in a call to esp_pm_lock_create, or any of the lower power
+ * modes (higher numeric values of 'mode').
+ *
+ * The lock is recursive, in the sense that if esp_pm_lock_acquire is called
+ * a number of times, esp_pm_lock_release has to be called the same number of
+ * times in order to release the lock.
+ *
+ * This function may be called from an ISR.
+ *
+ * This function is not thread-safe w.r.t. calls to other esp_pm_lock_*
+ * functions for the same handle.
+ *
+ * @param handle handle obtained from esp_pm_lock_create function
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the handle is invalid
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_lock_acquire(esp_pm_lock_handle_t handle);
+
+/**
+ * @brief Release the lock taken using esp_pm_lock_acquire.
+ *
+ * Call to this functions removes power management restrictions placed when
+ * taking the lock.
+ *
+ * Locks are recursive, so if esp_pm_lock_acquire is called a number of times,
+ * esp_pm_lock_release has to be called the same number of times in order to
+ * actually release the lock.
+ *
+ * This function may be called from an ISR.
+ *
+ * This function is not thread-safe w.r.t. calls to other esp_pm_lock_*
+ * functions for the same handle.
+ *
+ * @param handle handle obtained from esp_pm_lock_create function
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the handle is invalid
+ *      - ESP_ERR_INVALID_STATE if lock is not acquired
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_lock_release(esp_pm_lock_handle_t handle);
+
+/**
+ * @brief Delete a lock created using esp_pm_lock
+ *
+ * The lock must be released before calling this function.
+ *
+ * This function must not be called from an ISR.
+ *
+ * @param handle handle obtained from esp_pm_lock_create function
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if the handle argument is NULL
+ *      - ESP_ERR_INVALID_STATE if the lock is still acquired
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_lock_delete(esp_pm_lock_handle_t handle);
+
+/**
+ * Dump the list of all locks to stderr
+ *
+ * This function dumps debugging information about locks created using
+ * esp_pm_lock_create to an output stream.
+ *
+ * This function must not be called from an ISR. If esp_pm_lock_acquire/release
+ * are called while this function is running, inconsistent results may be
+ * reported.
+ *
+ * @param stream stream to print information to; use stdout or stderr to print
+ *               to the console; use fmemopen/open_memstream to print to a
+ *               string buffer.
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+esp_err_t esp_pm_dump_locks(FILE* stream);
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp_private/pm_impl.h

@@ -0,0 +1,217 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+/**
+ * @file esp_private/pm_impl.h
+ *
+ * This header file defines interface between PM lock functions (pm_locks.c)
+ * and the chip-specific power management (DFS/light sleep) implementation.
+ */
+
+#include "soc/rtc.h"
+#include "esp_pm.h"
+#include "esp_timer.h"
+#include "sdkconfig.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * 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_t;
+
+/**
+ * @brief Get the mode corresponding to a certain lock
+ * @param type lock type
+ * @param arg argument value for this lock (passed to esp_pm_lock_create)
+ * @return lowest power consumption mode which meets the constraints of the lock
+ */
+pm_mode_t esp_pm_impl_get_mode(esp_pm_lock_type_t type, int arg);
+
+/**
+ * @brief Get CPU clock frequency by power mode
+ * @param mode power mode
+ * @return CPU clock frequency
+ */
+int esp_pm_impl_get_cpu_freq(pm_mode_t mode);
+
+/**
+ * If profiling is enabled, this data type will be used to store microsecond
+ * timestamps.
+ */
+typedef int64_t pm_time_t;
+
+/**
+ * See \ref esp_pm_impl_switch_mode
+ */
+typedef enum {
+    MODE_LOCK,
+    MODE_UNLOCK
+} pm_mode_switch_t;
+
+/**
+ * @brief Switch between power modes when lock is taken or released
+ * @param mode pm_mode_t corresponding to the lock being taken or released,
+ *             as returned by \ref esp_pm_impl_get_mode
+ * @param lock_or_unlock
+ *              - MODE_LOCK: lock was taken. Implementation needs to make sure
+ *                that the constraints of the lock are met by switching to the
+ *                given 'mode' or any of the higher power ones.
+ *              - MODE_UNLOCK: lock was released. If all the locks for given
+ *                mode are released, and no locks for higher power modes are
+ *                taken, implementation can switch to one of lower power modes.
+ * @param now timestamp when the lock was taken or released. Passed as
+ *            a minor optimization, so that the implementation does not need to
+ *            call pm_get_time again.
+ */
+void esp_pm_impl_switch_mode(pm_mode_t mode, pm_mode_switch_t lock_or_unlock, pm_time_t now);
+
+/**
+ * @brief Call once at startup to initialize pm implementation
+ */
+void esp_pm_impl_init(void);
+
+/**
+ * @brief Hook function for the idle task
+ * Must be called from the IDLE task on each CPU before entering waiti state.
+ */
+void esp_pm_impl_idle_hook(void);
+
+/**
+ * @brief Hook function for the interrupt dispatcher
+ * Must be called soon after entering the ISR
+ */
+void esp_pm_impl_isr_hook(void);
+
+/**
+ * @brief Dump the information about time spent in each of the pm modes.
+ *
+ * Prints three columns:
+ * mode name, total time in mode (in microseconds), percentage of time in mode
+ *
+ * @param out stream to dump the information to
+ */
+void esp_pm_impl_dump_stats(FILE* out);
+
+/**
+ * @brief Hook function implementing `waiti` instruction, should be invoked from idle task context
+ */
+void esp_pm_impl_waiti(void);
+
+/**
+ * @brief Callback function type for peripherals to skip light sleep.
+ *
+ */
+typedef bool (* skip_light_sleep_cb_t)(void);
+
+/**
+  * @brief  Register peripherals skip light sleep callback
+  *
+  * This function allows you to register a callback that gets the result
+  * that if light sleep should be skipped by peripherals.
+  * @param cb function to get the result
+  * @return
+  *   - ESP_OK on success
+  *   - ESP_ERR_NO_MEM if no more callback slots are available
+  */
+esp_err_t esp_pm_register_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
+
+/**
+  * @brief  Unregisterperipherals skip light sleep callback
+  *
+  * This function allows you to unregister a callback which was previously
+  * registered using esp_register_skip_light_sleep_callback.
+  * @param cb function to get the result
+  * @return
+  *   - ESP_OK on success
+  *   - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before
+  */
+esp_err_t esp_pm_unregister_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
+
+/**
+ * @brief Callback function type for peripherals to know light sleep wakeup overhead.
+ *
+ */
+typedef void (* inform_out_light_sleep_overhead_cb_t)(uint32_t);
+
+/**
+  * @brief  Register informing peripherals light sleep wakeup overhead time callback
+  *
+  * This function allows you to register a callback that informs the peripherals of
+  * the wakeup overhead time of light sleep.
+  * @param cb function to inform time
+  * @return
+  *   - ESP_OK on success
+  *   - ESP_ERR_NO_MEM if no more callback slots are available
+  */
+esp_err_t esp_pm_register_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb);
+
+/**
+  * @brief  Unregister informing peripherals light sleep wakeup overhead time callback
+  *
+  * This function allows you to unregister a callback that informs the peripherals of
+  * the wakeup overhead time of light sleep.
+  * @param cb function to inform time
+  * @return
+  *   - ESP_OK on success
+  *   - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before
+  */
+esp_err_t esp_pm_unregister_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb);
+
+/**
+ * @brief Callback function type for peripherals to know light sleep default parameters
+ */
+typedef void (* update_light_sleep_default_params_config_cb_t)(int, int);
+
+/**
+ * @brief  Register peripherals light sleep default parameters configure callback
+ *
+ * This function allows you to register a callback that configure the peripherals
+ * of default parameters of light sleep
+ * @param cb function to update default parameters
+ */
+void esp_pm_register_light_sleep_default_params_config_callback(update_light_sleep_default_params_config_cb_t cb);
+
+/**
+ * @brief  Unregister peripherals light sleep default parameters configure Callback
+ *
+ * This function allows you to unregister a callback that configure the peripherals
+ * of default parameters of light sleep
+ */
+void esp_pm_unregister_light_sleep_default_params_config_callback(void);
+
+#ifdef CONFIG_PM_PROFILING
+#define WITH_PROFILING
+#endif
+
+#ifdef WITH_PROFILING
+static inline pm_time_t IRAM_ATTR pm_get_time(void)
+{
+    return esp_timer_get_time();
+}
+#endif // WITH_PROFILING
+
+#ifdef __cplusplus
+}
+#endif

tools/sdk/esp32c3/include/esp_pm/include/esp_private/pm_trace.h

@@ -0,0 +1,53 @@
+// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "sdkconfig.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    ESP_PM_TRACE_IDLE,
+    ESP_PM_TRACE_TICK,
+    ESP_PM_TRACE_FREQ_SWITCH,
+    ESP_PM_TRACE_CCOMPARE_UPDATE,
+    ESP_PM_TRACE_ISR_HOOK,
+    ESP_PM_TRACE_SLEEP,
+    ESP_PM_TRACE_TYPE_MAX
+} esp_pm_trace_event_t;
+
+void esp_pm_trace_init(void);
+void esp_pm_trace_enter(esp_pm_trace_event_t event, int core_id);
+void esp_pm_trace_exit(esp_pm_trace_event_t event, int core_id);
+
+#ifdef CONFIG_PM_TRACE
+
+#define ESP_PM_TRACE_ENTER(event, core_id)   \
+            esp_pm_trace_enter(ESP_PM_TRACE_ ## event, core_id)
+#define ESP_PM_TRACE_EXIT(event, core_id)    \
+            esp_pm_trace_exit(ESP_PM_TRACE_ ## event, core_id)
+
+#else // CONFIG_PM_TRACE
+
+#define ESP_PM_TRACE_ENTER(type, core_id) do { (void) core_id; } while(0)
+#define ESP_PM_TRACE_EXIT(type, core_id)  do { (void) core_id; } while(0)
+
+#endif // CONFIG_PM_TRACE
+
+#ifdef __cplusplus
+}
+#endif