IDF release/v4.0 08219f3cf

tools/sdk/include/esp_common/esp_private/crosscore_int.h

@@ -0,0 +1,54 @@
+// Copyright 2015-2016 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.
+#ifndef __ESP_CROSSCORE_INT_H
+#define __ESP_CROSSCORE_INT_H
+
+
+/**
+ * Initialize the crosscore interrupt system for this CPU.
+ * This needs to be called once on every CPU that is used
+ * by FreeRTOS.
+ *
+ * If multicore FreeRTOS support is enabled, this will be
+ * called automatically by the startup code and should not
+ * be called manually.
+ */
+void esp_crosscore_int_init();
+
+
+/**
+ * Send an interrupt to a CPU indicating it should yield its
+ * currently running task in favour of a higher-priority task
+ * that presumably just woke up.
+ *
+ * This is used internally by FreeRTOS in multicore mode
+ * and should not be called by the user.
+ *
+ * @param core_id Core that should do the yielding
+ */
+void esp_crosscore_int_send_yield(int core_id);
+
+
+/**
+ * Send an interrupt to a CPU indicating it should update its
+ * CCOMPARE1 value due to a frequency switch.
+ *
+ * This is used internally when dynamic frequency switching is
+ * enabled, and should not be called from application code.
+ *
+ * @param core_id Core that should update its CCOMPARE1 value
+ */
+void esp_crosscore_int_send_freq_switch(int core_id);
+
+#endif

tools/sdk/include/esp_common/esp_private/dbg_stubs.h

@@ -0,0 +1,50 @@
+// Copyright 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.
+#ifndef ESP_DBG_STUBS_H_
+#define ESP_DBG_STUBS_H_
+
+#include "esp_err.h"
+
+/**
+ * Debug stubs entries IDs
+ */
+typedef enum {
+    ESP_DBG_STUB_CONTROL_DATA,	///< stubs descriptor entry
+    ESP_DBG_STUB_ENTRY_FIRST,
+    ESP_DBG_STUB_ENTRY_GCOV		///< GCOV entry
+    						= ESP_DBG_STUB_ENTRY_FIRST,
+    ESP_DBG_STUB_ENTRY_MAX
+} esp_dbg_stub_id_t;
+
+/**
+ * @brief  Initializes debug stubs.
+ *
+ * @note   Must be called after esp_apptrace_init() if app tracing is enabled.
+ */
+void esp_dbg_stubs_init(void);
+
+/**
+ * @brief  Initializes application tracing module.
+ *
+ * @note   Should be called before any esp_apptrace_xxx call.
+ *
+ * @param id 	Stub ID.
+ * @param entry Stub entry. Usually it is stub entry function address,
+ *              but can be any value meaningfull for OpenOCD command/code.
+ *
+ * @return ESP_OK on success, otherwise see esp_err_t
+ */
+esp_err_t esp_dbg_stub_entry_set(esp_dbg_stub_id_t id, uint32_t entry);
+
+#endif //ESP_DBG_STUBS_H_

tools/sdk/include/esp_common/esp_private/esp_timer_impl.h

@@ -0,0 +1,101 @@
+// Copyright 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/esp_timer_impl.h
+ *
+ * @brief Interface between common and platform-specific parts of esp_timer.
+ *
+ * The functions in this header file are implemented for each supported SoC.
+ * High level functions defined in esp_timer.c call the functions here to
+ * interact with the hardware.
+ */
+
+#include <stdint.h>
+#include "esp_err.h"
+#include "esp_intr_alloc.h"
+
+/**
+ * @brief Initialize platform specific layer of esp_timer
+ * @param alarm_handler function to call on timer interrupt
+ * @return ESP_OK, ESP_ERR_NO_MEM, or one of the errors from interrupt allocator
+ */
+esp_err_t esp_timer_impl_init(intr_handler_t alarm_handler);
+
+/**
+ * @brief Deinitialize platform specific layer of esp_timer
+ */
+void esp_timer_impl_deinit();
+
+/**
+ * @brief Set up the timer interrupt to fire at a particular time
+ *
+ * If the alarm time is too close in the future, implementation should set the
+ * alarm to the earliest time possible.
+ *
+ * @param timestamp time in microseconds when interrupt should fire (relative to
+ *                  boot time, i.e. as returned by esp_timer_impl_get_time)
+ */
+void esp_timer_impl_set_alarm(uint64_t timestamp);
+
+/**
+ * @brief Notify esp_timer implementation that APB frequency has changed
+ *
+ * Called by the frequency switching code.
+ *
+ * @param apb_ticks_per_us new number of APB clock ticks per microsecond
+ */
+void esp_timer_impl_update_apb_freq(uint32_t apb_ticks_per_us);
+
+/**
+ * @brief Adjust current esp_timer time by a certain value
+ *
+ * Called from light sleep code to synchronize esp_timer time with RTC time.
+ *
+ * @param time_us  adjustment to apply to esp_timer time, in microseconds
+ */
+void esp_timer_impl_advance(int64_t time_us);
+
+/**
+ * @brief Get time, in microseconds, since esp_timer_impl_init was called
+ * @return timestamp in microseconds
+ */
+uint64_t esp_timer_impl_get_time();
+
+/**
+ * @brief Get minimal timer period, in microseconds
+ * Periods shorter than the one returned may not be possible to achieve due to
+ * interrupt latency and context switch time. Short period of periodic timer may
+ * cause the system to spend all the time servicing the interrupt and timer
+ * callback, preventing other tasks from running.
+ * @return minimal period of periodic timer, in microseconds
+ */
+uint64_t esp_timer_impl_get_min_period_us();
+
+/**
+ * @brief obtain internal critical section used esp_timer implementation
+ * This can be used when a sequence of calls to esp_timer has to be made,
+ * and it is necessary that the state of the timer is consistent between
+ * the calls. Should be treated in the same way as a spinlock.
+ * Call esp_timer_impl_unlock to release the lock
+ */
+void esp_timer_impl_lock();
+
+
+/**
+ * @brief counterpart of esp_timer_impl_lock
+ */
+void esp_timer_impl_unlock();

tools/sdk/include/esp_common/esp_private/gdbstub.h

@@ -0,0 +1,22 @@
+// Copyright 2015-2016 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.
+#ifndef GDBSTUB_H
+#define GDBSTUB_H
+
+#include <xtensa/config/core.h>
+#include "freertos/xtensa_api.h"
+
+void esp_gdbstub_panic_handler(XtExcFrame *frame) __attribute__((noreturn));
+
+#endif

tools/sdk/include/esp_common/esp_private/pm_impl.h

@@ -0,0 +1,121 @@
+// 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"
+
+
+/**
+ * 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);
+
+/**
+ * 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();
+
+/**
+ * @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();
+
+/**
+ * @brief Hook function for the interrupt dispatcher
+ * Must be called soon after entering the ISR
+ */
+void esp_pm_impl_isr_hook();
+
+/**
+ * @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();
+
+#ifdef CONFIG_PM_PROFILING
+#define WITH_PROFILING
+#endif
+
+#ifdef WITH_PROFILING
+static inline pm_time_t IRAM_ATTR pm_get_time()
+{
+    return esp_timer_get_time();
+}
+#endif // WITH_PROFILING

tools/sdk/include/esp_common/esp_private/pm_trace.h

@@ -0,0 +1,45 @@
+// 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"
+
+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 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

tools/sdk/include/esp_common/esp_private/system_internal.h

@@ -0,0 +1,56 @@
+// Copyright 2018 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
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "esp_system.h"
+
+/**
+ * @brief  Internal function to restart PRO and APP CPUs.
+ *
+ * @note This function should not be called from FreeRTOS applications.
+ *       Use esp_restart instead.
+ *
+ * This is an internal function called by esp_restart. It is called directly
+ * by the panic handler and brownout detector interrupt.
+ */
+void esp_restart_noos() __attribute__ ((noreturn));
+
+/**
+ * @brief  Internal function to set reset reason hint
+ *
+ * The hint is used do distinguish different reset reasons when software reset
+ * is performed.
+ *
+ * The hint is stored in RTC store register, RTC_RESET_CAUSE_REG.
+ *
+ * @param hint  Desired esp_reset_reason_t value for the real reset reason
+ */
+void esp_reset_reason_set_hint(esp_reset_reason_t hint);
+
+/**
+ * @brief  Internal function to get the reset hint value
+ * @return  - Reset hint value previously stored into RTC_RESET_CAUSE_REG using
+ *          esp_reset_reason_set_hint function
+ *          - ESP_RST_UNKNOWN if the value in RTC_RESET_CAUSE_REG is invalid
+ */
+esp_reset_reason_t esp_reset_reason_get_hint(void);
+
+#ifdef __cplusplus
+}
+#endif