dasmos 4.2.0__tar.gz → 4.2.1__tar.gz

{dasmos-4.2.0/src/dasmos.egg-info → dasmos-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dasmos
-Version: 4.2.0
+Version: 4.2.1
 Summary: Extensible tracing disassembler for classic CPUs, with CPU, renderer and environment extension points.
 Author-email: Robert Smallshire <rob@sixty-north.com>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
   <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
 </p>
 
-An extensible tracing disassembler for classic CPUs, version `4.2.0`.
+An extensible tracing disassembler for classic CPUs, version `4.2.1`.
 
 <p align="center">
   <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>

{dasmos-4.2.0 → dasmos-4.2.1}/README.md

@@ -2,7 +2,7 @@
   <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
 </p>
 
-An extensible tracing disassembler for classic CPUs, version `4.2.0`.
+An extensible tracing disassembler for classic CPUs, version `4.2.1`.
 
 <p align="center">
   <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>

{dasmos-4.2.0 → dasmos-4.2.1}/pyproject.toml

@@ -108,7 +108,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "4.2.0"
+current_version = "4.2.1"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 tag = true

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos/__init__.py

@@ -4,7 +4,7 @@ The top-level package re-exports the public API. Consumers should import
 from :mod:`dasmos` rather than reaching into sub-modules.
 """
 
-__version__ = "4.2.0"
+__version__ = "4.2.1"
 
 from dasmos.core.annotations import Align, Annotation, AnnotationStore, Banner, Comment
 from dasmos.core.format_hint import FormatHint

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos/asm_renderer.py

@@ -77,6 +77,21 @@ BYTE_COLUMN_TOTAL_WIDTH = 27
 # surrounding text.
 BANNER_SEPARATOR_WIDTH = 87
 
+# Absolute addressing modes and the zero-page mode a size-optimising
+# assembler (beebasm, 64tass) substitutes when the operand value is
+# below ``&100`` *and* the mnemonic has that zero-page form. An
+# instruction encoded in one of these modes with such an operand must
+# be rendered so the assembler keeps the absolute encoding (#46).
+_ZERO_PAGE_FORM_OF_ABSOLUTE_MODE = {
+    "ABSOLUTE": "ZERO_PAGE",
+    "ABSOLUTE_X": "ZERO_PAGE_X",
+    "ABSOLUTE_Y": "ZERO_PAGE_Y",
+}
+_ABSOLUTE_FORM_OF_ZERO_PAGE_MODE = {
+    zero_page: absolute
+    for absolute, zero_page in _ZERO_PAGE_FORM_OF_ABSOLUTE_MODE.items()
+}
+
 if TYPE_CHECKING:
     from dasmos.ir import IntermediateRepresentation
 
@@ -163,6 +178,11 @@ class AssemblerRenderer(TextRenderer):
         # so). Drivers wanting per-expression control can fold selected
         # expressions themselves before registering them.
         self.fold_string_ops = fold_string_ops
+        # Initialise the per-render state so the public helpers that
+        # rely on it (e.g. :meth:`render_expression`) also work on a
+        # renderer that hasn't rendered anything yet; :meth:`render`
+        # resets it again at the start of every render.
+        self._reset_render_state()
 
     @property
     def emit_boundary_labels(self) -> bool:
@@ -259,6 +279,18 @@ class AssemblerRenderer(TextRenderer):
         # Macro names already warned about being inline-expanded, so the
         # warning fires once per macro rather than once per call site.
         self._macros_expansion_warned: set[str] = set()
+        # ``(operation, addressing-mode name)`` pairs the IR's CPU
+        # offers, built lazily on first use (see
+        # :meth:`_needs_forced_absolute`).
+        self._cpu_operation_modes: frozenset | None = None
+        # Explicit label name -> runtime address, so an expression that
+        # names a label (a ``Sym``) can mark it used (see
+        # :meth:`_note_symbol_use`). Filled in by :meth:`render`.
+        self._label_addr_by_name: dict[str, int] = {}
+        # While an instruction's operand is being rendered: the runtime
+        # addresses of the labels it names (see :meth:`_render_opcode`);
+        # ``None`` otherwise.
+        self._operand_label_refs: set[int] | None = None
 
     def render(self, ir: "IntermediateRepresentation") -> TextOutput:
         """Walk the IR's classifications and emit a beebasm source
@@ -304,6 +336,7 @@ class AssemblerRenderer(TextRenderer):
         """
         self._reset_render_state()
         self._comment_label_resolver = self._build_comment_label_resolver(ir)
+        self._label_addr_by_name = self._build_label_addr_by_name(ir)
 
         lines: list[str] = []
         lines.extend(self.disassembly_start())
@@ -859,6 +892,34 @@ class AssemblerRenderer(TextRenderer):
                 name_to_addr.setdefault(name, addr)
         return name_to_addr.get
 
+    def _build_label_addr_by_name(self, ir) -> dict[str, int]:
+        """Map each explicit label name to its runtime address (first
+        registration wins), for :meth:`_note_symbol_use`."""
+        addr_by_name: dict[str, int] = {}
+        for runtime_addr_obj, label in ir.labels.items():
+            for name in label.explicit_names_in_insertion_order():
+                addr_by_name.setdefault(name, int(runtime_addr_obj))
+        return addr_by_name
+
+    def _note_symbol_use(self, ir, name: str) -> None:
+        """Record that an emitted expression names the label ``name``.
+
+        An expression can refer to a label by *name* (a ``Sym`` — e.g.
+        the ``fscv+1`` alias the ``acorn_mos`` environment registers for
+        ``&021F``, or a driver's ``d.expr(addr, "ptr+1")``) rather than by
+        address. That is still a use of the label: an optional label
+        outside the loaded range must then get its ``name = &xxxx``
+        definition, exactly as an operand that resolves to it by address
+        does (#47). A name dasmos doesn't know is left to the driver.
+        """
+        addr = self._label_addr_by_name.get(name)
+        if addr is None:
+            return
+        if not self._label_address_is_in_range(ir, addr):
+            self._used_external_labels.add(addr)
+        if self._operand_label_refs is not None:
+            self._operand_label_refs.add(addr)
+
     def _build_explicit_label_table(self, ir) -> list[str]:
         """Return ``name = &xxxx`` definition lines for out-of-range
         labels:
@@ -1488,15 +1549,210 @@ class AssemblerRenderer(TextRenderer):
         self, ir, binary_addr, opcode: Opcode, *, active_move=None,
     ) -> str:
         """Format a single instruction line."""
+        if self._needs_forced_absolute(ir, binary_addr, opcode):
+            return self._render_pinned_size(
+                ir, binary_addr, opcode, absolute=True, active_move=active_move,
+            )
         mnemonic = self._apply_case(opcode.default_mnemonic())
-        operand = self._render_operand(
-            ir, binary_addr, opcode, active_move=active_move,
+        # Collect the labels the operand names, to spot a forward
+        # reference whose size the assembler would have to guess.
+        self._operand_label_refs = set()
+        try:
+            operand = self._render_operand(
+                ir, binary_addr, opcode, active_move=active_move,
+            )
+            referenced = self._operand_label_refs
+        finally:
+            self._operand_label_refs = None
+        pin_absolute = self._forward_reference_pin(
+            ir, binary_addr, opcode, referenced, active_move=active_move,
         )
+        if pin_absolute is not None:
+            return self._render_pinned_size(
+                ir, binary_addr, opcode,
+                absolute=pin_absolute, active_move=active_move,
+            )
         char_hint = self._immediate_char_hint(ir, binary_addr, opcode)
         if operand:
             return f"    {mnemonic} {operand}{char_hint}"
         return f"    {mnemonic}"
 
+    def _cpu_has_mode(self, ir, operation, mode_name: str) -> bool:
+        """True iff the IR's CPU offers ``operation`` in the addressing
+        mode named ``mode_name``."""
+        if self._cpu_operation_modes is None:
+            self._cpu_operation_modes = frozenset(
+                (op.operation, op.addressing_mode.name)
+                for op in ir.cpu.opcodes().values()
+            )
+        return (operation, mode_name) in self._cpu_operation_modes
+
+    def _needs_forced_absolute(self, ir, binary_addr, opcode: Opcode) -> bool:
+        """True when the instruction is encoded with absolute addressing
+        but a size-optimising assembler would reassemble it to the
+        shorter zero-page form.
+
+        That happens exactly when the operand value is below ``&100``
+        *and* the mnemonic has the matching zero-page mode — the rule
+        beebasm and 64tass both apply. ``LDA abs,Y`` with a zero-page
+        operand is therefore safe (LDA has no ``zp,Y``), while
+        ``LDX abs,Y`` is not (#46).
+        """
+        zero_page_mode = _ZERO_PAGE_FORM_OF_ABSOLUTE_MODE.get(
+            opcode.addressing_mode.name,
+        )
+        if zero_page_mode is None:
+            return False
+        if ir.memory.get_u16_le(int(binary_addr) + 1) >= 0x100:
+            return False
+        return self._cpu_has_mode(ir, opcode.operation, zero_page_mode)
+
+    def _forward_reference_pin(
+        self, ir, binary_addr, opcode: Opcode, referenced, *, active_move=None,
+    ) -> bool | None:
+        """Decide whether an instruction's operand size must be pinned
+        because its operand forward-references a label (#48).
+
+        When a mnemonic has both a zero-page and an absolute form, the
+        assembler can only choose between them once it knows the
+        operand's value. For a label defined later in the listing it
+        must guess on its first pass, and a wrong guess can settle into
+        a self-consistent but wrong layout: the guessed size moves the
+        label to the matching side of ``&100``. So the size is pinned
+        when the operand names a label defined later *and* this
+        assembler's first-pass guess
+        (:meth:`forward_reference_assumes_zero_page`) disagrees with
+        the encoded size. Where the guess already matches, the
+        instruction renders normally.
+
+        Returns ``True`` to pin the absolute form, ``False`` to pin the
+        zero-page form, or ``None`` when no pinning is needed.
+        """
+        mode_name = opcode.addressing_mode.name
+        if mode_name in _ZERO_PAGE_FORM_OF_ABSOLUTE_MODE:
+            encoded_zero_page = False
+            alternative = _ZERO_PAGE_FORM_OF_ABSOLUTE_MODE[mode_name]
+        elif mode_name in _ABSOLUTE_FORM_OF_ZERO_PAGE_MODE:
+            encoded_zero_page = True
+            alternative = _ABSOLUTE_FORM_OF_ZERO_PAGE_MODE[mode_name]
+        else:
+            return None
+        if not self._cpu_has_mode(ir, opcode.operation, alternative):
+            return None
+        if not any(self._label_defined_later(ir, addr) for addr in referenced):
+            return None
+        if active_move is not None:
+            pc = int(active_move.dest_runtime_addr) + (
+                int(binary_addr) - int(active_move.src_binary_addr)
+            )
+        else:
+            pc = int(ir.moves.b2r(BinaryAddr(int(binary_addr))))
+        if self.forward_reference_assumes_zero_page(pc) == encoded_zero_page:
+            return None
+        return not encoded_zero_page
+
+    def _label_defined_later(self, ir, runtime_addr: int) -> bool:
+        """True iff the label at ``runtime_addr`` is defined further on
+        in the listing than the line being rendered.
+
+        Labels outside the loaded range are equates at the top of the
+        listing, and in-range labels with no inline anchor go into the
+        same table, so only an inline anchor (or an inline
+        ``name = base+offset``) not yet emitted is still to come.
+        """
+        if runtime_addr in self._inline_emitted_runtime_addrs:
+            return False
+        if not self._label_address_is_in_range(ir, runtime_addr):
+            return False
+        return (
+            self._label_address_is_classification_start(ir, runtime_addr)
+            or self._label_has_inline_offset_base(ir, runtime_addr)
+        )
+
+    def forward_reference_assumes_zero_page(self, pc: int) -> bool:
+        """Whether this assembler's first pass assumes zero-page
+        addressing for an instruction at ``pc`` whose operand is a
+        not-yet-defined symbol.
+
+        Default ``False``: an undefined symbol is assumed to be 16-bit,
+        so the absolute form is chosen (64tass's behaviour). Backends
+        whose assembler guesses otherwise override this; beebasm
+        substitutes the instruction's own address, so it guesses zero
+        page exactly when ``pc`` is below ``&100``.
+        """
+        return False
+
+    def _render_pinned_size(
+        self, ir, binary_addr, opcode: Opcode, *, absolute: bool,
+        active_move=None,
+    ) -> str:
+        """Render an instruction so it reassembles to its encoded size —
+        absolute (three bytes) or zero page (two bytes) — whatever the
+        assembler would otherwise choose.
+
+        The backend's :meth:`force_abs_instruction` /
+        :meth:`force_zp_instruction` supply its operand-size syntax
+        where it has one (64tass ``@w`` / ``@b``). Otherwise the
+        instruction is emitted as data via
+        :meth:`forced_absolute_as_data` /
+        :meth:`forced_zero_page_as_data`, with the instruction kept
+        readable in a trailing comment.
+        """
+        mnemonic = self._apply_case(opcode.default_mnemonic())
+        symbol = self._resolve_operand_symbol(
+            ir, binary_addr, opcode, int(binary_addr) + 1,
+            active_move=active_move,
+        )
+        mode_name = opcode.addressing_mode.name
+        if mode_name.endswith("_X"):
+            suffix = f",{self._apply_case('X')}"
+        elif mode_name.endswith("_Y"):
+            suffix = f",{self._apply_case('Y')}"
+        else:
+            suffix = ""
+        if absolute:
+            forced = self.force_abs_instruction(mnemonic, "", symbol, suffix)
+        else:
+            forced = self.force_zp_instruction(mnemonic, "", symbol, suffix)
+        if forced is not None:
+            return f"    {forced}"
+        opcode_byte = ir.memory.get_u8(binary_addr)
+        if absolute:
+            data = self.forced_absolute_as_data(opcode_byte, symbol)
+            size = "absolute"
+        else:
+            data = self.forced_zero_page_as_data(opcode_byte, symbol)
+            size = "zero page"
+        return (
+            f"    {data} {self.comment_prefix()} "
+            f"{mnemonic} {symbol}{suffix} ({size})"
+        )
+
+    def forced_absolute_as_data(self, opcode_byte: int, operand: str) -> str:
+        """An absolute-mode instruction spelled as data: its opcode byte
+        then its 16-bit operand, as one source line.
+
+        Used when the assembler has no syntax to force absolute
+        addressing (:meth:`force_abs_instruction` returned ``None``).
+        The default joins a byte and a word directive with ``:``, the
+        statement separator beebasm (the backend that needs this)
+        accepts. Override for an assembler that separates statements
+        differently.
+        """
+        return (
+            f"{self.byte_prefix()}{self.hex2(opcode_byte)} : "
+            f"{self.word_prefix()}{operand}"
+        )
+
+    def forced_zero_page_as_data(self, opcode_byte: int, operand: str) -> str:
+        """A zero-page instruction spelled as data: its opcode byte then
+        its 8-bit operand, as one byte directive.
+
+        Used when the assembler has no syntax to force zero-page
+        addressing (:meth:`force_zp_instruction` returned ``None``).
+        """
+        return f"{self.byte_prefix()}{self.hex2(opcode_byte)}, {operand}"
+
     def _apply_case(self, text: str) -> str:
         """Apply the renderer's ``lower_case`` setting to ``text``.
 
@@ -1834,6 +2090,8 @@ class AssemblerRenderer(TextRenderer):
             if names:
                 if not self._label_address_is_in_range(ir, addr):
                     self._used_external_labels.add(addr)
+                if self._operand_label_refs is not None:
+                    self._operand_label_refs.add(addr)
                 return names[0]
             # No explicit name — fall back to an expression. Drivers
             # use ``d.expr_label(addr, "<base>-1")`` to register a
@@ -2190,6 +2448,7 @@ class AssemblerRenderer(TextRenderer):
         if isinstance(e, Int):
             return self._render_int_node(e), self._ATOM_PRECEDENCE
         if isinstance(e, Sym):
+            self._note_symbol_use(ir, e.name)
             return e.name, self._ATOM_PRECEDENCE
         if isinstance(e, Ref):
             return (

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos/ext/renderers/beebasm/renderer.py

@@ -412,6 +412,12 @@ class BeebasmRenderer(AssemblerRenderer):
     def render_string_length(self, s: str) -> str:
         return f"LEN({s})"
 
+    def forward_reference_assumes_zero_page(self, pc: int) -> bool:
+        # On its first pass beebasm substitutes the current PC for an
+        # undefined symbol (assemble.cpp), so it guesses zero page
+        # exactly when the instruction itself sits below &100.
+        return pc < 0x100
+
     def included_binary_directive(self, path: str) -> list[str]:
         # beebasm includes an external file verbatim at assembly time
         # with ``incbin "<path>"``; the file must sit next to the

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos/ext/renderers/tass64/renderer.py

@@ -202,6 +202,20 @@ class Tass64Renderer(AssemblerRenderer):
             return chr(n)
         return None
 
+    def force_abs_instruction(
+        self, instruction: str, prefix: str, operand: str, suffix: str,
+    ) -> str | None:
+        # 64tass's ``@w`` operand-size prefix forces the 16-bit
+        # (absolute) encoding even when the value fits in zero page.
+        return f"{instruction} {prefix}@w {operand}{suffix}"
+
+    def force_zp_instruction(
+        self, instruction: str, prefix: str, operand: str, suffix: str,
+    ) -> str | None:
+        # ``@b`` forces the 8-bit (zero-page) encoding, so a forward
+        # reference can't settle on the absolute form (#48).
+        return f"{instruction} {prefix}@b {operand}{suffix}"
+
     def included_binary_directive(self, path: str) -> list[str]:
         # 64tass includes an external file with ``.binary "<path>"``
         # (raw bytes, no header). The file must sit next to the listing

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos/renderer.py

@@ -235,11 +235,34 @@ class TextRenderer(Renderer[TextOutput]):
     def force_zp_instruction(
         self, instruction: str, prefix: str, operand: str, suffix: str,
     ) -> str | None:
+        """Instruction text that forces zero-page (8-bit) addressing, or
+        ``None`` when the assembler has no syntax for it.
+
+        Called for a zero-page instruction whose operand names a label
+        defined later in the listing, when the assembler's first pass
+        would otherwise guess the absolute form (see
+        ``AssemblerRenderer.forward_reference_assumes_zero_page``).
+        Arguments as for :meth:`force_abs_instruction`. 64tass returns
+        ``lda @b name``; the default ``None`` makes the renderer emit
+        the instruction as data instead.
+        """
         return None
 
     def force_abs_instruction(
         self, instruction: str, prefix: str, operand: str, suffix: str,
     ) -> str | None:
+        """Instruction text that forces absolute (16-bit) addressing, or
+        ``None`` when the assembler has no syntax for it.
+
+        Called for an instruction encoded with absolute addressing whose
+        operand is below ``&100`` and whose mnemonic also has a
+        zero-page form — the case a size-optimising assembler would
+        otherwise shrink to two bytes. ``instruction`` is the mnemonic,
+        ``operand`` the resolved symbol, ``prefix`` / ``suffix`` the
+        surrounding mode punctuation (``""`` / ``",x"`` / ``",y"``).
+        64tass returns ``sta @w name``; the default ``None`` makes the
+        renderer emit the instruction as data instead.
+        """
         return None
 
     def force_zp_label_prefix(self) -> str:

{dasmos-4.2.0 → dasmos-4.2.1/src/dasmos.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dasmos
-Version: 4.2.0
+Version: 4.2.1
 Summary: Extensible tracing disassembler for classic CPUs, with CPU, renderer and environment extension points.
 Author-email: Robert Smallshire <rob@sixty-north.com>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
   <img src="https://raw.githubusercontent.com/acornaeology/dasmos/master/docs/_static/dasmos-banner.svg" alt="Dasmos — an extensible tracing disassembler for classic CPUs">
 </p>
 
-An extensible tracing disassembler for classic CPUs, version `4.2.0`.
+An extensible tracing disassembler for classic CPUs, version `4.2.1`.
 
 <p align="center">
   <a href="https://pypi.org/project/dasmos/"><img src="https://img.shields.io/pypi/v/dasmos.svg" alt="PyPI"></a>

{dasmos-4.2.0 → dasmos-4.2.1}/src/dasmos.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ src/dasmos/ext/renderers/json/__init__.py
 src/dasmos/ext/renderers/json/renderer.py
 src/dasmos/ext/renderers/tass64/__init__.py
 src/dasmos/ext/renderers/tass64/renderer.py
+tests/test_absolute_operands.py
 tests/test_adfs_roundtrip.py
 tests/test_anfs_418_roundtrip.py
 tests/test_anfs_421_roundtrip.py
@@ -86,7 +87,9 @@ tests/test_environment.py
 tests/test_expr.py
 tests/test_expr_operators.py
 tests/test_expr_parse.py
+tests/test_expression_symbols.py
 tests/test_file_header.py
+tests/test_forward_operand_size.py
 tests/test_golden_asm.py
 tests/test_golden_json.py
 tests/test_include_binary.py