#!/usr/bin/env python # # ESP32 core dump Utility from __future__ import print_function from __future__ import unicode_literals from __future__ import division import sys try: from builtins import zip from builtins import str from builtins import range from past.utils import old_div from builtins import object except ImportError: print('Import has failed probably because of the missing "future" package. Please install all the packages for ' 'interpreter {} from the $IDF_PATH/requirements.txt file.'.format(sys.executable)) sys.exit(1) import os import argparse import subprocess import tempfile import struct import errno import base64 import binascii import logging idf_path = os.getenv('IDF_PATH') if idf_path: sys.path.insert(0, os.path.join(idf_path, 'components', 'esptool_py', 'esptool')) try: import esptool except ImportError: print("Esptool is not found! Set proper $IDF_PATH in environment.") sys.exit(2) __version__ = "0.3-dev" if os.name == 'nt': CLOSE_FDS = False else: CLOSE_FDS = True class ESPCoreDumpError(RuntimeError): """Core dump runtime error class """ def __init__(self, message): """Constructor for core dump error """ super(ESPCoreDumpError, self).__init__(message) class BinStruct(object): """Binary structure representation Subclasses must specify actual structure layout using 'fields' and 'format' members. For example, the following subclass represents structure with two fields: f1 of size 2 bytes and 4 bytes f2. Little endian. class SomeStruct(BinStruct): fields = ("f1", "f2") format = "<HL" Then subclass can be used to initialize fields of underlaying structure and convert it to binary representation: f = open('some_struct.bin', 'wb') s = SomeStruct() s.f1 = 1 s.f2 = 10 f.write(s.dump()) f.close() """ def __init__(self, buf=None): """Base constructor for binary structure objects """ if buf is None: buf = b'\0' * self.sizeof() fields = struct.unpack(self.__class__.format, buf[:self.sizeof()]) self.__dict__.update(zip(self.__class__.fields, fields)) def sizeof(self): """Returns the size of the structure represented by specific subclass """ return struct.calcsize(self.__class__.format) def dump(self): """Returns binary representation of structure """ keys = self.__class__.fields return struct.pack(self.__class__.format, *(self.__dict__[k] for k in keys)) class Elf32FileHeader(BinStruct): """ELF32 file header """ fields = ("e_ident", "e_type", "e_machine", "e_version", "e_entry", "e_phoff", "e_shoff", "e_flags", "e_ehsize", "e_phentsize", "e_phnum", "e_shentsize", "e_shnum", "e_shstrndx") format = "<16sHHLLLLLHHHHHH" def __init__(self, buf=None): """Constructor for ELF32 file header structure """ super(Elf32FileHeader, self).__init__(buf) if buf is None: # Fill in sane ELF header for LSB32 self.e_ident = b"\x7fELF\1\1\1\0\0\0\0\0\0\0\0\0" self.e_version = ESPCoreDumpElfFile.EV_CURRENT self.e_ehsize = self.sizeof() class Elf32ProgramHeader(BinStruct): """ELF32 program header """ fields = ("p_type", "p_offset", "p_vaddr", "p_paddr", "p_filesz", "p_memsz", "p_flags", "p_align") format = "<LLLLLLLL" class Elf32NoteDesc(object): """ELF32 note descriptor """ def __init__(self, name, type, desc): """Constructor for ELF32 note descriptor """ self.name = bytearray(name, encoding='ascii') + b'\0' self.type = type self.desc = desc def dump(self): """Returns binary representation of ELF32 note descriptor """ hdr = struct.pack("<LLL", len(self.name), len(self.desc), self.type) # pad for 4 byte alignment name = self.name + ((4 - len(self.name)) % 4) * b'\0' desc = self.desc + ((4 - len(self.desc)) % 4) * b'\0' return hdr + name + desc class XtensaPrStatus(BinStruct): """Xtensa program status structure""" fields = ("si_signo", "si_code", "si_errno", "pr_cursig", "pr_pad0", "pr_sigpend", "pr_sighold", "pr_pid", "pr_ppid", "pr_pgrp", "pr_sid", "pr_utime", "pr_stime", "pr_cutime", "pr_cstime") format = "<3LHHLLLLLLQQQQ" class ESPCoreDumpSegment(esptool.ImageSegment): """ Wrapper class for a program segment in core ELF file, has a segment type and flags as well as the common properties of an ImageSegment. """ # segment flags PF_X = 0x1 # Execute PF_W = 0x2 # Write PF_R = 0x4 # Read def __init__(self, addr, data, type, flags): """Constructor for program segment """ super(ESPCoreDumpSegment, self).__init__(addr, data) self.flags = flags self.type = type def __repr__(self): """Returns string representation of program segment """ return "%s %s %s" % (self.type, self.attr_str(), super(ESPCoreDumpSegment, self).__repr__()) def attr_str(self): """Returns string representation of program segment attributes """ str = '' if self.flags & self.PF_R: str += 'R' else: str += ' ' if self.flags & self.PF_W: str += 'W' else: str += ' ' if self.flags & self.PF_X: str += 'X' else: str += ' ' return str class ESPCoreDumpSection(esptool.ELFSection): """ Wrapper class for a section in core ELF file, has a section flags as well as the common properties of an esptool.ELFSection. """ # section flags SHF_WRITE = 0x1 SHF_ALLOC = 0x2 SHF_EXECINSTR = 0x4 def __init__(self, name, addr, data, flags): """Constructor for section """ super(ESPCoreDumpSection, self).__init__(name, addr, data) self.flags = flags def __repr__(self): """Returns string representation of section """ return "%s %s" % (super(ESPCoreDumpSection, self).__repr__(), self.attr_str()) def attr_str(self): """Returns string representation of section attributes """ str = "R" if self.flags & self.SHF_WRITE: str += 'W' else: str += ' ' if self.flags & self.SHF_EXECINSTR: str += 'X' else: str += ' ' if self.flags & self.SHF_ALLOC: str += 'A' else: str += ' ' return str class ESPCoreDumpElfFile(esptool.ELFFile): """ Wrapper class for core dump ELF file """ # ELF file type ET_NONE = 0x0 # No file type ET_REL = 0x1 # Relocatable file ET_EXEC = 0x2 # Executable file ET_DYN = 0x3 # Shared object file ET_CORE = 0x4 # Core file # ELF file version EV_NONE = 0x0 EV_CURRENT = 0x1 # ELF file machine type EM_NONE = 0x0 EM_XTENSA = 0x5E # section types SEC_TYPE_PROGBITS = 0x01 SEC_TYPE_STRTAB = 0x03 # special section index SHN_UNDEF = 0x0 # program segment types PT_NULL = 0x0 PT_LOAD = 0x1 PT_DYNAMIC = 0x2 PT_INTERP = 0x3 PT_NOTE = 0x4 PT_SHLIB = 0x5 PT_PHDR = 0x6 def __init__(self, name=None): """Constructor for core dump ELF file """ if name: super(ESPCoreDumpElfFile, self).__init__(name) else: self.sections = [] self.program_segments = [] self.e_type = self.ET_NONE self.e_machine = self.EM_NONE def _read_elf_file(self, f): """Reads core dump from ELF file """ # read the ELF file header LEN_FILE_HEADER = 0x34 try: (ident,type,machine,_version, self.entrypoint,phoff,shoff,_flags, _ehsize, phentsize,phnum,_shentsize, shnum,shstrndx) = struct.unpack("<16sHHLLLLLHHHHHH", f.read(LEN_FILE_HEADER)) except struct.error as e: raise ESPCoreDumpError("Failed to read a valid ELF header from %s: %s" % (self.name, e)) if bytearray([ident[0]]) != b'\x7f' or ident[1:4] != b'ELF': raise ESPCoreDumpError("%s has invalid ELF magic header" % self.name) if machine != self.EM_XTENSA: raise ESPCoreDumpError("%s does not appear to be an Xtensa ELF file. e_machine=%04x" % (self.name, machine)) self.e_type = type self.e_machine = machine self.sections = [] self.program_segments = [] if shnum > 0: self._read_sections(f, shoff, shstrndx) if phnum > 0: self._read_program_segments(f, phoff, phentsize, phnum) def _read_sections(self, f, section_header_offs, shstrndx): """Reads core dump sections from ELF file """ f.seek(section_header_offs) section_header = f.read() LEN_SEC_HEADER = 0x28 if len(section_header) == 0: raise ESPCoreDumpError("No section header found at offset %04x in ELF file." % section_header_offs) if len(section_header) % LEN_SEC_HEADER != 0: logging.warning('Unexpected ELF section header length %04x is not mod-%02x' % (len(section_header),LEN_SEC_HEADER)) # walk through the section header and extract all sections section_header_offsets = range(0, len(section_header), LEN_SEC_HEADER) def read_section_header(offs): name_offs,sec_type,flags,lma,sec_offs,size = struct.unpack_from("<LLLLLL", section_header[offs:]) return (name_offs, sec_type, flags, lma, size, sec_offs) all_sections = [read_section_header(offs) for offs in section_header_offsets] prog_sections = [s for s in all_sections if s[1] == esptool.ELFFile.SEC_TYPE_PROGBITS] # search for the string table section if not shstrndx * LEN_SEC_HEADER in section_header_offsets: raise ESPCoreDumpError("ELF file has no STRTAB section at shstrndx %d" % shstrndx) _,sec_type,_,_,sec_size,sec_offs = read_section_header(shstrndx * LEN_SEC_HEADER) if sec_type != esptool.ELFFile.SEC_TYPE_STRTAB: logging.warning('ELF file has incorrect STRTAB section type 0x%02x' % sec_type) f.seek(sec_offs) string_table = f.read(sec_size) # build the real list of ELFSections by reading the actual section names from the # string table section, and actual data for each section from the ELF file itself def lookup_string(offs): raw = string_table[offs:] return raw[:raw.index(b'\x00')] def read_data(offs,size): f.seek(offs) return f.read(size) prog_sections = [ESPCoreDumpSection(lookup_string(n_offs), lma, read_data(offs, size), flags) for (n_offs, _type, flags, lma, size, offs) in prog_sections if lma != 0] self.sections = prog_sections def _read_program_segments(self, f, seg_table_offs, entsz, num): """Reads core dump program segments from ELF file """ f.seek(seg_table_offs) seg_table = f.read(entsz * num) LEN_SEG_HEADER = 0x20 if len(seg_table) == 0: raise ESPCoreDumpError("No program header table found at offset %04x in ELF file." % seg_table_offs) if len(seg_table) % LEN_SEG_HEADER != 0: logging.warning('Unexpected ELF program header table length %04x is not mod-%02x' % (len(seg_table),LEN_SEG_HEADER)) # walk through the program segment table and extract all segments seg_table_offs = range(0, len(seg_table), LEN_SEG_HEADER) def read_program_header(offs): type,offset,vaddr,_paddr,filesz,_memsz,flags,_align = struct.unpack_from("<LLLLLLLL", seg_table[offs:]) return (type,offset,vaddr,filesz,flags) prog_segments = [read_program_header(offs) for offs in seg_table_offs] # build the real list of ImageSegment by reading actual data for each segment from the ELF file itself def read_data(offs,size): f.seek(offs) return f.read(size) self.program_segments = [ESPCoreDumpSegment(vaddr, read_data(offset, filesz), type, flags) for (type, offset, vaddr, filesz,flags) in prog_segments if vaddr != 0] def add_program_segment(self, addr, data, type, flags): """Adds new program segment """ # TODO: currently merging with existing segments is not supported data_sz = len(data) # check for overlapping and merge if needed if addr != 0 and data_sz != 0: for ps in self.program_segments: seg_len = len(ps.data) if addr >= ps.addr and addr < (ps.addr + seg_len): raise ESPCoreDumpError("Can not add overlapping region [%x..%x] to ELF file. Conflict with existing [%x..%x]." % (addr, addr + data_sz - 1, ps.addr, ps.addr + seg_len - 1)) if (addr + data_sz) > ps.addr and (addr + data_sz) <= (ps.addr + seg_len): raise ESPCoreDumpError("Can not add overlapping region [%x..%x] to ELF file. Conflict with existing [%x..%x]." % (addr, addr + data_sz - 1, ps.addr, ps.addr + seg_len - 1)) # append self.program_segments.append(ESPCoreDumpSegment(addr, data, type, flags)) def dump(self, f): """Write core dump contents to file """ # TODO: currently dumps only program segments. # dumping sections is not supported yet # write ELF header ehdr = Elf32FileHeader() ehdr.e_type = self.e_type ehdr.e_machine = self.e_machine ehdr.e_entry = 0 ehdr.e_phoff = ehdr.sizeof() ehdr.e_shoff = 0 ehdr.e_flags = 0 ehdr.e_phentsize = Elf32ProgramHeader().sizeof() ehdr.e_phnum = len(self.program_segments) ehdr.e_shentsize = 0 ehdr.e_shnum = 0 ehdr.e_shstrndx = self.SHN_UNDEF f.write(ehdr.dump()) # write program header table cur_off = ehdr.e_ehsize + ehdr.e_phnum * ehdr.e_phentsize for i in range(len(self.program_segments)): phdr = Elf32ProgramHeader() phdr.p_type = self.program_segments[i].type phdr.p_offset = cur_off phdr.p_vaddr = self.program_segments[i].addr phdr.p_paddr = phdr.p_vaddr # TODO phdr.p_filesz = len(self.program_segments[i].data) phdr.p_memsz = phdr.p_filesz # TODO phdr.p_flags = self.program_segments[i].flags phdr.p_align = 0 # TODO f.write(phdr.dump()) cur_off += phdr.p_filesz # write program segments for i in range(len(self.program_segments)): f.write(self.program_segments[i].data) class ESPCoreDumpLoaderError(ESPCoreDumpError): """Core dump loader error class """ def __init__(self, message): """Constructor for core dump loader error """ super(ESPCoreDumpLoaderError, self).__init__(message) class ESPCoreDumpLoader(object): """Core dump loader base class """ ESP32_COREDUMP_VESION = 1 ESP32_COREDUMP_HDR_FMT = '<4L' ESP32_COREDUMP_HDR_SZ = struct.calcsize(ESP32_COREDUMP_HDR_FMT) ESP32_COREDUMP_TSK_HDR_FMT = '<3L' ESP32_COREDUMP_TSK_HDR_SZ = struct.calcsize(ESP32_COREDUMP_TSK_HDR_FMT) def __init__(self): """Base constructor for core dump loader """ self.fcore = None def _get_registers_from_stack(self, data, grows_down): """Returns list of registers (in GDB format) from xtensa stack frame """ # from "gdb/xtensa-tdep.h" # typedef struct # { # 0 xtensa_elf_greg_t pc; # 1 xtensa_elf_greg_t ps; # 2 xtensa_elf_greg_t lbeg; # 3 xtensa_elf_greg_t lend; # 4 xtensa_elf_greg_t lcount; # 5 xtensa_elf_greg_t sar; # 6 xtensa_elf_greg_t windowstart; # 7 xtensa_elf_greg_t windowbase; # 8..63 xtensa_elf_greg_t reserved[8+48]; # 64 xtensa_elf_greg_t ar[64]; # } xtensa_elf_gregset_t; REG_PC_IDX = 0 REG_PS_IDX = 1 REG_LB_IDX = 2 REG_LE_IDX = 3 REG_LC_IDX = 4 REG_SAR_IDX = 5 # REG_WS_IDX = 6 # REG_WB_IDX = 7 REG_AR_START_IDX = 64 # REG_AR_NUM = 64 # FIXME: acc to xtensa_elf_gregset_t number of regs must be 128, # but gdb complanis when it less then 129 REG_NUM = 129 # XT_SOL_EXIT = 0 XT_SOL_PC = 1 XT_SOL_PS = 2 # XT_SOL_NEXT = 3 XT_SOL_AR_START = 4 XT_SOL_AR_NUM = 4 # XT_SOL_FRMSZ = 8 XT_STK_EXIT = 0 XT_STK_PC = 1 XT_STK_PS = 2 XT_STK_AR_START = 3 XT_STK_AR_NUM = 16 XT_STK_SAR = 19 # XT_STK_EXCCAUSE = 20 # XT_STK_EXCVADDR = 21 XT_STK_LBEG = 22 XT_STK_LEND = 23 XT_STK_LCOUNT = 24 XT_STK_FRMSZ = 25 regs = [0] * REG_NUM # TODO: support for growing up stacks if not grows_down: raise ESPCoreDumpLoaderError("Growing up stacks are not supported for now!") ex_struct = "<%dL" % XT_STK_FRMSZ if len(data) < struct.calcsize(ex_struct): raise ESPCoreDumpLoaderError("Too small stack to keep frame: %d bytes!" % len(data)) stack = struct.unpack(ex_struct, data[:struct.calcsize(ex_struct)]) # Stack frame type indicator is always the first item rc = stack[XT_STK_EXIT] if rc != 0: regs[REG_PC_IDX] = stack[XT_STK_PC] regs[REG_PS_IDX] = stack[XT_STK_PS] for i in range(XT_STK_AR_NUM): regs[REG_AR_START_IDX + i] = stack[XT_STK_AR_START + i] regs[REG_SAR_IDX] = stack[XT_STK_SAR] regs[REG_LB_IDX] = stack[XT_STK_LBEG] regs[REG_LE_IDX] = stack[XT_STK_LEND] regs[REG_LC_IDX] = stack[XT_STK_LCOUNT] # FIXME: crashed and some running tasks (e.g. prvIdleTask) have EXCM bit set # and GDB can not unwind callstack properly (it implies not windowed call0) if regs[REG_PS_IDX] & (1 << 5): regs[REG_PS_IDX] &= ~(1 << 4) else: regs[REG_PC_IDX] = stack[XT_SOL_PC] regs[REG_PS_IDX] = stack[XT_SOL_PS] for i in range(XT_SOL_AR_NUM): regs[REG_AR_START_IDX + i] = stack[XT_SOL_AR_START + i] # nxt = stack[XT_SOL_NEXT] # TODO: remove magic hack with saved PC to get proper value regs[REG_PC_IDX] = ((regs[REG_PC_IDX] & 0x3FFFFFFF) | 0x40000000) if regs[REG_PC_IDX] & 0x80000000: regs[REG_PC_IDX] = (regs[REG_PC_IDX] & 0x3fffffff) | 0x40000000 if regs[REG_AR_START_IDX + 0] & 0x80000000: regs[REG_AR_START_IDX + 0] = (regs[REG_AR_START_IDX + 0] & 0x3fffffff) | 0x40000000 return regs def remove_tmp_file(self, fname): """Silently removes temporary file """ try: os.remove(fname) except OSError as e: if e.errno != errno.ENOENT: logging.warning("Failed to remove temp file '%s' (%d)!" % (fname, e.errno)) def cleanup(self): """Cleans up loader resources """ if self.fcore: self.fcore.close() if self.fcore_name: self.remove_tmp_file(self.fcore_name) def create_corefile(self, core_fname=None, off=0, rom_elf=None): """Creates core dump ELF file """ core_off = off data = self.read_data(core_off, self.ESP32_COREDUMP_HDR_SZ) tot_len,coredump_ver,task_num,tcbsz = struct.unpack_from(self.ESP32_COREDUMP_HDR_FMT, data) if coredump_ver > self.ESP32_COREDUMP_VESION: raise ESPCoreDumpLoaderError("Core dump version '%d' is not supported! Should be up to '%d'." % (coredump_ver, self.ESP32_COREDUMP_VESION)) tcbsz_aligned = tcbsz if tcbsz_aligned % 4: tcbsz_aligned = 4 * (old_div(tcbsz_aligned,4) + 1) core_off += self.ESP32_COREDUMP_HDR_SZ core_elf = ESPCoreDumpElfFile() notes = b'' for i in range(task_num): data = self.read_data(core_off, self.ESP32_COREDUMP_TSK_HDR_SZ) tcb_addr,stack_top,stack_end = struct.unpack_from(self.ESP32_COREDUMP_TSK_HDR_FMT, data) if stack_end > stack_top: stack_len = stack_end - stack_top stack_base = stack_top else: stack_len = stack_top - stack_end stack_base = stack_end stack_len_aligned = stack_len if stack_len_aligned % 4: stack_len_aligned = 4 * (old_div(stack_len_aligned,4) + 1) core_off += self.ESP32_COREDUMP_TSK_HDR_SZ logging.info("Read TCB %d bytes @ 0x%x" % (tcbsz_aligned, tcb_addr)) data = self.read_data(core_off, tcbsz_aligned) try: if tcbsz != tcbsz_aligned: core_elf.add_program_segment(tcb_addr, data[:tcbsz - tcbsz_aligned], ESPCoreDumpElfFile.PT_LOAD, ESPCoreDumpSegment.PF_R | ESPCoreDumpSegment.PF_W) else: core_elf.add_program_segment(tcb_addr, data, ESPCoreDumpElfFile.PT_LOAD, ESPCoreDumpSegment.PF_R | ESPCoreDumpSegment.PF_W) except ESPCoreDumpError as e: logging.warning("Skip TCB %d bytes @ 0x%x. (Reason: %s)" % (tcbsz_aligned, tcb_addr, e)) core_off += tcbsz_aligned logging.info("Read stack %d bytes @ 0x%x" % (stack_len_aligned, stack_base)) data = self.read_data(core_off, stack_len_aligned) if stack_len != stack_len_aligned: data = data[:stack_len - stack_len_aligned] try: core_elf.add_program_segment(stack_base, data, ESPCoreDumpElfFile.PT_LOAD, ESPCoreDumpSegment.PF_R | ESPCoreDumpSegment.PF_W) except ESPCoreDumpError as e: logging.warning("Skip task's (%x) stack %d bytes @ 0x%x. (Reason: %s)" % (tcb_addr, stack_len_aligned, stack_base, e)) core_off += stack_len_aligned try: logging.info("Stack start_end: 0x%x @ 0x%x" % (stack_top, stack_end)) task_regs = self._get_registers_from_stack(data, stack_end > stack_top) except Exception as e: print(e) return None prstatus = XtensaPrStatus() prstatus.pr_cursig = 0 # TODO: set sig only for current/failed task prstatus.pr_pid = i # TODO: use pid assigned by OS note = Elf32NoteDesc("CORE", 1, prstatus.dump() + struct.pack("<%dL" % len(task_regs), *task_regs)).dump() notes += note # add notes try: core_elf.add_program_segment(0, notes, ESPCoreDumpElfFile.PT_NOTE, 0) except ESPCoreDumpError as e: logging.warning("Skip NOTES segment %d bytes @ 0x%x. (Reason: %s)" % (len(notes), 0, e)) # add ROM text sections if rom_elf: for ps in rom_elf.program_segments: if ps.flags & ESPCoreDumpSegment.PF_X: try: core_elf.add_program_segment(ps.addr, ps.data, ESPCoreDumpElfFile.PT_LOAD, ps.flags) except ESPCoreDumpError as e: logging.warning("Skip ROM segment %d bytes @ 0x%x. (Reason: %s)" % (len(ps.data), ps.addr, e)) core_elf.e_type = ESPCoreDumpElfFile.ET_CORE core_elf.e_machine = ESPCoreDumpElfFile.EM_XTENSA if core_fname: fce = open(core_fname, 'wb') else: fhnd,core_fname = tempfile.mkstemp() fce = os.fdopen(fhnd, 'wb') core_elf.dump(fce) fce.close() return core_fname def read_data(self, off, sz): """Reads data from raw core dump got from flash or UART """ self.fcore.seek(off) data = self.fcore.read(sz) return data class ESPCoreDumpFileLoader(ESPCoreDumpLoader): """Core dump file loader class """ def __init__(self, path, b64=False): """Constructor for core dump file loader """ super(ESPCoreDumpFileLoader, self).__init__() self.fcore = self._load_coredump(path, b64) def _load_coredump(self, path, b64): """Loads core dump from (raw binary or base64-encoded) file """ self.fcore_name = None if b64: fhnd,self.fcore_name = tempfile.mkstemp() fcore = os.fdopen(fhnd, 'wb') fb64 = open(path, 'rb') try: while True: line = fb64.readline() if len(line) == 0: break data = base64.standard_b64decode(line.rstrip(b'\r\n')) fcore.write(data) fcore.close() fcore = open(self.fcore_name, 'rb') except Exception as e: if self.fcore_name: self.remove_tmp_file(self.fcore_name) raise e finally: fb64.close() else: fcore = open(path, 'rb') return fcore class ESPCoreDumpFlashLoader(ESPCoreDumpLoader): """Core dump flash loader class """ ESP32_COREDUMP_FLASH_CRC_FMT = '<L' ESP32_COREDUMP_FLASH_CRC_SZ = struct.calcsize(ESP32_COREDUMP_FLASH_CRC_FMT) ESP32_COREDUMP_FLASH_LEN_FMT = '<L' ESP32_COREDUMP_FLASH_LEN_SZ = struct.calcsize(ESP32_COREDUMP_FLASH_LEN_FMT) def __init__(self, off, tool_path=None, chip='esp32', port=None, baud=None): """Constructor for core dump flash loader """ super(ESPCoreDumpFlashLoader, self).__init__() if not tool_path: self.path = esptool.__file__ _,e = os.path.splitext(self.path) if e == '.pyc': self.path = self.path[:-1] else: self.path = tool_path self.port = port self.baud = baud self.chip = chip self.dump_sz = 0 self.fcore = self._load_coredump(off) def _load_coredump(self, off): """Loads core dump from flash """ tool_args = [sys.executable, self.path, '-c', self.chip] if self.port: tool_args.extend(['-p', self.port]) if self.baud: tool_args.extend(['-b', str(self.baud)]) tool_args.extend(['read_flash', str(off), str(self.ESP32_COREDUMP_FLASH_LEN_SZ), '']) self.fcore_name = None try: fhnd,self.fcore_name = tempfile.mkstemp() tool_args[-1] = self.fcore_name # read core dump length et_out = subprocess.check_output(tool_args) print(et_out.decode('utf-8')) f = os.fdopen(fhnd, 'rb') self.dump_sz = self._read_core_dump_length(f) # read core dump tool_args[-2] = str(self. dump_sz) et_out = subprocess.check_output(tool_args) print(et_out.decode('utf-8')) except subprocess.CalledProcessError as e: logging.error("esptool script execution failed with err %d" % e.returncode) logging.info("Command ran: '%s'" % e.cmd) logging.info("Command out:") logging.info(e.output) if self.fcore_name: self.remove_tmp_file(self.fcore_name) raise e return f def _read_core_dump_length(self, f): """Reads core dump length """ data = f.read(self.ESP32_COREDUMP_FLASH_LEN_SZ) tot_len, = struct.unpack_from(self.ESP32_COREDUMP_FLASH_LEN_FMT, data) return tot_len def create_corefile(self, core_fname=None, rom_elf=None): """Checks flash coredump data integrity and creates ELF file """ data = self.read_data(self.dump_sz - self.ESP32_COREDUMP_FLASH_CRC_SZ, self.ESP32_COREDUMP_FLASH_CRC_SZ) dump_crc, = struct.unpack_from(self.ESP32_COREDUMP_FLASH_CRC_FMT, data) data = self.read_data(0, self.dump_sz - self.ESP32_COREDUMP_FLASH_CRC_SZ) data_crc = binascii.crc32(data) & 0xffffffff if dump_crc != data_crc: raise ESPCoreDumpLoaderError("Invalid core dump CRC %x, should be %x" % (data_crc, dump_crc)) return super(ESPCoreDumpFlashLoader, self).create_corefile(core_fname) class GDBMIOutRecordHandler(object): """GDB/MI output record handler base class """ TAG = '' def __init__(self, f, verbose=False): """Base constructor for GDB/MI output record handler """ self.verbose = verbose def execute(self, ln): """Base method to execute GDB/MI output record handler function """ if self.verbose: print("%s.execute: [[%s]]" % (self.__class__.__name__, ln)) class GDBMIOutStreamHandler(GDBMIOutRecordHandler): """GDB/MI output stream handler class """ def __init__(self, f, verbose=False): """Constructor for GDB/MI output stream handler """ super(GDBMIOutStreamHandler, self).__init__(None, verbose) self.func = f def execute(self, ln): """Executes GDB/MI output stream handler function """ GDBMIOutRecordHandler.execute(self, ln) if self.func: # remove TAG / quotes and replace c-string \n with actual NL self.func(ln[1:].strip('"').replace('\\n', '\n').replace('\\t', '\t')) class GDBMIResultHandler(GDBMIOutRecordHandler): """GDB/MI result handler class """ TAG = '^' RC_DONE = 'done' RC_RUNNING = 'running' RC_CONNECTED = 'connected' RC_ERROR = 'error' RC_EXIT = 'exit' def __init__(self, verbose=False): """Constructor for GDB/MI result handler """ super(GDBMIResultHandler, self).__init__(None, verbose) self.result_class = None self.result_str = None def _parse_rc(self, ln, rc): """Parses result code """ rc_str = "{0}{1}".format(self.TAG, rc) if ln.startswith(rc_str): self.result_class = rc sl = len(rc_str) if len(ln) > sl: self.result_str = ln[sl:] if self.result_str.startswith(','): self.result_str = self.result_str[1:] else: logging.error("Invalid result format: '%s'" % ln) else: self.result_str = '' return True return False def execute(self, ln): """Executes GDB/MI result handler function """ GDBMIOutRecordHandler.execute(self, ln) if self._parse_rc(ln, self.RC_DONE): return if self._parse_rc(ln, self.RC_RUNNING): return if self._parse_rc(ln, self.RC_CONNECTED): return if self._parse_rc(ln, self.RC_ERROR): return if self._parse_rc(ln, self.RC_EXIT): return logging.error("Unknown GDB/MI result: '%s'" % ln) class GDBMIStreamConsoleHandler(GDBMIOutStreamHandler): """GDB/MI console stream handler class """ TAG = '~' def load_aux_elf(elf_path): """ Loads auxilary ELF file and composes GDB command to read its symbols """ elf = None sym_cmd = '' if os.path.exists(elf_path): elf = ESPCoreDumpElfFile(elf_path) for s in elf.sections: if s.name == '.text': sym_cmd = 'add-symbol-file %s 0x%x' % (elf_path, s.addr) return (elf, sym_cmd) def dbg_corefile(args): """ Command to load core dump from file or flash and run GDB debug session with it """ global CLOSE_FDS loader = None rom_elf,rom_sym_cmd = load_aux_elf(args.rom_elf) if not args.core: loader = ESPCoreDumpFlashLoader(args.off, port=args.port) core_fname = loader.create_corefile(args.save_core, rom_elf=rom_elf) if not core_fname: logging.error("Failed to create corefile!") loader.cleanup() return else: core_fname = args.core if args.core_format and args.core_format != 'elf': loader = ESPCoreDumpFileLoader(core_fname, args.core_format == 'b64') core_fname = loader.create_corefile(args.save_core, rom_elf=rom_elf) if not core_fname: logging.error("Failed to create corefile!") loader.cleanup() return p = subprocess.Popen(bufsize=0, args=[args.gdb, '--nw', # ignore .gdbinit '--core=%s' % core_fname, # core file, '-ex', rom_sym_cmd, args.prog ], stdin=None, stdout=None, stderr=None, close_fds=CLOSE_FDS ) p.wait() if loader: if not args.core and not args.save_core: loader.remove_tmp_file(core_fname) loader.cleanup() print('Done!') def info_corefile(args): """ Command to load core dump from file or flash and print it's data in user friendly form """ global CLOSE_FDS def gdbmi_console_stream_handler(ln): sys.stdout.write(ln) sys.stdout.flush() def gdbmi_read2prompt(f, out_handlers=None): while True: ln = f.readline().decode('utf-8').rstrip(' \r\n') if ln == '(gdb)': break elif len(ln) == 0: break elif out_handlers: for h in out_handlers: if ln.startswith(out_handlers[h].TAG): out_handlers[h].execute(ln) break def gdbmi_start(handlers, gdb_cmds): gdb_args = [args.gdb, '--quiet', # inhibit dumping info at start-up '--nx', # inhibit window interface '--nw', # ignore .gdbinit '--interpreter=mi2', # use GDB/MI v2 '--core=%s' % core_fname] # core file for c in gdb_cmds: gdb_args += ['-ex', c] gdb_args.append(args.prog) p = subprocess.Popen(bufsize=0, args=gdb_args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, close_fds=CLOSE_FDS) gdbmi_read2prompt(p.stdout, handlers) return p def gdbmi_getinfo(p, handlers, gdb_cmd): for t in handlers: handlers[t].result_class = None p.stdin.write(bytearray("-interpreter-exec console \"%s\"\n" % gdb_cmd, encoding='utf-8')) gdbmi_read2prompt(p.stdout, handlers) if not handlers[GDBMIResultHandler.TAG].result_class or handlers[GDBMIResultHandler.TAG].result_class == GDBMIResultHandler.RC_EXIT: logging.error("GDB exited (%s / %s)!" % (handlers[GDBMIResultHandler.TAG].result_class, handlers[GDBMIResultHandler.TAG].result_str)) p.wait() logging.error("Problem occured! GDB exited, restart it.") p = gdbmi_start(handlers, []) elif handlers[GDBMIResultHandler.TAG].result_class != GDBMIResultHandler.RC_DONE: logging.error("GDB/MI command failed (%s / %s)!" % (handlers[GDBMIResultHandler.TAG].result_class, handlers[GDBMIResultHandler.TAG].result_str)) return p loader = None rom_elf,rom_sym_cmd = load_aux_elf(args.rom_elf) if not args.core: loader = ESPCoreDumpFlashLoader(args.off, port=args.port) core_fname = loader.create_corefile(args.save_core, rom_elf=rom_elf) if not core_fname: logging.error("Failed to create corefile!") loader.cleanup() return else: core_fname = args.core if args.core_format and args.core_format != 'elf': loader = ESPCoreDumpFileLoader(core_fname, args.core_format == 'b64') core_fname = loader.create_corefile(args.save_core, rom_elf=rom_elf) if not core_fname: logging.error("Failed to create corefile!") loader.cleanup() return exe_elf = ESPCoreDumpElfFile(args.prog) core_elf = ESPCoreDumpElfFile(core_fname) merged_segs = [] core_segs = core_elf.program_segments for s in exe_elf.sections: merged = False for ps in core_segs: if ps.addr <= s.addr and ps.addr + len(ps.data) >= s.addr: # sec: |XXXXXXXXXX| # seg: |...XXX.............| seg_addr = ps.addr if ps.addr + len(ps.data) <= s.addr + len(s.data): # sec: |XXXXXXXXXX| # seg: |XXXXXXXXXXX...| # merged: |XXXXXXXXXXXXXX| seg_len = len(s.data) + (s.addr - ps.addr) else: # sec: |XXXXXXXXXX| # seg: |XXXXXXXXXXXXXXXXX| # merged: |XXXXXXXXXXXXXXXXX| seg_len = len(ps.data) merged_segs.append((s.name, seg_addr, seg_len, s.attr_str(), True)) core_segs.remove(ps) merged = True elif ps.addr >= s.addr and ps.addr <= s.addr + len(s.data): # sec: |XXXXXXXXXX| # seg: |...XXX.............| seg_addr = s.addr if (ps.addr + len(ps.data)) >= (s.addr + len(s.data)): # sec: |XXXXXXXXXX| # seg: |..XXXXXXXXXXX| # merged: |XXXXXXXXXXXXX| seg_len = len(s.data) + (ps.addr + len(ps.data)) - (s.addr + len(s.data)) else: # sec: |XXXXXXXXXX| # seg: |XXXXXX| # merged: |XXXXXXXXXX| seg_len = len(s.data) merged_segs.append((s.name, seg_addr, seg_len, s.attr_str(), True)) core_segs.remove(ps) merged = True if not merged: merged_segs.append((s.name, s.addr, len(s.data), s.attr_str(), False)) handlers = {} handlers[GDBMIResultHandler.TAG] = GDBMIResultHandler(verbose=False) handlers[GDBMIStreamConsoleHandler.TAG] = GDBMIStreamConsoleHandler(None, verbose=False) p = gdbmi_start(handlers, [rom_sym_cmd]) print("===============================================================") print("==================== ESP32 CORE DUMP START ====================") handlers[GDBMIResultHandler.TAG].result_class = None handlers[GDBMIStreamConsoleHandler.TAG].func = gdbmi_console_stream_handler print("\n================== CURRENT THREAD REGISTERS ===================") p = gdbmi_getinfo(p, handlers, "info registers") print("\n==================== CURRENT THREAD STACK =====================") p = gdbmi_getinfo(p, handlers, "bt") print("\n======================== THREADS INFO =========================") p = gdbmi_getinfo(p, handlers, "info threads") print("\n======================= ALL MEMORY REGIONS ========================") print("Name Address Size Attrs") for ms in merged_segs: print("%s 0x%x 0x%x %s" % (ms[0], ms[1], ms[2], ms[3])) for cs in core_segs: # core dump exec segments are from ROM, other are belong to tasks (TCB or stack) if cs.flags & ESPCoreDumpSegment.PF_X: seg_name = 'rom.text' else: seg_name = 'tasks.data' print(".coredump.%s 0x%x 0x%x %s" % (seg_name, cs.addr, len(cs.data), cs.attr_str())) if args.print_mem: print("\n====================== CORE DUMP MEMORY CONTENTS ========================") for cs in core_elf.program_segments: # core dump exec segments are from ROM, other are belong to tasks (TCB or stack) if cs.flags & ESPCoreDumpSegment.PF_X: seg_name = 'rom.text' else: seg_name = 'tasks.data' print(".coredump.%s 0x%x 0x%x %s" % (seg_name, cs.addr, len(cs.data), cs.attr_str())) p = gdbmi_getinfo(p, handlers, "x/%dx 0x%x" % (old_div(len(cs.data),4), cs.addr)) print("\n===================== ESP32 CORE DUMP END =====================") print("===============================================================") p.stdin.write(b'q\n') p.wait() p.stdin.close() p.stdout.close() if loader: if not args.core and not args.save_core: loader.remove_tmp_file(core_fname) loader.cleanup() print('Done!') def main(): parser = argparse.ArgumentParser(description='espcoredump.py v%s - ESP32 Core Dump Utility' % __version__, prog='espcoredump') parser.add_argument('--chip', '-c', help='Target chip type', choices=['auto', 'esp32'], default=os.environ.get('ESPTOOL_CHIP', 'auto')) parser.add_argument( '--port', '-p', help='Serial port device', default=os.environ.get('ESPTOOL_PORT', esptool.ESPLoader.DEFAULT_PORT)) parser.add_argument( '--baud', '-b', help='Serial port baud rate used when flashing/reading', type=int, default=os.environ.get('ESPTOOL_BAUD', esptool.ESPLoader.ESP_ROM_BAUD)) subparsers = parser.add_subparsers( dest='operation', help='Run coredumper {command} -h for additional help') parser_debug_coredump = subparsers.add_parser( 'dbg_corefile', help='Starts GDB debugging session with specified corefile') parser_debug_coredump.add_argument('--debug', '-d', help='Log level (0..3)', type=int, default=2) parser_debug_coredump.add_argument('--gdb', '-g', help='Path to gdb', default='xtensa-esp32-elf-gdb') parser_debug_coredump.add_argument('--core', '-c', help='Path to core dump file (if skipped core dump will be read from flash)', type=str) parser_debug_coredump.add_argument('--core-format', '-t', help='(elf, raw or b64). File specified with "-c" is an ELF ("elf"), ' 'raw (raw) or base64-encoded (b64) binary', type=str, default='elf') parser_debug_coredump.add_argument('--off', '-o', help='Ofsset of coredump partition in flash ' '(type "make partition_table" to see).', type=int, default=0x110000) parser_debug_coredump.add_argument('--save-core', '-s', help='Save core to file. Othwerwise temporary core file will be deleted. ' 'Ignored with "-c"', type=str) parser_debug_coredump.add_argument('--rom-elf', '-r', help='Path to ROM ELF file.', type=str, default='esp32_rom.elf') parser_debug_coredump.add_argument('prog', help='Path to program\'s ELF binary', type=str) parser_info_coredump = subparsers.add_parser( 'info_corefile', help='Print core dump info from file') parser_info_coredump.add_argument('--debug', '-d', help='Log level (0..3)', type=int, default=0) parser_info_coredump.add_argument('--gdb', '-g', help='Path to gdb', default='xtensa-esp32-elf-gdb') parser_info_coredump.add_argument('--core', '-c', help='Path to core dump file (if skipped core dump will be read from flash)', type=str) parser_info_coredump.add_argument('--core-format', '-t', help='(elf, raw or b64). File specified with "-c" is an ELF ("elf"), ' 'raw (raw) or base64-encoded (b64) binary', type=str, default='elf') parser_info_coredump.add_argument('--off', '-o', help='Offset of coredump partition in flash (type ' '"make partition_table" to see).', type=int, default=0x110000) parser_info_coredump.add_argument('--save-core', '-s', help='Save core to file. Othwerwise temporary core file will be deleted. ' 'Does not work with "-c"', type=str) parser_info_coredump.add_argument('--rom-elf', '-r', help='Path to ROM ELF file.', type=str, default='esp32_rom.elf') parser_info_coredump.add_argument('--print-mem', '-m', help='Print memory dump', action='store_true') parser_info_coredump.add_argument('prog', help='Path to program\'s ELF binary', type=str) # internal sanity check - every operation matches a module function of the same name for operation in subparsers.choices: assert operation in globals(), "%s should be a module function" % operation args = parser.parse_args() log_level = logging.CRITICAL if args.debug == 0: log_level = logging.CRITICAL elif args.debug == 1: log_level = logging.ERROR elif args.debug == 2: log_level = logging.WARNING elif args.debug == 3: log_level = logging.INFO else: log_level = logging.DEBUG # logging.warning('Watch out!') # will print a message to the console # logging.info('I told you so') # will not print anything logging.basicConfig(format='%(levelname)s:%(message)s', level=log_level) print('espcoredump.py v%s' % __version__) operation_func = globals()[args.operation] operation_func(args) if __name__ == '__main__': try: main() except ESPCoreDumpError as e: print('\nA fatal error occurred: %s' % e) sys.exit(2)