1 // Copyright 2015-2019 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 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #ifndef __ASSEMBLER__ 22 23 #include <stdbool.h> 24 #include "esp_err.h" 25 #include "soc/soc.h" // [refactor-todo] IDF-2297 26 27 #define ESP_WATCHPOINT_LOAD 0x40000000 28 #define ESP_WATCHPOINT_STORE 0x80000000 29 #define ESP_WATCHPOINT_ACCESS 0xC0000000 30 31 /* 32 * @brief Structure used for backtracing 33 * 34 * This structure stores the backtrace information of a particular stack frame 35 * (i.e. the PC and SP). This structure is used iteratively with the 36 * esp_cpu_get_next_backtrace_frame() function to traverse each frame within a 37 * single stack. The next_pc represents the PC of the current frame's caller, thus 38 * a next_pc of 0 indicates that the current frame is the last frame on the stack. 39 * 40 * @note Call esp_backtrace_get_start() to obtain initialization values for 41 * this structure 42 */ 43 typedef struct { 44 uint32_t pc; /* PC of the current frame */ 45 uint32_t sp; /* SP of the current frame */ 46 uint32_t next_pc; /* PC of the current frame's caller */ 47 } esp_backtrace_frame_t; 48 49 /** 50 * @brief If an OCD is connected over JTAG. set breakpoint 0 to the given function 51 * address. Do nothing otherwise. 52 * @param fn Pointer to the target breakpoint position 53 */ 54 void esp_set_breakpoint_if_jtag(void *fn); 55 56 /** 57 * @brief Set a watchpoint to break/panic when a certain memory range is accessed. 58 * 59 * @param no Watchpoint number. On the ESP32, this can be 0 or 1. 60 * @param adr Base address to watch 61 * @param size Size of the region, starting at the base address, to watch. Must 62 * be one of 2^n, with n in [0..6]. 63 * @param flags One of ESP_WATCHPOINT_* flags 64 * 65 * @return ESP_ERR_INVALID_ARG on invalid arg, ESP_OK otherwise 66 * 67 * @warning The ESP32 watchpoint hardware watches a region of bytes by effectively 68 * masking away the lower n bits for a region with size 2^n. If adr does 69 * not have zero for these lower n bits, you may not be watching the 70 * region you intended. 71 */ 72 esp_err_t esp_set_watchpoint(int no, void *adr, int size, int flags); 73 74 /** 75 * @brief Clear a watchpoint 76 * 77 * @param no Watchpoint to clear 78 * 79 */ 80 void esp_clear_watchpoint(int no); 81 82 /** 83 * Get the first frame of the current stack's backtrace 84 * 85 * Given the following function call flow (B -> A -> X -> esp_backtrace_get_start), 86 * this function will do the following. 87 * - Flush CPU registers and window frames onto the current stack 88 * - Return PC and SP of function A (i.e. start of the stack's backtrace) 89 * - Return PC of function B (i.e. next_pc) 90 * 91 * @note This function is implemented in assembly 92 * 93 * @param[out] pc PC of the first frame in the backtrace 94 * @param[out] sp SP of the first frame in the backtrace 95 * @param[out] next_pc PC of the first frame's caller 96 */ 97 extern void esp_backtrace_get_start(uint32_t *pc, uint32_t *sp, uint32_t *next_pc); 98 99 /** 100 * Get the next frame on a stack for backtracing 101 * 102 * Given a stack frame(i), this function will obtain the next stack frame(i-1) 103 * on the same call stack (i.e. the caller of frame(i)). This function is meant to be 104 * called iteratively when doing a backtrace. 105 * 106 * Entry Conditions: Frame structure containing valid SP and next_pc 107 * Exit Conditions: 108 * - Frame structure updated with SP and PC of frame(i-1). next_pc now points to frame(i-2). 109 * - If a next_pc of 0 is returned, it indicates that frame(i-1) is last frame on the stack 110 * 111 * @param[inout] frame Pointer to frame structure 112 * 113 * @return 114 * - True if the SP and PC of the next frame(i-1) are sane 115 * - False otherwise 116 */ 117 bool esp_backtrace_get_next_frame(esp_backtrace_frame_t *frame); 118 119 /** 120 * @brief Print the backtrace of the current stack 121 * 122 * @param depth The maximum number of stack frames to print (should be > 0) 123 * 124 * @return 125 * - ESP_OK Backtrace successfully printed to completion or to depth limit 126 * - ESP_FAIL Backtrace is corrupted 127 */ 128 esp_err_t esp_backtrace_print(int depth); 129 130 #endif 131 #ifdef __cplusplus 132 } 133 #endif 134