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