diff options
Diffstat (limited to 'gdb/contrib/dwarf-to-dwarf-assembler.py')
| -rwxr-xr-x | gdb/contrib/dwarf-to-dwarf-assembler.py | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/gdb/contrib/dwarf-to-dwarf-assembler.py b/gdb/contrib/dwarf-to-dwarf-assembler.py new file mode 100755 index 0000000..4b4774d --- /dev/null +++ b/gdb/contrib/dwarf-to-dwarf-assembler.py @@ -0,0 +1,642 @@ +#!/usr/bin/env python3 +# pyright: strict + +# Copyright 2024 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +# Due to the pyelftools dependency, this script requires Python version +# 3.10 or greater to run. + +"""A utility to convert ELF files with DWARF info to Dwarf::assemble code. + +Usage: + python ./asm_to_dwarf_assembler.py <path/to/elf/file> + +Dependencies: + Python >= 3.10 + pyelftools >= 0.31 + +Notes: +- Line tables are not currently supported. +- Non-contiguous subprograms are not currently supported. +- If you want to use $srcfile or similar, you must edit the references to the + file name manually, including DW_AT_name attributes on compile units. +- If run with binaries generated by make check-gdb, it may include an + additional compile_unit before and after the actual compile units. This is + an artifact of the normal compilation process, as these CUs are indeed in + the generated DWARF in some cases. +""" + +import errno +import re +import sys +from copy import copy +from dataclasses import dataclass +from datetime import datetime +from functools import cache +from io import BytesIO, IOBase +from logging import getLogger +from typing import Annotated, Optional + +from elftools.dwarf.compileunit import CompileUnit as RawCompileUnit +from elftools.dwarf.die import DIE as RawDIE +from elftools.dwarf.die import AttributeValue +from elftools.elf.elffile import ELFFile + +logger = getLogger(__file__) + + +# While these aren't supported, their detection is important for replacing them +# with SPECIAL_expr and for writing the placeholder {MANUAL} expr list. +EXPR_ATTRIBUTE_FORMS = [ + "DW_FORM_exprloc", + "DW_FORM_block", + "DW_FORM_block1", + "DW_FORM_block2", + "DW_FORM_block4", +] + + +# Workaround for my editor not to freak out over unclosed braces. +lbrace, rbrace = "{", "}" + + +@cache +def get_indent_str(indent_count: int) -> str: + """Get whitespace string to prepend to another for indenting.""" + indent = (indent_count // 2) * "\t" + if indent_count % 2 == 1: + indent += " " + return indent + + +def indent(line: str, indent_count: int) -> str: + """Indent line by indent_count levels.""" + return get_indent_str(indent_count) + line + + +def labelify_str(s: str) -> str: + """Make s appropriate for a label name.""" + # Replace "*" with the literal word "ptr". + s = s.replace("*", "ptr") + + # Replace any non-"word" characters by "_". + s = re.sub(r"\W", "_", s) + + # Remove consecutive "_"s. + s = re.sub(r"__+", "_", s) + + return s + + +class DWARFAttribute: + """Storage unit for a single DWARF attribute. + + All its values are strings that are usually passed on + directly to format. The exceptions to this are attributes + with int values with DW_FORM_ref4 or DW_FORM_ref_addr form. + Their values are interpreted as the global offset of the DIE + being referenced, which are looked up dynamically to fetch + their labels. + """ + + def __init__( + self, + die_offset: int, + name: str, + value: str | bytes | int | bool, + form=None, + ): + self.die_offset = die_offset + self.name = name + self.value = value + self.form = form + + def _format_expr_value(self) -> str: + self.form = "SPECIAL_expr" + return "{ MANUAL: Fill expr list }" + + def _needs_escaping(self, str_value: str) -> bool: + charset = set(str_value) + return bool(charset.intersection({"{", "}", " ", "\t"})) + + def _format_str(self, str_value: str) -> str: + if self._needs_escaping(str_value): + escaped_str = str(str_value) + # Replace single escape (which is itself escaped because of regex) + # with a double escape (which doesn't mean anything to regex so + # it doesn't need escaping). + escaped_str = re.sub(r"\\", r"\\", escaped_str) + escaped_str = re.sub("([{}])", r"\\\1", escaped_str) + return "{" + escaped_str + "}" + else: + return str_value + + def _format_value( + self, offset_die_lookup: dict[int, "DWARFDIE"], indent_count: int = 0 + ) -> str: + if self.form in EXPR_ATTRIBUTE_FORMS: + return self._format_expr_value() + elif isinstance(self.value, bool): + return str(int(self.value)) + elif isinstance(self.value, int): + if self.form == "DW_FORM_ref4": + # ref4-style referencing label. + die = offset_die_lookup[self.value] + return ":$" + die.tcl_label + elif self.form == "DW_FORM_ref_addr": + # ref_addr-style referencing label. + die = offset_die_lookup[self.value] + return "%$" + die.tcl_label + else: + return str(self.value) + elif isinstance(self.value, bytes): + return self._format_str(self.value.decode("ascii")) + elif isinstance(self.value, str): + return self._format_str(self.value) + else: + raise NotImplementedError(f"Unknown data type: {type(self.value)}") + + def format( + self, offset_die_lookup: dict[int, "DWARFDIE"], indent_count: int = 0 + ) -> str: + """Format the attribute in the form {name value form}. + + If form is DW_FORM_exprloc or DW_FORM_block, see next section on + DWARFOperations. + + If it isn't, value is formatted as follows: + If bool, use "1" if True, "0" if False. + If int: + If form is DW_FORM_ref4, use ":$label" where label is the + tcl_label of the DWARFDIE at offset "value". + If form is DW_FORM_ref_addr, use "%$label" where label is + the tcl_label of the DWARFDIE at offset "value". + Else, use value directly. + If bytes, use value.decode("ascii") + If str, use value directly. + Any other type results in a NotImplementedError being raised. + + Regarding DW_FORM_exprloc and DW_FORM_block: + The form is replaced with SPECIAL_expr. + The entries in the value are interpreted and decoded using the + dwarf_operations dictionary, and replaced with their names where + applicable. + """ + s = lbrace + s += self.name + " " + s += self._format_value(offset_die_lookup) + + # Only explicitly state form if it's not a reference. + if self.form not in [None, "DW_FORM_ref4", "DW_FORM_ref_addr"]: + s += " " + self.form + + s += rbrace + return indent(s, indent_count) + + +class DWARFDIE: + """This script's parsed version of a RawDIE.""" + + def __init__( + self, + offset: int, + tag: str, + attrs: dict[str, DWARFAttribute], + tcl_label: Optional[str] = None, + ): + self.offset: Annotated[int, "Global offset of the DIE."] = offset + self.tag: Annotated[str, "DWARF tag for this DIE."] = tag + self.attrs: Annotated[ + dict[str, DWARFAttribute], "Dict of attributes for this DIE." + ] = copy(attrs) + self.children: Annotated[list[DWARFDIE], "List of child DIEs of this DIE."] = [] + self.tcl_label: Annotated[ + str, + "Label used by the Tcl code to reference this DIE, if any. These " + 'take the form of "label: " before the actual DIE definition.', + ] = tcl_label + + def format_lines( + self, offset_die_lookup: dict[int, "DWARFDIE"], indent_count: int = 0 + ) -> list[str]: + """Get the list of lines that represent this DIE in Dwarf assembler.""" + die_lines = [] + + # Prepend label to first line, if it's set. + if self.tcl_label: + first_line_start = self.tcl_label + ": " + else: + first_line_start = "" + + # First line, including label. + first_line = indent(first_line_start + self.tag + " " + lbrace, indent_count) + die_lines.append(first_line) + + # Format attributes, if any. + if self.attrs: + for attr_name, attr in self.attrs.items(): + attr_line = attr.format( + offset_die_lookup, indent_count=indent_count + 1 + ) + die_lines.append(attr_line) + die_lines.append(indent(rbrace, indent_count)) + else: + # Don't create a new line, just append and immediately close the + # brace on the last line. + die_lines[-1] += rbrace + + # Format children, if any. + if self.children: + # Only open a new brace if there are any children for the + # current DIE. + die_lines[-1] += " " + lbrace + for child in self.children: + child_lines = child.format_lines( + offset_die_lookup, indent_count=indent_count + 1 + ) + die_lines.extend(child_lines) + die_lines.append(indent(rbrace, indent_count)) + + return die_lines + + def format( + self, offset_die_lookup: dict[int, "DWARFDIE"], indent_count: int = 0 + ) -> str: + """Join result from format_lines into a single str.""" + return "\n".join(self.format_lines(offset_die_lookup, indent_count)) + + def name(self) -> Optional[str]: + """Get DW_AT_name (if present) decoded as ASCII.""" + raw_value = self.attrs.get("DW_AT_name") + if raw_value is None: + return None + else: + return raw_value.value.decode("ascii") + + def type_name(self) -> str: + """Name of Dwarf tag, with the "DW_TAG_" prefix removed.""" + return re.sub("DW_TAG_", "", self.tag) + + +class DWARFCompileUnit(DWARFDIE): + """Wrapper subclass for CU DIEs. + + This is necessary due to the special format CUs take in Dwarf::assemble. + + Instead of simply: + DW_TAG_compile_unit { + <attributes> + } { + <children> + } + + CUs are formatted as: + cu { <cu_special_vars> } { + DW_TAG_compile_unit { + <attributes> + } { + <children> + } + } + """ + + # Default value for parameter is_64 defined in dwarf.exp line 1553. + # This value is converted to 0/1 automatically when emitting + # Dwarf::assemble code. + default_is_64 = False + + # Default value for parameter dwarf_version defined in dwarf.exp line 1552. + default_dwarf_version = 4 + + # Default value for parameter is_fission defined in dwarf.exp line 1556. + # Currently not implemented, see comment below. + # default_is_fission = False + + # Tag that signifies a DIE is a compile unit. + compile_unit_tag = "DW_TAG_compile_unit" + + def __init__( + self, + raw_die: RawDIE, + raw_cu: RawCompileUnit, + attrs: dict[str, DWARFAttribute], + ): + """Initialize additional instance variables for CU encoding. + + The additional instance variables are: + - is_64_bit: bool + Whether this CU is 64 bit or not. + - dwarf_version: int + default DWARFCompileUnit.default_dwarf_version + Version of DWARF this CU is using. + - addr_size: Optional[int] + default None + Size of an address in bytes. + + These variables are used to configure the first parameter of the cu + proc (which contains calls to the compile_unit proc in the body of + Dwarf::assemble). + """ + super().__init__(raw_die.offset, DWARFCompileUnit.compile_unit_tag, attrs) + self.raw_cu = raw_cu + self.dwarf_version: int = raw_cu.header.get( + "version", DWARFCompileUnit.default_dwarf_version + ) + self.addr_size: Optional[int] = raw_cu.header.get("address_size") + self.is_64_bit: bool = raw_cu.dwarf_format() == 64 + + # Fission is not currently implemented because I don't know where to + # fetch this information from. + # self.is_fission: bool = self.default_is_fission + + # CU labels are not currently implemented because I haven't found where + # pyelftools exposes this information. + # self.cu_label: Optional[str] = None + + def format_lines( + self, + offset_die_lookup: dict[int, DWARFDIE], + indent_count: int = 0, + ) -> list[str]: + lines = [] + lines.append(self._get_header(indent_count)) + inner_lines = super().format_lines(offset_die_lookup, indent_count + 1) + lines += inner_lines + lines.append(indent(rbrace, indent_count)) + return lines + + def _get_header(self, indent_count: int = 0) -> str: + """Assemble the first line of the surrounding 'cu {} {}' proc call.""" + header = indent("cu " + lbrace, indent_count) + cu_params = [] + + if self.is_64_bit != DWARFCompileUnit.default_is_64: + # Convert from True/False to 1/0. + param_value = int(self.is_64_bit) + cu_params += ["is_64", str(param_value)] + + if self.dwarf_version != DWARFCompileUnit.default_dwarf_version: + cu_params += ["version", str(self.dwarf_version)] + + if self.addr_size is not None: + cu_params += ["addr_size", str(self.addr_size)] + + # Fission is not currently implemented, see comment above. + # if self.is_fission != DWARFCompileUnit.default_is_fission: + # # Same as is_64_bit conversion, True/False -> 1/0. + # param_value = int(self.is_fission) + # cu_params += ["fission", str(param_value)] + + # CU labels are not currently implemented, see commend above. + # if self.cu_label is not None: + # cu_params += ["label", self.cu_label] + + if cu_params: + header += " ".join(cu_params) + + header += rbrace + " " + lbrace + return header + + +class DWARFParser: + """Converter from pyelftools's DWARF representation to this script's.""" + + def __init__(self, elf_file: IOBase): + """Init parser with file opened in binary mode. + + File can be closed after this function is called. + """ + self.raw_data = BytesIO(elf_file.read()) + self.elf_data = ELFFile(self.raw_data) + self.dwarf_info = self.elf_data.get_dwarf_info() + self.offset_to_die: dict[int, DWARFDIE] = {} + self.label_to_die: dict[str, DWARFDIE] = {} + self.referenced_offsets: Annotated[ + set[int], "The set of all offsets that were referenced by some DIE." + ] = set() + self.raw_cu_list: list[RawCompileUnit] = [] + self.top_level_dies: list[DWARFDIE] = [] + self.subprograms: list[DWARFDIE] = [] + self.taken_labels: set[str] = set() + + self._read_all_cus() + self._create_necessary_labels() + + def _read_all_cus(self): + """Populate self.raw_cu_list with all CUs in self.dwarf_info.""" + for cu in self.dwarf_info.iter_CUs(): + self._read_cu(cu) + + def _read_cu(self, raw_cu: RawCompileUnit): + """Read a compile_unit into self.cu_list.""" + self.raw_cu_list.append(raw_cu) + for raw_die in raw_cu.iter_DIEs(): + if not raw_die.is_null(): + self._parse_die(raw_cu, raw_die) + + def _parse_die(self, die_cu: RawCompileUnit, raw_die: RawDIE) -> DWARFDIE: + """Process a single DIE and add it to offset_to_die. + + Look for DW_FORM_ref4 and DWD_FORM_ref_addr form attributes and replace + them with the global offset of the referenced DIE, and adding the + referenced DIE to a set. This will be used later to assign and use + labels only to DIEs that need it. + + In case the DIE is a top-level DIE, add it to self.top_level_dies. + + In case the DIE is a subprogram, add it to self.subprograms and call + self._use_vars_for_low_and_high_pc_attr with it. + """ + processed_attrs = {} + attr_value: AttributeValue + for attr_name, attr_value in raw_die.attributes.items(): + actual_value = attr_value.value + if attr_value.form in ("DW_FORM_ref4", "DW_FORM_ref_addr"): + referenced_die = raw_die.get_DIE_from_attribute(attr_name) + actual_value = referenced_die.offset + self.referenced_offsets.add(referenced_die.offset) + + processed_attrs[attr_name] = DWARFAttribute( + raw_die.offset, attr_name, actual_value, attr_value.form + ) + + if raw_die.tag == DWARFCompileUnit.compile_unit_tag: + processed_die = DWARFCompileUnit(raw_die, die_cu, processed_attrs) + else: + processed_die = DWARFDIE(raw_die.offset, raw_die.tag, processed_attrs, None) + + if raw_die.get_parent() is None: + # Top level DIE + self.top_level_dies.append(processed_die) + else: + # Setting the parent here assumes the parent was already processed + # prior to this DIE being found. + # As far as I'm aware, this is always true in DWARF. + processed_parent = self.offset_to_die[raw_die.get_parent().offset] + processed_parent.children.append(processed_die) + + if processed_die.tag == "DW_TAG_subprogram": + self.subprograms.append(processed_die) + self._use_vars_for_low_and_high_pc_attr(processed_die) + + self.offset_to_die[processed_die.offset] = processed_die + return processed_die + + def _create_necessary_labels(self): + """Create labels to DIEs that were referenced by others.""" + for offset in self.referenced_offsets: + die = self.offset_to_die[offset] + self._create_label_for_die(die) + + def _use_vars_for_low_and_high_pc_attr(self, subprogram: DWARFDIE) -> None: + """Replace existing PC attributes with Tcl variables. + + If DW_AT_low_pc exists for this DIE, replace it with accessing the + variable whose name is given by self.subprogram_start_var(subprogram). + + If DW_AT_high_pc exists for this DIE, replace it with accessing the + variable whose name is given by self.subprogram_end_var(subprogram). + """ + low_pc_attr_name = "DW_AT_low_pc" + if low_pc_attr_name in subprogram.attrs: + start = self.subprogram_start_var(subprogram) + subprogram.attrs[low_pc_attr_name].value = start + + high_pc_attr_name = "DW_AT_high_pc" + if high_pc_attr_name in subprogram.attrs: + end = self.subprogram_end_var(subprogram) + subprogram.attrs[high_pc_attr_name].value = end + + def _create_label_for_die(self, die: DWARFDIE) -> None: + """Set tcl_label to a unique string among other DIEs for this parser. + + As a first attempt, use labelify(die.name()). If the DIE does not have + a name, use labelify(die.type_name()). + + If the chosen initial label is already taken, try again appending "_2". + While the attempt is still taken, try again replacing it with "_3", then + "_4", and so on. + + This function also creates an entry on self.label_to_die. + """ + if die.tcl_label is not None: + return + + label = labelify_str(die.name() or die.type_name()) + + # Deduplicate label in case of collision + if label in self.taken_labels: + suffix_nr = 2 + + # Walrus operator to prevent writing the assembled label_suffix + # string literal twice. This could be rewritten by copying the + # string literal to the line after the end of the while loop, + # but I deemed it would be too frail in case one of them needs + # to be changed and the other is forgotten. + while (new_label := f"{label}_{suffix_nr}") in self.taken_labels: + suffix_nr += 1 + label = new_label + + die.tcl_label = label + self.label_to_die[label] = die + self.taken_labels.add(label) + + def subprogram_start_var(self, subprogram: DWARFDIE) -> str: + """Name of the Tcl variable that holds the low PC for a subprogram.""" + return f"${subprogram.name()}_start" + + def subprogram_end_var(self, subprogram: DWARFDIE) -> str: + """Name of the Tcl variable that holds the high PC for a subprogram.""" + return f"${subprogram.name()}_end" + + def all_labels(self) -> set[str]: + """Get a copy of the set of all labels known to the parser so far.""" + return copy(self.taken_labels) + + +class DWARFAssemblerGenerator: + """Class that generates Dwarf::assemble code out of a DWARFParser.""" + + def __init__(self, dwarf_parser: DWARFParser, output=sys.stdout): + self.dwarf_parser = dwarf_parser + self.output = output + + def emit(self, line: str, indent_count: int) -> None: + """Print a single line indented indent_count times to self.output. + + If line is empty, it will always print an empty line, even with nonzero + indent_count. + """ + if line: + line = get_indent_str(indent_count) + line + print(line, file=self.output) + + def generate_die(self, die: DWARFDIE, indent_count: int): + """Generate the lines that represent a DIE.""" + die_lines = die.format(self.dwarf_parser.offset_to_die, indent_count) + self.emit(die_lines, 0) + + def generate(self): + indent_count = 0 + + self.emit("Dwarf::assemble $asm_file {", indent_count) + + # Begin Dwarf::assemble body. + indent_count += 1 + self.emit("global srcdir subdir srcfile", indent_count) + + all_labels = self.dwarf_parser.all_labels() + if all_labels: + self.emit("declare_labels " + " ".join(all_labels), indent_count) + + self.emit("", 0) + for subprogram in self.dwarf_parser.subprograms: + self.emit(f"get_func_info {subprogram.name()}", indent_count) + + for die in self.dwarf_parser.top_level_dies: + self.generate_die(die, indent_count) + + # TODO: line table, if it's within scope (it probably isn't). + + # End Dwarf::assemble body. + indent_count -= 1 + self.emit(rbrace, indent_count) + + +def main(argv): + try: + filename = argv[1] + except IndexError: + print("Usage:", file=sys.stderr) + print("python ./asm_to_dwarf_assembler.py <path/to/elf/file>", file=sys.stderr) + sys.exit(errno.EOPNOTSUP) + + try: + with open(filename, "rb") as elf_file: + parser = DWARFParser(elf_file) + except Exception as e: + print( + "Error parsing ELF file. Does it contain DWARF information?", + file=sys.stderr, + ) + print(str(e), file=sys.stderr) + sys.exit(errno.ENODATA) + generator = DWARFAssemblerGenerator(parser) + generator.generate() + + +if __name__ == "__main__": + main(sys.argv) |