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.
- {dasmos-4.0.0/src/dasmos.egg-info → dasmos-4.2.0}/PKG-INFO +2 -2
- {dasmos-4.0.0 → dasmos-4.2.0}/README.md +1 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/pyproject.toml +1 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/__init__.py +1 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/asm_renderer.py +68 -6
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/classification.py +34 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/markdown_asm.py +78 -32
- dasmos-4.2.0/src/dasmos/core/program.py +63 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/disassembler.py +96 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/beebasm/renderer.py +40 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/json/renderer.py +23 -1
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/tass64/renderer.py +27 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ir.py +59 -0
- {dasmos-4.0.0 → dasmos-4.2.0/src/dasmos.egg-info}/PKG-INFO +2 -2
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/SOURCES.txt +3 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_beebasm.py +103 -0
- dasmos-4.2.0/tests/test_include_binary.py +163 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_json_renderer.py +14 -0
- dasmos-4.2.0/tests/test_program.py +75 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_tass64.py +48 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/LICENSE +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/setup.cfg +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/_text.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/cli.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/annotations.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/config.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/cpu_state.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/data_type.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/disassembly.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/expr.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/expr_parse.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/file_header.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/format_hint.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/labels.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/memory.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/move.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/core/regions.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/cpu.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/exceptions.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/expr.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu6502/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu6502/cpu.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu65c02/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/cpus/cpu65c02/cpu.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/_acorn_bbc_common.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_1770/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_1770/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_8271/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_fdc_8271/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_master_hardware/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_master_hardware/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_model_b_hardware/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_model_b_hardware/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/enums.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_mos/hooks.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_sideways_rom/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/acorn_sideways_rom/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/environments/bbc_basic_6502/floats.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/beebasm/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/json/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/ext/renderers/tass64/__init__.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/extension.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/hooks.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/output.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/py.typed +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos/renderer.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/dependency_links.txt +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/entry_points.txt +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/requires.txt +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/src/dasmos.egg-info/top_level.txt +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_adfs_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_anfs_418_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_anfs_421_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cli.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu6502.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_cpu65c02.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_disassembler.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_driver_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_econet_bridge_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_environment.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr_operators.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_expr_parse.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_file_header.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_golden_asm.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_golden_json.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_index_regions.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_macros.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_mnemonic_hash.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_nfs_334_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_nfs_roundtrip.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_output.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_py8dis2dasmos.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_reference_kinds.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_renderer.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_smoke.py +0 -0
- {dasmos-4.0.0 → dasmos-4.2.0}/tests/test_trace.py +0 -0
- {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.
|
|
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.
|
|
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.
|
|
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>
|
|
@@ -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.
|
|
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])``
|
|
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
|
|
156
|
+
def rewrite_address(match: re.Match[str]) -> str:
|
|
111
157
|
label = match.group("label").replace("`", "")
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
if
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
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
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
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
|
|
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:
|