Debian Codegraph @

libdrgn/build-aux/gen_arch_inc_strswitch.py

raw
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 &registers[{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()