1 /*
2 * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file DWARF Exception Frames parser
9 *
10 * This file performs parsing and execution of DWARF except frames described in
11 * section `.eh_frame` and `.eh_frame_hdr`. This is currently used on RISC-V
12 * boards to implement a complete backtracing when a panic occurs.
13 *
14 * More information about the sections structure and DWARF instructions can be
15 * found in the official documentation:
16 * http://dwarfstd.org/Download.php
17 */
18
19 #include "esp_private/eh_frame_parser.h"
20 #include "esp_private/panic_internal.h"
21 #include <string.h>
22
23 #if CONFIG_ESP_SYSTEM_USE_EH_FRAME
24
25 #include "eh_frame_parser_impl.h"
26
27 /**
28 * @brief Dimension of an array (number of elements)
29 */
30 #ifndef DIM
31 #define DIM(array) (sizeof(array)/sizeof(*array))
32 #endif
33
34 /**
35 * @brief DWARF Exception Header Encoding
36 * This is used to know how the data in .eh_frame and .eh_frame_hdr sections
37 * are encoded.
38 */
39 /* DWARF Exception Exception Header value format. */
40 #define DW_EH_PE_omit 0xff /*!< No value is present */
41 #define DW_EH_PE_uleb128 0x01 /*!< Unsigned value encoded in LEB128 (Little Endian Base 128). */
42 #define DW_EH_PE_udata2 0x02 /*!< Unsigned 16-bit value. */
43 #define DW_EH_PE_udata4 0x03 /*!< Unsigned 32-bit value. */
44 #define DW_EH_PE_udata8 0x04 /*!< Unsigned 64-bit value. */
45 #define DW_EH_PE_sleb128 0x09 /*!< Signed value encoded in LEB128 (Little Endian Base 128). */
46 #define DW_EH_PE_sdata2 0x0A /*!< Signed 16-bit value. */
47 #define DW_EH_PE_sdata4 0x0B /*!< Signed 32-bit value. */
48 #define DW_EH_PE_sdata8 0x0C /*!< Signed 64-bit value. */
49
50 /* DWARF Exception Exception Header value application.
51 * These values are in fact represented in the high nibble of a given data.
52 * For example:
53 * 0x3A describes the values as signed 16-bit offsets relative to .eh_frame_hdr section.
54 * 0x11 describes the values as unsigned value encoded in LEB128, relative to their location ion memory. */
55 #define DW_EH_PE_absptr 0x00 /*!< The value itself is a pointer, it is not an offset. */
56 #define DW_EH_PE_pcrel 0x01 /*!< The value is an offset, relative to its location in memory. */
57 #define DW_EH_PE_datarel 0x03 /*!< The value is an offset, relative to .eh_frame_hdr section. */
58
59 /* Macros simplifying testing relative offset data encoding. */
60 #define ESP_ENCODING_PC_REL(ENCODING) (((ENCODING >> 4) & 0xf) == DW_EH_PE_pcrel)
61 #define ESP_ENCODING_FRAME_HDR_REL(ENCODING) (((ENCODING >> 4) & 0xf) == DW_EH_PE_datarel)
62
63 /**
64 * @brief Call Frame Information (CIE) fields information.
65 * As the size of CIE is variable, the simplest way to described it is to
66 * have a pointer at the beginning of CIE structure and access the fields
67 * thanks to the index macros defined here.
68 */
69 #define ESP_CIE_VARIABLE_FIELDS_IDX (9) /*!< Offset, in bytes, where variable length fields start. */
70
71 /**
72 * @brief Frame Description Entry (FDE) fields index.
73 * For the same reasons as above, we prefer defining these macros rather than
74 * having a structure.
75 */
76 #define ESP_FDE_LENGTH_IDX (0) /*!< Length, in bytes, of the FDE excluding this field. 4 bytes field. */
77 #define ESP_FDE_CIE_IDX (1) /*!< Nearest preceding Common Information Entry (CIE) offset. 4 bytes field. */
78 #define ESP_FDE_INITLOC_IDX (2) /*!< Initial location (of the function) the FDE describes. Variable size (encoding in CIE). */
79 #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). */
80 #define ESP_FDE_AUGMENTATION_IDX (4) /*!< Augmentation data length. Unsigned LEB128. */
81
82 /**
83 * @brief Pointers to both .eh_frame_hdr and .eh_frame sections.
84 */
85 #define EH_FRAME_HDR_ADDR (&__eh_frame_hdr)
86 #define EH_FRAME_ADDR (&__eh_frame)
87
88 /**
89 * @brief Structure of .eh_frame_hdr section header.
90 */
91 typedef struct {
92 uint8_t version; /*!< Structure version, must be 1.*/
93 uint8_t eh_frame_ptr_enc; /*!< eh_frame_ptr entry encoding. */
94 uint8_t fde_count_enc; /*!< fde_count entry encoding. */
95 uint8_t table_enc; /*!< table entries encoding. */
96 /* The rest of the structure has variable length. Thus, we cannot define
97 * them here. Here are their names:
98 * - eh_frame_ptr : encoded pointer to the .eh_frame section.
99 * - fde_Count : number of entries in the array of table_entry.
100 * - table_entry array : sorted array of table_entry. */
101 } __attribute__((packed)) fde_header;
102
103 /**
104 * @brief .eh_frame_hdr table's entry format.
105 * Each entry of the table contains 2 32-bit encoded addresses.
106 * Encoding is defined in the previous structure. Check table_enc field.
107 */
108 typedef struct {
109 uint32_t fun_addr; /*!< Address of the function described. */
110 uint32_t fde_addr; /*!< Address of the FDE for the function.*/
111 } table_entry;
112
113 /**
114 * @brief DWARF state constant macros.
115 */
116 #define ESP_EH_FRAME_STACK_SIZE (2) /*!< DWARF virtual machine can save the push the current on a virtual
117 stack. we mimic the stack with an array. While testing, a stack
118 size of 2 was enough. */
119
120 /**
121 * @brief
122 * Structure representing the state of the DWARF virtual machine.
123 */
124 typedef struct {
125 /* Stack for DWARF state registers.
126 * For caller saved registers, save their CFA address (value in previous call frame).
127 * As these registers will be used to define offset in the CFA, they will always be
128 * multiple of CPU word (4-bytes in our case). Thus, it will save the offset in word-size, not
129 * in bytes. Plus, the highest bit will be used to mark that this register is NOY
130 * ESP_EH_FRAME_REG_SAME. (0x80000000 is a valid value then, meaning that the register value
131 * is CFA + 0 offset) */
132 uint32_t regs_offset[ESP_EH_FRAME_STACK_SIZE][EXECUTION_FRAME_MAX_REGS];
133 /* reg_offset represents the state of registers when PC reaches the following location. */
134 uint32_t location;
135 /* Index of the registers offset to use (1 for saved offset, 0 else). */
136 uint8_t offset_idx;
137 } dwarf_regs;
138
139 /**
140 * @brief DWARF's register state.
141 * When a DWARF register is set to ESP_EH_FRAME_REG_SAME, the CPU register corresponding to this
142 * virtual register will be unchanged after executing DWARF instructions.
143 * Please see esp_eh_frame_restore_caller_state() for more details.
144 */
145 #define ESP_EH_FRAME_REG_SAME (0)
146
147 /**
148 * @brief Set a register's offset (relative to CFA).
149 * The highest bit is set to 1 to mark that this register needs to be retrived because it has been
150 * altered.
151 */
152 #define ESP_EH_FRAME_SET_REG_OFFSET(offset) (0x80000000 | offset)
153
154 /**
155 * @brief Get a register's offset (relative to CFA).
156 */
157 #define ESP_EH_FRAME_GET_REG_OFFSET(offset) (0x7fffffff & offset)
158
159 /**
160 * @brief Get a register's CFA offset.
161 */
162 #define ESP_EH_FRAME_IS_CFA_RELATIVE(reg) ((reg >> 31) == 1)
163
164 /**
165 * @brief Test whether an offset is small enough to be stored
166 * in our 32-bit register.
167 * Note: the highest bit is used.
168 */
169 #define ESP_EH_FRAME_CFA_OFFSET_VALID(offset) (offset < 0x80000000)
170
171 /**
172 * @brief Index of Call Frame Address (CFA) in DWARF registers array.
173 */
174 #define ESP_ESH_FRAME_CFA_IDX (EXECUTION_FRAME_SP_REG)
175
176 /**
177 * @brief Macros to get and set CFA's relative register and offset.
178 * Indeed, CFA is defined by two values: register and offset. CFA is then
179 * calculated by adding the offset to the register value.
180 * `register` will be stored in the lowest 8 bits.
181 * `offset` will be stored in the highest 24 bits.
182 *
183 * NOTE: with this implementation, CFA will be affected by
184 * DW_CFA_REMEMBER_STATE and DW_CFA_RESTORE_STATE instructions.
185 */
186 #if EXECUTION_FRAME_MAX_REGS > 255
187 #error "Too many registers defined for the target ExecutionFrame"
188 #endif
189 #define ESP_EH_FRAME_CFA_REG_VALID(reg) (reg < EXECUTION_FRAME_MAX_REGS)
190 #define ESP_EH_FRAME_CFA_OFF_VALID(off) (((off) >> 24) == 0)
191 #define ESP_EH_FRAME_CFA(state) ((state)->regs_offset[(state)->offset_idx][ESP_ESH_FRAME_CFA_IDX])
192
193 #define ESP_EH_FRAME_NEW_CFA(reg, off) (((off) << 8) | ((reg) & 0xff))
194 #define ESP_EH_FRAME_SET_CFA_REG(value, reg) (((value) & ~0xff) | ((reg) & 0xff))
195 #define ESP_EH_FRAME_SET_CFA_OFF(value, off) (((value) & 0xff) | ((off) << 8))
196 #define ESP_EH_FRAME_GET_CFA_REG(value) ((value) & 0xff)
197 #define ESP_EH_FRAME_GET_CFA_OFF(value) ((value) >> 8)
198
199
200 /**
201 * @brief Unsupported opcode value to return when exeucting 0-opcode type instructions.
202 */
203 #define ESP_EH_FRAME_UNSUPPORTED_OPCODE ((uint32_t) -1)
204
205 /**
206 * @brief Macros defining the DWARF instructions code.
207 */
208 #define DW_GET_OPCODE(OP) ((OP) >> 6)
209 #define DW_GET_PARAM(OP) ((OP) & 0b111111)
210 #define DW_CFA_ADVANCE_LOC (1)
211 #define DW_CFA_OFFSET (2)
212 #define DW_CFA_RESTORE (3)
213 /**
214 * @brief Constant for DWARF instructions code when high 2 bits are 0.
215 */
216 #define DW_CFA_0_OPCODE (0)
217 #define DW_CFA_NOP (0x0)
218 #define DW_CFA_SET_LOC (0x1)
219 #define DW_CFA_ADVANCE_LOC1 (0x2)
220 #define DW_CFA_ADVANCE_LOC2 (0x3)
221 #define DW_CFA_ADVANCE_LOC4 (0x4)
222 #define DW_CFA_OFFSET_EXTENDED (0x5)
223 #define DW_CFA_RESTORE_EXTENDED (0x6)
224 #define DW_CFA_UNDEFINED (0x7)
225 #define DW_CFA_SAME_VALUE (0x8)
226 #define DW_CFA_REGISTER (0x9)
227 #define DW_CFA_REMEMBER_STATE (0xA)
228 #define DW_CFA_RESTORE_STATE (0xB)
229 #define DW_CFA_DEF_CFA (0xC)
230 #define DW_CFA_DEF_CFA_REGISTER (0xD)
231 #define DW_CFA_DEF_CFA_OFFSET (0xE)
232 #define DW_CFA_DEF_CFA_EXPRESSION (0xF)
233 #define DW_CFA_EXPRESSION (0x10)
234 #define DW_CFA_OFFSET_EXTENDED_SF (0x11)
235 #define DW_CFA_DEF_CFA_SF (0x12)
236 #define DW_CFA_DEF_CFA_OFFSET_SF (0x13)
237 #define DW_CFA_VAL_OFFSET (0x14)
238 #define DW_CFA_VAL_OFFSET_SF (0x15)
239 #define DW_CFA_VAL_EXPRESSION (0x16)
240 #define DW_CFA_LO_USER (0x1C)
241
242 /**
243 * @brief Constants used for decoding (U)LEB128 integers.
244 */
245 #define DW_LEB128_HIGHEST_BIT(byte) (((byte) >> 7) & 1)
246 #define DW_LEB128_SIGN_BIT(byte) (((byte) >> 6) & 1)
247 #define DW_LEB128_MAX_SHIFT (31)
248
249
250 /**
251 * @brief Symbols defined by the linker.
252 * Retrieve the addresses of both .eh_frame_hdr and .eh_frame sections.
253 */
254 extern char __eh_frame_hdr;
255 extern char __eh_frame;
256
257 /**
258 * @brief Decode multiple bytes encoded in LEB128.
259 *
260 * @param bytes bytes encoded in LEB128. They will not be modified.
261 * @param is_signed true if bytes represent a signed value, false else.
262 * @param size Size in bytes of the encoded value.
263 *
264 * @return Decoded bytes.
265 */
decode_leb128(const uint8_t * bytes,bool is_signed,uint32_t * lebsize)266 static uint32_t decode_leb128(const uint8_t* bytes, bool is_signed, uint32_t* lebsize)
267 {
268 uint32_t res = 0;
269 uint32_t shf = 0;
270 uint32_t size = 0;
271 uint8_t byte = 0;
272
273 while(1) {
274 byte = bytes[size++];
275 res |= (byte & 0x7f) << shf;
276 shf += 7;
277 if (DW_LEB128_HIGHEST_BIT(byte) == 0)
278 break;
279 }
280
281 if (is_signed && shf <= DW_LEB128_MAX_SHIFT && DW_LEB128_SIGN_BIT(byte)) {
282 res |= ((uint32_t) ~0 << shf);
283 }
284
285 if (lebsize) {
286 *lebsize = size;
287 }
288
289 return res;
290 }
291
292 /**
293 * @brief Get the value of data encoded.
294 *
295 * @param data Pointer to the encoded data.
296 * @param encoding Encoding for the data to read.
297 * @param psize Reference to be filled with data size, in bytes.
298 *
299 * @return Decoded data read from the pointer.
300 */
esp_eh_frame_get_encoded(void * data,uint8_t encoding,uint32_t * psize)301 static uint32_t esp_eh_frame_get_encoded(void* data, uint8_t encoding, uint32_t* psize)
302 {
303 int32_t svalue = 0;
304 uint32_t uvalue = 0;
305 uint32_t fvalue = 0;
306 uint32_t size = 0;
307 const uint32_t high = encoding >> 4;
308 const uint32_t low = encoding & 0xf;
309
310 assert(psize != NULL);
311
312 if (encoding == DW_EH_PE_omit) {
313 *psize = size;
314 return uvalue;
315 }
316
317 switch (low) {
318 case DW_EH_PE_udata2:
319 size = 2;
320 uvalue = *((uint16_t*) data);
321 break;
322 case DW_EH_PE_udata4:
323 size = 4;
324 uvalue = *((uint32_t*) data);
325 break;
326 case DW_EH_PE_sdata2:
327 size = 2;
328 svalue = *((int16_t*) data);
329 break;
330 case DW_EH_PE_sdata4:
331 size = 4;
332 svalue = *((int32_t*) data);
333 break;
334 default:
335 /* Unsupported yet. */
336 assert(false);
337 break;
338 }
339
340 switch (high) {
341 case DW_EH_PE_absptr:
342 /* Do not change the values, as one of them will be 0, fvalue will
343 * contain the data no matter whether it is signed or unsigned. */
344 fvalue = svalue + uvalue;
345 break;
346 case DW_EH_PE_pcrel:
347 /* Relative to the address of the data.
348 * svalue has been casted to an 32-bit value, so even if it was a
349 * 2-byte signed value, fvalue will be calculated correctly here. */
350 fvalue = (uint32_t) data + svalue + uvalue;
351 break;
352 case DW_EH_PE_datarel:
353 fvalue = (uint32_t) EH_FRAME_HDR_ADDR + svalue + uvalue;
354 break;
355 }
356
357 *psize = size;
358 return fvalue;
359 }
360
361 /**
362 * @brief Find entry in the table for the given return_address.
363 *
364 * @param sorted_table Pointer to the sorted table of entries.
365 * @param length Number of entries in the table.
366 * @param encoding Encoding for the addresses in the table
367 * (Check DWARF documentation for more info about encoding).
368 * @param return_address The address to find in the table. This address can be
369 * part of one in the function listed.
370 *
371 * @note The table is structured like this (after decoding the addresses):
372 * Function address FDE address Index
373 * +-------------------------------+
374 * |0x403805a4 0x4038d014| 0
375 * +-------------------------------+
376 * |0x403805be 0x4038d034| 1
377 * +-------------------------------+
378 * |0x403805d8 0x4038d070| 2
379 * +-------------------------------+
380 * |.......... ..........| ...
381 * +-------------------------------+
382 * |0x42020c48 0x4038ddb4| length-3
383 * +-------------------------------+
384 * |0x42020dca 0x4038dde4| length-2
385 *+-------------------------------+
386 * |0x42020f92 0x4038debc| length-1
387 * +-------------------------------+
388 *
389 * For example, if return_address passed is 0x403805b4, this function will
390 * return a pointer to the entry (0x403805a4, 0x4038d014).
391 *
392 * @return Pointer to the entry found, NULL if not found.
393 */
esp_eh_frame_find_entry(const table_entry * sorted_table,const uint32_t length,const uint32_t encoding,const uint32_t return_address)394 static const table_entry* esp_eh_frame_find_entry(const table_entry* sorted_table,
395 const uint32_t length,
396 const uint32_t encoding,
397 const uint32_t return_address)
398 {
399 int32_t ra = 0;
400
401 /* Used for decoding addresses in the table. */
402 uint32_t is_signed = (encoding & 0xf) >= 0x9;
403 uint32_t pc_relative = true;
404
405 /* The following local variables are used for dichotomic search. */
406 uint32_t found = false;
407 uint32_t begin = 0;
408 uint32_t end = length;
409 uint32_t middle = (end + begin) / 2;
410
411 /* If the addresses in the table are offsets relative to the eh_frame section,
412 * instead of decoding each of them, we can simply encode the return_address
413 * we have to find. If addresses are offsets relative to the programe counter,
414 * then we have no other choice than decoding each of them to compare them
415 * with return_address. */
416 if (ESP_ENCODING_FRAME_HDR_REL(encoding)) {
417 ra = return_address - (uint32_t) EH_FRAME_HDR_ADDR;
418 pc_relative = false;
419 }
420
421 /* Perform dichotomic search. */
422 while (end != 0 && middle != (length - 1) && !found) {
423 const uint32_t fun_addr = sorted_table[middle].fun_addr;
424 const uint32_t nxt_addr = sorted_table[middle + 1].fun_addr;
425
426 if (pc_relative) {
427 ra = return_address - (uint32_t) (sorted_table + middle);
428 }
429
430 if (is_signed) {
431 /* Signed comparisons. */
432 const int32_t sfun_addr = (int32_t) fun_addr;
433 const int32_t snxt_addr = (int32_t) nxt_addr;
434 if (sfun_addr <= ra && snxt_addr > ra)
435 found = true;
436 else if (snxt_addr <= ra)
437 begin = middle + 1;
438 else
439 end = middle;
440
441 } else {
442 /* Unsigned comparisons. */
443 const uint32_t ura = (uint32_t) ra;
444 if (fun_addr <= ura && nxt_addr > ura)
445 found = true;
446 else if (nxt_addr <= ura)
447 begin = middle + 1;
448 else
449 end = middle;
450 }
451
452 middle = (end + begin) / 2;
453 }
454
455 /* If 'end' reached the beginning of the array, it means the return_address
456 * passed was below the first address of the array, thus, it was wrong.
457 * Else, return the address found. */
458 return (end == 0) ? 0 : sorted_table + middle;
459 }
460
461 /**
462 * @brief Decode an address according to the encoding passed.
463 *
464 * @param addr Pointer to the address to decode.
465 * This pointer's value MUST be an address in .eh_frame_hdr section.
466 * @param encoding DWARF encoding byte.
467 *
468 * @return address dedoded (e.g. absolute address)
469 */
esp_eh_frame_decode_address(const uint32_t * addr,const uint32_t encoding)470 static inline uint32_t* esp_eh_frame_decode_address(const uint32_t* addr,
471 const uint32_t encoding)
472 {
473 uint32_t* decoded = 0;
474
475 if (ESP_ENCODING_FRAME_HDR_REL(encoding))
476 decoded = (uint32_t*) (*addr + (uint32_t) EH_FRAME_HDR_ADDR);
477 else if (ESP_ENCODING_PC_REL(encoding))
478 decoded = (uint32_t*) (*addr + (uint32_t) addr);
479 else
480 decoded = (uint32_t*) (*addr);
481
482 return decoded;
483 }
484
485 /**
486 * @brief Execute the DWARF instruction which high 2 bits are 0.
487 *
488 * @param opcode low 6 bits of the instruction code.
489 * @param operands pointer to the possible operands.
490 * @param state state of the DWARF machine. Its registers may be modified.
491 *
492 * @return Number of operands used for executing the instruction.
493 */
esp_eh_frame_execute_opcode_0(const uint32_t opcode,const uint8_t * operands,dwarf_regs * state)494 static inline uint32_t esp_eh_frame_execute_opcode_0(const uint32_t opcode, const uint8_t* operands,
495 dwarf_regs* state)
496 {
497 uint32_t operand1 = 0;
498 uint32_t used_operands = 0;
499 uint32_t operand2 = 0;
500 uint32_t used_operands2 = 0;
501
502 switch(opcode) {
503 case DW_CFA_NOP:
504 break;
505 case DW_CFA_ADVANCE_LOC1:
506 /* Advance location with a 1-byte delta. */
507 used_operands = 1;
508 state->location += *operands;
509 break;
510 case DW_CFA_ADVANCE_LOC2:
511 /* Advance location with a 2-byte delta. */
512 used_operands = 2;
513 state->location += *((const uint16_t*) operands);
514 break;
515 case DW_CFA_ADVANCE_LOC4:
516 /* Advance location with a 4-byte delta. */
517 used_operands = 4;
518 state->location += *((const uint32_t*) operands);
519 break;
520 case DW_CFA_REMEMBER_STATE:
521 assert(state->offset_idx == 0);
522 memcpy(state->regs_offset[1], state->regs_offset[0],
523 EXECUTION_FRAME_MAX_REGS * sizeof(uint32_t));
524 state->offset_idx++;
525 break;
526 case DW_CFA_RESTORE_STATE:
527 assert(state->offset_idx == 1);
528 /* Drop the saved state. */
529 state->offset_idx--;
530 break;
531 case DW_CFA_DEF_CFA:
532 /* CFA changes according to a register and an offset.
533 * This instruction appears when the assembly code saves the
534 * SP in the middle of a routine, before modifying it.
535 * For example (on RISC-V):
536 * addi s0, sp, 80
537 * addi sp, sp, -10
538 * ... */
539 /* Operand1 is the register containing the CFA value. */
540 operand1 = decode_leb128(operands, false, &used_operands);
541 /* Offset for the register's value. */
542 operand2 = decode_leb128(operands + used_operands, false, &used_operands2);
543 /* Calculate the number of bytes */
544 used_operands += used_operands2;
545 /* Assert that the register and the offset are valid. */
546 assert(ESP_EH_FRAME_CFA_REG_VALID(operand1));
547 assert(ESP_EH_FRAME_CFA_OFF_VALID(operand2));
548 ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_NEW_CFA(operand1, operand2);
549 break;
550 case DW_CFA_DEF_CFA_REGISTER:
551 /* Define the register of the current frame address (CFA).
552 * Its operand is in the next bytes, its type is ULEB128. */
553 operand1 = decode_leb128(operands, false, &used_operands);
554 /* Check whether the value is valid or not. */
555 assert(ESP_EH_FRAME_CFA_OFF_VALID(operand1));
556 /* Offset will be unchanged, only register changes. */
557 ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_SET_CFA_REG(ESP_EH_FRAME_CFA(state), operand1);
558 break;
559 case DW_CFA_DEF_CFA_OFFSET:
560 /* Same as above but for the offset. The register of CFA remains unchanged. */
561 operand1 = decode_leb128(operands, false, &used_operands);
562 assert(ESP_EH_FRAME_CFA_OFF_VALID(operand1));
563 ESP_EH_FRAME_CFA(state) = ESP_EH_FRAME_SET_CFA_OFF(ESP_EH_FRAME_CFA(state), operand1);
564 break;
565 default:
566 panic_print_str("\r\nUnsupported DWARF opcode 0: 0x");
567 panic_print_hex(opcode);
568 panic_print_str("\r\n");
569 used_operands = ESP_EH_FRAME_UNSUPPORTED_OPCODE;
570 break;
571 }
572
573 return used_operands;
574 }
575
576
577 /**
578 * @brief Execute DWARF instructions.
579 *
580 * @param instructions Array of instructions to execute.
581 * @param instructions_length Length of the array of instructions.
582 * @param frame Execution frame of the crashed task. This will only be used to
583 * get the PC where the task crashed.
584 * @param state DWARF machine state. The registers contained in the state will
585 * modified accordingly to the instructions.
586 *
587 * @return true if the execution went fine, false if an unsupported instruction was met.
588 */
esp_eh_frame_execute(const uint8_t * instructions,const uint32_t instructions_length,const ExecutionFrame * frame,dwarf_regs * state)589 static bool esp_eh_frame_execute(const uint8_t* instructions, const uint32_t instructions_length,
590 const ExecutionFrame* frame, dwarf_regs* state)
591 {
592 for (uint32_t i = 0; i < instructions_length; i++) {
593 const uint8_t instr = instructions[i];
594 const uint8_t param = DW_GET_PARAM(instr);
595 uint32_t operand1 = 0;
596 uint32_t size = 0;
597 uint32_t used_operands = 0;
598
599 /* Decode the instructions. According to DWARF documentation, there are three
600 * types of Call Frame Instructions. The upper 2 bits defines the type. */
601 switch (DW_GET_OPCODE(instr)) {
602 case DW_CFA_0_OPCODE:
603 used_operands = esp_eh_frame_execute_opcode_0(param, &instructions[i + 1], state);
604 /* Exit the function if an unsupported opcode was met. */
605 if (used_operands == ESP_EH_FRAME_UNSUPPORTED_OPCODE) {
606 return false;
607 }
608 i += used_operands;
609 break;
610 case DW_CFA_ADVANCE_LOC:
611 /* Move the location forward. This instruction will mark when to stop:
612 * once we reach the instruction where the PC left, we can break out of the loop
613 * The delta is part of the lowest 6 bits.
614 */
615 state->location += param;
616 break;
617 case DW_CFA_OFFSET:
618 operand1 = decode_leb128(&instructions[i + 1], false, &size);
619 assert(ESP_EH_FRAME_CFA_OFFSET_VALID(operand1));
620 state->regs_offset[state->offset_idx][param] = ESP_EH_FRAME_SET_REG_OFFSET(operand1);
621 i += size;
622 break;
623
624 case DW_CFA_RESTORE:
625 state->regs_offset[state->offset_idx][param] = ESP_EH_FRAME_REG_SAME;
626 break;
627 default:
628 /* Illegal opcode */
629 assert(false);
630 break;
631 }
632
633 /* As the state->location can also be modified by 0-opcode instructions (in the function)
634 * and also because we need to break the loop (and not only the switch), let's put this
635 * check here, after the execution of the instruction, outside of the switch block. */
636 if (state->location >= EXECUTION_FRAME_PC(*frame))
637 break;
638 }
639
640 /* Everything went fine, no unsupported opcode was met, return true. */
641 return true;
642 }
643
644 /**
645 * @brief Initialize the DWARF registers state by parsing and executing CIE instructions.
646 *
647 * @param cie Pointer to the CIE data.
648 * @param frame Pointer to the execution frame.
649 * @param state DWARF machine state (DWARF registers).
650 *
651 * @return index of the DWARF register containing the return address.
652 */
esp_eh_frame_initialize_state(const uint8_t * cie,ExecutionFrame * frame,dwarf_regs * state)653 static uint32_t esp_eh_frame_initialize_state(const uint8_t* cie, ExecutionFrame* frame, dwarf_regs* state)
654 {
655 char c = 0;
656 uint32_t size = 0;
657
658 /* The first word in the CIE structure is the length of the structure,
659 * excluding this field itself. */
660 const uint32_t length = ((uint32_t*) cie)[0];
661
662 /* ID of the CIE, should be 0 for .eh_frame (which is our case) */
663 const uint32_t id = ((uint32_t*) cie)[1];
664 assert(id == 0);
665
666 /* Ignore CIE version (1 byte). */
667
668 /* The following data in the structure have variable length as they are
669 * encoded in (U)LEB128. Thus, let's use a byte pointer to parse them. */
670 uint8_t* cie_data = (uint8_t*) cie + ESP_CIE_VARIABLE_FIELDS_IDX;
671
672 /* Next field is a null-terminated UTF-8 string. Ignore it, look for the end. */
673 while((c = *cie_data++) != 0);
674
675 /* Field alignment factor shall be 1. It is encoded in ULEB128. */
676 const uint32_t code_align = decode_leb128(cie_data, false, &size);
677 assert(code_align == 1);
678 /* Jump to the next field */
679 cie_data += size;
680
681 /* Same goes for data alignment factor. Shall be equal to -4. */
682 const int32_t data_align = decode_leb128(cie_data, true, &size);
683 cie_data += size;
684 assert(data_align == -4);
685
686 /* Field describing the index of the DWARF register which will contain
687 * the return address. */
688 const uint32_t ra_reg = decode_leb128(cie_data, false, &size);
689 cie_data += size;
690
691 /* Augmentation data length is encoded in ULEB128. It represents the,
692 * length of the augmentation data. Jump after it to retrieve the
693 * instructions to execute. */
694 const uint32_t augmentation_len = decode_leb128(cie_data, false, &size);
695 cie_data += size + augmentation_len;
696
697 /* Calculate the instructions length in order to prevent any out of bounds
698 * bug. Subtract the offset of this field (minus sizeof(uint32_t) because
699 * `length` field is not part of the structure length) to the total length
700 * of the structure. */
701 const uint32_t instructions_length = length - (cie_data - sizeof(uint32_t) - cie);
702
703 /* Execute the instructions contained in CIE structure. Their goal is to
704 * initialize the DWARF registers. Usually it binds the CFA (virtual stack
705 * pointer), to its hardware equivalent. It will also bind a hardware
706 * register to the virtual return address register. For example, x86
707 * doesn't have a return address register, the address to return to
708 * it stored on the stack when `call` instruction is used. DWARF will
709 * use `eip` (instruction pointer, a.k.a. program counter) as a
710 * register containing the return address register. */
711 esp_eh_frame_execute(cie_data, instructions_length, frame, state);
712
713 return ra_reg;
714 }
715
716 /**
717 * @brief Modify the execution frame and DWARF VM state for restoring caller's context.
718 *
719 * @param fde Pointer to the Frame Description Entry for the current program counter (defined by frame's MEPC register)
720 * @param frame Snapshot of the CPU registers when the CPU stopped its normal execution.
721 * @param state DWARF VM registers.
722 *
723 * @return Return Address of the current context. Frame has been restored to the previous context
724 * (before calling the function program counter is currently going throught).
725 */
esp_eh_frame_restore_caller_state(const uint32_t * fde,ExecutionFrame * frame,dwarf_regs * state)726 static uint32_t esp_eh_frame_restore_caller_state(const uint32_t* fde,
727 ExecutionFrame* frame,
728 dwarf_regs* state)
729 {
730 /* Length of the whole Frame Description Entry (FDE), excluding this field. */
731 const uint32_t length = fde[ESP_FDE_LENGTH_IDX];
732
733 /* The addresses in FDE are relative to the location of each field.
734 * Thus, to get the absolute address of the function it is pointing to,
735 * we have to compute:
736 * fun_addr = &fde[IDX] +/- fde[IDX]
737 */
738 const uint8_t* cie = (uint8_t*) ((uint32_t) &fde[ESP_FDE_CIE_IDX] - fde[ESP_FDE_CIE_IDX]);
739 const uint32_t initial_location = ((uint32_t) &fde[ESP_FDE_INITLOC_IDX] + fde[ESP_FDE_INITLOC_IDX]);
740 const uint32_t range_length = fde[ESP_FDE_RANGELEN_IDX];
741 const uint8_t augmentation = *((uint8_t*) (fde + ESP_FDE_AUGMENTATION_IDX));
742
743 /* The length, in byte, of the instructions is the size of the FDE header minus
744 * the above fields' length. */
745 const uint32_t instructions_length = length - 3 * sizeof(uint32_t) - sizeof(uint8_t);
746 const uint8_t* instructions = ((uint8_t*) (fde + ESP_FDE_AUGMENTATION_IDX)) + 1;
747
748 /* Make sure this FDE is the correct one for the PC given. */
749 assert(initial_location <= EXECUTION_FRAME_PC(*frame) &&
750 EXECUTION_FRAME_PC(*frame) < initial_location + range_length);
751
752 /* Augmentation not supported. */
753 assert(augmentation == 0);
754
755 /* Initialize the DWARF state by executing the CIE's instructions. */
756 const uint32_t ra_reg = esp_eh_frame_initialize_state(cie, frame, state);
757 state->location = initial_location;
758
759 /**
760 * Execute the DWARf instructions is order to create rules that will be executed later to retrieve
761 * the registers former value.
762 */
763 bool success = esp_eh_frame_execute(instructions, instructions_length, frame, state);
764 if (!success) {
765 /* An error occured (unsupported opcode), return PC as the return address.
766 * This will be tested by the caller, and the backtrace will be finished. */
767 return EXECUTION_FRAME_PC(*frame);
768 }
769
770 /* Execute the rules calculated previously. Start with the CFA. */
771 const uint32_t cfa_val = ESP_EH_FRAME_CFA(state);
772 const uint32_t cfa_reg = ESP_EH_FRAME_GET_CFA_REG(cfa_val);
773 const uint32_t cfa_off = ESP_EH_FRAME_GET_CFA_OFF(cfa_val);
774 const uint32_t cfa_addr = EXECUTION_FRAME_REG(frame, cfa_reg) + cfa_off;
775
776 /* Restore the registers that need to be restored. */
777 for (uint32_t i = 0; i < DIM(state->regs_offset[0]); i++) {
778 uint32_t value_addr = state->regs_offset[state->offset_idx][i];
779 /* Check that the value changed and that we are not treating the CFA register (if it is part of the array). */
780 if (i != ESP_ESH_FRAME_CFA_IDX && value_addr != ESP_EH_FRAME_REG_SAME) {
781 /* value_addr contains a description of how to find its address:
782 * it has an offset relative to the CFA, which will point to the actual former value.
783 * In fact, the register's previous value (in the context of the caller) is on the stack,
784 * this is what value_addr will point to. */
785 value_addr = cfa_addr - ESP_EH_FRAME_GET_REG_OFFSET(value_addr) * sizeof(uint32_t);
786 EXECUTION_FRAME_REG(frame, i) = *((uint32_t*) value_addr);
787 }
788 }
789
790 /* Restore the stack pointer according to DWARF CFA register. */
791 EXECUTION_FRAME_SP(*frame) = cfa_addr;
792
793 /* If the frame was not available, it would be possible to retrieve the return address
794 * register thanks to CIE structure.
795 * The return address points to the address the PC needs to jump to. It
796 * does NOT point to the instruction where the routine call occured.
797 * This can cause problems with functions without epilogue (i.e. function
798 * which last instruction is a function call). This happens when compiler
799 * optimization are ON or when a function is marked as "noreturn".
800 *
801 * Thus, in order to point to the call/jal instruction, we need to
802 * subtract at least 1 byte but not more than an instruction size.
803 */
804 return EXECUTION_FRAME_REG(frame, ra_reg) - 2;
805 }
806
807 /**
808 * @brief Test whether the DWARF information for the given PC are missing or not.
809 *
810 * @param fde FDE associated to this PC. This FDE is the one found thanks to
811 * `esp_eh_frame_find_entry()`.
812 * @param pc PC to get information from.
813 *
814 * @return true is DWARF information are missing, false else.
815 */
esp_eh_frame_missing_info(const uint32_t * fde,uint32_t pc)816 static bool esp_eh_frame_missing_info(const uint32_t* fde, uint32_t pc) {
817 if (fde == NULL) {
818 return true;
819 }
820
821 /* Get the range of this FDE entry. It is possible that there are some
822 * gaps between DWARF entries, in that case, the FDE entry found has
823 * indeed an initial_location very close to PC but doesn't reach it.
824 * For example, if FDE initial_location is 0x40300000 and its length is
825 * 0x100, but PC value is 0x40300200, then some DWARF information
826 * are missing as there is a gap.
827 * End the backtrace. */
828 const uint32_t initial_location = ((uint32_t) &fde[ESP_FDE_INITLOC_IDX] + fde[ESP_FDE_INITLOC_IDX]);
829 const uint32_t range_length = fde[ESP_FDE_RANGELEN_IDX];
830
831 return (initial_location + range_length) <= pc;
832 }
833
834 /**
835 * @brief When one step of the backtrace is generated, output it to the serial.
836 * This function can be overriden as it is defined as weak.
837 *
838 * @param pc Program counter of the backtrace step.
839 * @param sp Stack pointer of the backtrace step.
840 */
esp_eh_frame_generated_step(uint32_t pc,uint32_t sp)841 void __attribute__((weak)) esp_eh_frame_generated_step(uint32_t pc, uint32_t sp)
842 {
843 panic_print_str(" 0x");
844 panic_print_hex(pc);
845 panic_print_str(":0x");
846 panic_print_hex(sp);
847 }
848
849 /**
850 * @brief Print backtrace for the given execution frame.
851 *
852 * @param frame_or Snapshot of the CPU registers when the CPU stopped its normal execution.
853 */
esp_eh_frame_print_backtrace(const void * frame_or)854 void esp_eh_frame_print_backtrace(const void *frame_or)
855 {
856 assert(frame_or != NULL);
857
858 static dwarf_regs state = { 0 };
859 ExecutionFrame frame = *((ExecutionFrame*) frame_or);
860 uint32_t size = 0;
861 uint8_t* enc_values = NULL;
862 bool end_of_backtrace = false;
863
864 /* Start parsing the .eh_frame_hdr section. */
865 fde_header* header = (fde_header*) EH_FRAME_HDR_ADDR;
866 assert(header->version == 1);
867
868 /* Make enc_values point to the end of the structure, where the encoded
869 * values start. */
870 enc_values = (uint8_t*) (header + 1);
871
872 /* Retrieve the encoded value eh_frame_ptr. Get the size of the data also. */
873 const uint32_t eh_frame_ptr = esp_eh_frame_get_encoded(enc_values, header->eh_frame_ptr_enc, &size);
874 assert(eh_frame_ptr == (uint32_t) EH_FRAME_ADDR);
875 enc_values += size;
876
877 /* Same for the number of entries in the sorted table. */
878 const uint32_t fde_count = esp_eh_frame_get_encoded(enc_values, header->fde_count_enc, &size);
879 enc_values += size;
880
881 /* enc_values points now at the beginning of the sorted table. */
882 /* Only support 4-byte entries. */
883 const uint32_t table_enc = header->table_enc;
884 assert(((table_enc >> 4) == 0x3) || ((table_enc >> 4) == 0xB));
885
886 const table_entry* sorted_table = (const table_entry*) enc_values;
887
888 panic_print_str("Backtrace:");
889 while (!end_of_backtrace) {
890
891 /* Output one step of the backtrace. */
892 esp_eh_frame_generated_step(EXECUTION_FRAME_PC(frame), EXECUTION_FRAME_SP(frame));
893
894 const table_entry* from_fun = esp_eh_frame_find_entry(sorted_table, fde_count,
895 table_enc, EXECUTION_FRAME_PC(frame));
896
897 /* Get absolute address of FDE entry describing the function where PC left of. */
898 uint32_t* fde = NULL;
899
900 if (from_fun != NULL) {
901 fde = esp_eh_frame_decode_address(&from_fun->fde_addr, table_enc);
902 }
903
904 if (esp_eh_frame_missing_info(fde, EXECUTION_FRAME_PC(frame))) {
905 /* Address was not found in the list. */
906 panic_print_str("\r\nBacktrace ended abruptly: cannot find DWARF information for"
907 " instruction at address 0x");
908 panic_print_hex(EXECUTION_FRAME_PC(frame));
909 panic_print_str("\r\n");
910 break;
911 }
912
913 /* Clean and set the DWARF register structure. */
914 memset(&state, 0, sizeof(dwarf_regs));
915
916 const uint32_t prev_sp = EXECUTION_FRAME_SP(frame);
917
918 /* Retrieve the return address of the frame. The frame's registers will be modified.
919 * The frame we get then is the caller's one. */
920 uint32_t ra = esp_eh_frame_restore_caller_state(fde, &frame, &state);
921
922 /* End of backtrace is reached if the stack and the PC don't change anymore. */
923 end_of_backtrace = (EXECUTION_FRAME_SP(frame) == prev_sp) && (EXECUTION_FRAME_PC(frame) == ra);
924
925 /* Go back to the caller: update stack pointer and program counter. */
926 EXECUTION_FRAME_PC(frame) = ra;
927 }
928
929 panic_print_str("\r\n");
930 }
931 #endif //ESP_SYSTEM_USE_EH_FRAME
932
