| 1 |
#!/usr/bin/env python3 |
| 2 |
# Copyright (c) Meta Platforms, Inc. and affiliates. |
| 3 |
# SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
|
| 5 |
r""" |
| 6 |
This script reads a drgn architecture definition file ("arch_foo_defs.py") and |
| 7 |
outputs architecture definition code which must then be processed by |
| 8 |
gen_strswitch.py to produce the final "arch_foo.inc" file. |
| 9 |
|
| 10 |
The definition file must define three global variables: |
| 11 |
|
| 12 |
* REGISTERS must be a sequence of DrgnRegister defining the names of all of the |
| 13 |
registers in the architecture. They should be defined in the architecture's |
| 14 |
logical order. See DrgnRegister below for more details. |
| 15 |
|
| 16 |
* REGISTER_LAYOUT must be a sequence of DrgnRegisterLayout defining how drgn |
| 17 |
stores the registers in memory. The defined registers are laid out |
| 18 |
sequentially. To minimize memory usage, registers can be ordered by how |
| 19 |
commonly they are saved (typically, the program counter/return address |
| 20 |
register first, then the stack pointer register, then callee-saved registers, |
| 21 |
and last caller-saved registers). They can also be ordered to match the |
| 22 |
format in, e.g., NT_PRSTATUS. Every register in REGISTERS must have an entry |
| 23 |
in REGISTER_LAYOUT. However, the converse does not need to be true. For |
| 24 |
example, REGISTER_LAYOUT can contain pseudo-registers that are not in |
| 25 |
REGISTERS and are thus not exposed to the API. See DrgnRegisterLayout below |
| 26 |
for more details. |
| 27 |
|
| 28 |
* STACK_POINTER_REGISTER must be the identifier of the register which contains |
| 29 |
the stack pointer. |
| 30 |
|
| 31 |
The generated file includes "arch_register_layout.h" and defines several things: |
| 32 |
|
| 33 |
1. An enum of register numbers used to implement DRGN_REGISTER_NUMBER(). |
| 34 |
|
| 35 |
2. A structure corresponding to the register layout used to implement |
| 36 |
DRGN_REGISTER_OFFSET(), DRGN_REGISTER_SIZE(), and DRGN_REGISTER_END(): |
| 37 |
struct drgn_arch_register_layout; |
| 38 |
|
| 39 |
3. An array of register layouts indexed by internal register number: |
| 40 |
static const struct drgn_register_layout register_layout[]; |
| 41 |
|
| 42 |
4. An array of register definitions: |
| 43 |
static const struct drgn_register registers[]; |
| 44 |
|
| 45 |
5. A name lookup function: |
| 46 |
static const struct drgn_register *register_by_name(const char *name); |
| 47 |
|
| 48 |
6. A mapping from DWARF register numbers to internal register numbers: |
| 49 |
static drgn_register_number dwarf_regno_to_internal(uint64_t dwarf_regno); |
| 50 |
|
| 51 |
7. A macro containing initializers for the "register_layout", |
| 52 |
"dwarf_regno_to_internal", "registers", "num_registers", |
| 53 |
"stack_pointer_regno", and "register_by_name" members of |
| 54 |
"struct drgn_architecture_info": |
| 55 |
#define DRGN_ARCHITECTURE_REGISTERS ... |
| 56 |
""" |
| 57 |
|
| 58 |
import argparse |
| 59 |
import re |
| 60 |
import runpy |
| 61 |
import sys |
| 62 |
from typing import Optional, Sequence, TextIO, Union |
| 63 |
|
| 64 |
from codegen_utils import c_string_literal |
| 65 |
|
| 66 |
|
| 67 |
class ArchDefsError(Exception): |
| 68 |
pass |
| 69 |
|
| 70 |
|
| 71 |
class DrgnRegister: |
| 72 |
def __init__( |
| 73 |
self, names: Union[str, Sequence[str]], *, identifier: Optional[str] = None |
| 74 |
) -> None: |
| 75 |
""" |
| 76 |
Register definition. |
| 77 |
|
| 78 |
:param names: Name or names of the register (i.e., name used for this |
| 79 |
register in assembly language or documentation). |
| 80 |
:param identifier: Register identifier matching |
| 81 |
:attr:`DrgnRegisterLayout.identifier`. Defaults to the first |
| 82 |
register name with non-alphanumeric characters replaced by "_" and |
| 83 |
prepended with "_" if the first character is numeric. |
| 84 |
""" |
| 85 |
self.names = (names,) if isinstance(names, str) else names |
| 86 |
for name in self.names: |
| 87 |
if not name: |
| 88 |
raise ArchDefsError(f"invalid register name {name!r}") |
| 89 |
if identifier is None: |
| 90 |
identifier = re.sub(r"[^a-zA-Z0-9_]", "_", self.names[0]) |
| 91 |
if not re.match(r"^[a-zA-Z_]", identifier): |
| 92 |
identifier = "_" + identifier |
| 93 |
self.identifier = identifier |
| 94 |
|
| 95 |
|
| 96 |
class DrgnRegisterLayout: |
| 97 |
def __init__( |
| 98 |
self, identifier: str, *, size: int, dwarf_number: Optional[int] |
| 99 |
) -> None: |
| 100 |
""" |
| 101 |
Register layout definition. |
| 102 |
|
| 103 |
:param identifier: C identifier for the register to use in the |
| 104 |
generated file. |
| 105 |
:param size: Size used to store the register in bytes. |
| 106 |
:param dwarf_number: DWARF register number, or ``None`` if the register |
| 107 |
is not represented in DWARF. |
| 108 |
""" |
| 109 |
self.identifier = identifier |
| 110 |
if not re.fullmatch(r"^[a-zA-Z_][a-zA-Z0-9_]*", identifier): |
| 111 |
raise ArchDefsError(f"invalid register identifier {identifier!r}") |
| 112 |
self.size = size |
| 113 |
if size <= 0: |
| 114 |
raise ArchDefsError(f"invalid register layout size {size}") |
| 115 |
self.dwarf_number = dwarf_number |
| 116 |
|
| 117 |
|
| 118 |
def validate_register_defs( |
| 119 |
registers: Sequence[DrgnRegister], |
| 120 |
register_layout: Sequence[DrgnRegisterLayout], |
| 121 |
stack_pointer_register: str, |
| 122 |
) -> None: |
| 123 |
layout_by_identifier = {} |
| 124 |
for layout in register_layout: |
| 125 |
if layout.identifier in layout_by_identifier: |
| 126 |
raise ArchDefsError( |
| 127 |
f"register identifier {layout.identifier!r} is duplicated in REGISTER_LAYOUT" |
| 128 |
) |
| 129 |
layout_by_identifier[layout.identifier] = layout |
| 130 |
|
| 131 |
names = set() |
| 132 |
register_identifiers = set() |
| 133 |
for register in registers: |
| 134 |
for name in register.names: |
| 135 |
if name in names: |
| 136 |
raise ArchDefsError( |
| 137 |
f"register name {name!r} is duplicated in REGISTERS" |
| 138 |
) |
| 139 |
names.add(name) |
| 140 |
if register.identifier not in layout_by_identifier: |
| 141 |
raise ArchDefsError( |
| 142 |
f"register identifier {register.identifier} in REGISTERS is not in REGISTER_LAYOUT" |
| 143 |
) |
| 144 |
if register.identifier in register_identifiers: |
| 145 |
raise ArchDefsError( |
| 146 |
f"register identifier {register.identifier!r} is duplicated in REGISTERS" |
| 147 |
) |
| 148 |
register_identifiers.add(register.identifier) |
| 149 |
|
| 150 |
if stack_pointer_register not in layout_by_identifier: |
| 151 |
raise ArchDefsError( |
| 152 |
f"stack pointer register identifier {stack_pointer_register!r} is not in REGISTER_LAYOUT" |
| 153 |
) |
| 154 |
if layout_by_identifier[stack_pointer_register].size > 8: |
| 155 |
raise ArchDefsError( |
| 156 |
f"stack pointer register {stack_pointer_register!r} is too big" |
| 157 |
) |
| 158 |
|
| 159 |
|
| 160 |
def gen_arch_inc_strswitch( |
| 161 |
registers: Sequence[DrgnRegister], |
| 162 |
register_layout: Sequence[DrgnRegisterLayout], |
| 163 |
stack_pointer_register: str, |
| 164 |
out_file: TextIO, |
| 165 |
) -> None: |
| 166 |
validate_register_defs(registers, register_layout, stack_pointer_register) |
| 167 |
|
| 168 |
out_file.write("/* Generated by libdrgn/build-aux/gen_arch_inc_strswitch.py. */\n") |
| 169 |
|
| 170 |
out_file.write("\n") |
| 171 |
out_file.write("enum {\n") |
| 172 |
for layout in register_layout: |
| 173 |
out_file.write(f"\tDRGN_REGISTER_NUMBER__{layout.identifier},\n") |
| 174 |
out_file.write("};\n") |
| 175 |
|
| 176 |
out_file.write("\n") |
| 177 |
out_file.write("struct drgn_arch_register_layout {\n") |
| 178 |
for layout in register_layout: |
| 179 |
out_file.write(f"\tchar {layout.identifier}[{layout.size}];\n") |
| 180 |
out_file.write("};\n") |
| 181 |
|
| 182 |
out_file.write("\n") |
| 183 |
out_file.write("static const struct drgn_register_layout register_layout[] = {\n") |
| 184 |
for layout in register_layout: |
| 185 |
out_file.write( |
| 186 |
f"\t{{ offsetof(struct drgn_arch_register_layout, {layout.identifier}), {layout.size} }},\n" |
| 187 |
) |
| 188 |
out_file.write("};\n") |
| 189 |
|
| 190 |
out_file.write("\n") |
| 191 |
out_file.write( |
| 192 |
"static drgn_register_number dwarf_regno_to_internal(uint64_t dwarf_regno)\n" |
| 193 |
) |
| 194 |
out_file.write("{\n") |
| 195 |
out_file.write("\tswitch (dwarf_regno) {\n") |
| 196 |
for layout in register_layout: |
| 197 |
if layout.dwarf_number is not None: |
| 198 |
out_file.write(f"\tcase {layout.dwarf_number}:\n") |
| 199 |
out_file.write(f"\t\treturn DRGN_REGISTER_NUMBER__{layout.identifier};\n") |
| 200 |
out_file.write("\tdefault:\n") |
| 201 |
out_file.write("\t\treturn DRGN_REGISTER_NUMBER_UNKNOWN;\n") |
| 202 |
out_file.write("\t}\n") |
| 203 |
out_file.write("}\n") |
| 204 |
|
| 205 |
out_file.write("\n") |
| 206 |
out_file.write("static const struct drgn_register registers[] = {\n") |
| 207 |
for register in registers: |
| 208 |
out_file.write("\t{\n") |
| 209 |
out_file.write("\t\t.names = (const char * const []){\n") |
| 210 |
for name in register.names: |
| 211 |
out_file.write(f"\t\t\t{c_string_literal(name)},\n") |
| 212 |
out_file.write("\t\t},\n") |
| 213 |
out_file.write(f"\t\t.num_names = {len(register.names)},\n") |
| 214 |
out_file.write(f"\t\t.regno = DRGN_REGISTER_NUMBER__{register.identifier},\n") |
| 215 |
out_file.write("\t},\n") |
| 216 |
out_file.write("};\n") |
| 217 |
|
| 218 |
out_file.write("\n") |
| 219 |
out_file.write( |
| 220 |
"static const struct drgn_register *register_by_name(const char *name)\n" |
| 221 |
) |
| 222 |
out_file.write("{\n") |
| 223 |
out_file.write("\t@strswitch (name)@\n") |
| 224 |
for i, register in enumerate(registers): |
| 225 |
for name in register.names: |
| 226 |
out_file.write(f"\t@case {c_string_literal(name)}@\n") |
| 227 |
out_file.write(f"\t\treturn ®isters[{i}];\n") |
| 228 |
out_file.write("\t@default@\n") |
| 229 |
out_file.write("\t\treturn NULL;\n") |
| 230 |
out_file.write("\t@endswitch@\n") |
| 231 |
out_file.write("}\n") |
| 232 |
|
| 233 |
out_file.write("\n") |
| 234 |
out_file.write("#define DRGN_ARCHITECTURE_REGISTERS \\\n") |
| 235 |
out_file.write("\t.register_layout = register_layout, \\\n") |
| 236 |
out_file.write("\t.dwarf_regno_to_internal = dwarf_regno_to_internal, \\\n") |
| 237 |
out_file.write("\t.registers = registers, \\\n") |
| 238 |
out_file.write(f"\t.num_registers = {len(registers)}, \\\n") |
| 239 |
out_file.write( |
| 240 |
f"\t.stack_pointer_regno = DRGN_REGISTER_NUMBER__{stack_pointer_register}, \\\n" |
| 241 |
) |
| 242 |
out_file.write("\t.register_by_name = register_by_name\n") |
| 243 |
|
| 244 |
|
| 245 |
def main() -> None: |
| 246 |
parser = argparse.ArgumentParser( |
| 247 |
description="Generate arch_foo.inc.strswitch from arch_foo_defs.py" |
| 248 |
) |
| 249 |
parser.add_argument("input", metavar="FILE", help="input arch_foo_defs.py file") |
| 250 |
args = parser.parse_args() |
| 251 |
|
| 252 |
try: |
| 253 |
defs = runpy.run_path( |
| 254 |
args.input, |
| 255 |
init_globals={ |
| 256 |
"DrgnRegister": DrgnRegister, |
| 257 |
"DrgnRegisterLayout": DrgnRegisterLayout, |
| 258 |
}, |
| 259 |
) |
| 260 |
try: |
| 261 |
registers = defs["REGISTERS"] |
| 262 |
register_layout = defs["REGISTER_LAYOUT"] |
| 263 |
stack_pointer_register = defs["STACK_POINTER_REGISTER"] |
| 264 |
except KeyError as e: |
| 265 |
sys.exit(f"{e.args[0]} is not defined") |
| 266 |
gen_arch_inc_strswitch( |
| 267 |
registers, register_layout, stack_pointer_register, sys.stdout |
| 268 |
) |
| 269 |
except ArchDefsError as e: |
| 270 |
sys.exit(e) |
| 271 |
|
| 272 |
|
| 273 |
if __name__ == "__main__": |
| 274 |
main() |