gdb/contrib/dwarf-to-dwarf-assembler.py - third_party/binutils-gdb - Git at Google

 #!/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
         if isinstance(self.name, int):
             s += "DW_AT_" + hex(self.name)
         else:
             s += self.name
         s += " "
         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.EOPNOTSUPP)

     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)
	#!/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
	if isinstance(self.name, int):
	s += "DW_AT_" + hex(self.name)
	else:
	s += self.name
	s += " "
	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.EOPNOTSUPP)

	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)