/* * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ /** * @file DWARF Exception Frames parser * * This file performs parsing and execution of DWARF except frames described in * section `.eh_frame` and `.eh_frame_hdr`. This is currently used on RISC-V * boards to implement a complete backtracing when a panic occurs. * * More information about the sections structure and DWARF instructions can be * found in the official documentation: * http://dwarfstd.org/Download.php */ #include "eh_frame_parser.h" #include "esp_private/panic_internal.h" #include #if CONFIG_ESP_SYSTEM_USE_EH_FRAME #include "eh_frame_parser_impl.h" /** * @brief Dimension of an array (number of elements) */ #ifndef DIM #define DIM(array) (sizeof(array)/sizeof(*array)) #endif /** * @brief DWARF Exception Header Encoding * This is used to know how the data in .eh_frame and .eh_frame_hdr sections * are encoded. */ /* DWARF Exception Exception Header value format. */ #define DW_EH_PE_omit 0xff /*!< No value is present */ #define DW_EH_PE_uleb128 0x01 /*!< Unsigned value encoded in LEB128 (Little Endian Base 128). */ #define DW_EH_PE_udata2 0x02 /*!< Unsigned 16-bit value. */ #define DW_EH_PE_udata4 0x03 /*!< Unsigned 32-bit value. */ #define DW_EH_PE_udata8 0x04 /*!< Unsigned 64-bit value. */ #define DW_EH_PE_sleb128 0x09 /*!< Signed value encoded in LEB128 (Little Endian Base 128). */ #define DW_EH_PE_sdata2 0x0A /*!< Signed 16-bit value. */ #define DW_EH_PE_sdata4 0x0B /*!< Signed 32-bit value. */ #define DW_EH_PE_sdata8 0x0C /*!< Signed 64-bit value. */ /* DWARF Exception Exception Header value application. * These values are in fact represented in the high nibble of a given data. * For example: * 0x3A describes the values as signed 16-bit offsets relative to .eh_frame_hdr section. * 0x11 describes the values as unsigned value encoded in LEB128, relative to their location ion memory. */ #define DW_EH_PE_absptr 0x00 /*!< The value itself is a pointer, it is not an offset. */ #define DW_EH_PE_pcrel 0x01 /*!< The value is an offset, relative to its location in memory. */ #define DW_EH_PE_datarel 0x03 /*!< The value is an offset, relative to .eh_frame_hdr section. */ /* Macros simplifying testing relative offset data encoding. */ #define ESP_ENCODING_PC_REL(ENCODING) (((ENCODING >> 4) & 0xf) == DW_EH_PE_pcrel) #define ESP_ENCODING_FRAME_HDR_REL(ENCODING) (((ENCODING >> 4) & 0xf) == DW_EH_PE_datarel) /** * @brief Call Frame Information (CIE) fields information. * As the size of CIE is variable, the simplest way to described it is to * have a pointer at the beginning of CIE structure and access the fields * thanks to the index macros defined here. */ #define ESP_CIE_VARIABLE_FIELDS_IDX (9) /*!< Offset, in bytes, where variable length fields start. */ /** * @brief Frame Description Entry (FDE) fields index. * For the same reasons as above, we prefer defining these macros rather than * having a structure. */ #define ESP_FDE_LENGTH_IDX (0) /*!< Length, in bytes, of the FDE excluding this field. 4 bytes field. */ #define ESP_FDE_CIE_IDX (1) /*!< Nearest preceding Common Information Entry (CIE) offset. 4 bytes field. */ #define ESP_FDE_INITLOC_IDX (2) /*!< Initial location (of the function) the FDE describes. Variable size (encoding in CIE). */ #define ESP_FDE_RANGELEN_IDX (3) /*!< Size, in bytes, of the function described by this FDE location the FDE describes. Variable size (encoding in CIE). */ #define ESP_FDE_AUGMENTATION_IDX (4) /*!< Augmentation data length. Unsigned LEB128. */ /** * @brief Pointers to both .eh_frame_hdr and .eh_frame sections. */ #define EH_FRAME_HDR_ADDR (&__eh_frame_hdr) #define EH_FRAME_ADDR (&__eh_frame) /** * @brief Structure of .eh_frame_hdr section header. */ typedef struct { uint8_t version; /*!< Structure version, must be 1.*/ uint8_t eh_frame_ptr_enc; /*!< eh_frame_ptr entry encoding. */ uint8_t fde_count_enc; /*!< fde_count entry encoding. */ uint8_t table_enc; /*!< table entries encoding. */ /* The rest of the structure has variable length. Thus, we cannot define * them here. Here are their names: * - eh_frame_ptr : encoded pointer to the .eh_frame section. * - fde_Count : number of entries in the array of table_entry. * - table_entry array : sorted array of table_entry. */ } __attribute__((packed)) fde_header; /** * @brief .eh_frame_hdr table's entry format. * Each entry of the table contains 2 32-bit encoded addresses. * Encoding is defined in the previous structure. Check table_enc field. */ typedef struct { uint32_t fun_addr; /*!< Address of the function described. */ uint32_t fde_addr; /*!< Address of the FDE for the function.*/ } table_entry; /** * @brief DWARF state constant macros. */ #define ESP_EH_FRAME_STACK_SIZE (2) /*!< DWARF virtual machine can save the push the current on a virtual stack. we mimic the stack with an array. While testing, a stack size of 2 was enough. */ /** * @brief * Structure representing the state of the DWARF virtual machine. */ typedef struct { /* Stack for DWARF state registers. * For caller saved registers, save their CFA address (value in previous call frame). * As these registers will be used to define offset in the CFA, they will always be * multiple of CPU word (4-bytes in our case). Thus, it will save the offset in word-size, not * in bytes. Plus, the highest bit will be used to mark that this register is NOY * ESP_EH_FRAME_REG_SAME. (0x80000000 is a valid value then, meaning that the register value * is CFA + 0 offset) */ uint32_t regs_offset[ESP_EH_FRAME_STACK_SIZE][EXECUTION_FRAME_MAX_REGS]; /* reg_offset represents the state of registers when PC reaches the following location. */ uint32_t location; /* Index of the registers offset to use (1 for saved offset, 0 else). */ uint8_t offset_idx; } dwarf_regs; /** * @brief DWARF's register state. * When a DWARF register is set to ESP_EH_FRAME_REG_SAME, the CPU register corresponding to this * virtual register will be unchanged after executing DWARF instructions. * Please see esp_eh_frame_restore_caller_state() for more details. */ #define ESP_EH_FRAME_REG_SAME (0) /** * @brief Set a register's offset (relative to CFA). * The highest bit is set to 1 to mark that this register needs to be retrived because it has been * altered. */ #define ESP_EH_FRAME_SET_REG_OFFSET(offset) (0x80000000 | offset) /** * @brief Get a register's offset (relative to CFA). */ #define ESP_EH_FRAME_GET_REG_OFFSET(offset) (0x7fffffff & offset) /** * @brief Get a register's CFA offset. */ #define ESP_EH_FRAME_IS_CFA_RELATIVE(reg) ((reg >> 31) == 1) /** * @brief Test whether an offset is small enough to be stored * in our 32-bit register. * Note: the highest bit is used. */ #define ESP_EH_FRAME_CFA_OFFSET_VALID(offset) (offset < 0x80000000) /** * @brief Index of Call Frame Address (CFA) in DWARF registers array. */ #define ESP_ESH_FRAME_CFA_IDX (EXECUTION_FRAME_SP_REG) /** * @brief Macros to get and set CFA's relative register and offset. * Indeed, CFA is defined by two values: register and offset. CFA is then * calculated by adding the offset to the register value. * `register` will be stored in the lowest 8 bits. * `offset` will be stored in the highest 24 bits. * * NOTE: with this implementation, CFA will be affected by * DW_CFA_REMEMBER_STATE and DW_CFA_RESTORE_STATE instructions. */ #if EXECUTION_FRAME_MAX_REGS > 255 #error "Too many registers defined for the target ExecutionFrame" #endif #define ESP_EH_FRAME_CFA_REG_VALID(reg) (reg < EXECUTION_FRAME_MAX_REGS) #define ESP_EH_FRAME_CFA_OFF_VALID(off) (((off) >> 24) == 0) #define ESP_EH_FRAME_CFA(state) ((state)->regs_offset[(state)->offset_idx][ESP_ESH_FRAME_CFA_IDX]) #define ESP_EH_FRAME_NEW_CFA(reg, off) (((off) << 8) | ((reg) & 0xff)) #define ESP_EH_FRAME_SET_CFA_REG(value, reg) (((value) & ~0xff) | ((reg) & 0xff)) #define ESP_EH_FRAME_SET_CFA_OFF(value, off) (((value) & 0xff) | ((off) << 8)) #define ESP_EH_FRAME_GET_CFA_REG(value) ((value) & 0xff) #define ESP_EH_FRAME_GET_CFA_OFF(value) ((value) >> 8) /** * @brief Unsupported opcode value to return when exeucting 0-opcode type instructions. */ #define ESP_EH_FRAME_UNSUPPORTED_OPCODE ((uint32_t) -1) /** * @brief Macros defining the DWARF instructions code. */ #define DW_GET_OPCODE(OP) ((OP) >> 6) #define DW_GET_PARAM(OP) ((OP) & 0b111111) #define DW_CFA_ADVANCE_LOC (1) #define DW_CFA_OFFSET (2) #define DW_CFA_RESTORE (3) /** * @brief Constant for DWARF instructions code when high 2 bits are 0. */ #define DW_CFA_0_OPCODE (0) #define DW_CFA_NOP (0x0) #define DW_CFA_SET_LOC (0x1) #define DW_CFA_ADVANCE_LOC1 (0x2) #define DW_CFA_ADVANCE_LOC2 (0x3) #define DW_CFA_ADVANCE_LOC4 (0x4) #define DW_CFA_OFFSET_EXTENDED (0x5) #define DW_CFA_RESTORE_EXTENDED (0x6) #define DW_CFA_UNDEFINED (0x7) #define DW_CFA_SAME_VALUE (0x8) #define DW_CFA_REGISTER (0x9) #define DW_CFA_REMEMBER_STATE (0xA) #define DW_CFA_RESTORE_STATE (0xB) #define DW_CFA_DEF_CFA (0xC) #define DW_CFA_DEF_CFA_REGISTER (0xD) #define DW_CFA_DEF_CFA_OFFSET (0xE) #define DW_CFA_DEF_CFA_EXPRESSION (0xF) #define DW_CFA_EXPRESSION (0x10) #define DW_CFA_OFFSET_EXTENDED_SF (0x11) #define DW_CFA_DEF_CFA_SF (0x12) #define DW_CFA_DEF_CFA_OFFSET_SF (0x13) #define DW_CFA_VAL_OFFSET (0x14) #define DW_CFA_VAL_OFFSET_SF (0x15) #define DW_CFA_VAL_EXPRESSION (0x16) #define DW_CFA_LO_USER (0x1C) /** * @brief Constants used for decoding (U)LEB128 integers. */ #define DW_LEB128_HIGHEST_BIT(byte) (((byte) >> 7) & 1) #define DW_LEB128_SIGN_BIT(byte) (((byte) >> 6) & 1) #define DW_LEB128_MAX_SHIFT (31) /** * @brief Symbols defined by the linker. * Retrieve the addresses of both .eh_frame_hdr and .eh_frame sections. */ extern char __eh_frame_hdr; extern char __eh_frame; /** * @brief Decode multiple bytes encoded in LEB128. * * @param bytes bytes encoded in LEB128. They will not be modified. * @param is_signed true if bytes represent a signed value, false else. * @param size Size in bytes of the encoded value. * * @return Decoded bytes. */ static uint32_t decode_leb128(const uint8_t* bytes, bool is_signed, uint32_t* lebsize) { uint32_t res = 0; uint32_t shf = 0; uint32_t size = 0; uint8_t byte = 0; while(1) { byte = bytes[size++]; res |= (byte & 0x7f) << shf; shf += 7; if (DW_LEB128_HIGHEST_BIT(byte) == 0) break; } if (is_signed && shf <= DW_LEB128_MAX_SHIFT && DW_LEB128_SIGN_BIT(byte)) { res |= ((uint32_t) ~0 << shf); } if (lebsize) { *lebsize = size; } return res; } /** * @brief Get the value of data encoded. * * @param data Pointer to the encoded data. * @param encoding Encoding for the data to read. * @param psize Reference to be filled with data size, in bytes. * * @return Decoded data read from the pointer. */ static uint32_t esp_eh_frame_get_encoded(void* data, uint8_t encoding, uint32_t* psize) { int32_t svalue = 0; uint32_t uvalue = 0; uint32_t fvalue = 0; uint32_t size = 0; const uint32_t high = encoding >> 4; const uint32_t low = encoding & 0xf; assert(psize != NULL); if (encoding == DW_EH_PE_omit) { *psize = size; return uvalue; } switch (low) { case DW_EH_PE_udata2: size = 2; uvalue = *((uint16_t*) data); break; case DW_EH_PE_udata4: size = 4; uvalue = *((uint32_t*) data); break; case DW_EH_PE_sdata2: size = 2; svalue = *((int16_t*) data); break; case DW_EH_PE_sdata4: size = 4; svalue = *((int32_t*) data); break; default: /* Unsupported yet. */ assert(false); break; } switch (high) { case DW_EH_PE_absptr: /* Do not change the values, as one of them will be 0, fvalue will * contain the data no matter whether it is signed or unsigned. */ fvalue = svalue + uvalue; break; case DW_EH_PE_pcrel: /* Relative to the address of the data. * svalue has been casted to an 32-bit value, so even if it was a * 2-byte signed value, fvalue will be calculated correctly here. */ fvalue = (uint32_t) data + svalue + uvalue; break; case DW_EH_PE_datarel: fvalue = (uint32_t) EH_FRAME_HDR_ADDR + svalue + uvalue; break; } *psize = size; return fvalue; } /** * @brief Find entry in the table for the given return_address. * * @param sorted_table Pointer to the sorted table of entries. * @param length Number of entries in the table. * @param encoding Encoding for the addresses in the table * (Check DWARF documentation for more info about encoding). * @param return_address The address to find in the table. This address can be * part of one in the function listed. * * @note The table is structured like this (after decoding the addresses): * Function address FDE address Index * +-------------------------------+ * |0x403805a4 0x4038d014| 0 * +-------------------------------+ * |0x403805be 0x4038d034| 1 * +-------------------------------+ * |0x403805d8 0x4038d070| 2 * +-------------------------------+ * |.......... ..........| ... * +-------------------------------+ * |0x42020c48 0x4038ddb4| length-3 * +-------------------------------+ * |0x42020dca 0x4038dde4| length-2 *+-------------------------------+ * |0x42020f92 0x4038debc| length-1 * +-------------------------------+ * * For example, if return_address passed is 0x403805b4, this function will * return a pointer to the entry (0x403805a4, 0x4038d014). * * @return Pointer to the entry found, NULL if not found. */ static const table_entry* esp_eh_frame_find_entry(const table_entry* sorted_table, const uint32_t length, const uint32_t encoding, const uint32_t return_address) { int32_t ra = 0; /* Used for decoding addresses in the table. */ uint32_t is_signed = (encoding & 0xf) >= 0x9; uint32_t pc_relative = true; /* The following local variables are used for dichotomic search. */ uint32_t found = false; uint32_t begin = 0; uint32_t end = length; uint32_t middle = (end + begin) / 2; /* If the addresses in the table are offsets relative to the eh_frame section, * instead of decoding each of them, we can simply encode the return_address * we have to find. If addresses are offsets relative to the programe counter, * then we have no other choice than decoding each of them to compare them * with return_address. */ if (ESP_ENCODING_FRAME_HDR_REL(encoding)) { ra = return_address - (uint32_t) EH_FRAME_HDR_ADDR; pc_relative = false; } /* Perform dichotomic search. */ while (end != 0 && middle != (length - 1) && !found) { const uint32_t fun_addr = sorted_table[middle].fun_addr; const uint32_t nxt_addr = sorted_table[middle + 1].fun_addr; if (pc_relative) { ra = return_address - (uint32_t) (sorted_table + middle); } if (is_signed) { /* Signed comparisons. */ const int32_t sfun_addr = (int32_t) fun_addr; const int32_t snxt_addr = (int32_t) nxt_addr; if (sfun_addr <= ra && snxt_addr > ra) found = true; else if (snxt_addr <= ra) begin = middle + 1; else end = middle; } else { /* Unsigned comparisons. */ const uint32_t ura = (uint32_t) ra; if (fun_addr <= ura && nxt_addr > ura) found = true; else if (nxt_addr <= ura) begin = middle + 1; else end = middle; } middle = (end + begin) / 2; } /* If 'end' reached the beginning of the array, it means the return_address * passed was below the first address of the array, thus, it was wrong. * Else, return the address found. */ return (end == 0) ? 0 : sorted_table + middle; } /** * @brief Decode an address according to the encoding passed. * * @param addr Pointer to the address to decode. * This pointer's value MUST be an address in .eh_frame_hdr section. * @param encoding DWARF encoding byte. * * @return address dedoded (e.g. absolute address) */ static inline uint32_t* esp_eh_frame_decode_address(const uint32_t* addr, const uint32_t encoding) { uint32_t* decoded = 0; if (ESP_ENCODING_FRAME_HDR_REL(encoding)) decoded = (uint32_t*) (*addr + (uint32_t) EH_FRAME_HDR_ADDR); else if (ESP_ENCODING_PC_REL(encoding)) decoded = (uint32_t*) (*addr + (uint32_t) addr); else decoded = (uint32_t*) (*addr); return decoded; } /** * @brief Execute the DWARF instruction which high 2 bits are 0. * * @param opcode low 6 bits of the instruction code. * @param operands pointer to the possible operands. * @param state state of the DWARF machine. Its registers may be modified. * * @return Number of operands used for executing the instruction. */ static inline uint32_t esp_eh_frame_execute_opcode_0(const uint32_t opcode, const uint8_t* operands, dwarf_regs* state) { uint32_t operand1 = 0; uint32_t used_operands = 0; uint32_t operand2 = 0; uint32_t used_operands2 = 0; switch(opcode) { case DW_CFA_NOP: break; case DW_CFA_ADVANCE_LOC1: /* Advance location with a 1-byte delta. */ used_operands = 1; state->location += *operands; break; case DW_CFA_ADVANCE_LOC2: /* Advance location with a 2-byte delta. */ used_operands = 2; state->location += *((const uint16_t*) operands); break; case DW_CFA_ADVANCE_LOC4: /* Advance location with a 4-byte delta. */ used_operands = 4; state->location += *((const uint32_t*) operands); break; case DW_CFA_REMEMBER_STATE: assert(state->offset_idx == 0); memcpy(state->regs_offset[1], state->regs_offset[0], EXECUTION_FRAME_MAX_REGS * sizeof(uint32_t)); state->offset_idx++; break; case DW_CFA_RESTORE_STATE: assert(state->offset_idx == 1); /* Drop the saved state. */ state->offset_idx--; break; case DW_CFA_DEF_CFA: /* CFA changes according to a register and an offset. * This instruction appears when the assembly code saves the * SP in the middle of a routine, before modifying it. * For example (on RISC-V): * addi s0, sp, 80 * addi sp, sp, -10 * ... */ /* Operand1 is the register containing the CFA value. */ operand1 = decode_leb128(operands, false, &used_operands); /* Offset for the register's value. */ operand2 = decode_leb128(operands + used_operands, false, &used_operands2); /* Calculate the number of bytes */ used_operands += used_operands2; /* Assert that the register and the offset are valid. */ assert(ESP_EH_FRAME_CFA_REG_VALID(operand1)); assert(ESP_EH_FRAME_CFA_OFF_VALID(operand2)); ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_NEW_CFA(operand1, operand2); break; case DW_CFA_DEF_CFA_REGISTER: /* Define the register of the current frame address (CFA). * Its operand is in the next bytes, its type is ULEB128. */ operand1 = decode_leb128(operands, false, &used_operands); /* Check whether the value is valid or not. */ assert(ESP_EH_FRAME_CFA_OFF_VALID(operand1)); /* Offset will be unchanged, only register changes. */ ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_SET_CFA_REG(ESP_EH_FRAME_CFA(state), operand1); break; case DW_CFA_DEF_CFA_OFFSET: /* Same as above but for the offset. The register of CFA remains unchanged. */ operand1 = decode_leb128(operands, false, &used_operands); assert(ESP_EH_FRAME_CFA_OFF_VALID(operand1)); ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_SET_CFA_OFF(ESP_EH_FRAME_CFA(state), operand1); break; default: panic_print_str("\r\nUnsupported DWARF opcode 0: 0x"); panic_print_hex(opcode); panic_print_str("\r\n"); used_operands = ESP_EH_FRAME_UNSUPPORTED_OPCODE; break; } return used_operands; } /** * @brief Execute DWARF instructions. * * @param instructions Array of instructions to execute. * @param instructions_length Length of the array of instructions. * @param frame Execution frame of the crashed task. This will only be used to * get the PC where the task crashed. * @param state DWARF machine state. The registers contained in the state will * modified accordingly to the instructions. * * @return true if the execution went fine, false if an unsupported instruction was met. */ static bool esp_eh_frame_execute(const uint8_t* instructions, const uint32_t instructions_length, const ExecutionFrame* frame, dwarf_regs* state) { for (uint32_t i = 0; i < instructions_length; i++) { const uint8_t instr = instructions[i]; const uint8_t param = DW_GET_PARAM(instr); uint32_t operand1 = 0; uint32_t size = 0; uint32_t used_operands = 0; /* Decode the instructions. According to DWARF documentation, there are three * types of Call Frame Instructions. The upper 2 bits defines the type. */ switch (DW_GET_OPCODE(instr)) { case DW_CFA_0_OPCODE: used_operands = esp_eh_frame_execute_opcode_0(param, &instructions[i + 1], state); /* Exit the function if an unsupported opcode was met. */ if (used_operands == ESP_EH_FRAME_UNSUPPORTED_OPCODE) { return false; } i += used_operands; break; case DW_CFA_ADVANCE_LOC: /* Move the location forward. This instruction will mark when to stop: * once we reach the instruction where the PC left, we can break out of the loop * The delta is part of the lowest 6 bits. */ state->location += param; break; case DW_CFA_OFFSET: operand1 = decode_leb128(&instructions[i + 1], false, &size); assert(ESP_EH_FRAME_CFA_OFFSET_VALID(operand1)); state->regs_offset[state->offset_idx][param] = ESP_EH_FRAME_SET_REG_OFFSET(operand1); i += size; break; case DW_CFA_RESTORE: state->regs_offset[state->offset_idx][param] = ESP_EH_FRAME_REG_SAME; break; default: /* Illegal opcode */ assert(false); break; } /* As the state->location can also be modified by 0-opcode instructions (in the function) * and also because we need to break the loop (and not only the switch), let's put this * check here, after the execution of the instruction, outside of the switch block. */ if (state->location >= EXECUTION_FRAME_PC(*frame)) break; } /* Everything went fine, no unsupported opcode was met, return true. */ return true; } /** * @brief Initialize the DWARF registers state by parsing and executing CIE instructions. * * @param cie Pointer to the CIE data. * @param frame Pointer to the execution frame. * @param state DWARF machine state (DWARF registers). * * @return index of the DWARF register containing the return address. */ static uint32_t esp_eh_frame_initialize_state(const uint8_t* cie, ExecutionFrame* frame, dwarf_regs* state) { char c = 0; uint32_t size = 0; /* The first word in the CIE structure is the length of the structure, * excluding this field itself. */ const uint32_t length = ((uint32_t*) cie)[0]; /* ID of the CIE, should be 0 for .eh_frame (which is our case) */ const uint32_t id = ((uint32_t*) cie)[1]; assert(id == 0); /* Ignore CIE version (1 byte). */ /* The following data in the structure have variable length as they are * encoded in (U)LEB128. Thus, let's use a byte pointer to parse them. */ uint8_t* cie_data = (uint8_t*) cie + ESP_CIE_VARIABLE_FIELDS_IDX; /* Next field is a null-terminated UTF-8 string. Ignore it, look for the end. */ while((c = *cie_data++) != 0); /* Field alignment factor shall be 1. It is encoded in ULEB128. */ const uint32_t code_align = decode_leb128(cie_data, false, &size); assert(code_align == 1); /* Jump to the next field */ cie_data += size; /* Same goes for data alignment factor. Shall be equal to -4. */ const int32_t data_align = decode_leb128(cie_data, true, &size); cie_data += size; assert(data_align == -4); /* Field describing the index of the DWARF register which will contain * the return address. */ const uint32_t ra_reg = decode_leb128(cie_data, false, &size); cie_data += size; /* Augmentation data length is encoded in ULEB128. It represents the, * length of the augmentation data. Jump after it to retrieve the * instructions to execute. */ const uint32_t augmentation_len = decode_leb128(cie_data, false, &size); cie_data += size + augmentation_len; /* Calculate the instructions length in order to prevent any out of bounds * bug. Subtract the offset of this field (minus sizeof(uint32_t) because * `length` field is not part of the structure length) to the total length * of the structure. */ const uint32_t instructions_length = length - (cie_data - sizeof(uint32_t) - cie); /* Execute the instructions contained in CIE structure. Their goal is to * initialize the DWARF registers. Usually it binds the CFA (virtual stack * pointer), to its hardware equivalent. It will also bind a hardware * register to the virtual return address register. For example, x86 * doesn't have a return address register, the address to return to * it stored on the stack when `call` instruction is used. DWARF will * use `eip` (instruction pointer, a.k.a. program counter) as a * register containing the return address register. */ esp_eh_frame_execute(cie_data, instructions_length, frame, state); return ra_reg; } /** * @brief Modify the execution frame and DWARF VM state for restoring caller's context. * * @param fde Pointer to the Frame Description Entry for the current program counter (defined by frame's MEPC register) * @param frame Snapshot of the CPU registers when the CPU stopped its normal execution. * @param state DWARF VM registers. * * @return Return Address of the current context. Frame has been restored to the previous context * (before calling the function program counter is currently going throught). */ static uint32_t esp_eh_frame_restore_caller_state(const uint32_t* fde, ExecutionFrame* frame, dwarf_regs* state) { /* Length of the whole Frame Description Entry (FDE), excluding this field. */ const uint32_t length = fde[ESP_FDE_LENGTH_IDX]; /* The addresses in FDE are relative to the location of each field. * Thus, to get the absolute address of the function it is pointing to, * we have to compute: * fun_addr = &fde[IDX] +/- fde[IDX] */ const uint8_t* cie = (uint8_t*) ((uint32_t) &fde[ESP_FDE_CIE_IDX] - fde[ESP_FDE_CIE_IDX]); const uint32_t initial_location = ((uint32_t) &fde[ESP_FDE_INITLOC_IDX] + fde[ESP_FDE_INITLOC_IDX]); const uint32_t range_length = fde[ESP_FDE_RANGELEN_IDX]; const uint8_t augmentation = *((uint8_t*) (fde + ESP_FDE_AUGMENTATION_IDX)); /* The length, in byte, of the instructions is the size of the FDE header minus * the above fields' length. */ const uint32_t instructions_length = length - 3 * sizeof(uint32_t) - sizeof(uint8_t); const uint8_t* instructions = ((uint8_t*) (fde + ESP_FDE_AUGMENTATION_IDX)) + 1; /* Make sure this FDE is the correct one for the PC given. */ assert(initial_location <= EXECUTION_FRAME_PC(*frame) && EXECUTION_FRAME_PC(*frame) < initial_location + range_length); /* Augmentation not supported. */ assert(augmentation == 0); /* Initialize the DWARF state by executing the CIE's instructions. */ const uint32_t ra_reg = esp_eh_frame_initialize_state(cie, frame, state); state->location = initial_location; /** * Execute the DWARf instructions is order to create rules that will be executed later to retrieve * the registers former value. */ bool success = esp_eh_frame_execute(instructions, instructions_length, frame, state); if (!success) { /* An error occured (unsupported opcode), return PC as the return address. * This will be tested by the caller, and the backtrace will be finished. */ return EXECUTION_FRAME_PC(*frame); } /* Execute the rules calculated previously. Start with the CFA. */ const uint32_t cfa_val = ESP_EH_FRAME_CFA(state); const uint32_t cfa_reg = ESP_EH_FRAME_GET_CFA_REG(cfa_val); const uint32_t cfa_off = ESP_EH_FRAME_GET_CFA_OFF(cfa_val); const uint32_t cfa_addr = EXECUTION_FRAME_REG(frame, cfa_reg) + cfa_off; /* Restore the registers that need to be restored. */ for (uint32_t i = 0; i < DIM(state->regs_offset[0]); i++) { uint32_t value_addr = state->regs_offset[state->offset_idx][i]; /* Check that the value changed and that we are not treating the CFA register (if it is part of the array). */ if (i != ESP_ESH_FRAME_CFA_IDX && value_addr != ESP_EH_FRAME_REG_SAME) { /* value_addr contains a description of how to find its address: * it has an offset relative to the CFA, which will point to the actual former value. * In fact, the register's previous value (in the context of the caller) is on the stack, * this is what value_addr will point to. */ value_addr = cfa_addr - ESP_EH_FRAME_GET_REG_OFFSET(value_addr) * sizeof(uint32_t); EXECUTION_FRAME_REG(frame, i) = *((uint32_t*) value_addr); } } /* Restore the stack pointer according to DWARF CFA register. */ EXECUTION_FRAME_SP(*frame) = cfa_addr; /* If the frame was not available, it would be possible to retrieve the return address * register thanks to CIE structure. * The return address points to the address the PC needs to jump to. It * does NOT point to the instruction where the routine call occured. * This can cause problems with functions without epilogue (i.e. function * which last instruction is a function call). This happens when compiler * optimization are ON or when a function is marked as "noreturn". * * Thus, in order to point to the call/jal instruction, we need to * subtract at least 1 byte but not more than an instruction size. */ return EXECUTION_FRAME_REG(frame, ra_reg) - 2; } /** * @brief Test whether the DWARF information for the given PC are missing or not. * * @param fde FDE associated to this PC. This FDE is the one found thanks to * `esp_eh_frame_find_entry()`. * @param pc PC to get information from. * * @return true is DWARF information are missing, false else. */ static bool esp_eh_frame_missing_info(const uint32_t* fde, uint32_t pc) { if (fde == NULL) { return true; } /* Get the range of this FDE entry. It is possible that there are some * gaps between DWARF entries, in that case, the FDE entry found has * indeed an initial_location very close to PC but doesn't reach it. * For example, if FDE initial_location is 0x40300000 and its length is * 0x100, but PC value is 0x40300200, then some DWARF information * are missing as there is a gap. * End the backtrace. */ const uint32_t initial_location = ((uint32_t) &fde[ESP_FDE_INITLOC_IDX] + fde[ESP_FDE_INITLOC_IDX]); const uint32_t range_length = fde[ESP_FDE_RANGELEN_IDX]; return (initial_location + range_length) <= pc; } /** * @brief When one step of the backtrace is generated, output it to the serial. * This function can be overriden as it is defined as weak. * * @param pc Program counter of the backtrace step. * @param sp Stack pointer of the backtrace step. */ void __attribute__((weak)) esp_eh_frame_generated_step(uint32_t pc, uint32_t sp) { panic_print_str(" 0x"); panic_print_hex(pc); panic_print_str(":0x"); panic_print_hex(sp); } /** * @brief Print backtrace for the given execution frame. * * @param frame_or Snapshot of the CPU registers when the CPU stopped its normal execution. */ void esp_eh_frame_print_backtrace(const void *frame_or) { assert(frame_or != NULL); static dwarf_regs state = { 0 }; ExecutionFrame frame = *((ExecutionFrame*) frame_or); uint32_t size = 0; uint8_t* enc_values = NULL; bool end_of_backtrace = false; /* Start parsing the .eh_frame_hdr section. */ fde_header* header = (fde_header*) EH_FRAME_HDR_ADDR; assert(header->version == 1); /* Make enc_values point to the end of the structure, where the encoded * values start. */ enc_values = (uint8_t*) (header + 1); /* Retrieve the encoded value eh_frame_ptr. Get the size of the data also. */ const uint32_t eh_frame_ptr = esp_eh_frame_get_encoded(enc_values, header->eh_frame_ptr_enc, &size); assert(eh_frame_ptr == (uint32_t) EH_FRAME_ADDR); enc_values += size; /* Same for the number of entries in the sorted table. */ const uint32_t fde_count = esp_eh_frame_get_encoded(enc_values, header->fde_count_enc, &size); enc_values += size; /* enc_values points now at the beginning of the sorted table. */ /* Only support 4-byte entries. */ const uint32_t table_enc = header->table_enc; assert(((table_enc >> 4) == 0x3) || ((table_enc >> 4) == 0xB)); const table_entry* sorted_table = (const table_entry*) enc_values; panic_print_str("Backtrace:"); while (!end_of_backtrace) { /* Output one step of the backtrace. */ esp_eh_frame_generated_step(EXECUTION_FRAME_PC(frame), EXECUTION_FRAME_SP(frame)); const table_entry* from_fun = esp_eh_frame_find_entry(sorted_table, fde_count, table_enc, EXECUTION_FRAME_PC(frame)); /* Get absolute address of FDE entry describing the function where PC left of. */ uint32_t* fde = NULL; if (from_fun != NULL) { fde = esp_eh_frame_decode_address(&from_fun->fde_addr, table_enc); } if (esp_eh_frame_missing_info(fde, EXECUTION_FRAME_PC(frame))) { /* Address was not found in the list. */ panic_print_str("\r\nBacktrace ended abruptly: cannot find DWARF information for" " instruction at address 0x"); panic_print_hex(EXECUTION_FRAME_PC(frame)); panic_print_str("\r\n"); break; } /* Clean and set the DWARF register structure. */ memset(&state, 0, sizeof(dwarf_regs)); const uint32_t prev_sp = EXECUTION_FRAME_SP(frame); /* Retrieve the return address of the frame. The frame's registers will be modified. * The frame we get then is the caller's one. */ uint32_t ra = esp_eh_frame_restore_caller_state(fde, &frame, &state); /* End of backtrace is reached if the stack and the PC don't change anymore. */ end_of_backtrace = (EXECUTION_FRAME_SP(frame) == prev_sp) && (EXECUTION_FRAME_PC(frame) == ra); /* Go back to the caller: update stack pointer and program counter. */ EXECUTION_FRAME_PC(frame) = ra; } panic_print_str("\r\n"); } #endif //ESP_SYSTEM_USE_EH_FRAME