1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_FREERTOS_HOOKS_H__ 16 #define __ESP_FREERTOS_HOOKS_H__ 17 18 #include <stdbool.h> 19 #include "esp_err.h" 20 21 #ifdef __cplusplus 22 extern "C" 23 { 24 #endif 25 26 /* 27 Definitions for the tickhook and idlehook callbacks 28 */ 29 typedef bool (*esp_freertos_idle_cb_t)(void); 30 typedef void (*esp_freertos_tick_cb_t)(void); 31 32 /** 33 * @brief Register a callback to be called from the specified core's idle hook. 34 * The callback should return true if it should be called by the idle hook 35 * once per interrupt (or FreeRTOS tick), and return false if it should 36 * be called repeatedly as fast as possible by the idle hook. 37 * 38 * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL 39 * A FUNCTION THAT MIGHT BLOCK. 40 * 41 * @param[in] new_idle_cb Callback to be called 42 * @param[in] cpuid id of the core 43 * 44 * @return 45 * - ESP_OK: Callback registered to the specified core's idle hook 46 * - ESP_ERR_NO_MEM: No more space on the specified core's idle hook to register callback 47 * - ESP_ERR_INVALID_ARG: cpuid is invalid 48 */ 49 esp_err_t esp_register_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t new_idle_cb, UBaseType_t cpuid); 50 51 /** 52 * @brief Register a callback to the idle hook of the core that calls this function. 53 * The callback should return true if it should be called by the idle hook 54 * once per interrupt (or FreeRTOS tick), and return false if it should 55 * be called repeatedly as fast as possible by the idle hook. 56 * 57 * @warning Idle callbacks MUST NOT, UNDER ANY CIRCUMSTANCES, CALL 58 * A FUNCTION THAT MIGHT BLOCK. 59 * 60 * @param[in] new_idle_cb Callback to be called 61 * 62 * @return 63 * - ESP_OK: Callback registered to the calling core's idle hook 64 * - ESP_ERR_NO_MEM: No more space on the calling core's idle hook to register callback 65 */ 66 esp_err_t esp_register_freertos_idle_hook(esp_freertos_idle_cb_t new_idle_cb); 67 68 /** 69 * @brief Register a callback to be called from the specified core's tick hook. 70 * 71 * @param[in] new_tick_cb Callback to be called 72 * @param[in] cpuid id of the core 73 * 74 * @return 75 * - ESP_OK: Callback registered to specified core's tick hook 76 * - ESP_ERR_NO_MEM: No more space on the specified core's tick hook to register the callback 77 * - ESP_ERR_INVALID_ARG: cpuid is invalid 78 */ 79 esp_err_t esp_register_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t new_tick_cb, UBaseType_t cpuid); 80 81 /** 82 * @brief Register a callback to be called from the calling core's tick hook. 83 * 84 * @param[in] new_tick_cb Callback to be called 85 * 86 * @return 87 * - ESP_OK: Callback registered to the calling core's tick hook 88 * - ESP_ERR_NO_MEM: No more space on the calling core's tick hook to register the callback 89 */ 90 esp_err_t esp_register_freertos_tick_hook(esp_freertos_tick_cb_t new_tick_cb); 91 92 /** 93 * @brief Unregister an idle callback from the idle hook of the specified core 94 * 95 * @param[in] old_idle_cb Callback to be unregistered 96 * @param[in] cpuid id of the core 97 */ 98 void esp_deregister_freertos_idle_hook_for_cpu(esp_freertos_idle_cb_t old_idle_cb, UBaseType_t cpuid); 99 100 /** 101 * @brief Unregister an idle callback. If the idle callback is registered to 102 * the idle hooks of both cores, the idle hook will be unregistered from 103 * both cores 104 * 105 * @param[in] old_idle_cb Callback to be unregistered 106 */ 107 void esp_deregister_freertos_idle_hook(esp_freertos_idle_cb_t old_idle_cb); 108 109 /** 110 * @brief Unregister a tick callback from the tick hook of the specified core 111 * 112 * @param[in] old_tick_cb Callback to be unregistered 113 * @param[in] cpuid id of the core 114 */ 115 void esp_deregister_freertos_tick_hook_for_cpu(esp_freertos_tick_cb_t old_tick_cb, UBaseType_t cpuid); 116 117 /** 118 * @brief Unregister a tick callback. If the tick callback is registered to the 119 * tick hooks of both cores, the tick hook will be unregistered from 120 * both cores 121 * 122 * @param[in] old_tick_cb Callback to be unregistered 123 */ 124 void esp_deregister_freertos_tick_hook(esp_freertos_tick_cb_t old_tick_cb); 125 126 #ifdef __cplusplus 127 } 128 #endif 129 130 131 #endif 132