dasmos 4.0.0__tar.gz → 4.2.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 (109) hide show
  1. {dasmos-4.0.0/src/dasmos.egg-info → dasmos-4.2.0}/PKG-INFO +2 -2
  2. {dasmos-4.0.0 → dasmos-4.2.0}/README.md +1 -1
  3. {dasmos-4.0.0 → dasmos-4.2.0}/pyproject.toml +1 -1
  4. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/__init__.py +1 -1
  5. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/asm_renderer.py +68 -6
  6. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/classification.py +34 -0
  7. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/markdown_asm.py +78 -32
  8. dasmos-4.2.0/src/dasmos/core/program.py +63 -0
  9. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/disassembler.py +96 -1
  10. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/beebasm/renderer.py +40 -1
  11. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/json/renderer.py +23 -1
  12. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/tass64/renderer.py +27 -0
  13. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ir.py +59 -0
  14. {dasmos-4.0.0 → dasmos-4.2.0/src/dasmos.egg-info}/PKG-INFO +2 -2
  15. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/SOURCES.txt +3 -0
  16. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_beebasm.py +103 -0
  17. dasmos-4.2.0/tests/test_include_binary.py +163 -0
  18. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_json_renderer.py +14 -0
  19. dasmos-4.2.0/tests/test_program.py +75 -0
  20. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_tass64.py +48 -0
  21. {dasmos-4.0.0 → dasmos-4.2.0}/LICENSE +0 -0
  22. {dasmos-4.0.0 → dasmos-4.2.0}/setup.cfg +0 -0
  23. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/_text.py +0 -0
  24. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/cli.py +0 -0
  25. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/__init__.py +0 -0
  26. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/annotations.py +0 -0
  27. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/config.py +0 -0
  28. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/cpu_state.py +0 -0
  29. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/data_type.py +0 -0
  30. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/disassembly.py +0 -0
  31. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/expr.py +0 -0
  32. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/expr_parse.py +0 -0
  33. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/file_header.py +0 -0
  34. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/format_hint.py +0 -0
  35. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/labels.py +0 -0
  36. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/memory.py +0 -0
  37. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/move.py +0 -0
  38. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/regions.py +0 -0
  39. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/cpu.py +0 -0
  40. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/environment.py +0 -0
  41. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/exceptions.py +0 -0
  42. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/expr.py +0 -0
  43. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/__init__.py +0 -0
  44. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/__init__.py +0 -0
  45. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu6502/__init__.py +0 -0
  46. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu6502/cpu.py +0 -0
  47. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu65c02/__init__.py +0 -0
  48. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu65c02/cpu.py +0 -0
  49. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/__init__.py +0 -0
  50. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/_acorn_bbc_common.py +0 -0
  51. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_1770/__init__.py +0 -0
  52. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_1770/environment.py +0 -0
  53. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_8271/__init__.py +0 -0
  54. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_8271/environment.py +0 -0
  55. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_master_hardware/__init__.py +0 -0
  56. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_master_hardware/environment.py +0 -0
  57. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_model_b_hardware/__init__.py +0 -0
  58. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_model_b_hardware/environment.py +0 -0
  59. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/__init__.py +0 -0
  60. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/enums.py +0 -0
  61. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/environment.py +0 -0
  62. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/hooks.py +0 -0
  63. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_sideways_rom/__init__.py +0 -0
  64. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_sideways_rom/environment.py +0 -0
  65. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/__init__.py +0 -0
  66. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/environment.py +0 -0
  67. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/floats.py +0 -0
  68. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/__init__.py +0 -0
  69. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/beebasm/__init__.py +0 -0
  70. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/json/__init__.py +0 -0
  71. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/tass64/__init__.py +0 -0
  72. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/extension.py +0 -0
  73. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/hooks.py +0 -0
  74. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/output.py +0 -0
  75. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/py.typed +0 -0
  76. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/renderer.py +0 -0
  77. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/dependency_links.txt +0 -0
  78. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/entry_points.txt +0 -0
  79. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/requires.txt +0 -0
  80. {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/top_level.txt +0 -0
  81. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_adfs_roundtrip.py +0 -0
  82. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_anfs_418_roundtrip.py +0 -0
  83. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_anfs_421_roundtrip.py +0 -0
  84. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cli.py +0 -0
  85. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu.py +0 -0
  86. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu6502.py +0 -0
  87. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu65c02.py +0 -0
  88. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_disassembler.py +0 -0
  89. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_driver_roundtrip.py +0 -0
  90. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_econet_bridge_roundtrip.py +0 -0
  91. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_environment.py +0 -0
  92. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr.py +0 -0
  93. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr_operators.py +0 -0
  94. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr_parse.py +0 -0
  95. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_file_header.py +0 -0
  96. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_golden_asm.py +0 -0
  97. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_golden_json.py +0 -0
  98. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_index_regions.py +0 -0
  99. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_macros.py +0 -0
  100. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_mnemonic_hash.py +0 -0
  101. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_nfs_334_roundtrip.py +0 -0
  102. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_nfs_roundtrip.py +0 -0
  103. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_output.py +0 -0
  104. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_py8dis2dasmos.py +0 -0
  105. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_reference_kinds.py +0 -0
  106. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_renderer.py +0 -0
  107. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_smoke.py +0 -0
  108. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_trace.py +0 -0
  109. {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_tube_client_roundtrip.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dasmos
3
- Version: 4.0.0
3
+ Version: 4.2.0
4
4
  Summary: Extensible tracing disassembler for classic CPUs, with CPU, renderer and environment extension points.
5
5
  Author-email: Robert Smallshire <rob@sixty-north.com>
6
6
  License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
32
32
  <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
33
33
  </p>
34
34
 
35
- An extensible tracing disassembler for classic CPUs, version `4.0.0`.
35
+ An extensible tracing disassembler for classic CPUs, version `4.2.0`.
36
36
 
37
37
  <p align="center">
38
38
  <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>
@@ -2,7 +2,7 @@
2
2
  <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
3
3
  </p>
4
4
 
5
- An extensible tracing disassembler for classic CPUs, version `4.0.0`.
5
+ An extensible tracing disassembler for classic CPUs, version `4.2.0`.
6
6
 
7
7
  <p align="center">
8
8
  <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>
@@ -108,7 +108,7 @@ dev = [
108
108
  ]
109
109
 
110
110
  [tool.bumpversion]
111
- current_version = "4.0.0"
111
+ current_version = "4.2.0"
112
112
  parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
113
113
  serialize = ["{major}.{minor}.{patch}"]
114
114
  tag = true
@@ -4,7 +4,7 @@ The top-level package re-exports the public API. Consumers should import
4
4
  from :mod:`dasmos` rather than reaching into sub-modules.
5
5
  """
6
6
 
7
- __version__ = "4.0.0"
7
+ __version__ = "4.2.0"
8
8
 
9
9
  from dasmos.core.annotations import Align, Annotation, AnnotationStore, Banner, Comment
10
10
  from dasmos.core.format_hint import FormatHint
@@ -29,7 +29,7 @@ from dasmos.core.annotations import (
29
29
  Comment,
30
30
  DecodedAnnotation,
31
31
  )
32
- from dasmos.core.classification import Byte, Fill, String, Word
32
+ from dasmos.core.classification import Byte, Fill, IncludedBinary, String, Word
33
33
  from dasmos.core.expr import (
34
34
  BinOp,
35
35
  Binary,
@@ -200,20 +200,45 @@ class AssemblerRenderer(TextRenderer):
200
200
  """
201
201
  return None
202
202
 
203
- def _save_directive(self, load_start, load_end) -> str | None:
203
+ def _save_directive(self, load_start, load_end, program=None) -> str | None:
204
204
  """A directive writing the loaded range to a binary file, or
205
205
  ``None`` when the assembler saves via a command-line flag
206
206
  instead. Default: ``None`` (no in-source save). Beebasm
207
207
  overrides with its ``save`` directive; 64tass leaves it to the
208
208
  ``-o`` flag.
209
+
210
+ ``program`` is the IR's :class:`~dasmos.core.program.ProgramInfo`
211
+ (or ``None``) — load-and-run metadata (exec/reload addresses) a
212
+ backend may fold into its save directive.
209
213
  """
210
214
  return None
211
215
 
216
+ def included_binary_directive(self, path: str) -> list[str]:
217
+ """Lines emitting an external binary include for ``path`` (an
218
+ :class:`~dasmos.core.classification.IncludedBinary` region).
219
+
220
+ Backends whose assembler can include an external file at
221
+ assembly time override this (beebasm ``incbin "path"``; 64tass
222
+ ``.binary "path"``). The base raises so a backend with no such
223
+ directive fails with a clear, actionable message rather than
224
+ silently mis-rendering the region as something else.
225
+ """
226
+ raise NotImplementedError(
227
+ f"{type(self).__name__} has no external-binary include "
228
+ f"directive, so it cannot render the include_binary region "
229
+ f"for {path!r}. Use a backend that supports file inclusion "
230
+ f"(beebasm's incbin / 64tass's .binary), or classify the "
231
+ f"region with byte()/word() instead."
232
+ )
233
+
212
234
  def _reset_render_state(self) -> None:
213
235
  """Reset per-render tracking state. Called at the start of
214
236
  every :meth:`render` call so the renderer is reusable across
215
237
  multiple IRs.
216
238
  """
239
+ # name -> address lookup for label: comment links; render()
240
+ # replaces this with the real resolver once the IR is known.
241
+ self._comment_label_resolver = None
217
242
  # Runtime addresses of out-of-range labels we resolved to a
218
243
  # name during operand rendering. The explicit-label table at
219
244
  # the top of the output emits these (plus all required
@@ -278,6 +303,7 @@ class AssemblerRenderer(TextRenderer):
278
303
  byte-equality holds.
279
304
  """
280
305
  self._reset_render_state()
306
+ self._comment_label_resolver = self._build_comment_label_resolver(ir)
281
307
 
282
308
  lines: list[str] = []
283
309
  lines.extend(self.disassembly_start())
@@ -354,7 +380,7 @@ class AssemblerRenderer(TextRenderer):
354
380
  if expected_pc != int(load_end):
355
381
  lines.extend(self.set_origin(int(load_end)))
356
382
  lines.append(self.inline_label(self.boundary_end_label))
357
- save = self._save_directive(load_start, load_end)
383
+ save = self._save_directive(load_start, load_end, ir.program)
358
384
  if save is not None:
359
385
  lines.append("")
360
386
  lines.append(save)
@@ -447,6 +473,7 @@ class AssemblerRenderer(TextRenderer):
447
473
  if header.title:
448
474
  title = markdown_to_asm_text(
449
475
  header.title, inline=True, hex_format=self.address_link_hex,
476
+ label_resolver=self._comment_label_resolver,
450
477
  )
451
478
  out.append(f"{cp} {title}")
452
479
  if header.description:
@@ -455,6 +482,7 @@ class AssemblerRenderer(TextRenderer):
455
482
  desc = markdown_to_asm_text(
456
483
  header.description, wrap_width=self.comment_wrap_column,
457
484
  hex_format=self.address_link_hex,
485
+ label_resolver=self._comment_label_resolver,
458
486
  )
459
487
  for line in desc.split("\n"):
460
488
  out.append(f"{cp} {line}" if line else cp)
@@ -537,7 +565,7 @@ class AssemblerRenderer(TextRenderer):
537
565
  if c.comment:
538
566
  line = (
539
567
  f"{line} {self.comment_prefix()} "
540
- f"{markdown_to_asm_text(c.comment, inline=True, hex_format=self.address_link_hex)}"
568
+ f"{markdown_to_asm_text(c.comment, inline=True, hex_format=self.address_link_hex, label_resolver=self._comment_label_resolver)}"
541
569
  )
542
570
  lines.append(line)
543
571
  return lines
@@ -819,6 +847,18 @@ class AssemblerRenderer(TextRenderer):
819
847
  lines.extend(self._render_annotation(ann))
820
848
  return lines
821
849
 
850
+ def _build_comment_label_resolver(self, ir):
851
+ """Build a ``name -> runtime-address`` lookup for ``label:NAME``
852
+ comment links, so a ``label:NAME?hex`` renders ``text (&ADDR)``
853
+ with the label's current address. Built once per render (the
854
+ per-name :meth:`LabelManager.addr_for_name` is linear)."""
855
+ name_to_addr: dict[str, int] = {}
856
+ for runtime_addr_obj, label in ir.labels.items():
857
+ addr = int(runtime_addr_obj)
858
+ for name in label.all_names():
859
+ name_to_addr.setdefault(name, addr)
860
+ return name_to_addr.get
861
+
822
862
  def _build_explicit_label_table(self, ir) -> list[str]:
823
863
  """Return ``name = &xxxx`` definition lines for out-of-range
824
864
  labels:
@@ -914,7 +954,7 @@ class AssemblerRenderer(TextRenderer):
914
954
  if description:
915
955
  line = (
916
956
  f"{line} {self.comment_prefix()} "
917
- f"{markdown_to_asm_text(description, inline=True, hex_format=self.address_link_hex)}"
957
+ f"{markdown_to_asm_text(description, inline=True, hex_format=self.address_link_hex, label_resolver=self._comment_label_resolver)}"
918
958
  )
919
959
  lines.append(line)
920
960
  # If this address has tracked references, follow the equate
@@ -1008,6 +1048,8 @@ class AssemblerRenderer(TextRenderer):
1008
1048
  word_count = 0
1009
1049
  string_byte_count = 0
1010
1050
  string_count = 0
1051
+ included_byte_count = 0
1052
+ included_count = 0
1011
1053
  for _addr, c in ir.classifications.iter_classified_starts():
1012
1054
  length = c.length()
1013
1055
  if isinstance(c, Opcode):
@@ -1024,6 +1066,9 @@ class AssemblerRenderer(TextRenderer):
1024
1066
  string_count += 1
1025
1067
  elif isinstance(c, Fill):
1026
1068
  byte_count += length
1069
+ elif isinstance(c, IncludedBinary):
1070
+ included_byte_count += length
1071
+ included_count += 1
1027
1072
  total = code_bytes + data_bytes
1028
1073
  if total == 0:
1029
1074
  return []
@@ -1041,7 +1086,14 @@ class AssemblerRenderer(TextRenderer):
1041
1086
  f"{cp} Number of data words = {word_count} bytes",
1042
1087
  f"{cp} Number of string bytes = {string_byte_count} bytes",
1043
1088
  f"{cp} Number of strings = {string_count}",
1044
- ]
1089
+ ] + (
1090
+ [
1091
+ f"{cp} Number of included bytes = {included_byte_count} bytes",
1092
+ f"{cp} Number of includes = {included_count}",
1093
+ ]
1094
+ if included_count
1095
+ else []
1096
+ )
1045
1097
 
1046
1098
  def _build_auto_label_footer(self, ir) -> list[str]:
1047
1099
  """``; Automatically generated labels:`` block listing every
@@ -1317,6 +1369,7 @@ class AssemblerRenderer(TextRenderer):
1317
1369
  if not ann.word_wrap:
1318
1370
  text = strip_address_uri_links(
1319
1371
  ann.text, hex_format=self.address_link_hex,
1372
+ label_resolver=self._comment_label_resolver,
1320
1373
  )
1321
1374
  if inline:
1322
1375
  # Collapse whitespace for inline rendering even in
@@ -1327,6 +1380,7 @@ class AssemblerRenderer(TextRenderer):
1327
1380
  return text
1328
1381
  return markdown_to_asm_text(
1329
1382
  ann.text, inline=inline, hex_format=self.address_link_hex,
1383
+ label_resolver=self._comment_label_resolver,
1330
1384
  )
1331
1385
 
1332
1386
  def _render_banner_lines(self, banner: Banner) -> list[str]:
@@ -1360,6 +1414,7 @@ class AssemblerRenderer(TextRenderer):
1360
1414
  # any incidental wrap-style whitespace and strip Markdown.
1361
1415
  title_text = markdown_to_asm_text(
1362
1416
  banner.title, inline=True, hex_format=self.address_link_hex,
1417
+ label_resolver=self._comment_label_resolver,
1363
1418
  )
1364
1419
  out.append(f"{prefix} {title_text}")
1365
1420
  if banner.description:
@@ -1368,6 +1423,7 @@ class AssemblerRenderer(TextRenderer):
1368
1423
  description_text = markdown_to_asm_text(
1369
1424
  banner.description, wrap_width=self.comment_wrap_column,
1370
1425
  hex_format=self.address_link_hex,
1426
+ label_resolver=self._comment_label_resolver,
1371
1427
  )
1372
1428
  for line in description_text.split("\n"):
1373
1429
  if line:
@@ -1389,6 +1445,7 @@ class AssemblerRenderer(TextRenderer):
1389
1445
  # as descriptions, so flatten through the same helper.
1390
1446
  value_text = markdown_to_asm_text(
1391
1447
  value, inline=True, hex_format=self.address_link_hex,
1448
+ label_resolver=self._comment_label_resolver,
1392
1449
  )
1393
1450
  out.append(f"{prefix} {key.upper()}: {value_text}")
1394
1451
  return out
@@ -1417,6 +1474,11 @@ class AssemblerRenderer(TextRenderer):
1417
1474
  return [" " + self.fill_directive(c.value(), c.length())[0]]
1418
1475
  if isinstance(c, String):
1419
1476
  return self._render_string(ir, binary_addr, c)
1477
+ if isinstance(c, IncludedBinary):
1478
+ return [
1479
+ " " + line
1480
+ for line in self.included_binary_directive(c.path())
1481
+ ]
1420
1482
  raise TypeError(
1421
1483
  f"{type(self).__name__} does not know how to render "
1422
1484
  f"{type(c).__name__}"
@@ -178,6 +178,40 @@ class String(Classification):
178
178
  self._length = length
179
179
 
180
180
 
181
+ class IncludedBinary(Classification):
182
+ """Marks a span whose bytes are supplied by an *external* file at
183
+ assembly time.
184
+
185
+ The span still **owns** its loaded bytes exactly like :class:`Byte`
186
+ (the tracer won't enter it and nothing is left unaccounted for), but
187
+ the renderer emits an include directive (beebasm ``incbin "path"``;
188
+ 64tass ``.binary "path"``) instead of ``equb`` lines. The owned
189
+ bytes are the canonical payload: :meth:`IntermediateRepresentation
190
+ .write_included_binaries` writes them to ``path`` so an assembler
191
+ reads back exactly what dasmos accounted for, keeping the round-trip
192
+ self-consistent even though the data lives in a separate file.
193
+
194
+ ``path`` is the include path as it should appear in the directive
195
+ (and the relative path the payload is written to) — typically a
196
+ bare filename sitting next to the listing.
197
+ """
198
+
199
+ def __init__(self, length: int, path: str):
200
+ _validate_positive_length(length)
201
+ if not isinstance(path, str) or not path:
202
+ raise ClassificationError(
203
+ f"IncludedBinary path must be a non-empty string; got {path!r}"
204
+ )
205
+ self._length = length
206
+ self._path = path
207
+
208
+ def length(self) -> int:
209
+ return self._length
210
+
211
+ def path(self) -> str:
212
+ return self._path
213
+
214
+
181
215
  class ExpressionRegistry:
182
216
  """Per-disassembly mapping from binary address to a user-supplied
183
217
  operand expression.
@@ -65,6 +65,47 @@ _ADDRESS_URI_TARGET_RE = re.compile(
65
65
  re.IGNORECASE,
66
66
  )
67
67
 
68
+ # The symbolic ``[label](label:NAME[@version][?flag])`` form. NAME is
69
+ # resolved to its address via the ``label_resolver`` the renderer
70
+ # supplies, so a ``?hex`` label link renders ``label (&ADDR)`` just like
71
+ # the address form — but stays correct when code shifts between versions.
72
+ _LABEL_URI_LINK_RE = re.compile(
73
+ r"\[(?P<label>[^\]\[]+)\]\(label:"
74
+ r"(?P<name>[^\]\[()?@\s]+)"
75
+ r"(?:@[^)?]+)?"
76
+ r"(?:\?(?P<flag>[^)]*))?"
77
+ r"\)",
78
+ )
79
+
80
+ _LABEL_URI_TARGET_RE = re.compile(
81
+ r"^label:"
82
+ r"(?P<name>[^?@\s]+)"
83
+ r"(?:@[^?]+)?"
84
+ r"(?:\?(?P<flag>[^&]*))?"
85
+ r"$",
86
+ )
87
+
88
+
89
+ def _render_uri_link_text(label, hex_str, flag, fmt):
90
+ """Shared collapse for address:/label: comment links.
91
+
92
+ ``hex_str`` is the target's hex digits (from an address: URI, or a
93
+ resolved label: name) or ``None`` when a label: name didn't resolve.
94
+ Without a flag, or when ``?hex`` can't show a hex, the link collapses
95
+ to its label text; ``?hex`` with a known address appends ``(&ADDR)``.
96
+ """
97
+ flag = (flag or "").lower()
98
+ if flag == "hex" and hex_str is not None:
99
+ return f"{label} ({fmt(hex_str)})"
100
+ if flag and flag != "hex" and flag not in _warned_flags:
101
+ _warned_flags.add(flag)
102
+ warnings.warn(
103
+ f"unknown flag '?{flag}' in address:/label: URI — "
104
+ f"rendering label only in asm output",
105
+ stacklevel=3,
106
+ )
107
+ return label
108
+
68
109
 
69
110
  # Track flags we've already warned about so each unknown flag fires
70
111
  # only ONCE per process. Without this, a 1000-line driver with a
@@ -83,10 +124,10 @@ def _default_address_link_hex(hex_str: str) -> str:
83
124
 
84
125
 
85
126
  def strip_address_uri_links(
86
- text: str, *, hex_format=None,
127
+ text: str, *, hex_format=None, label_resolver=None,
87
128
  ) -> str:
88
- """Replace ``[label](address:HEX[?hex])`` with plain text — no
89
- markdown parser involved, just the regex.
129
+ """Replace ``[label](address:HEX[?hex])`` / ``[label](label:NAME[?hex])``
130
+ with plain text — no markdown parser involved, just the regex.
90
131
 
91
132
  Use when the surrounding text needs to keep its literal layout
92
133
  (banner separators, ASCII-art tables) and full Markdown parsing
@@ -99,6 +140,11 @@ def strip_address_uri_links(
99
140
  With ``?hex``: the hex is appended uppercased in parentheses:
100
141
  ``see [foo](address:E000?hex)`` → ``see foo (&E000)``
101
142
 
143
+ A ``label:NAME`` link resolves ``NAME`` to its address via
144
+ ``label_resolver`` (a ``name -> int | None`` callable); ``?hex`` then
145
+ shows that resolved address, so the link stays correct across
146
+ versions. A name that doesn't resolve collapses to its label text.
147
+
102
148
  An ``@version`` suffix is silently stripped. Unknown flags warn
103
149
  once per flag value and collapse as if no flag were present.
104
150
  Backticks around the label are removed (they're HTML-only
@@ -107,24 +153,21 @@ def strip_address_uri_links(
107
153
 
108
154
  fmt = hex_format or _default_address_link_hex
109
155
 
110
- def rewrite(match: re.Match[str]) -> str:
156
+ def rewrite_address(match: re.Match[str]) -> str:
111
157
  label = match.group("label").replace("`", "")
112
- hex_str = match.group("hex")
113
- flag = (match.group("flag") or "").lower()
114
- if not flag:
115
- return label
116
- if flag == "hex":
117
- return f"{label} ({fmt(hex_str)})"
118
- if flag not in _warned_flags:
119
- _warned_flags.add(flag)
120
- warnings.warn(
121
- f"unknown flag '?{flag}' in address: URI — "
122
- f"rendering label only in asm output",
123
- stacklevel=2,
124
- )
125
- return label
158
+ return _render_uri_link_text(
159
+ label, match.group("hex"), match.group("flag"), fmt)
160
+
161
+ def rewrite_label(match: re.Match[str]) -> str:
162
+ label = match.group("label").replace("`", "")
163
+ addr = label_resolver(match.group("name")) if label_resolver else None
164
+ hex_str = f"{int(addr):04X}" if addr is not None else None
165
+ return _render_uri_link_text(
166
+ label, hex_str, match.group("flag"), fmt)
126
167
 
127
- return _ADDRESS_URI_LINK_RE.sub(rewrite, text)
168
+ text = _ADDRESS_URI_LINK_RE.sub(rewrite_address, text)
169
+ text = _LABEL_URI_LINK_RE.sub(rewrite_label, text)
170
+ return text
128
171
 
129
172
 
130
173
  def markdown_normalize_headings(text: str) -> str:
@@ -205,6 +248,7 @@ def markdown_to_asm_text(
205
248
  inline: bool = False,
206
249
  wrap_width: int | None = None,
207
250
  hex_format=None,
251
+ label_resolver=None,
208
252
  ) -> str:
209
253
  """Render ``text`` (CommonMark + GFM tables) as plaintext for asm.
210
254
 
@@ -213,6 +257,8 @@ def markdown_to_asm_text(
213
257
  - ``wrap_width=N`` wraps prose paragraphs and list items at column
214
258
  N. Tables and code fences are laid out structurally and ignore
215
259
  the wrap.
260
+ - ``label_resolver`` (a ``name -> int | None`` callable) resolves a
261
+ ``label:NAME`` link's address for its ``?hex`` rendering.
216
262
 
217
263
  Returns the plaintext with paragraphs separated by blank lines and
218
264
  no trailing newline.
@@ -220,6 +266,7 @@ def markdown_to_asm_text(
220
266
  import mistletoe
221
267
  with _AsmTextRenderer(
222
268
  wrap_width=wrap_width, inline=inline, hex_format=hex_format,
269
+ label_resolver=label_resolver,
223
270
  ) as renderer:
224
271
  doc = mistletoe.Document(text)
225
272
  return renderer.render(doc)
@@ -240,11 +287,12 @@ class _AsmTextRenderer(BaseRenderer):
240
287
  """
241
288
 
242
289
  def __init__(self, wrap_width: int | None = None, inline: bool = False,
243
- hex_format=None):
290
+ hex_format=None, label_resolver=None):
244
291
  super().__init__()
245
292
  self.wrap_width = wrap_width
246
293
  self.inline = inline
247
294
  self._hex_format = hex_format or _default_address_link_hex
295
+ self._label_resolver = label_resolver
248
296
  self._indent = ""
249
297
  self._list_markers: list[tuple[str, int | None]] = []
250
298
 
@@ -412,18 +460,16 @@ class _AsmTextRenderer(BaseRenderer):
412
460
  target = getattr(token, "target", "") or ""
413
461
  match = _ADDRESS_URI_TARGET_RE.match(target)
414
462
  if match:
415
- flag = (match.group("flag") or "").lower()
416
- hex_str = match.group("hex")
417
- if flag == "hex":
418
- return f"{label} ({self._hex_format(hex_str)})"
419
- if flag and flag not in _warned_flags:
420
- _warned_flags.add(flag)
421
- warnings.warn(
422
- f"unknown flag '?{flag}' in address: URI — "
423
- f"rendering label only in asm output",
424
- stacklevel=2,
425
- )
426
- return label
463
+ return _render_uri_link_text(
464
+ label, match.group("hex"), match.group("flag"),
465
+ self._hex_format)
466
+ match = _LABEL_URI_TARGET_RE.match(target)
467
+ if match:
468
+ addr = (self._label_resolver(match.group("name"))
469
+ if self._label_resolver else None)
470
+ hex_str = f"{int(addr):04X}" if addr is not None else None
471
+ return _render_uri_link_text(
472
+ label, hex_str, match.group("flag"), self._hex_format)
427
473
  # Ordinary URLs collapse to label text — asm has no hypertext.
428
474
  return label
429
475
 
@@ -0,0 +1,63 @@
1
+ """Program-level metadata for a disassembled load-and-run file.
2
+
3
+ Some target programs are not position-fixed ROMs but *load-and-run*
4
+ files: a DFS ``*RUN`` program loads at one address and begins execution
5
+ at another (its **exec** address), and the filesystem records a
6
+ **reload** address distinct from where the bytes sit in the image.
7
+ These addresses are properties of the *program*, not of any particular
8
+ assembler syntax, so they live in the model and every renderer reads
9
+ what it can express (beebasm's ``save … , exec, reload``; a structural
10
+ field in JSON; a graceful no-op where the backend has no equivalent).
11
+
12
+ The load range itself is already known from the loaded image; a driver
13
+ only needs to declare the addresses the image can't imply.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass
19
+
20
+ from dasmos.exceptions import DasmosError
21
+
22
+
23
+ class ProgramError(DasmosError):
24
+ """Raised on invalid program-metadata declaration."""
25
+
26
+
27
+ def _validate_addr(name: str, value: int | None) -> int | None:
28
+ if value is None:
29
+ return None
30
+ if not isinstance(value, int) or isinstance(value, bool) or value < 0:
31
+ raise ProgramError(
32
+ f"{name} must be a non-negative integer address; got {value!r}"
33
+ )
34
+ return value
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class ProgramInfo:
39
+ """Declared metadata for a load-and-run program.
40
+
41
+ Every field is optional; ``None`` means 'not declared' (the
42
+ renderer falls back to a sensible default or omits the datum). A
43
+ plain-ROM disassembly never constructs one of these.
44
+
45
+ - ``load_addr`` — where the program loads. Usually implied by the
46
+ loaded image's range; declared only when a driver wants it
47
+ recorded explicitly.
48
+ - ``exec_addr`` — where execution begins (the DFS exec address),
49
+ distinct from the load address for a driver whose entry point
50
+ is not its first byte.
51
+ - ``reload_addr`` — the address the filesystem reloads the file
52
+ to. Defaults to the load-range start when a renderer needs it
53
+ and it was not declared.
54
+ """
55
+
56
+ load_addr: int | None = None
57
+ exec_addr: int | None = None
58
+ reload_addr: int | None = None
59
+
60
+ def __post_init__(self) -> None:
61
+ _validate_addr("load_addr", self.load_addr)
62
+ _validate_addr("exec_addr", self.exec_addr)
63
+ _validate_addr("reload_addr", self.reload_addr)
@@ -41,7 +41,14 @@ from dasmos.core.annotations import (
41
41
  Comment,
42
42
  DecodedAnnotation,
43
43
  )
44
- from dasmos.core.classification import Byte, ExpressionRegistry, Fill, String, Word
44
+ from dasmos.core.classification import (
45
+ Byte,
46
+ ExpressionRegistry,
47
+ Fill,
48
+ IncludedBinary,
49
+ String,
50
+ Word,
51
+ )
45
52
  from dasmos.core.data_type import DataType, DecodedValue
46
53
  from dasmos.core.expr import Expr, MacroCall, MacroDef, Ref, macro_arg
47
54
  from dasmos.core.file_header import FileHeader
@@ -57,6 +64,7 @@ from dasmos.core.disassembly import (
57
64
  from dasmos.core.labels import LabelManager
58
65
  from dasmos.core.memory import BinaryAddr, MemoryImage
59
66
  from dasmos.core.move import BASE_MOVE_ID, Move, MoveManager
67
+ from dasmos.core.program import ProgramInfo
60
68
  from dasmos.core.regions import IndexRegion, RegionManager
61
69
  from dasmos.cpu import Cpu, create_cpu
62
70
  from dasmos.exceptions import DasmosError
@@ -208,6 +216,10 @@ class Disassembler:
208
216
  # Optional provenance prose emitted at the top of a listing and in
209
217
  # the JSON meta (set via :meth:`set_file_header`).
210
218
  self._file_header: FileHeader | None = None
219
+ # Optional load-and-run program metadata (exec/reload/load
220
+ # addresses) declared via :meth:`program`. ``None`` for a
221
+ # plain position-fixed ROM disassembly.
222
+ self._program_info: ProgramInfo | None = None
211
223
  # Deprecated → replacement constant-name aliases registered by
212
224
  # environments via :meth:`register_deprecated_constant_name`.
213
225
  # When a driver calls :meth:`constant` with a key in this dict,
@@ -334,6 +346,48 @@ class Disassembler:
334
346
  """The provenance header, or ``None`` (see :meth:`set_file_header`)."""
335
347
  return self._file_header
336
348
 
349
+ @property
350
+ def program_info(self) -> "ProgramInfo | None":
351
+ """Declared load-and-run program metadata, or ``None``
352
+ (see :meth:`program`)."""
353
+ return self._program_info
354
+
355
+ def program(
356
+ self,
357
+ *,
358
+ load_addr: int | None = None,
359
+ exec_addr: int | None = None,
360
+ reload_addr: int | None = None,
361
+ ) -> None:
362
+ """Declare load-and-run program metadata for the disassembly.
363
+
364
+ A DFS ``*RUN`` program loads at one address but may begin
365
+ execution at another (its ``exec_addr``), and the filesystem
366
+ records a ``reload_addr`` distinct from where the bytes sit.
367
+ These are properties of the program, not of any assembler
368
+ syntax, so they are declared here and each renderer emits what
369
+ it can express:
370
+
371
+ - beebasm appends them to its ``save`` directive
372
+ (``save "NAME", start, end, exec, reload``), producing a
373
+ directly ``*RUN``-able file whose header matches the original
374
+ DFS metadata;
375
+ - the JSON renderer surfaces them structurally;
376
+ - a backend with no equivalent (e.g. 64tass, which saves via
377
+ ``-o``) warns and omits them, leaving the raw payload — and
378
+ so ``fantasm verify`` — unaffected.
379
+
380
+ Every argument is optional; an omitted address is simply not
381
+ recorded. ``reload_addr`` defaults to the loaded range's start
382
+ when a renderer needs it and it was not declared.
383
+ """
384
+ self._raise_if_disassembled("program")
385
+ self._program_info = ProgramInfo(
386
+ load_addr=load_addr,
387
+ exec_addr=exec_addr,
388
+ reload_addr=reload_addr,
389
+ )
390
+
337
391
  def set_file_header(self, title=None, description=None) -> None:
338
392
  """Set the backend-agnostic provenance header emitted at the top of
339
393
  a listing (and in the JSON ``meta``).
@@ -1010,6 +1064,47 @@ class Disassembler:
1010
1064
  self._override_clear(binary_addr, length, override)
1011
1065
  self._classifications.add_classification(binary_addr, String(length))
1012
1066
 
1067
+ def include_binary(
1068
+ self,
1069
+ runtime_addr,
1070
+ length: int,
1071
+ path: str,
1072
+ *,
1073
+ move: Move | None = None,
1074
+ override: bool = False,
1075
+ ):
1076
+ """Mark ``length`` bytes at ``runtime_addr`` as an external
1077
+ binary include.
1078
+
1079
+ Classifies the span as data — the bytes are accounted for and
1080
+ the tracer won't enter it, exactly like :meth:`byte` — but tags
1081
+ it so a renderer emits an include directive (beebasm
1082
+ ``incbin "<path>"``; 64tass ``.binary "<path>"``) instead of a
1083
+ wall of ``equb`` lines. Use it for a region whose source of
1084
+ truth lives outside the disassembly and is regenerated at build
1085
+ time (e.g. detokenised BASIC re-encoded to bytes).
1086
+
1087
+ The span still owns its loaded bytes, so nothing is left
1088
+ unaccounted for. Those bytes are the canonical payload:
1089
+ :meth:`IntermediateRepresentation.write_included_binaries` writes
1090
+ them to ``path`` next to the listing, so the assembler reads back
1091
+ exactly the bytes dasmos accounted for and the round-trip stays
1092
+ self-consistent. A project whose own generator must reproduce the
1093
+ region can diff its output against that canonical payload.
1094
+
1095
+ ``path`` is the include path as it should appear in the directive
1096
+ (typically a bare filename beside the listing). Pass
1097
+ ``override=True`` to clear a conflicting classification in the
1098
+ range first; otherwise an overlap raises
1099
+ :class:`ClassificationError`.
1100
+ """
1101
+ self._raise_if_disassembled("include_binary")
1102
+ binary_addr = self._resolve_to_binary_addr(runtime_addr, move)
1103
+ self._override_clear(binary_addr, length, override)
1104
+ self._classifications.add_classification(
1105
+ binary_addr, IncludedBinary(length, path),
1106
+ )
1107
+
1013
1108
  # -- driver-script API: custom data types ----------------------------
1014
1109
 
1015
1110
  def register_data_type(self, name: str, data_type: DataType) -> None: