scientific-method-engine 18.3.0__tar.gz → 18.4.0__tar.gz

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 (87) hide show
  1. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/cli.py +3 -0
  4. scientific_method_engine-18.4.0/src/scientific_method_engine/x86/dispatch.py +168 -0
  5. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/inventory.py +36 -7
  6. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/reach.py +60 -27
  7. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/reports.py +21 -4
  8. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/trace.py +26 -6
  9. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_inventory_check.py +43 -0
  10. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_reach.py +174 -0
  11. scientific_method_engine-18.3.0/src/scientific_method_engine/x86/dispatch.py +0 -51
  12. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/.gitignore +0 -0
  13. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/LICENSE +0 -0
  14. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/README.md +0 -0
  15. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/__init__.py +0 -0
  16. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/__main__.py +0 -0
  17. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  18. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  19. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  20. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  21. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  22. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  23. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  24. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  25. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  26. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  27. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  28. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  29. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  30. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  31. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  32. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  33. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  34. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  35. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  36. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  37. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  38. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  39. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  40. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  41. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  42. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  43. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  44. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  45. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  46. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  47. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  48. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  49. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  50. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  51. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  52. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  53. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  54. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  55. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/image.py +0 -0
  56. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/loops.py +0 -0
  57. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/machine.py +0 -0
  58. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  59. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  60. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  61. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pe.py +0 -0
  62. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/relational.py +0 -0
  63. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  64. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/values.py +0 -0
  65. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/oracle.py +0 -0
  66. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_config_encoding.py +0 -0
  67. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_continuation_budget.py +0 -0
  68. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_dispatch.py +0 -0
  69. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_effect_order.py +0 -0
  70. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_enter_frames.py +0 -0
  71. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_entry_frame.py +0 -0
  72. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_indirect_far_transfers.py +0 -0
  73. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_interrupt_models.py +0 -0
  74. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_join_terms.py +0 -0
  75. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_loops.py +0 -0
  76. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_memory_scopes.py +0 -0
  77. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_nested_frame_request.py +0 -0
  78. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_oracle.py +0 -0
  79. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_pe.py +0 -0
  80. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_relational_controls.py +0 -0
  81. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_return_checks.py +0 -0
  82. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_successor_rule.py +0 -0
  83. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_table_continuations.py +0 -0
  84. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_term_limit.py +0 -0
  85. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_upstream_gaps.py +0 -0
  86. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_volatile_memory.py +0 -0
  87. {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 18.3.0
3
+ Version: 18.4.0
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "18.3.0"
8
+ version = "18.4.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
27
27
  "a call to a noReturn routine and a noReturn interrupt do not continue at the next instruction,\n"
28
28
  "and a noReturn routine with a return, or a jump into a returning leaf, on its own read paths\n"
29
29
  "is reported contradicted;\n"
30
+ "indirectCalls declares the targets of a computed call as a table read from the build or a list,\n"
31
+ "and the walk calls each of them; one not declared exhaustive stays unresolved;\n"
30
32
  "controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
31
33
  "and a failed control fails the report saying whether it was reached.\n"
32
34
  "inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
@@ -38,6 +40,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
38
40
  "noReturn takes reach's declarations: the walk stops at a call to a declared routine and at a declared\n"
39
41
  "interrupt, a declared routine with a return on its own read paths is reported contradicted, and\n"
40
42
  "rowsPastNoReturn lists each row whose body continues past such a call or interrupt.\n"
43
+ "indirectCalls takes reach's declarations: each declared target of a reached computed call is a call target.\n"
41
44
  "uses matches accesses whose footprint intersects query offset..offset+width; its rawCandidates give each unreached\n"
42
45
  "operand's encoded displacement, width, access, segment register and intersection, and never count as uses.\n"
43
46
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
@@ -0,0 +1,168 @@
1
+ """Explicit, source-derived indirect jump tables and call targets for CFG discovery, and explicitly conditional path continuations."""
2
+ from capstone.x86 import X86_OP_IMM, X86_OP_MEM
3
+ from .image import integer
4
+
5
+ CALL_NOT_EXHAUSTIVE = "indirect call targets are not declared exhaustive"
6
+
7
+
8
+ def _word(image, at):
9
+ return int.from_bytes(image.data[at:at + 2], "little")
10
+
11
+
12
+ def _table_operands(image, table, width, label, field_label):
13
+ """The file offset of each row's target field in a declared ``table`` of ``width``-byte targets."""
14
+ start = integer(table.get("start"), 0, len(image.data) - 1, f"{label} start")
15
+ count = integer(table.get("count"), 1, 256, f"{label} count")
16
+ stride = integer(table.get("stride"), width, 65536, f"{label} stride")
17
+ field = integer(table.get("fieldOffset", 0), 0, stride - width, field_label)
18
+ if start + (count - 1) * stride + field + width > len(image.data):
19
+ raise ValueError(f"{label[0].upper()}{label[1:]} leaves source bounds")
20
+ return [start + index * stride + field for index in range(count)]
21
+
22
+
23
+ def read_indirect_jumps(image):
24
+ declarations = image.config.get("indirectJumps", [])
25
+ if not isinstance(declarations, list) or len(declarations) > 256:
26
+ raise ValueError("indirectJumps must contain at most 256 declarations")
27
+ if declarations and image.flat:
28
+ raise ValueError("indirectJumps currently requires segmented16")
29
+ result = {}
30
+ for claim in declarations:
31
+ if not isinstance(claim, dict):
32
+ raise ValueError("Each indirect jump needs an object")
33
+ site = integer(claim.get("site"), 0, len(image.data) - 1, "indirect jump site")
34
+ if site in result:
35
+ raise ValueError("Duplicate indirect jump site")
36
+ if not isinstance(claim.get("evidence"), str) or not claim["evidence"].strip():
37
+ raise ValueError("An indirect jump needs consumer/mapping evidence")
38
+ if type(claim.get("exhaustive")) is not bool:
39
+ raise ValueError("An indirect jump needs explicit exhaustive true or false")
40
+ ins = image.decode(site)
41
+ if (ins is None or ins.mnemonic != "jmp" or len(ins.operands) != 1
42
+ or ins.operands[0].type == X86_OP_IMM or ins.operands[0].size != 2
43
+ or 0x66 in ins.prefix or 0x67 in ins.prefix):
44
+ raise ValueError("indirectJumps site must decode as an unprefixed computed near word jump")
45
+ table = claim.get("table")
46
+ if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
47
+ raise ValueError("Indirect table needs layout/count evidence")
48
+ if type(table.get("width", 2)) is not int or table.get("width", 2) != 2:
49
+ raise ValueError("Indirect table targets must be word width 2")
50
+ rows = []
51
+ operands = _table_operands(image, table, 2, "indirect table", "indirect target field offset")
52
+ for index, operand in enumerate(operands):
53
+ raw = _word(image, operand)
54
+ target = image.near_target(site, raw)
55
+ if target is None:
56
+ raise ValueError("Indirect table target leaves declared code mappings")
57
+ rows.append({"index": index, "operandSite": operand, "rawOffset": raw, "target": target})
58
+ result[site] = {"site": site, "evidence": claim["evidence"], "table": table,
59
+ "exhaustive": claim["exhaustive"], "rows": rows,
60
+ "interpretation": "source words under supplied consumer, mapping and exhaustiveness evidence; "
61
+ "not executed dispatch or an overlap-boundary proof"}
62
+ return result
63
+
64
+
65
+ def indirect_call_declarations(value, image):
66
+ """The declared targets of computed calls, by call site, as ``reach`` and ``inventory-check`` take them.
67
+
68
+ Each declaration names a ``site`` that decodes as an unprefixed segmented16 computed call (a near
69
+ call through a word register or memory operand, or a far call through memory), its ``evidence``,
70
+ an explicit boolean ``exhaustive``, and exactly one of ``table`` and ``targets``. A table's rows are
71
+ read from the source bytes as ``indirectJumps`` reads them: words placed through the call site's
72
+ region mapping for a near call, and for a far call ``offset, segment`` word pairs whose segment
73
+ word has a declared relocation, admitted as ``Image.far_pointer_target`` admits the pointer a
74
+ traced far call reads; a far row whose pointer names an FBOV trampoline carries its
75
+ ``trampoline``. ``targets`` gives file offsets in declared code, which rest on the evidence
76
+ alone; a near call's targets must be bytes some IP in the call site's segment places. Each
77
+ declaration is returned with the call's ``instruction`` text, a table's ``rows``, and its
78
+ distinct ``targets`` in row order.
79
+ """
80
+ if not isinstance(value, list) or len(value) > 256:
81
+ raise ValueError("indirectCalls must be a list of at most 256 declarations")
82
+ if value and image.flat:
83
+ raise ValueError("indirectCalls currently requires segmented16")
84
+ result = {}
85
+ for claim in value:
86
+ keys = set(claim) if isinstance(claim, dict) else None
87
+ if keys not in ({"site", "evidence", "exhaustive", "table"}, {"site", "evidence", "exhaustive", "targets"}):
88
+ raise ValueError("Each indirect call needs site, evidence, exhaustive and exactly one of table and targets")
89
+ site = integer(claim["site"], 0, len(image.data) - 1, "indirect call site")
90
+ if site in result:
91
+ raise ValueError("Duplicate indirect call site")
92
+ if not isinstance(claim["evidence"], str) or not claim["evidence"].strip():
93
+ raise ValueError("An indirect call needs evidence that connects the call's operand to its targets")
94
+ if type(claim["exhaustive"]) is not bool:
95
+ raise ValueError("An indirect call needs explicit exhaustive true or false")
96
+ ins = image.decode(site)
97
+ far = ins is not None and ins.mnemonic == "lcall"
98
+ if (ins is None or ins.mnemonic not in ("call", "lcall") or len(ins.operands) != 1
99
+ or ins.operands[0].type == X86_OP_IMM or (far and ins.operands[0].type != X86_OP_MEM)
100
+ or (not far and ins.operands[0].size != 2) or 0x66 in ins.prefix or 0x67 in ins.prefix):
101
+ raise ValueError(f"indirect call site {site} must decode as an unprefixed computed near word call "
102
+ "or a far call through memory")
103
+ declaration = {"site": site, "instruction": (ins.mnemonic + " " + ins.op_str).strip(),
104
+ "evidence": claim["evidence"], "exhaustive": claim["exhaustive"]}
105
+ if "table" in claim:
106
+ table, width = claim["table"], 4 if far else 2
107
+ if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
108
+ raise ValueError("An indirect call table needs layout/count evidence")
109
+ if type(table.get("width", width)) is not int or table.get("width", width) != width:
110
+ raise ValueError(f"An indirect {'far' if far else 'near'} call table holds {width}-byte targets, "
111
+ f"so its width must be {width}")
112
+ rows = []
113
+ operands = _table_operands(image, table, width, "indirect call table", "indirect call target field offset")
114
+ for index, operand in enumerate(operands):
115
+ row = {"index": index, "operandSite": operand, "rawOffset": _word(image, operand)}
116
+ if far:
117
+ # The segment word is relocated at load time, and the pointer is admitted as a traced far
118
+ # call through memory admits the pointer it reads (Image.far_pointer_target).
119
+ fixup = image.fixups.get(operand + 2)
120
+ if fixup is None:
121
+ raise ValueError(f"Indirect call table row {index} has no declared relocation for its segment "
122
+ f"word at {operand + 2}")
123
+ target, admission = image.far_pointer_target(fixup["segment"], row["rawOffset"])
124
+ if target is None:
125
+ raise ValueError(f"Indirect call table row {index} target is not admitted: {admission['reason']}")
126
+ row |= {"rawSegment": _word(image, operand + 2), "resolvedSegment": fixup["segment"]}
127
+ # A pointer at an FBOV trampoline continues at its overlay entry, which the row names.
128
+ if "trampoline" in admission:
129
+ row["trampoline"] = admission["trampoline"]
130
+ else:
131
+ target = image.near_target(site, row["rawOffset"])
132
+ if target is None or image.region(target) is None:
133
+ raise ValueError(f"Indirect call table row {index} target leaves declared code mappings")
134
+ rows.append(row | {"target": target})
135
+ declaration |= {"table": table, "rows": rows}
136
+ targets = [row["target"] for row in rows]
137
+ else:
138
+ targets = claim["targets"]
139
+ if (not isinstance(targets, list) or not 1 <= len(targets) <= 256
140
+ or len(set(map(repr, targets))) != len(targets)):
141
+ raise ValueError("indirect call targets must be a list of 1..256 distinct file offsets")
142
+ for at in targets:
143
+ integer(at, 0, len(image.data) - 1, "indirect call target")
144
+ region = image.region(at)
145
+ if region is None:
146
+ raise ValueError(f"indirect call target {at} is outside declared code")
147
+ if not far:
148
+ # A near call keeps CS, so its target needs an IP that the call site's mapping places there.
149
+ linear = region["segment"] * 16 + region["ip"] + at - region["start"]
150
+ ip = linear - image.region(site)["segment"] * 16
151
+ if not 0 <= ip <= image.mask or image.near_target(site, ip) != at:
152
+ raise ValueError(f"indirect call target {at} is not placed by any IP in the near call "
153
+ f"site {site}'s segment")
154
+ result[site] = declaration | {"targets": list(dict.fromkeys(targets))}
155
+ return result
156
+
157
+
158
+ def declared_call_ends(declaration, no_return_calls):
159
+ """Whether a declared indirect call ends its branch: it is exhaustive and every target is in ``no_return_calls``."""
160
+ return declaration["exhaustive"] and all(target in no_return_calls for target in declaration["targets"])
161
+
162
+
163
+ def call_ends(site, target, indirect_calls, no_return_calls):
164
+ """Whether the call at ``site`` to ``target`` ends its branch, under ``declared_call_ends`` for a declared site."""
165
+ declaration = indirect_calls.get(site)
166
+ if declaration is not None:
167
+ return declared_call_ends(declaration, no_return_calls)
168
+ return target in no_return_calls
@@ -4,6 +4,7 @@ from bisect import bisect_right
4
4
  from pathlib import Path
5
5
  from .image import integer
6
6
  from .trace import LIMIT_REASON, CONTESTED_REASON, walk, holding_instruction
7
+ from .dispatch import indirect_call_declarations, call_ends
7
8
 
8
9
  MAX_INVENTORY = 16 * 1024 * 1024
9
10
  MAX_ROWS = 200000
@@ -214,7 +215,8 @@ def inventory_check(image, config):
214
215
  walk established is listed in ``rowStarts``. ``noReturn`` declarations, in ``reach``'s shape, end
215
216
  the walk at a call to a declared routine and at a declared interrupt site, are checked for a
216
217
  return on the routine's own paths, and list in ``rowsPastNoReturn`` each row whose body
217
- continues past such a call or interrupt.
218
+ continues past such a call or interrupt. ``indirectCalls`` declarations, in ``reach``'s shape,
219
+ make each declared target of a reached computed call a call target, and the walk reads on in them.
218
220
  """
219
221
  from .reports import call_controls, direct_calls, entries, search_coverage
220
222
  from .reach import no_return_declarations, no_return_rows, successor_graph, fewest_calls
@@ -223,8 +225,19 @@ def inventory_check(image, config):
223
225
  rows = read_inventory(config["inventory"], image)
224
226
  limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
225
227
  no_return_routines, no_return_interrupts = no_return_declarations(config.get("noReturn", []), image)
226
- declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts)}
228
+ indirect_calls = indirect_call_declarations(config.get("indirectCalls", []), image)
229
+ for at in config.get("controls", []) if isinstance(config.get("controls"), list) else []:
230
+ # call_controls refuses a control that is no integer.
231
+ if type(at) is int and at in indirect_calls:
232
+ raise ValueError(f"Positive control {at} is a declared indirect call, whose targets rest on its "
233
+ "declaration; a control must resolve from its own encoding")
234
+ declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts),
235
+ "indirect_calls": indirect_calls}
227
236
  calls = direct_calls(image, config, **declared)
237
+
238
+ def ends_branch(row):
239
+ # A declared indirect call ends its branch only when every target it may call is declared noReturn.
240
+ return call_ends(row["site"], row["target"], indirect_calls, no_return_routines)
228
241
  seen, contested = calls["seen"], calls["contested"]
229
242
 
230
243
  starts = {(row["space"], row["at"]) for row in rows}
@@ -314,14 +327,22 @@ def inventory_check(image, config):
314
327
  config.get("instructionLimit", 10000))
315
328
  entry_calls = {}
316
329
  for row in calls["rows"]:
317
- if row["target"] in no_return_routines and row["site"] in seen:
330
+ if row["target"] in no_return_routines and row["site"] in seen and ends_branch(row):
318
331
  entry_calls.setdefault(row["target"], []).append(row["site"])
319
332
  no_return = no_return_rows(no_return_routines, no_return_interrupts, returns,
320
333
  {at: sorted(sites) for at, sites in entry_calls.items()}, seen, seen, check_read)
321
334
 
322
335
  # A row whose body holds a declared call or interrupt and the byte after it still covers what follows.
323
- ends = [(row["site"], image.decode(row["site"]).size, "call", row["target"], row["classification"])
324
- for row in calls["rows"] if row["target"] in no_return_routines]
336
+ # A declared computed call has one row for each target, and is listed once with all of them.
337
+ ends, declared_ends = [], set()
338
+ for row in calls["rows"]:
339
+ if row["target"] not in no_return_routines or not ends_branch(row) or row["site"] in declared_ends:
340
+ continue
341
+ routine = row["target"]
342
+ if row["site"] in indirect_calls:
343
+ declared_ends.add(row["site"])
344
+ routine = list(indirect_calls[row["site"]]["targets"])
345
+ ends.append((row["site"], image.decode(row["site"]).size, "call", routine, row["classification"]))
325
346
  ends += [(at, row["following"] - at, "interrupt", None,
326
347
  "entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site")
327
348
  for at, row in no_return_interrupts.items()]
@@ -338,7 +359,9 @@ def inventory_check(image, config):
338
359
  continue
339
360
  entry = {**_row_fields(rows[i]), "kind": kind, "site": site, "siteAddress": here[2],
340
361
  "siteClassification": classification}
341
- if routine is not None:
362
+ if isinstance(routine, list):
363
+ entry["routines"] = routine
364
+ elif routine is not None:
342
365
  entry["routine"] = routine
343
366
  past.append(entry | {"following": site + size, "followingAddress": after[2],
344
367
  "followingRead": site + size in seen, "bytesAfter": piece[1] - after[1]})
@@ -420,10 +443,15 @@ def inventory_check(image, config):
420
443
  + "; interrupt handlers are not read")
421
444
  if no_return:
422
445
  assumptions.append("each noReturn routine and interrupt never returns, for the reason it gives")
446
+ if indirect_calls:
447
+ assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
448
+ "it gives, and only those when it is declared exhaustive")
449
+ indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
423
450
  return {"inventory": {"path": config["inventory"], "rows": len(rows)},
424
451
  "targets": missing[:limit], "unresolved": unresolved[:limit],
425
452
  "rowsOutsideDeclaredCode": outside_code[:limit],
426
453
  "rowStarts": row_starts[:limit], "noReturn": no_return, "rowsPastNoReturn": past[:limit],
454
+ "indirectCalls": indirect_rows,
427
455
  "counts": {"callTargets": len(by_target), **tally, "unresolvedCalls": len(unresolved),
428
456
  "inventoryRows": len(rows), "rowsOutsideDeclaredCode": len(outside_code),
429
457
  "rowStarts": start_counts, "rowsPastNoReturn": len(past_rows),
@@ -434,7 +462,8 @@ def inventory_check(image, config):
434
462
  "summary": summary, "controls": controls,
435
463
  "searched": [r for r in image.regions if r["name"] in calls["scans"]], "coverage": coverage,
436
464
  "partialSearch": partial, "gaps": calls["gaps"],
437
- "exclusions": ["computed call targets (listed in unresolved when the walk reaches them)", "unrelocated far calls",
465
+ "exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
466
+ "walk reaches them)", "unrelocated far calls",
438
467
  "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"],
439
468
  "interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
440
469
  "notation and compared with its rows. A target only raw byte candidates or contested "
@@ -4,6 +4,7 @@ from .image import integer
4
4
  from .trace import (walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS,
5
5
  LIMIT_REASON, OVERLAP_REASON, UNDECODED_REASON)
6
6
  from .pcode_backend import interrupt_vector
7
+ from .dispatch import indirect_call_declarations, call_ends
7
8
 
8
9
  # The virtual root of the dominator computation; no file offset is negative.
9
10
  ROOT = -1
@@ -102,15 +103,16 @@ def returns_from(graph, seen, returning_leaves, routine):
102
103
  def successor_kinds(at, ins, step):
103
104
  """Each successor of ``step`` with how the CFG reaches it: call, return, table, interrupt, jump or fall."""
104
105
  m, following = base_mnemonic(ins), at + ins.size
106
+ # A call lists its resolved or declared targets first, then its return site; a call to the next
107
+ # instruction lists that site twice.
105
108
  targets = {e["target"] for e in step.edges if e["target"] is not None}
106
- rows, called = [], False
109
+ calls = sum(e["target"] is not None for e in step.edges) if m in CALLS else 0
110
+ rows = []
107
111
  for successor in step.successors:
108
- if step.supplied:
112
+ if m in CALLS:
113
+ kind = "call" if len(rows) < calls else "return"
114
+ elif step.supplied:
109
115
  kind = "table"
110
- elif m in CALLS:
111
- # A call names its target first; a call to the next instruction lists that site twice.
112
- kind = "call" if successor in targets and not called else "return"
113
- called = called or kind == "call"
114
116
  elif m in INTERRUPTS:
115
117
  kind = "interrupt"
116
118
  elif successor == following and m not in ("jmp", "ljmp") and (successor not in targets or len(rows) > 0):
@@ -202,11 +204,12 @@ def reach(image, config):
202
204
 
203
205
  The walk decodes from ``starts`` (established region entries) and follows every resolved call
204
206
  into its callee and on at its return site, every resolved jump and branch, the rows of a
205
- declared indirect jump table, and every interrupt to the next instruction. A ``leaves`` routine
206
- is reached but never decoded. A call to a ``noReturn`` routine and a ``noReturn`` interrupt site
207
- do not continue at the next instruction. Each reached target gets one chain with the fewest
208
- calls, the assumptions its route rests on, and the routines on every route to it within the
209
- read graph.
207
+ declared indirect jump table, the declared targets of an ``indirectCalls`` site, and every
208
+ interrupt to the next instruction. A ``leaves`` routine is reached but never decoded. A call to a
209
+ ``noReturn`` routine and a ``noReturn`` interrupt site do not continue at the next instruction,
210
+ nor does a declared indirect call that is exhaustive and whose targets are all ``noReturn``.
211
+ Each reached target gets one chain with the fewest calls, the assumptions its route rests on,
212
+ and the routines on every route to it within the read graph.
210
213
  """
211
214
  from .reports import entries
212
215
  starts = _sites(config.get("starts"), "starts", image)
@@ -218,6 +221,12 @@ def reach(image, config):
218
221
  leaves = _leaves(config.get("leaves", []), image, set(starts))
219
222
  controls = _sites(config.get("controls", []), "controls", image, least=0)
220
223
  instruction_controls = _sites(config.get("instructionControls", []), "instructionControls", image, least=0)
224
+ indirect_calls = indirect_call_declarations(config.get("indirectCalls", []), image)
225
+ # A control shows that the walk resolved a call from its own encoding, which a declaration does not.
226
+ for at in controls:
227
+ if at in indirect_calls:
228
+ raise ValueError(f"control {at} is a declared indirect call, whose targets rest on its declaration; give "
229
+ "the site as an instructionControls entry, or a call inside a declared target as a control")
221
230
  # The walk decodes a site as image.decode does, so a control whose bytes are no call can never pass.
222
231
  for at in controls:
223
232
  ins = image.decode(at)
@@ -233,11 +242,13 @@ def reach(image, config):
233
242
  limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
234
243
  instruction_limit = config.get("instructionLimit", 10000)
235
244
  no_return_routines, no_return_interrupts = no_return_declarations(config.get("noReturn", []), image)
236
- declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts)}
245
+ declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts),
246
+ "indirect_calls": indirect_calls}
237
247
  seen, walk_gaps, _, _, contested = walk(image, starts, instruction_limit, follow_interrupts=True,
238
248
  stops=frozenset(leaves), **declared)
239
249
 
240
- graph, unresolved, interrupts, resolved_calls = {}, [], [], {}
250
+ # Each reached call site with its resolved or declared targets.
251
+ graph, unresolved, interrupts, call_targets = {}, [], [], {}
241
252
  for at, ins in sorted(seen.items()):
242
253
  step = cfg_step(image, at, ins, follow_interrupts=True, **declared)
243
254
  graph[at] = [(s, kind) for s, kind in successor_kinds(at, ins, step) if s in seen or s in leaves]
@@ -251,7 +262,7 @@ def reach(image, config):
251
262
  unresolved.append({"site": at, "instruction": text, "kind": kind,
252
263
  "reason": edge["provenance"].get("reason", "target outside declared regions")})
253
264
  elif m in CALLS:
254
- resolved_calls[at] = edge["target"]
265
+ call_targets.setdefault(at, []).append(edge["target"])
255
266
  if m in INTERRUPTS and at not in no_return_interrupts:
256
267
  vector, conditional = interrupt_vector(image.flat, ins, at)
257
268
  interrupts.append({"site": at, "instruction": text, "vector": vector, "conditional": conditional})
@@ -278,15 +289,17 @@ def reach(image, config):
278
289
  for child in successors[node]:
279
290
  predecessors[child].append(node)
280
291
  idom = _dominators(order, predecessors)
281
- routine_starts = set(starts) | {target for at, target in resolved_calls.items() if target in distance}
292
+ routine_starts = set(starts) | {target for found in call_targets.values() for target in found if target in distance}
282
293
 
283
294
  def chain(target):
284
- hops, assumed_returns, tables, continued = [], [], [], []
295
+ hops, assumed_returns, tables, declared_calls, continued = [], [], [], [], []
285
296
  at = target
286
297
  while parent[at] is not None:
287
298
  previous, kind = parent[at]
288
299
  if kind == "call":
289
300
  hops.append({"callSite": previous, "routine": at})
301
+ if previous in indirect_calls:
302
+ declared_calls.append({"site": previous, "target": at})
290
303
  elif kind == "return":
291
304
  assumed_returns.append(previous)
292
305
  elif kind == "table":
@@ -297,7 +310,7 @@ def reach(image, config):
297
310
  hops.append({"routine": at})
298
311
  return {"chain": hops[::-1], "calls": distance[target],
299
312
  "route": {"assumedReturns": assumed_returns[::-1], "declaredTableJumps": tables[::-1],
300
- "interruptsContinued": continued[::-1]}}
313
+ "declaredCalls": declared_calls[::-1], "interruptsContinued": continued[::-1]}}
301
314
 
302
315
  # The walk decodes both instructions of an unresolved overlap and keeps neither, so their starts are not in seen.
303
316
  overlapping = {g["site"] for g in walk_gaps if g["reason"] == OVERLAP_REASON}
@@ -337,13 +350,16 @@ def reach(image, config):
337
350
  # Kept apart from the gap rows, which the result limit can cut.
338
351
  stopped = any(g["reason"] == LIMIT_REASON for g in walk_gaps)
339
352
  # A control at a site a noReturn declaration kept the walk from names that declaration, which may be the cause.
340
- cut_by = {at + seen[at].size: f"the call at {at} to noReturn routine {target}"
341
- for at, target in sorted(resolved_calls.items()) if target in no_return_routines}
353
+ def ends(at, found):
354
+ return call_ends(at, found[0], indirect_calls, no_return_routines)
355
+ cut_by = {at + seen[at].size: f"the call at {at} to noReturn routine{'s' if len(found) > 1 else ''} "
356
+ + ", ".join(map(str, found))
357
+ for at, found in sorted(call_targets.items()) if ends(at, found)}
342
358
  cut_by |= {row["following"]: f"the noReturn interrupt at {at}"
343
359
  for at, row in no_return_interrupts.items() if at in seen}
344
360
  # Not reached and reached-but-unresolved need different fixes, so each failure says which it is.
345
361
  failures = []
346
- for label, sites, passed in (("control", controls, resolved_calls), ("instruction control", instruction_controls, seen)):
362
+ for label, sites, passed in (("control", controls, call_targets), ("instruction control", instruction_controls, seen)):
347
363
  for at in sites:
348
364
  if at in passed:
349
365
  continue
@@ -363,16 +379,27 @@ def reach(image, config):
363
379
  + (" (the walk stopped at its instruction limit)" if stopped else ""))
364
380
  if failures:
365
381
  raise ValueError("Positive controls failed: " + "; ".join(failures))
366
- call_sites = {}
367
- for site, target in sorted(resolved_calls.items()):
368
- call_sites.setdefault(target, []).append(site)
382
+ # Every call to each routine, and the calls to a noReturn routine that the declaration ended.
383
+ call_sites, ended_sites = {}, {}
384
+ for site, found in sorted(call_targets.items()):
385
+ ended = ends(site, found)
386
+ for target in found:
387
+ call_sites.setdefault(target, []).append(site)
388
+ if ended:
389
+ ended_sites.setdefault(target, []).append(site)
369
390
  leaf_rows = [{"routine": at, "reason": reason, "reached": at in distance, "callSites": call_sites.get(at, [])}
370
391
  for at, reason in leaves.items()]
371
392
  # Each call the declaration kept from its return site, so a reviewer can check what follows it.
372
393
  returning_leaves = set(leaves) - set(no_return_routines)
373
394
  returns = {at: returns_from(graph, seen, returning_leaves, at) for at in no_return_routines}
374
- no_return = no_return_rows(no_return_routines, no_return_interrupts, returns, call_sites, seen, distance, seen)
395
+ no_return = no_return_rows(no_return_routines, no_return_interrupts, returns, ended_sites, seen, distance, seen)
375
396
  contradicted = any(row.get("contradicted") for row in no_return)
397
+ # A declared target the walk entered but established no instruction at shows in gaps or contested too,
398
+ # unless the walk stopped at its instruction limit before reading it.
399
+ indirect_rows = [declaration | {"reached": site in seen, "routine": routine.get(site),
400
+ "unreadTargets": [t for t in declaration["targets"]
401
+ if site in seen and t not in seen and t not in leaves]}
402
+ for site, declaration in indirect_calls.items()]
376
403
  counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
377
404
  "interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
378
405
  assumptions = ["each reached call returns to its next instruction"
@@ -382,21 +409,24 @@ def reach(image, config):
382
409
  + "; interrupt handlers are not read",
383
410
  "each leaf calls nothing, for the reason it gives",
384
411
  "each declared indirect jump table holds the routes its declaration gives"]
412
+ if indirect_calls:
413
+ assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
414
+ "it gives, and only those when it is declared exhaustive")
385
415
  if no_return:
386
416
  assumptions.append("each noReturn routine and interrupt never returns, for the reason it gives")
387
- return {"starts": starts, "targets": rows, "leaves": leaf_rows, "noReturn": no_return,
417
+ return {"starts": starts, "targets": rows, "leaves": leaf_rows, "noReturn": no_return, "indirectCalls": indirect_rows,
388
418
  "reachedRoutines": sorted(routine_starts), "counts": counts,
389
419
  "unresolved": unresolved[:limit], "interrupts": interrupts[:limit], "gaps": gaps[:limit],
390
420
  "contested": sorted(contested)[:limit],
391
421
  "truncated": any(len(x) > limit for x in (unresolved, interrupts, gaps, contested)),
392
422
  "instructionLimitReached": stopped,
393
- "controls": [{"site": at, "target": resolved_calls[at]} for at in controls],
423
+ "controls": [{"site": at, "target": call_targets[at][0]} for at in controls],
394
424
  "instructionControls": [{"site": at, "instruction": _text(seen[at]), "routine": routine.get(at)}
395
425
  for at in instruction_controls],
396
426
  "negativeUsable": bool(controls or instruction_controls)
397
427
  and not (stopped or unresolved or gaps or contested or contradicted),
398
428
  "assumptions": assumptions,
399
- "exclusions": ["computed call and jump targets (listed in unresolved)", "unrelocated far calls",
429
+ "exclusions": ["computed call and jump targets no declaration gives (listed in unresolved)", "unrelocated far calls",
400
430
  "code reached only from outside the starts", "runtime reachability"],
401
431
  "interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
402
432
  "throughEveryRoute lists the routine starts every read route to the target passes, "
@@ -404,6 +434,9 @@ def reach(image, config):
404
434
  "negativeUsable needs a control of either kind, a walk that did not stop at its instruction limit, "
405
435
  "and no unresolved transfer, gap, contested instruction or contradicted noReturn "
406
436
  "routine, and still rests on the listed assumptions, leaves and noReturn declarations. "
437
+ "A declared indirect call counts as resolved when it is declared exhaustive: its table "
438
+ "rows are read from the build's bytes and its targets list rests on its evidence alone, "
439
+ "and neither proves an instruction boundary or that the call runs. "
407
440
  "A noReturn routine is contradicted when a return instruction, or a leaf entered "
408
441
  "other than by a call, lies on its own read paths; an empty returnSites means only "
409
442
  "that the walk read none. "
@@ -15,6 +15,7 @@ from .image import Image, instruction_limit, integer, scan_limit
15
15
  from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, holding_instruction, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON, LIMIT_REASON,
16
16
  RETURNS, INTERRUPTS, PORTS, PORT_INPUTS, port_width, budget_input, modeled_interrupt_sites)
17
17
  from .pcode_backend import interrupt_vector
18
+ from .dispatch import CALL_NOT_EXHAUSTIVE
18
19
 
19
20
 
20
21
  def entries(image):
@@ -85,13 +86,16 @@ def search_coverage(image, spans):
85
86
  return rows
86
87
 
87
88
 
88
- def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupts=frozenset()):
89
+ def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupts=frozenset(), indirect_calls=None):
89
90
  """Every direct call site in the searched regions, as ``incoming`` and ``inventory-check`` read them.
90
91
 
91
92
  Walks the entry-path CFG from every established entry, ending a branch at a call to a routine in
92
- ``no_return_calls`` and at an interrupt site in ``no_return_interrupts`` as ``walk`` does, then
93
+ ``no_return_calls`` and at an interrupt site in ``no_return_interrupts`` and following the declared
94
+ targets of each ``indirect_calls`` site as ``walk`` does, then
93
95
  scans every byte of the regions ``searchRegions`` names (all regions by default) for E8 and 9A
94
- call starts, and adds each reached call the scan cannot see (one that starts with a prefix). Returns a dict with the walk's
96
+ call starts, and adds each reached call the scan cannot see (one that starts with a prefix). A
97
+ reached declared indirect call gives one row for each declared target, and one unresolved row more
98
+ when it is not declared exhaustive; those rows are not in ``scanned``. Returns a dict with the walk's
95
99
  ``seen``, ``gaps`` (with a ``raw scan limit`` gap where ``scanLimit`` stopped a region),
96
100
  ``edges``, ``undecoded`` and ``contested``; ``rows``, every call row in the order it was read,
97
101
  each with its ``target`` (None when unresolved); ``scanned``, those rows by site, leaving out
@@ -99,7 +103,8 @@ def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupt
99
103
  searched; and ``read``, the byte span the scan read in each.
100
104
  """
101
105
  seen, gaps, edges, undecoded, contested = walk(image, entries(image), config.get("instructionLimit", 10000),
102
- no_return_calls=no_return_calls, no_return_interrupts=no_return_interrupts)
106
+ no_return_calls=no_return_calls, no_return_interrupts=no_return_interrupts,
107
+ indirect_calls=indirect_calls)
103
108
  rows, scanned = [], {}
104
109
 
105
110
  def classify(at):
@@ -144,6 +149,15 @@ def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupt
144
149
  rows.append({"site": at, "target": None, "encoding": ins.mnemonic, "region": region["name"],
145
150
  "classification": "unsupported control-transfer frame encoding"})
146
151
  continue
152
+ declaration = (indirect_calls or {}).get(at)
153
+ if declaration is not None:
154
+ provenance = {"encoding": "declared indirect call", "evidence": declaration["evidence"]}
155
+ rows.extend({"site": at, "target": target, "encoding": ins.mnemonic, "classification": classify(at),
156
+ "provenance": provenance, "region": region["name"]} for target in declaration["targets"])
157
+ if not declaration["exhaustive"]:
158
+ rows.append({"site": at, "target": None, "encoding": ins.mnemonic, "classification": classify(at),
159
+ "provenance": {"reason": CALL_NOT_EXHAUSTIVE}, "region": region["name"]})
160
+ continue
147
161
  resolved, provenance = call_target(image, at, ins)
148
162
  row = {"site": at, "target": resolved, "encoding": ins.mnemonic,
149
163
  "classification": classify(at), "provenance": provenance, "region": region["name"]}
@@ -1854,6 +1868,9 @@ def _run_report(image, config, command):
1854
1868
  raise ValueError("entryFrame applies only to " + ", ".join(TRACE_COMMANDS))
1855
1869
  if "inventory" in config and command != "inventory-check":
1856
1870
  raise ValueError("inventory applies only to inventory-check")
1871
+ # Other commands do not read the declarations, so a config that carries them is refused rather than ignored.
1872
+ if "indirectCalls" in config and command not in ("reach", "inventory-check"):
1873
+ raise ValueError("indirectCalls applies only to reach and inventory-check")
1857
1874
  if command == "operand":
1858
1875
  return operand_provenance(image, config)
1859
1876
  if command == "target":