scientific-method-engine 19.5.0__tar.gz → 19.6.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 (92) hide show
  1. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/cli.py +3 -1
  4. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/dispatch.py +100 -11
  5. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/inventory.py +11 -6
  6. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode_backend.py +5 -1
  7. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reach.py +56 -17
  8. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/trace.py +4 -4
  9. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_inventory_check.py +28 -0
  10. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_reach.py +109 -6
  11. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/.gitignore +0 -0
  12. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/LICENSE +0 -0
  13. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/README.md +0 -0
  14. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__init__.py +0 -0
  15. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  17. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  18. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  19. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  20. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  21. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  22. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  23. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  24. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  25. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  26. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  27. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  28. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  29. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  30. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  31. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  32. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  33. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  34. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  35. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  37. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  38. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  39. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  40. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  41. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  42. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  43. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  44. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  45. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  46. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  47. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  48. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  49. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  50. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  51. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  52. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  53. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/derived_counts.py +0 -0
  54. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  55. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/image.py +0 -0
  56. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/loops.py +0 -0
  57. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/machine.py +0 -0
  58. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  59. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  60. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pe.py +0 -0
  61. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/ranges.py +0 -0
  62. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/relational.py +0 -0
  63. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reports.py +0 -0
  64. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  65. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/table_bounds.py +0 -0
  66. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/values.py +0 -0
  67. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/oracle.py +0 -0
  68. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_config_encoding.py +0 -0
  69. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_continuation_budget.py +0 -0
  70. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_derived_counts.py +0 -0
  71. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_dispatch.py +0 -0
  72. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_effect_order.py +0 -0
  73. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_enter_frames.py +0 -0
  74. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_entry_frame.py +0 -0
  75. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_indirect_far_transfers.py +0 -0
  76. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_interrupt_models.py +0 -0
  77. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_join_terms.py +0 -0
  78. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_loops.py +0 -0
  79. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_memory_scopes.py +0 -0
  80. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_nested_frame_request.py +0 -0
  81. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_oracle.py +0 -0
  82. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_pe.py +0 -0
  83. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_ranges.py +0 -0
  84. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_relational_controls.py +0 -0
  85. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_return_checks.py +0 -0
  86. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_successor_rule.py +0 -0
  87. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_table_bounds.py +0 -0
  88. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_table_continuations.py +0 -0
  89. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_term_limit.py +0 -0
  90. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_upstream_gaps.py +0 -0
  91. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.0}/tests/test_volatile_memory.py +0 -0
  92. {scientific_method_engine-19.5.0 → scientific_method_engine-19.6.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: 19.5.0
3
+ Version: 19.6.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 = "19.5.0"
8
+ version = "19.6.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"
@@ -33,7 +33,9 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
33
33
  "is followed, and each is repeated with its reason and where it cut the walk, not checked or assumed;\n"
34
34
  "the noReturn check reads past the stops, and returnCheckGaps lists what it could not read there;\n"
35
35
  "indirectCalls declares the targets of a computed call as a table read from the build or a list,\n"
36
- "and the walk calls each of them; one not declared exhaustive stays unresolved;\n"
36
+ "and the walk calls each of them; one not declared exhaustive stays unresolved; outside names where the\n"
37
+ "call leaves the image (a saved vector, an interrupt's returned pointer or a description), which is not\n"
38
+ "read and is grouped in outsideTransfers, and an exhaustive empty targets list says the call never runs;\n"
37
39
  "an exhaustive indirectJumps or indirectCalls table can leave out count and give bound {routine}:\n"
38
40
  "the engine derives its rows from a value-range analysis of that routine and lists the derivation,\n"
39
41
  "a count it cannot prove leaves the site unresolved with its reasons, a declared count larger than\n"
@@ -1,6 +1,7 @@
1
1
  """Explicit, source-derived indirect jump tables and call targets for CFG discovery, and explicitly conditional path continuations."""
2
2
  from capstone.x86 import X86_OP_IMM, X86_OP_MEM
3
3
  from .image import integer
4
+ from .pcode_backend import interrupt_vector, INTERRUPTS
4
5
 
5
6
  CALL_NOT_EXHAUSTIVE = "indirect call targets are not declared exhaustive"
6
7
  JUMP_NOT_EXHAUSTIVE = "indirect jump table is not declared exhaustive"
@@ -214,7 +215,12 @@ def indirect_call_declarations(value, image):
214
215
 
215
216
  Each declaration names a ``site`` that decodes as an unprefixed segmented16 computed call (a near
216
217
  call through a word register or memory operand, or a far call through memory), its ``evidence``,
217
- an explicit boolean ``exhaustive``, and exactly one of ``table`` and ``targets``. A table's rows are
218
+ an explicit boolean ``exhaustive``, at most one of ``table`` and ``targets``, and ``outside`` when
219
+ it has neither (ADR 0042). ``outside`` states that the call can leave the declared code, for one
220
+ stated destination: a saved interrupt ``vector``, the far pointer an ``interrupt`` site returned,
221
+ or a ``description`` of other code outside the image; it is returned normalized by
222
+ ``outside_destination``. An exhaustive declaration may give an empty ``targets`` list, which states
223
+ that the call never runs. A table's rows are
218
224
  read from the source bytes as ``indirectJumps`` reads them: words placed through the call site's
219
225
  region mapping for a near call, and for a far call ``offset, segment`` word pairs whose segment
220
226
  word has a declared relocation, admitted as ``Image.far_pointer_target`` admits the pointer a
@@ -235,9 +241,11 @@ def indirect_call_declarations(value, image):
235
241
  result = {}
236
242
  image.derived_call_reads = {}
237
243
  for claim in value:
238
- keys = set(claim) if isinstance(claim, dict) else None
239
- if keys not in ({"site", "evidence", "exhaustive", "table"}, {"site", "evidence", "exhaustive", "targets"}):
240
- raise ValueError("Each indirect call needs site, evidence, exhaustive and exactly one of table and targets")
244
+ keys = set(claim) - {"outside"} if isinstance(claim, dict) else None
245
+ base = {"site", "evidence", "exhaustive"}
246
+ if keys not in (base | {"table"}, base | {"targets"}) and not (keys == base and "outside" in claim):
247
+ raise ValueError("Each indirect call needs site, evidence, exhaustive, at most one of table and targets, "
248
+ "and outside when it has neither")
241
249
  site = integer(claim["site"], 0, len(image.data) - 1, "indirect call site")
242
250
  if site in result:
243
251
  raise ValueError("Duplicate indirect call site")
@@ -254,7 +262,12 @@ def indirect_call_declarations(value, image):
254
262
  "or a far call through memory")
255
263
  declaration = {"site": site, "instruction": (ins.mnemonic + " " + ins.op_str).strip(),
256
264
  "evidence": claim["evidence"], "exhaustive": claim["exhaustive"]}
257
- if "table" in claim:
265
+ if "outside" in claim:
266
+ declaration["outside"] = outside_destination(claim["outside"], image, site, far)
267
+ if "table" not in claim and "targets" not in claim:
268
+ # An outside destination alone: the call names no target in declared code.
269
+ targets = []
270
+ elif "table" in claim:
258
271
  table, width = claim["table"], 4 if far else 2
259
272
  if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
260
273
  raise ValueError("An indirect call table needs layout/count evidence")
@@ -279,9 +292,15 @@ def indirect_call_declarations(value, image):
279
292
  targets = [row["target"] for row in rows]
280
293
  else:
281
294
  targets = claim["targets"]
282
- if (not isinstance(targets, list) or not 1 <= len(targets) <= 256
295
+ if (not isinstance(targets, list) or len(targets) > 256
283
296
  or len(set(map(repr, targets))) != len(targets)):
284
- raise ValueError("indirect call targets must be a list of 1..256 distinct file offsets")
297
+ raise ValueError("indirect call targets must be a list of 0..256 distinct file offsets")
298
+ # No targets says the call never runs, which only an exhaustive declaration without an outside
299
+ # destination can state; anything else would be an undeclared call with extra words.
300
+ if not targets and (not claim["exhaustive"] or "outside" in claim):
301
+ raise ValueError(f"indirect call {site} declares no targets, which states that the call never runs; "
302
+ "that needs exhaustive true and no outside (give outside alone for a call that "
303
+ "leaves the declared code)")
285
304
  for at in targets:
286
305
  integer(at, 0, len(image.data) - 1, "indirect call target")
287
306
  region = image.region(at)
@@ -298,6 +317,50 @@ def indirect_call_declarations(value, image):
298
317
  return result
299
318
 
300
319
 
320
+ def declared_interrupt(image, at, label, conditional_reason):
321
+ """``(ins, vector)`` for the unconditional interrupt instruction at ``at``, which a declaration names as ``label``.
322
+
323
+ ``at`` must lie in declared code and decode as an interrupt, whatever prefix capstone names in the
324
+ mnemonic; a conditional interrupt (INTO) is refused with ``conditional_reason``.
325
+ """
326
+ if image.region(at) is None:
327
+ raise ValueError(f"{label} {at} is outside declared code")
328
+ ins = image.decode(at)
329
+ if ins is None or ins.mnemonic.split()[-1] not in INTERRUPTS:
330
+ raise ValueError(f"{label} {at} is not an interrupt instruction")
331
+ vector, conditional = interrupt_vector(image.flat, ins, at)
332
+ if conditional:
333
+ raise ValueError(f"{label} {at} is conditional {conditional_reason}")
334
+ return ins, vector
335
+
336
+
337
+ def outside_destination(value, image, site, far):
338
+ """The normalized ``outside`` destination of the declared indirect call at ``site``.
339
+
340
+ ``value`` names exactly one of ``vector`` (0..255: the call enters the handler that held that
341
+ interrupt vector before the program replaced it), ``interrupt`` (a file offset in declared code
342
+ that decodes as an unconditional interrupt instruction: the call goes through the far pointer
343
+ that interrupt returned, and the result adds the interrupt's ``vector`` and ``instruction``) or
344
+ ``description`` (nonempty free text naming other code outside the image, such as code built on
345
+ the stack or a table a loaded driver fills). A saved vector and an interrupt's returned pointer
346
+ are far pointers, so those two need a far call.
347
+ """
348
+ if not isinstance(value, dict) or len(value) != 1 or set(value) - {"vector", "interrupt", "description"}:
349
+ raise ValueError(f"indirect call {site} outside needs exactly one of vector, interrupt and description")
350
+ kind, given = next(iter(value.items()))
351
+ if kind != "description" and not far:
352
+ raise ValueError(f"indirect call {site} outside {kind} names a far pointer, which a near call cannot use")
353
+ if kind == "vector":
354
+ return {"vector": integer(given, 0, 255, "outside vector")}
355
+ if kind == "description":
356
+ if not isinstance(given, str) or not given.strip():
357
+ raise ValueError(f"indirect call {site} outside description must be nonempty text")
358
+ return {"description": given}
359
+ at = integer(given, 0, len(image.data) - 1, "outside interrupt")
360
+ ins, vector = declared_interrupt(image, at, f"indirect call {site} outside interrupt", "and may return nothing")
361
+ return {"interrupt": at, "vector": vector, "instruction": (ins.mnemonic + " " + ins.op_str).strip()}
362
+
363
+
301
364
  def open_reason(declaration, call):
302
365
  """Why a declared table or call leaves its site unresolved, or None.
303
366
 
@@ -321,11 +384,37 @@ def derived_assumptions(image, indirect_calls):
321
384
  return []
322
385
 
323
386
 
387
+ def never_runs(declaration):
388
+ """Whether a declared indirect call states that it never runs: exhaustive, with an empty ``targets`` list
389
+ and no outside. A table whose count was not proven also has no targets, but it is unresolved, not empty."""
390
+ return (declaration["exhaustive"] and "table" not in declaration and not declaration["targets"]
391
+ and "outside" not in declaration)
392
+
393
+
324
394
  def declared_call_ends(declaration, no_return_calls):
325
- """Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``) and
326
- every target is in ``no_return_calls``."""
327
- return open_reason(declaration, True) is None and all(target in no_return_calls
328
- for target in declaration["targets"])
395
+ """Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``), it
396
+ has no ``outside`` destination (which the walk does not read, so it is assumed to return), and every
397
+ target is in ``no_return_calls``.
398
+
399
+ A declaration that ``never_runs`` ends its branch, since the next instruction is reached through the
400
+ call only once it has run.
401
+ """
402
+ return (open_reason(declaration, True) is None and "outside" not in declaration
403
+ and all(target in no_return_calls for target in declaration["targets"]))
404
+
405
+
406
+ def indirect_call_assumptions(indirect_calls):
407
+ """The assumptions the ``indirectCalls`` declarations add to a report."""
408
+ if not indirect_calls:
409
+ return []
410
+ found = ["each declared indirect call can call the targets its declaration gives, for the evidence it gives, "
411
+ "and only those when it is declared exhaustive"]
412
+ if any("outside" in declaration for declaration in indirect_calls.values()):
413
+ found.append("each declared outside destination is where its call can leave the declared code, for the "
414
+ "evidence it gives; the code there is not read, and it returns to the call's next instruction")
415
+ if any(never_runs(declaration) for declaration in indirect_calls.values()):
416
+ found.append("each indirect call declared exhaustive with no targets never runs, for the evidence it gives")
417
+ return found
329
418
 
330
419
 
331
420
  def call_ends(site, target, indirect_calls, no_return_calls):
@@ -4,7 +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, OVERLAP_REASON, walk, holding_instruction
7
- from .dispatch import indirect_call_declarations, call_ends, derived_assumptions
7
+ from .dispatch import indirect_call_declarations, call_ends, never_runs, indirect_call_assumptions, derived_assumptions
8
8
 
9
9
  MAX_INVENTORY = 16 * 1024 * 1024
10
10
  MAX_ROWS = 200000
@@ -425,6 +425,11 @@ def inventory_check(image, config):
425
425
  def site_classification(at):
426
426
  return "entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site"
427
427
  listed = {site for site, *_ in ends}
428
+ # A call declared never to run has no target, so no call row holds it, yet it ends the branch as an
429
+ # exhaustive call whose every target is noReturn does; it is listed as one with no routines.
430
+ never = [at for at, declaration in indirect_calls.items() if never_runs(declaration)]
431
+ ends += [(at, image.decode(at).size, "call", [], site_classification(at)) for at in never]
432
+ listed |= set(never)
428
433
  ends += [(at, row["following"] - at, "call site",
429
434
  site_targets[at][0] if len(site_targets[at]) == 1 else site_targets[at] or None, site_classification(at))
430
435
  for at, row in no_return_sites.items() if at not in listed]
@@ -528,15 +533,13 @@ def inventory_check(image, config):
528
533
  if target_stopped:
529
534
  summary += (" The walk that checks the targets of the noReturn calls stopped at its instruction limit, so it "
530
535
  "can miss returns.")
531
- assumptions = [call_assumption(no_return_routines, no_return_sites)]
536
+ assumptions = [call_assumption(no_return_routines, no_return_sites, indirect_calls)]
532
537
  if checked:
533
538
  assumptions.append("each interrupt the noReturn check reads returns to its next instruction"
534
539
  + (", except at a noReturn interrupt site" if no_return_interrupts else "")
535
540
  + "; interrupt handlers are not read")
536
541
  assumptions += no_return_assumptions(no_return_routines, no_return_interrupts, no_return_sites)
537
- if indirect_calls:
538
- assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
539
- "it gives, and only those when it is declared exhaustive")
542
+ assumptions += indirect_call_assumptions(indirect_calls)
540
543
  assumptions += derived_assumptions(image, indirect_calls)
541
544
  indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
542
545
  return {"inventory": {"path": config["inventory"], "rows": len(rows)},
@@ -556,7 +559,9 @@ def inventory_check(image, config):
556
559
  "partialSearch": partial, "gaps": calls["gaps"],
557
560
  "exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
558
561
  "walk reaches them)", "unrelocated far calls",
559
- "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"],
562
+ "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"]
563
+ + (["the code a declared outside destination names, and anything it calls"]
564
+ if any("outside" in declaration for declaration in indirect_calls.values()) else []),
560
565
  "interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
561
566
  "notation and compared with its rows. A target only raw byte candidates or contested "
562
567
  "instructions call is not shown to be code. The counts are lower bounds on the targets "
@@ -988,6 +988,10 @@ def port_access(state, ins, direction, port, value, size):
988
988
  return result
989
989
 
990
990
 
991
+ # The interrupt mnemonics, as capstone names them without a prefix.
992
+ INTERRUPTS = ("int", "int1", "int3", "into")
993
+
994
+
991
995
  def interrupt_vector(flat, ins, site):
992
996
  """The vector p-code's ``swi`` operation names, and whether the interrupt is conditional (INTO)."""
993
997
  ops, _ = LIFTER.ops(flat, bytes(ins.bytes), site)
@@ -1015,7 +1019,7 @@ for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop
1015
1019
  (("shl", "sal", "shr", "sar"), shift), (("rol", "ror", "rcl", "rcr"), rotate),
1016
1020
  (("mul", "imul"), multiply), (("div", "idiv"), divide),
1017
1021
  (("cbw", "cwde", "cwd", "cdq"), conversion), (("cld", "std", "cli", "sti"), flag_write),
1018
- (("in", "out"), run_plain), (("int", "int1", "int3", "into"), interrupt)):
1022
+ (("in", "out"), run_plain), (INTERRUPTS, interrupt)):
1019
1023
  for name in names:
1020
1024
  HANDLERS[name] = handler
1021
1025
 
@@ -4,7 +4,8 @@ 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, derived_assumptions
7
+ from .dispatch import (indirect_call_declarations, call_ends, never_runs, indirect_call_assumptions,
8
+ declared_interrupt, derived_assumptions)
8
9
 
9
10
  # The virtual root of the dominator computation; no file offset is negative.
10
11
  ROOT = -1
@@ -115,12 +116,7 @@ def no_return_declarations(value, image):
115
116
  found[at] = {"reason": entry["reason"], "following": at + ins.size}
116
117
  continue
117
118
  if kind == "interrupt":
118
- ins = image.decode(at)
119
- if ins is None or base_mnemonic(ins) not in INTERRUPTS:
120
- raise ValueError(f"noReturn interrupt {at} is not an interrupt instruction")
121
- vector, conditional = interrupt_vector(image.flat, ins, at)
122
- if conditional:
123
- raise ValueError(f"noReturn interrupt {at} is conditional and continues when it does not interrupt")
119
+ ins, vector = declared_interrupt(image, at, "noReturn interrupt", "and continues when it does not interrupt")
124
120
  found[at] = {"reason": entry["reason"], "vector": vector, "following": at + ins.size}
125
121
  continue
126
122
  found[at] = entry["reason"]
@@ -135,9 +131,12 @@ def no_return_inputs(value, image, indirect_calls):
135
131
  return routines, interrupts, calls, declared
136
132
 
137
133
 
138
- def call_assumption(routines, calls):
139
- """The assumption that reached calls return, with the exceptions the ``noReturn`` declarations make."""
140
- exceptions = (["a call to a noReturn routine"] if routines else []) + (["a noReturn call"] if calls else [])
134
+ def call_assumption(routines, calls, indirect_calls):
135
+ """The assumption that reached calls return, with the exceptions the ``noReturn`` declarations make and
136
+ the indirect calls declared never to run (``never_runs``)."""
137
+ exceptions = ((["a call to a noReturn routine"] if routines else []) + (["a noReturn call"] if calls else [])
138
+ + (["an indirect call declared never to run"]
139
+ if any(never_runs(d) for d in indirect_calls.values()) else []))
141
140
  return "each reached call returns to its next instruction" + (", except " + " and ".join(exceptions)
142
141
  if exceptions else "")
143
142
 
@@ -238,6 +237,24 @@ def no_return_rows(routines, interrupts, returns, call_sites, seen, reached, rea
238
237
  for at, row in interrupts.items()]
239
238
 
240
239
 
240
+ def outside_transfers(indirect_calls, seen):
241
+ """The declared ``outside`` destinations, each once with the declared call ``sites`` that name it and the
242
+ ``reached`` ones among them; an ``interrupt`` destination also says whether the walk reached that interrupt."""
243
+ groups = {}
244
+ for site, declaration in indirect_calls.items():
245
+ if "outside" in declaration:
246
+ destination = declaration["outside"]
247
+ group = groups.setdefault(repr(sorted(destination.items())), dict(destination, sites=[], reached=[]))
248
+ group["sites"].append(site)
249
+ if site in seen:
250
+ group["reached"].append(site)
251
+ rows = list(groups.values())
252
+ for row in rows:
253
+ if "interrupt" in row:
254
+ row["interruptReached"] = row["interrupt"] in seen
255
+ return rows
256
+
257
+
241
258
  def fewest_calls(graph, starts):
242
259
  """``(distance, parent, routine)`` for every site ``graph`` reaches from ``starts`` by the route with the fewest calls.
243
260
 
@@ -451,7 +468,9 @@ def reach(image, config):
451
468
  interrupt to the next instruction. A ``leaves`` routine is reached but never decoded. A call to a
452
469
  ``noReturn`` routine, a ``noReturn`` call site and a ``noReturn`` interrupt site do not continue
453
470
  at the next instruction, nor does a declared indirect call that is exhaustive and whose targets
454
- are all ``noReturn``. A ``stops`` routine is reached but never decoded, and a call to it does not
471
+ are all ``noReturn``, which holds for one declared exhaustive with no targets (it never runs). A
472
+ declared ``outside`` destination is not read: the call continues at its return site, and
473
+ ``outsideTransfers`` groups the declared sites by destination. A ``stops`` routine is reached but never decoded, and a call to it does not
455
474
  continue at the next instruction, under the same rule as a call to a ``noReturn`` routine; a
456
475
  ``stops`` site is decoded and nothing after it is followed. A stop narrows the query and claims
457
476
  nothing about the build, so it is neither checked nor listed among the assumptions.
@@ -621,6 +640,14 @@ def reach(image, config):
621
640
  cut_by[row["following"]] = f"{cut_by[row['following']]} and {cause}" if row["following"] in cut_by else cause
622
641
  cut_by |= {row["following"]: f"the noReturn interrupt at {at}"
623
642
  for at, row in no_return_interrupts.items() if at in seen}
643
+ # A declared call that never runs has no targets, so call_targets does not hold it. Its site can be a
644
+ # noReturn call too, and the message then names both declarations.
645
+ never_following = {at: at + image.decode(at).size for at, declaration in indirect_calls.items()
646
+ if never_runs(declaration)}
647
+ for at, following in never_following.items():
648
+ if at in seen:
649
+ cause = f"the indirect call at {at}, declared never to run"
650
+ cut_by[following] = f"{cut_by[following]} and {cause}" if following in cut_by else cause
624
651
  # A site past a stop site may be reached by no other route; the first stop names the cut.
625
652
  for at, found in sorted(stop_successors.items()):
626
653
  for successor in found:
@@ -714,17 +741,21 @@ def reach(image, config):
714
741
  if site in seen and site not in stop_sites
715
742
  and t not in seen and t not in unread]}
716
743
  for site, declaration in indirect_calls.items()]
744
+ # A call that never runs ends its branch, so a reviewer can check whether what follows it is read another way.
745
+ for row in indirect_rows:
746
+ if row["site"] in never_following:
747
+ following = never_following[row["site"]]
748
+ row |= {"following": following, "followingRead": following in seen}
749
+ outside = outside_transfers(indirect_calls, seen)
717
750
  counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
718
751
  "interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
719
- assumptions = [call_assumption(no_return_routines, no_return_sites),
752
+ assumptions = [call_assumption(no_return_routines, no_return_sites, indirect_calls),
720
753
  "each reached interrupt returns to its next instruction"
721
754
  + (", except at a noReturn interrupt site" if no_return_interrupts else "")
722
755
  + "; interrupt handlers are not read",
723
756
  "each leaf calls nothing, for the reason it gives",
724
757
  "each declared indirect jump table holds the routes its declaration gives"]
725
- if indirect_calls:
726
- assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
727
- "it gives, and only those when it is declared exhaustive")
758
+ assumptions += indirect_call_assumptions(indirect_calls)
728
759
  assumptions += no_return_assumptions(no_return_routines, no_return_interrupts, no_return_sites)
729
760
  assumptions += derived_assumptions(image, indirect_calls)
730
761
  stopped = stopped or check_stopped
@@ -732,7 +763,7 @@ def reach(image, config):
732
763
  # instruction limit bounds their number.
733
764
  ranges = {"decodedRanges": decoded_ranges(seen, routine)} if with_ranges else {}
734
765
  return {"starts": starts, "targets": rows, "leaves": leaf_rows, "stops": stop_rows, "noReturn": no_return,
735
- "indirectCalls": indirect_rows,
766
+ "indirectCalls": indirect_rows, "outsideTransfers": outside,
736
767
  "reachedRoutines": sorted(routine_starts), **ranges, "counts": counts,
737
768
  "unresolved": unresolved[:limit], "interrupts": interrupts[:limit], "gaps": gaps[:limit],
738
769
  "contested": sorted(contested)[:limit], "returnCheckGaps": check_gap_rows[:limit],
@@ -746,7 +777,8 @@ def reach(image, config):
746
777
  or check_gap_rows),
747
778
  "assumptions": assumptions,
748
779
  "exclusions": ["computed call and jump targets no declaration gives (listed in unresolved)", "unrelocated far calls",
749
- "code reached only from outside the starts", "runtime reachability"],
780
+ "code reached only from outside the starts", "runtime reachability"]
781
+ + (["the code a declared outside destination names, and anything it calls"] if outside else []),
750
782
  "interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
751
783
  "throughEveryRoute lists the routine starts every read route to the target passes, "
752
784
  "and an unresolved transfer may add a route that passes none of them. "
@@ -762,6 +794,13 @@ def reach(image, config):
762
794
  "table without count, the code proves its count: its table "
763
795
  "rows are read from the build's bytes and its targets list rests on its evidence alone, "
764
796
  "and neither proves an instruction boundary or that the call runs. "
797
+ "A declared outside destination is where the call can leave the declared code, on its "
798
+ "evidence alone: the walk reads nothing there, assumes the code returns to the call's "
799
+ "next instruction, and claims nothing about what it does or calls; outsideTransfers "
800
+ "groups the declared sites by destination. "
801
+ "An indirect call declared exhaustive with no targets never runs, on its evidence alone: "
802
+ "the walk reads nothing past it, and followingRead says whether it read the next "
803
+ "instruction by another route. "
765
804
  "A noReturn routine is contradicted when a return instruction, or a leaf entered "
766
805
  "other than by a call, lies on its own read paths; an empty returnSites means only "
767
806
  "that the walk read none. "
@@ -10,7 +10,7 @@ from .values import const, unknown, sources, op, join, unformed, TermLimit
10
10
  from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
- from .pcode_backend import interrupt_vector
13
+ from .pcode_backend import interrupt_vector, INTERRUPTS
14
14
  from .dispatch import ENTERED, JUMP_NOT_DERIVED, declared_call_ends, open_reason
15
15
  from .relational import checkpoint_anchors, memory_probes, probe_memory
16
16
 
@@ -92,7 +92,6 @@ OVERLAP_REASON = "overlapping entry-path instructions; boundary unresolved"
92
92
  # The gap reason walk() records at a site it reaches but cannot decode.
93
93
  UNDECODED_REASON = "undecoded or unmapped edge"
94
94
  RETURNS = {"ret": "near return", "retf": "far return", "iret": "interrupt return", "iretd": "interrupt return"}
95
- INTERRUPTS = ("int", "int1", "int3", "into")
96
95
  PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
97
96
  PORT_INPUTS = ("in", "insb", "insw", "insd")
98
97
 
@@ -196,8 +195,9 @@ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False, fol
196
195
  they never come back. A call whose site is in ``no_return_call_sites`` has no return site either,
197
196
  whatever its target: the query declared that this one call never comes back. A call whose site
198
197
  is in ``indirect_calls`` (``indirect_call_declarations``) continues at each declared target and
199
- at its return site, unless the declaration is exhaustive and every target is in
200
- ``no_return_calls``, or the site is in ``no_return_call_sites``.
198
+ at its return site, unless the declaration ends the branch under ``declared_call_ends`` (exhaustive,
199
+ with no ``outside`` destination, and every target in ``no_return_calls``, which holds for a call
200
+ declared with no targets), or the site is in ``no_return_call_sites``.
201
201
  """
202
202
  m, following = base_mnemonic(ins), at + ins.size
203
203
  if unsupported_transfer(image, ins):
@@ -545,6 +545,34 @@ class InventoryCheckTests(unittest.TestCase):
545
545
  with self.assertRaisesRegex(ValueError, r"Positive control \[0\] missed or not verified"):
546
546
  self.check(inventory, data=data, indirectCalls=[table], controls=[[0]])
547
547
 
548
+ def test_an_outside_or_never_run_declaration_leaves_the_computed_call_resolved_with_no_call_target(self):
549
+ # 0000 calls through the word at 0010; 0005 returns.
550
+ data = bytes.fromhex("2eff971000" "c3" "90909090909090909090" "14001800" "c3" "909090" "c3")
551
+ inventory = "start\tsize\n1000:0000\t6\n"
552
+ outside = {"site": 0, "exhaustive": True, "evidence": "synthetic: bx always selects code built on the stack",
553
+ "outside": {"description": "code built on the stack"}}
554
+ r = self.check(inventory, data=data, indirectCalls=[outside])
555
+ self.assertEqual((r["unresolved"], r["targets"]), ([], []))
556
+ self.assertEqual([(d["site"], d["outside"], d["targets"]) for d in r["indirectCalls"]],
557
+ [(0, {"description": "code built on the stack"}, [])])
558
+ self.assertIn("each declared outside destination is where its call can leave the declared code, for the "
559
+ "evidence it gives; the code there is not read, and it returns to the call's next instruction",
560
+ r["assumptions"])
561
+ self.assertIn("the code a declared outside destination names, and anything it calls", r["exclusions"])
562
+ never = {"site": 0, "exhaustive": True, "targets": [], "evidence": "synthetic: the call is gated off"}
563
+ ended = self.check(inventory, data=data, indirectCalls=[never])
564
+ self.assertNotIn("the code a declared outside destination names, and anything it calls", ended["exclusions"])
565
+ self.assertEqual((ended["unresolved"], ended["targets"]), ([], []))
566
+ # The call ends the branch, so the row's ret at 0005 is past it and unread.
567
+ self.assertEqual([(row["start"], row["kind"], row["site"], row["routines"], row["following"],
568
+ row["followingRead"], row["siteClassification"]) for row in ended["rowsPastNoReturn"]],
569
+ [("1000:0000", "call", 0, [], 5, False, "entry-path instruction")])
570
+ self.assertEqual((ended["counts"]["rowsPastNoReturn"], ended["counts"]["rowsPastNoReturnUnreadAfter"]), (1, 1))
571
+ # The outside call returns, so the same row is not past anything.
572
+ self.assertEqual(r["rowsPastNoReturn"], [])
573
+ self.assertEqual(ended["assumptions"][0], "each reached call returns to its next instruction, except an "
574
+ "indirect call declared never to run")
575
+
548
576
  def test_a_missed_control_and_a_malformed_inventory_are_refused(self):
549
577
  with self.assertRaisesRegex(ValueError, "Positive control 12 missed"):
550
578
  self.check("start\tsize\n1000:0000\t6\n", data=RAW, controls=[12])
@@ -667,6 +667,7 @@ def _code(size, parts):
667
667
  # 0000 masks its argument to 0..3, doubles it and calls through the four words at 0040, which name
668
668
  # 0100, 0110, 0120 and 0130. It then calls through the far pointer at 0200. Only 0120 calls 0140, which
669
669
  # stores a word. 0130 never returns. The far pointer pair at 0048 names 0110 once its segment word is relocated.
670
+ # The interrupt at 0012 stands for one whose returned far pointer the program stores and later calls.
670
671
  COMPUTED = _code(0x160, {
671
672
  0x00: "8b5e06", # mov bx, [bp+6]
672
673
  0x03: "83e303", # and bx, 3
@@ -674,6 +675,8 @@ COMPUTED = _code(0x160, {
674
675
  0x08: "2eff974000", # call word ptr cs:[bx+0040]
675
676
  0x0D: "ff1e0002", # call far [0200]
676
677
  0x11: "c3", # ret
678
+ 0x12: "cd2f", # int 2Fh, which nothing reaches
679
+ 0x14: "ce", # into, which nothing reaches
677
680
  0x40: "0001100120013001",
678
681
  0x48: "10010000",
679
682
  0x100: "c3",
@@ -825,19 +828,19 @@ class DeclaredIndirectCallTests(unittest.TestCase):
825
828
  def test_rejected_declarations(self):
826
829
  table = NEAR_TABLE["table"]
827
830
  for declaration, message in [
828
- ({}, "site, evidence, exhaustive and exactly one of table and targets"),
829
- ({**NEAR_TABLE, "targets": [0x100]}, "exactly one of table and targets"),
830
- ({**FAR_TARGETS, "unknown": 1}, "exactly one of table and targets"),
831
+ ({}, "site, evidence, exhaustive, at most one of table and targets, and outside when it has neither"),
832
+ ({**NEAR_TABLE, "targets": [0x100]}, "at most one of table and targets"),
833
+ ({**FAR_TARGETS, "unknown": 1}, "at most one of table and targets"),
834
+ ({"site": 0x0D, "exhaustive": True, "evidence": "synthetic"}, "outside when it has neither"),
831
835
  ({**FAR_TARGETS, "evidence": " "}, "needs evidence"),
832
836
  ({**FAR_TARGETS, "exhaustive": 1}, "explicit exhaustive"),
833
837
  ({**FAR_TARGETS, "site": 0x120}, "site 288 must decode as an unprefixed computed near word call"),
834
838
  ({**FAR_TARGETS, "site": 0x00}, "site 0 must decode"),
835
- ({**FAR_TARGETS, "targets": []}, "1..256 distinct file offsets"),
836
- ({**FAR_TARGETS, "targets": [0x110, 0x110]}, "1..256 distinct file offsets"),
839
+ ({**FAR_TARGETS, "targets": [0x110, 0x110]}, "0..256 distinct file offsets"),
837
840
  ({**FAR_TARGETS, "targets": [0x1000]}, "indirect call target must be an integer"),
838
841
  ({**NEAR_TABLE, "table": {**table, "evidence": ""}}, "layout/count evidence"),
839
842
  ({**NEAR_TABLE, "table": {**table, "width": 4}}, "near call table holds 2-byte targets"),
840
- ({**FAR_TARGETS, "targets": list(range(0x100, 0x100 + 257))}, "1..256 distinct file offsets"),
843
+ ({**FAR_TARGETS, "targets": list(range(0x100, 0x100 + 257))}, "0..256 distinct file offsets"),
841
844
  ({**NEAR_TABLE, "table": {**table, "count": 0}}, "table count"),
842
845
  ({**NEAR_TABLE, "table": {**table, "count": 257}}, "table count must be an integer in 1..256"),
843
846
  ({**NEAR_TABLE, "table": {**table, "start": 0x15E, "count": 2}}, "leaves source bounds"),
@@ -852,6 +855,106 @@ class DeclaredIndirectCallTests(unittest.TestCase):
852
855
  computed(indirectCalls=[FAR_TARGETS] * 257)
853
856
 
854
857
 
858
+ NEVER_RUNS = {"site": 0x0D, "exhaustive": True, "targets": [],
859
+ "evidence": "synthetic: the count that gates the call is 0 at load and its only writer is unreferenced"}
860
+ SAVED_VECTOR = {"site": 0x0D, "exhaustive": True, "outside": {"vector": 8},
861
+ "evidence": "synthetic: 0200 holds vector 8 as the program read it before hooking the timer"}
862
+
863
+
864
+ class DeclaredOutsideAndNeverRunCallTests(unittest.TestCase):
865
+ def test_a_call_declared_with_no_targets_never_runs_and_ends_its_branch(self):
866
+ r = computed(indirectCalls=[NEAR_TABLE, NEVER_RUNS], controls=[0x120], targets=[0x11])
867
+ self.assertEqual(r["targets"][0]["status"], "not reached")
868
+ self.assertEqual((r["unresolved"], r["gaps"]), ([], []))
869
+ self.assertTrue(r["negativeUsable"])
870
+ row = r["indirectCalls"][1]
871
+ self.assertEqual({k: row[k] for k in ("site", "targets", "reached", "unreadTargets", "following",
872
+ "followingRead")},
873
+ {"site": 0x0D, "targets": [], "reached": True, "unreadTargets": [], "following": 0x11,
874
+ "followingRead": False})
875
+ self.assertNotIn("following", r["indirectCalls"][0])
876
+ self.assertEqual(r["outsideTransfers"], [])
877
+ self.assertIn("each indirect call declared exhaustive with no targets never runs, for the evidence it gives",
878
+ r["assumptions"])
879
+ self.assertEqual(r["assumptions"][0], "each reached call returns to its next instruction, except an indirect "
880
+ "call declared never to run")
881
+ with self.assertRaisesRegex(ValueError, r"instruction control 17 is not reached \(it follows the indirect "
882
+ r"call at 13, declared never to run\)"):
883
+ computed(indirectCalls=[NEVER_RUNS], instructionControls=[0x11])
884
+ # A noReturn declaration for the same call is named beside it.
885
+ with self.assertRaisesRegex(ValueError, r"\(it follows the noReturn call at 13 and the indirect call at 13, "
886
+ r"declared never to run\)"):
887
+ computed(indirectCalls=[NEVER_RUNS], instructionControls=[0x11],
888
+ noReturn=[{"call": 0x0D, "reason": "synthetic: gated off"}])
889
+
890
+ def test_an_outside_call_leaves_nothing_unresolved_and_continues_at_its_return_site(self):
891
+ r = computed(indirectCalls=[NEAR_TABLE, SAVED_VECTOR], controls=[0x120], instructionControls=[0x11])
892
+ self.assertEqual((r["unresolved"], r["gaps"]), ([], []))
893
+ self.assertTrue(r["negativeUsable"])
894
+ far = r["indirectCalls"][1]
895
+ self.assertEqual((far["outside"], far["targets"], far["reached"]), ({"vector": 8}, [], True))
896
+ self.assertNotIn("following", far)
897
+ self.assertEqual(r["outsideTransfers"], [{"vector": 8, "sites": [0x0D], "reached": [0x0D]}])
898
+ self.assertIn("each declared outside destination is where its call can leave the declared code, for the "
899
+ "evidence it gives; the code there is not read, and it returns to the call's next instruction",
900
+ r["assumptions"])
901
+ self.assertIn("the code a declared outside destination names, and anything it calls", r["exclusions"])
902
+ self.assertEqual(r["assumptions"][0], "each reached call returns to its next instruction")
903
+ # Without outside declarations the report adds neither the assumption nor the exclusion.
904
+ plain = computed(indirectCalls=[NEAR_TABLE], controls=[0x120])
905
+ self.assertNotIn("the code a declared outside destination names, and anything it calls", plain["exclusions"])
906
+
907
+ def test_an_outside_call_not_declared_exhaustive_stays_unresolved(self):
908
+ r = computed(indirectCalls=[{**SAVED_VECTOR, "exhaustive": False}], instructionControls=[0x11])
909
+ self.assertEqual([(u["site"], u["reason"]) for u in r["unresolved"]],
910
+ [(0x08, "computed transfer remains unresolved"),
911
+ (0x0D, "indirect call targets are not declared exhaustive")])
912
+ self.assertFalse(r["negativeUsable"])
913
+
914
+ def test_an_outside_destination_keeps_a_call_to_no_return_targets_returning(self):
915
+ no_return = [{"routine": 0x130, "reason": "synthetic: spins forever"}]
916
+ r = computed(indirectCalls=[{**FAR_TARGETS, "targets": [0x130], "outside": {"vector": 8}}],
917
+ noReturn=no_return, targets=[0x11], instructionControls=[0x11])
918
+ self.assertTrue(r["targets"][0]["reached"])
919
+ self.assertEqual(r["noReturn"][0]["callSites"], [])
920
+ self.assertEqual(r["indirectCalls"][0]["targets"], [0x130])
921
+ # A noReturn declaration for the call itself still ends it.
922
+ ended = computed(indirectCalls=[SAVED_VECTOR], targets=[0x11],
923
+ noReturn=[{"call": 0x0D, "reason": "synthetic: the saved handler never comes back"}])
924
+ self.assertEqual(ended["targets"][0]["status"], "not reached")
925
+
926
+ def test_outside_transfers_group_the_sites_that_name_one_destination(self):
927
+ built = {"description": "code the routine builds on the stack"}
928
+ r = computed(indirectCalls=[{**NEAR_TABLE, "outside": built, "table": NEAR_TABLE["table"]},
929
+ {**SAVED_VECTOR, "outside": dict(built)}], controls=[0x120])
930
+ self.assertEqual(r["outsideTransfers"], [{**built, "sites": [0x08, 0x0D], "reached": [0x08, 0x0D]}])
931
+ self.assertEqual(r["indirectCalls"][0]["targets"], [0x100, 0x110, 0x120, 0x130])
932
+ returned = computed(indirectCalls=[{**SAVED_VECTOR, "outside": {"interrupt": 0x12}}], controls=[])
933
+ self.assertEqual(returned["indirectCalls"][0]["outside"], {"interrupt": 0x12, "vector": 0x2F,
934
+ "instruction": "int 0x2f"})
935
+ self.assertEqual(returned["outsideTransfers"], [{"interrupt": 0x12, "vector": 0x2F, "instruction": "int 0x2f",
936
+ "sites": [0x0D], "reached": [0x0D],
937
+ "interruptReached": False}])
938
+
939
+ def test_rejected_outside_and_never_run_declarations(self):
940
+ for declaration, message in [
941
+ ({**NEVER_RUNS, "exhaustive": False}, "declares no targets, which states that the call never runs"),
942
+ ({**NEVER_RUNS, "outside": {"vector": 8}}, "needs exhaustive true and no outside"),
943
+ ({**SAVED_VECTOR, "outside": {}}, "outside needs exactly one of vector, interrupt and description"),
944
+ ({**SAVED_VECTOR, "outside": {"vector": 8, "description": "x"}}, "exactly one of vector"),
945
+ ({**SAVED_VECTOR, "outside": {"segment": 8}}, "exactly one of vector"),
946
+ ({**SAVED_VECTOR, "outside": "vector 8"}, "exactly one of vector"),
947
+ ({**SAVED_VECTOR, "outside": {"vector": 256}}, "outside vector must be an integer in 0..255"),
948
+ ({**SAVED_VECTOR, "outside": {"description": " "}}, "outside description must be nonempty text"),
949
+ ({**SAVED_VECTOR, "outside": {"interrupt": 0x11}}, "outside interrupt 17 is not an interrupt"),
950
+ ({**SAVED_VECTOR, "outside": {"interrupt": 0x14}}, "outside interrupt 20 is conditional"),
951
+ ({**SAVED_VECTOR, "site": 0x08, "outside": {"vector": 8}},
952
+ "outside vector names a far pointer, which a near call cannot use"),
953
+ ({**SAVED_VECTOR, "site": 0x08, "outside": {"interrupt": 0x12}}, "a near call cannot use")]:
954
+ with self.subTest(declaration=declaration), self.assertRaisesRegex(ValueError, message):
955
+ computed(indirectCalls=[declaration])
956
+
957
+
855
958
  # Three starts. A at 0000 calls H at 0010, which calls T at 001B and U at 001C. B at 0008 calls G at
856
959
  # 0017, which calls T. C at 000C makes a computed call through BX.
857
960
  STARTS = bytes.fromhex(