sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
sensorium/c/dwarf.py ADDED
@@ -0,0 +1,706 @@
1
+ """DWARF image index for the C recorder.
2
+
3
+ One pass over the compilation units builds a ``Func`` per ``low_pc``.
4
+ Types are the plain objects ``decode.py`` walks; nothing here is asked
5
+ again on the per-call path. Addresses are unrelocated ELF ``low_pc``
6
+ values, the same numbers a ``.scplan`` stores. The converter subtracts
7
+ the load bias from ``objs.txt`` before lookup, so PIE and non-PIE use
8
+ the same numbers.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ from bisect import bisect_right
14
+
15
+ from sensorium.c.decode import UNREAD, VOID, CType, Member
16
+ from sensorium.c.plan import classify_return
17
+
18
+ try:
19
+ from elftools.dwarf.descriptions import describe_form_class
20
+ from elftools.elf.elffile import ELFFile
21
+ except ImportError as e: # pragma: no cover - the tests skip this case
22
+ raise ImportError(
23
+ "pyelftools is required to read DWARF (pip install pyelftools)"
24
+ ) from e
25
+
26
+ _DW_OP_REG6 = 0x56
27
+ _DW_OP_BREG6 = 0x76
28
+ _DW_OP_FBREG = 0x91
29
+ _DW_OP_CFA = 0x9C
30
+ _DW_OP_PLUS_UCONST = 0x23
31
+
32
+ _STRIP = {
33
+ "DW_TAG_typedef", "DW_TAG_const_type", "DW_TAG_volatile_type",
34
+ "DW_TAG_restrict_type",
35
+ }
36
+ _FUNC_TYPES = {"STT_FUNC", "STT_GNU_IFUNC", "STT_LOOS"}
37
+
38
+
39
+ class Param:
40
+ """One formal parameter. ``off`` is None when the slot is not a
41
+ plain ``DW_OP_fbreg`` (optimized out, a register, or a location list)."""
42
+
43
+ __slots__ = ("name", "off", "typ")
44
+
45
+ def __init__(self, name, off, typ):
46
+ self.name = name
47
+ self.off = off
48
+ self.typ = typ
49
+
50
+
51
+ class Func:
52
+ """One subprogram. ``ret_type`` is the type ``classify_return`` saw,
53
+ so a mixed struct still carries its eightbyte map."""
54
+
55
+ __slots__ = (
56
+ "addr", "name", "file", "line", "params", "ret_type",
57
+ "ret_class", "ret_nreg", "ret_size",
58
+ )
59
+
60
+ def __init__(self, addr, name, file, line, params, ret_type):
61
+ self.addr = addr
62
+ self.name = name
63
+ self.file = file
64
+ self.line = line
65
+ self.params = params
66
+ self.ret_type = ret_type if ret_type is not None else VOID
67
+ cls, nreg, size = classify_return(self.ret_type)
68
+ self.ret_class = cls
69
+ self.ret_nreg = nreg
70
+ self.ret_size = size
71
+
72
+
73
+ class DwarfImage:
74
+ """Functions keyed by unrelocated ``low_pc``."""
75
+
76
+ def __init__(self, path):
77
+ self.path = os.fspath(path)
78
+ self.funcs: dict[int, Func] = {}
79
+ self._types: dict[int, CType] = {}
80
+ self._names: dict[int, str] = {}
81
+ self._spans: list[tuple] = []
82
+ self._starts: list[int] = []
83
+ self._syms: list[tuple] = []
84
+ self._sym_addrs: list[int] = []
85
+ with open(self.path, "rb") as fh:
86
+ elf = ELFFile(fh)
87
+ self._load_syms(elf)
88
+ if elf.has_dwarf_info():
89
+ dwarf = elf.get_dwarf_info()
90
+ for cu in dwarf.iter_CUs():
91
+ self._cu(dwarf, cu)
92
+ self._finish_lines()
93
+
94
+ def line_at(self, addr):
95
+ """``(file, line)`` for an unrelocated address, or None in a gap."""
96
+ if not self._starts:
97
+ return None
98
+ i = bisect_right(self._starts, addr) - 1
99
+ if i < 0:
100
+ return None
101
+ start, end, file, line = self._spans[i]
102
+ if start <= addr < end:
103
+ return (file, line)
104
+ return None
105
+
106
+ def symbol_at(self, addr):
107
+ """Innermost function symbol covering an unrelocated address."""
108
+ if not self._sym_addrs:
109
+ return None
110
+ i = bisect_right(self._sym_addrs, addr) - 1
111
+ best = None
112
+ best_span = None
113
+ while i >= 0:
114
+ val, end, name = self._syms[i]
115
+ if best is not None and addr - val >= best_span:
116
+ break
117
+ if val <= addr < end:
118
+ span = end - val
119
+ if best is None or span < best_span:
120
+ best = name
121
+ best_span = span
122
+ i -= 1
123
+ return best
124
+
125
+ def _cu(self, dwarf, cu) -> None:
126
+ top = cu.get_top_DIE()
127
+ comp = _text(top, "DW_AT_comp_dir") or ""
128
+ cu_name = _text(top, "DW_AT_name") or "?"
129
+ version = cu.header.version
130
+ files = _files(dwarf, cu, comp)
131
+ self._lines(dwarf, cu, files, version)
132
+ for die in cu.iter_DIEs():
133
+ if die.tag != "DW_TAG_subprogram":
134
+ continue
135
+ addr = _low_pc(die)
136
+ if addr is None or addr in self.funcs:
137
+ continue
138
+ if _flag(die, "DW_AT_declaration") and "DW_AT_low_pc" not in die.attributes:
139
+ continue
140
+ origin = _named(die)
141
+ name = _text(origin, "DW_AT_name") or f"fn_{addr:x}"
142
+ file = _decl_file(die, origin, files, comp, cu_name, version)
143
+ line = _decl_line(die) or _decl_line(origin)
144
+ kind = _frame_kind(die) or _frame_kind(origin)
145
+ params = _params(self, die, origin, kind)
146
+ tdie = _follow(origin, "DW_AT_type") or _follow(die, "DW_AT_type")
147
+ ret = VOID if tdie is None else self._type(tdie)
148
+ self.funcs[addr] = Func(addr, name, file, line, params, ret)
149
+
150
+ def _lines(self, dwarf, cu, files, version) -> None:
151
+ try:
152
+ lp = dwarf.line_program_for_CU(cu)
153
+ except Exception:
154
+ return
155
+ if lp is None:
156
+ return
157
+
158
+ def fidx(i):
159
+ slot = i if version >= 5 else i - 1
160
+ if isinstance(slot, int) and 0 <= slot < len(files):
161
+ return files[slot]
162
+ return "<unknown>"
163
+
164
+ open_row = None
165
+ for entry in lp.get_entries():
166
+ st = entry.state
167
+ if st is None:
168
+ continue
169
+ if open_row is not None:
170
+ start, file, line = open_row
171
+ if st.address > start:
172
+ self._spans.append((start, st.address, file, line))
173
+ open_row = None
174
+ if not st.end_sequence:
175
+ open_row = (st.address, fidx(st.file), st.line)
176
+
177
+ def _finish_lines(self) -> None:
178
+ spans = sorted(self._spans, key=lambda s: (s[0], s[1]))
179
+ dedup = {}
180
+ order = []
181
+ for start, end, file, line in spans:
182
+ if start not in dedup:
183
+ order.append(start)
184
+ dedup[start] = (start, end, file, line)
185
+ self._spans = [dedup[s] for s in order]
186
+ self._starts = order
187
+
188
+ def _load_syms(self, elf) -> None:
189
+ rows = []
190
+ for sec in (".symtab", ".dynsym"):
191
+ table = elf.get_section_by_name(sec)
192
+ if table is None:
193
+ continue
194
+ for sym in table.iter_symbols():
195
+ if sym["st_info"]["type"] not in _FUNC_TYPES:
196
+ continue
197
+ name = sym.name
198
+ if not name:
199
+ continue
200
+ val = int(sym["st_value"])
201
+ size = int(sym["st_size"] or 0)
202
+ if val == 0 and size == 0:
203
+ continue
204
+ rows.append((val, val + max(size, 1), name))
205
+ rows.sort()
206
+ self._syms = rows
207
+ self._sym_addrs = [r[0] for r in rows]
208
+
209
+ def _type(self, die, depth=0):
210
+ if die is None or depth > 24:
211
+ return UNREAD
212
+ seen = die.offset
213
+ hit = self._types.get(seen)
214
+ if hit is not None:
215
+ return hit
216
+ die = _strip(die)
217
+ if die is None:
218
+ self._types[seen] = UNREAD
219
+ return UNREAD
220
+ key = die.offset
221
+ cached = self._types.get(key)
222
+ if cached is not None:
223
+ self._types[seen] = cached
224
+ return cached
225
+ tag = die.tag
226
+ if tag == "DW_TAG_base_type":
227
+ return self._store(seen, key, _base(die))
228
+ if tag == "DW_TAG_pointer_type":
229
+ return self._pointer(die, seen, key, depth)
230
+ if tag == "DW_TAG_enumeration_type":
231
+ return self._store(seen, key, self._enum(die))
232
+ if tag in ("DW_TAG_structure_type", "DW_TAG_union_type",
233
+ "DW_TAG_class_type"):
234
+ return self._struct(die, seen, key, tag, depth)
235
+ if tag == "DW_TAG_array_type":
236
+ return self._array(die, seen, key, depth)
237
+ if tag == "DW_TAG_subroutine_type":
238
+ return self._store(seen, key, CType("ptr", 8, "void ()"))
239
+ if tag == "DW_TAG_unspecified_type":
240
+ return self._store(seen, key, VOID)
241
+ return self._store(seen, key, UNREAD)
242
+
243
+ def _store(self, seen, key, typ):
244
+ self._types[key] = typ
245
+ self._types[seen] = typ
246
+ return typ
247
+
248
+ def _pointer(self, die, seen, key, depth):
249
+ size = _size_attr(die) or 8
250
+ typ = CType("ptr", size, "void *")
251
+ self._types[key] = typ
252
+ self._types[seen] = typ
253
+ target_die = _follow(die, "DW_AT_type")
254
+ target = self._type(target_die, depth + 1) if target_die is not None else None
255
+ if target_die is None:
256
+ typ.name = "void *"
257
+ else:
258
+ typ.name = self._render(target_die) + " *"
259
+ typ.is_cstr = bool(
260
+ target is not None and target.kind == "int"
261
+ and target.is_char and target.size == 1)
262
+ return typ
263
+
264
+ def _enum(self, die):
265
+ size = _size_attr(die) or 4
266
+ enc = _int_attr(die, "DW_AT_encoding")
267
+ signed = enc not in (0x07, 0x08)
268
+ members = {}
269
+ bits = size * 8
270
+ for child in die.iter_children():
271
+ if child.tag != "DW_TAG_enumerator":
272
+ continue
273
+ name = _text(child, "DW_AT_name")
274
+ val = child.attributes.get("DW_AT_const_value")
275
+ if name is None or val is None:
276
+ continue
277
+ try:
278
+ n = int(val.value)
279
+ except (TypeError, ValueError):
280
+ continue
281
+ if signed and bits and 0 <= n < (1 << bits) and n >= (1 << (bits - 1)):
282
+ n -= 1 << bits
283
+ members[n] = name
284
+ raw = _text(die, "DW_AT_name")
285
+ label = "enum " + raw if raw else "enum"
286
+ return CType("enum", size, label, signed=signed, enums=members)
287
+
288
+ def _struct(self, die, seen, key, tag, depth):
289
+ kind = "union" if tag == "DW_TAG_union_type" else "struct"
290
+ label = self._render(die)
291
+ size = _size_attr(die) or 0
292
+ typ = CType(kind, size, label, members=[])
293
+ self._types[key] = typ
294
+ self._types[seen] = typ
295
+ members = []
296
+ for child in die.iter_children():
297
+ if child.tag != "DW_TAG_member":
298
+ continue
299
+ mname = _text(child, "DW_AT_name") or "?"
300
+ mtyp = self._type(_follow(child, "DW_AT_type"), depth + 1)
301
+ off = _member_off(child)
302
+ bit = _int_attr(child, "DW_AT_bit_size")
303
+ members.append(Member(
304
+ mname, off, mtyp, bit_size=bit,
305
+ bit_pos=_bit_pos(child, off, bit, mtyp)))
306
+ typ.members = members
307
+ if not typ.size:
308
+ end = 0
309
+ for m in members:
310
+ if m.bit_size or m.typ is None:
311
+ continue
312
+ end = max(end, m.offset + (m.typ.size or 0))
313
+ typ.size = end
314
+ return typ
315
+
316
+ def _array(self, die, seen, key, depth):
317
+ elem = self._type(_follow(die, "DW_AT_type"), depth + 1)
318
+ count = _array_count(die)
319
+ es = elem.size if elem is not None else 0
320
+ size = _size_attr(die)
321
+ if size is None and count is not None and es:
322
+ size = count * es
323
+ label = self._render(die)
324
+ typ = CType("array", size or 0, label, elem=elem, count=count)
325
+ return self._store(seen, key, typ)
326
+
327
+ def _render(self, die, stack=None) -> str:
328
+ """Display name. Typedefs expand. const, volatile and restrict stay."""
329
+ if die is None:
330
+ return "void"
331
+ off = die.offset
332
+ hit = self._names.get(off)
333
+ if hit is not None:
334
+ return hit
335
+ if stack is None:
336
+ stack = set()
337
+ if off in stack:
338
+ return "..."
339
+ stack.add(off)
340
+ try:
341
+ tag = die.tag
342
+ if tag == "DW_TAG_typedef":
343
+ name = self._render(_follow(die, "DW_AT_type"), stack)
344
+ elif tag == "DW_TAG_const_type":
345
+ name = "const " + self._render(_follow(die, "DW_AT_type"), stack)
346
+ elif tag == "DW_TAG_volatile_type":
347
+ name = "volatile " + self._render(_follow(die, "DW_AT_type"), stack)
348
+ elif tag == "DW_TAG_restrict_type":
349
+ name = "restrict " + self._render(_follow(die, "DW_AT_type"), stack)
350
+ elif tag == "DW_TAG_pointer_type":
351
+ name = self._render(_follow(die, "DW_AT_type"), stack) + " *"
352
+ elif tag == "DW_TAG_base_type":
353
+ name = _text(die, "DW_AT_name") or "void"
354
+ elif tag == "DW_TAG_structure_type":
355
+ raw = _text(die, "DW_AT_name")
356
+ name = "struct " + raw if raw else "struct"
357
+ elif tag == "DW_TAG_union_type":
358
+ raw = _text(die, "DW_AT_name")
359
+ name = "union " + raw if raw else "union"
360
+ elif tag == "DW_TAG_class_type":
361
+ raw = _text(die, "DW_AT_name")
362
+ name = "class " + raw if raw else "class"
363
+ elif tag == "DW_TAG_enumeration_type":
364
+ raw = _text(die, "DW_AT_name")
365
+ name = "enum " + raw if raw else "enum"
366
+ elif tag == "DW_TAG_array_type":
367
+ elem = self._render(_follow(die, "DW_AT_type"), stack)
368
+ count = _array_count(die)
369
+ name = f"{elem}[{count}]" if count is not None else f"{elem}[]"
370
+ elif tag == "DW_TAG_subroutine_type":
371
+ name = "void ()"
372
+ elif tag == "DW_TAG_unspecified_type":
373
+ name = _text(die, "DW_AT_name") or "void"
374
+ else:
375
+ name = _text(die, "DW_AT_name") or "?"
376
+ finally:
377
+ stack.discard(off)
378
+ self._names[off] = name
379
+ return name
380
+
381
+
382
+ def _params(image, die, origin, kind):
383
+ kids = [c for c in die.iter_children()
384
+ if c.tag == "DW_TAG_formal_parameter"]
385
+ if not kids and origin is not die:
386
+ kids = [c for c in origin.iter_children()
387
+ if c.tag == "DW_TAG_formal_parameter"]
388
+ out = []
389
+ for i, child in enumerate(kids):
390
+ if _flag(child, "DW_AT_artificial"):
391
+ continue
392
+ src = _named(child)
393
+ name = _text(src, "DW_AT_name") or _text(child, "DW_AT_name") or f"arg{i}"
394
+ typ = image._type(_follow(src, "DW_AT_type") or _follow(child, "DW_AT_type"))
395
+ off = _param_off(child, kind)
396
+ if off is None:
397
+ off = _param_off(src, kind)
398
+ out.append(Param(name, off, typ))
399
+ return out
400
+
401
+
402
+ def _low_pc(die):
403
+ attr = die.attributes.get("DW_AT_low_pc")
404
+ if attr is None:
405
+ return None
406
+ try:
407
+ return int(attr.value)
408
+ except (TypeError, ValueError):
409
+ return None
410
+
411
+
412
+ def _frame_kind(die):
413
+ """``cfa`` when the frame base is ``DW_OP_call_frame_cfa`` (gcc -O0).
414
+ ``rbp`` when it is ``DW_OP_reg6`` (clang -O0). Anything else is not
415
+ a single offset the runtime can add to ``rbp + 16``."""
416
+ if die is None:
417
+ return None
418
+ fb = die.attributes.get("DW_AT_frame_base")
419
+ if fb is None or describe_form_class(fb.form) != "exprloc":
420
+ return None
421
+ raw = list(_as_bytes(fb.value))
422
+ if raw == [_DW_OP_CFA]:
423
+ return "cfa"
424
+ if raw == [_DW_OP_REG6]:
425
+ return "rbp"
426
+ return None
427
+
428
+
429
+ def _param_off(die, kind):
430
+ """CFA-relative slot, or None. ``DW_OP_fbreg`` is already CFA-relative
431
+ when the frame base is the CFA. An ``rbp`` frame base, and
432
+ ``DW_OP_breg6``, sit 16 bytes below the CFA (saved rbp and the
433
+ return address). Extra ops are not a slot."""
434
+ if die is None or kind is None:
435
+ return None
436
+ loc = die.attributes.get("DW_AT_location")
437
+ if loc is None or describe_form_class(loc.form) != "exprloc":
438
+ return None
439
+ raw = _as_bytes(loc.value)
440
+ if not raw:
441
+ return None
442
+ if raw[0] == _DW_OP_FBREG:
443
+ off, n = _sleb(raw, 1)
444
+ if off is None or n != len(raw):
445
+ return None
446
+ if kind == "rbp":
447
+ off -= 16
448
+ return off
449
+ if raw[0] == _DW_OP_BREG6:
450
+ off, n = _sleb(raw, 1)
451
+ if off is None or n != len(raw):
452
+ return None
453
+ return off - 16
454
+ return None
455
+
456
+
457
+ def _bit_pos(die, byte_off, bit_size, typ):
458
+ """LSB of a bitfield from the start of the value.
459
+
460
+ ``DW_AT_data_bit_offset`` is already that position. GCC's
461
+ ``DW_AT_bit_offset`` counts down from the high bit of the container.
462
+ """
463
+ if bit_size is None:
464
+ return None
465
+ data = _int_attr(die, "DW_AT_data_bit_offset")
466
+ if data is not None:
467
+ return data
468
+ bit_off = _int_attr(die, "DW_AT_bit_offset")
469
+ if bit_off is None:
470
+ return None
471
+ container = _size_attr(die) or (typ.size if typ is not None else 0) or 0
472
+ cbits = container * 8
473
+ if cbits <= 0:
474
+ return None
475
+ lsb = cbits - bit_off - bit_size
476
+ if lsb < 0:
477
+ return None
478
+ return byte_off * 8 + lsb
479
+
480
+
481
+ def _member_off(die) -> int:
482
+ attr = die.attributes.get("DW_AT_data_member_location")
483
+ if attr is None:
484
+ return 0
485
+ if isinstance(attr.value, int):
486
+ return attr.value
487
+ raw = _as_bytes(attr.value)
488
+ if raw[:1] == bytes([_DW_OP_PLUS_UCONST]):
489
+ n, _i = _uleb(raw, 1)
490
+ return n or 0
491
+ if len(raw) == 1 and 0x30 <= raw[0] <= 0x4F:
492
+ return raw[0] - 0x30
493
+ return 0
494
+
495
+
496
+ def _base(die):
497
+ enc = _int_attr(die, "DW_AT_encoding") or 0
498
+ size = _size_attr(die) or 0
499
+ name = _text(die, "DW_AT_name") or "int"
500
+ if enc == 0x02:
501
+ return CType("bool", size or 1, name)
502
+ if enc == 0x04:
503
+ return CType("float", size, name)
504
+ signed = enc in (0x05, 0x06)
505
+ # char-sized signed_char / unsigned_char, and a 1-byte type named
506
+ # char. A pointer to that is FLAG_CSTR; a pointer to a pointer is not.
507
+ # Clang sometimes tags plain char as DW_ATE_signed (5) or unsigned (7).
508
+ is_char = size == 1 and (
509
+ enc in (0x06, 0x08)
510
+ or name in ("char", "signed char", "unsigned char"))
511
+ if enc in (0x05, 0x06, 0x07, 0x08, 0x01) or name:
512
+ return CType("int", size, name, signed=signed, is_char=is_char)
513
+ return UNREAD
514
+
515
+
516
+ def _array_count(die):
517
+ for child in die.iter_children():
518
+ if child.tag != "DW_TAG_subrange_type":
519
+ continue
520
+ count = _int_attr(child, "DW_AT_count")
521
+ if count is not None:
522
+ return count
523
+ upper = _int_attr(child, "DW_AT_upper_bound")
524
+ if upper is None:
525
+ return None
526
+ lower = _int_attr(child, "DW_AT_lower_bound") or 0
527
+ return upper - lower + 1
528
+ return None
529
+
530
+
531
+ def _files(dwarf, cu, comp):
532
+ """Line-table order, index 0 first. DWARF 4 directory 0 is ``comp_dir``
533
+ and the file numbers are 1-based. DWARF 5 directories include
534
+ ``comp_dir`` at index 0 and the file numbers are 0-based."""
535
+ try:
536
+ lp = dwarf.line_program_for_CU(cu)
537
+ except Exception:
538
+ return []
539
+ if lp is None:
540
+ return []
541
+ version = cu.header.version
542
+ dirs = []
543
+ for entry in getattr(lp.header, "include_directory", []) or []:
544
+ dirs.append(_dec(entry))
545
+ out = []
546
+ for entry in lp.header.file_entry:
547
+ name = _dec(getattr(entry, "name", entry))
548
+ di = getattr(entry, "dir_index", 0) or 0
549
+ if version >= 5:
550
+ directory = dirs[di] if 0 <= di < len(dirs) else ""
551
+ elif di == 0:
552
+ directory = comp
553
+ elif 0 <= di - 1 < len(dirs):
554
+ directory = dirs[di - 1]
555
+ else:
556
+ directory = ""
557
+ out.append(_join_file(comp, directory, name))
558
+ return out
559
+
560
+
561
+ def _join_file(comp, directory, name):
562
+ if not name:
563
+ return "?"
564
+ if os.path.isabs(name):
565
+ return os.path.normpath(name)
566
+ if directory:
567
+ if os.path.isabs(directory) or not comp or directory == comp:
568
+ base = directory
569
+ else:
570
+ base = os.path.join(comp, directory)
571
+ else:
572
+ base = comp
573
+ if base:
574
+ return os.path.normpath(os.path.join(base, name))
575
+ return os.path.normpath(name)
576
+
577
+
578
+ def _decl_file(die, origin, files, comp, cu_name, version):
579
+ for src in (die, origin):
580
+ if src is None:
581
+ continue
582
+ idx = _int_attr(src, "DW_AT_decl_file")
583
+ if idx is None:
584
+ continue
585
+ slot = idx if version >= 5 else idx - 1
586
+ if 0 <= slot < len(files):
587
+ return files[slot]
588
+ if comp and cu_name and not os.path.isabs(cu_name):
589
+ return os.path.normpath(os.path.join(comp, cu_name))
590
+ return cu_name or "?"
591
+
592
+
593
+ def _decl_line(die) -> int:
594
+ if die is None:
595
+ return 0
596
+ n = _int_attr(die, "DW_AT_decl_line")
597
+ return n or 0
598
+
599
+
600
+ def _strip(die):
601
+ seen = set()
602
+ while die is not None and id(die) not in seen:
603
+ seen.add(id(die))
604
+ if die.tag not in _STRIP:
605
+ return die
606
+ die = _follow(die, "DW_AT_type")
607
+ return None
608
+
609
+
610
+ def _named(die):
611
+ seen = set()
612
+ cur = die
613
+ while cur is not None and id(cur) not in seen:
614
+ seen.add(id(cur))
615
+ if "DW_AT_name" in cur.attributes:
616
+ return cur
617
+ nxt = _follow(cur, "DW_AT_abstract_origin") or _follow(
618
+ cur, "DW_AT_specification")
619
+ if nxt is None:
620
+ return cur
621
+ cur = nxt
622
+ return die
623
+
624
+
625
+ def _follow(die, attr):
626
+ if die is None or attr not in die.attributes:
627
+ return None
628
+ try:
629
+ return die.get_DIE_from_attribute(attr)
630
+ except Exception:
631
+ return None
632
+
633
+
634
+ def _text(die, attr):
635
+ if die is None:
636
+ return None
637
+ a = die.attributes.get(attr)
638
+ if a is None:
639
+ return None
640
+ return _dec(a.value)
641
+
642
+
643
+ def _dec(value):
644
+ if isinstance(value, bytes):
645
+ return value.decode("utf-8", "replace")
646
+ if isinstance(value, str):
647
+ return value
648
+ name = getattr(value, "name", None)
649
+ if name is not None and name is not value:
650
+ return _dec(name)
651
+ return str(value) if value is not None else None
652
+
653
+
654
+ def _int_attr(die, attr):
655
+ a = die.attributes.get(attr)
656
+ if a is None:
657
+ return None
658
+ try:
659
+ return int(a.value)
660
+ except (TypeError, ValueError):
661
+ return None
662
+
663
+
664
+ def _size_attr(die):
665
+ return _int_attr(die, "DW_AT_byte_size")
666
+
667
+
668
+ def _flag(die, attr) -> bool:
669
+ a = die.attributes.get(attr)
670
+ if a is None:
671
+ return False
672
+ return bool(a.value)
673
+
674
+
675
+ def _as_bytes(value) -> bytes:
676
+ if isinstance(value, (bytes, bytearray)):
677
+ return bytes(value)
678
+ if isinstance(value, list):
679
+ return bytes(x & 0xFF for x in value)
680
+ return b""
681
+
682
+
683
+ def _uleb(buf, i):
684
+ n = shift = 0
685
+ while i < len(buf):
686
+ b = buf[i]
687
+ i += 1
688
+ n |= (b & 0x7F) << shift
689
+ if not b & 0x80:
690
+ return n, i
691
+ shift += 7
692
+ return None, i
693
+
694
+
695
+ def _sleb(buf, i):
696
+ n = shift = 0
697
+ while i < len(buf):
698
+ b = buf[i]
699
+ i += 1
700
+ n |= (b & 0x7F) << shift
701
+ shift += 7
702
+ if not b & 0x80:
703
+ if b & 0x40:
704
+ n -= 1 << shift
705
+ return n, i
706
+ return None, i