angr 9.2.192__cp311-cp311-macosx_10_12_x86_64.whl

angr/utils/ssa/__init__.py

@@ -0,0 +1,455 @@
+from __future__ import annotations
+from typing import Any, Literal, overload
+from collections import defaultdict
+from collections.abc import Callable, Iterable
+
+import networkx
+
+import archinfo
+from angr.ailment import Expression, Block, UnaryOp, Address
+from angr.ailment.expression import (
+    VirtualVariable,
+    Const,
+    Phi,
+    Tmp,
+    Load,
+    Register,
+    StackBaseOffset,
+    DirtyExpression,
+    ITE,
+)
+from angr.ailment.statement import Statement, Assignment, Call, Store, CAS
+from angr.ailment.block_walker import AILBlockViewer
+
+from angr.knowledge_plugins.key_definitions import atoms
+from angr.code_location import AILCodeLocation
+from .vvar_uses_collector import VVarUsesCollector
+from .tmp_uses_collector import TmpUsesCollector
+
+
+DEPHI_VVAR_REG_OFFSET = 4096
+
+
+@overload
+def get_reg_offset_base_and_size(
+    reg_offset: int, arch: archinfo.Arch, size: int | None = None, resilient: Literal[True] = True
+) -> tuple[int, int]: ...
+@overload
+def get_reg_offset_base_and_size(
+    reg_offset: int, arch: archinfo.Arch, size: int | None = None, resilient: Literal[False] = False
+) -> tuple[int, int] | None: ...
+
+
+def get_reg_offset_base_and_size(
+    reg_offset: int, arch: archinfo.Arch, size: int | None = None, resilient: bool = True
+) -> tuple[int, int | None] | None:
+    """
+    Translate a given register offset into the offset of its full register and obtain the size of the full register.
+
+    :param reg_offset:  The offset of the register to translate.
+    :param arch:        The corresponding Arch object.
+    :param size:        Size of the register to translate. Optional.
+    :param resilient:   When set to True, this function will return the provided offset and size for registers that the
+                        arch does not know about.
+    :return:            A tuple of translated offset and the size of the full register.
+    """
+
+    base_reg_and_size = arch.get_base_register(reg_offset, size=size)
+    if resilient and base_reg_and_size is None:
+        base_reg_and_size = arch.get_base_register(reg_offset, size=None)
+        if base_reg_and_size is None:
+            # give up
+            return reg_offset, size
+    return base_reg_and_size
+
+
+@overload
+def get_reg_offset_base(
+    reg_offset: int, arch: archinfo.Arch, size: int | None = None, resilient: Literal[True] = True
+) -> int: ...
+@overload
+def get_reg_offset_base(
+    reg_offset: int, arch: archinfo.Arch, size: int | None = None, resilient: Literal[False] = False
+) -> int | None: ...
+
+
+def get_reg_offset_base(reg_offset, arch, size=None, resilient=True):
+    """
+    Translate a given register offset into the offset of its full register.
+
+    :param reg_offset:  The offset of the register to translate.
+    :param arch:        The corresponding Arch object.
+    :param size:        Size of the register to translate. Optional.
+    :param resilient:   When set to True, this function will return the provided offset and size for registers that the
+                        arch does not know about.
+    :return:            The translated offset of the full register.
+    """
+
+    base_reg_and_size = arch.get_base_register(reg_offset, size=size)
+    if base_reg_and_size is None:
+        return reg_offset if resilient else None
+    return base_reg_and_size[0]
+
+
+def get_vvar_deflocs(
+    blocks, phi_vvars: dict[int, set[int | None]] | None = None
+) -> dict[int, tuple[VirtualVariable, AILCodeLocation]]:
+    vvar_to_loc: dict[int, tuple[VirtualVariable, AILCodeLocation]] = {}
+    for block in blocks:
+        for stmt_idx, stmt in enumerate(block.statements):
+            if isinstance(stmt, Assignment) and isinstance(stmt.dst, VirtualVariable):
+                vvar_to_loc[stmt.dst.varid] = stmt.dst, AILCodeLocation(
+                    block.addr, block.idx, stmt_idx, stmt.tags.get("ins_addr")
+                )
+                if phi_vvars is not None and isinstance(stmt.src, Phi):
+                    phi_vvars[stmt.dst.varid] = {
+                        vvar_.varid if vvar_ is not None else None for src, vvar_ in stmt.src.src_and_vvars
+                    }
+            elif isinstance(stmt, Call):
+                if isinstance(stmt.ret_expr, VirtualVariable):
+                    vvar_to_loc[stmt.ret_expr.varid] = stmt.ret_expr, AILCodeLocation(
+                        block.addr, block.idx, stmt_idx, stmt.tags.get("ins_addr")
+                    )
+                if isinstance(stmt.fp_ret_expr, VirtualVariable):
+                    vvar_to_loc[stmt.fp_ret_expr.varid] = stmt.fp_ret_expr, AILCodeLocation(
+                        block.addr, block.idx, stmt_idx, stmt.tags.get("ins_addr")
+                    )
+
+    return vvar_to_loc
+
+
+def get_vvar_uselocs(blocks) -> dict[int, list[tuple[VirtualVariable, AILCodeLocation]]]:
+    vvar_to_loc: dict[int, list[tuple[VirtualVariable, AILCodeLocation]]] = defaultdict(list)
+    for block in blocks:
+        collector = VVarUsesCollector()
+        collector.walk(block)
+        for vvar_idx, vvar_and_uselocs in collector.vvar_and_uselocs.items():
+            if vvar_idx not in vvar_to_loc:
+                vvar_to_loc[vvar_idx] = list(vvar_and_uselocs)
+            else:
+                vvar_to_loc[vvar_idx] += vvar_and_uselocs
+    return vvar_to_loc
+
+
+def get_tmp_deflocs(blocks: Iterable[Block]) -> dict[Address, dict[atoms.Tmp, int]]:
+    tmp_to_loc: dict[Address, dict[atoms.Tmp, int]] = defaultdict(dict)
+
+    for block in blocks:
+        codeloc = (block.addr, block.idx)
+        for stmt_idx, stmt in enumerate(block.statements):
+            if isinstance(stmt, Assignment) and isinstance(stmt.dst, Tmp):
+                tmp_to_loc[codeloc][atoms.Tmp(stmt.dst.tmp_idx, stmt.dst.bits)] = stmt_idx
+            if isinstance(stmt, CAS):
+                if isinstance(stmt.old_lo, Tmp):
+                    tmp_to_loc[codeloc][atoms.Tmp(stmt.old_lo.tmp_idx, stmt.old_lo.bits)] = stmt_idx
+                if stmt.old_hi is not None and isinstance(stmt.old_hi, Tmp):
+                    tmp_to_loc[codeloc][atoms.Tmp(stmt.old_hi.tmp_idx, stmt.old_hi.bits)] = stmt_idx
+
+    return tmp_to_loc
+
+
+def get_tmp_uselocs(blocks: Iterable[Block]) -> dict[Address, dict[atoms.Tmp, set[tuple[Tmp, int]]]]:
+    tmp_to_loc: dict[Address, dict[atoms.Tmp, set[tuple[Tmp, int]]]] = defaultdict(dict)
+
+    for block in blocks:
+        collector = TmpUsesCollector()
+        collector.walk(block)
+        block_loc = (block.addr, block.idx)
+        for (tmp_idx, tmp_bits), tmp_and_stmtids in collector.tmp_and_uselocs.items():
+            if tmp_idx not in tmp_to_loc[block_loc]:
+                tmp_to_loc[block_loc][atoms.Tmp(tmp_idx, tmp_bits)] = tmp_and_stmtids
+            else:
+                tmp_to_loc[block_loc][atoms.Tmp(tmp_idx, tmp_bits)] |= tmp_and_stmtids
+
+    return tmp_to_loc
+
+
+def is_const_assignment(stmt: Statement) -> tuple[bool, Const | StackBaseOffset | None]:
+    if isinstance(stmt, Assignment) and isinstance(stmt.src, (Const, StackBaseOffset)):
+        return True, stmt.src
+    return False, None
+
+
+class AILBlacklistExprTypeWalker(AILBlockViewer):
+    """
+    Walks an AIL expression or statement and determines if it does not contain certain types of expressions.
+    """
+
+    def __init__(self, blacklist_expr_types: tuple[type, ...], skip_if_contains_vvar: int | None = None):
+        super().__init__()
+        self.blacklist_expr_types = blacklist_expr_types
+        self.has_blacklisted_exprs = False
+        self.skip_if_contains_vvar = skip_if_contains_vvar
+
+        self._has_specified_vvar = False
+
+    def _handle_expr(
+        self, expr_idx: int, expr: Expression, stmt_idx: int, stmt: Statement | None, block: Block | None
+    ) -> Any:
+        if isinstance(expr, self.blacklist_expr_types):
+            if self.skip_if_contains_vvar is None:
+                self.has_blacklisted_exprs = True
+                return None
+            # otherwise we do a more complicated check
+            self._has_specified_vvar = False  # we do not support nested blacklisted expr types
+            has_blacklisted_exprs = True
+            r = super()._handle_expr(expr_idx, expr, stmt_idx, stmt, block)
+            if self._has_specified_vvar is False:
+                # we have seen the vvar that we are looking for! ignore this match
+                self.has_blacklisted_exprs = has_blacklisted_exprs
+                return None
+            self._has_specified_vvar = False
+            return r
+
+        return super()._handle_expr(expr_idx, expr, stmt_idx, stmt, block)
+
+    def _handle_VirtualVariable(
+        self, expr_idx: int, expr: VirtualVariable, stmt_idx: int, stmt: Statement | None, block: Block | None
+    ):
+        if self.skip_if_contains_vvar is not None and expr.varid == self.skip_if_contains_vvar:
+            self._has_specified_vvar = True
+        return super()._handle_VirtualVariable(expr_idx, expr, stmt_idx, stmt, block)
+
+
+def is_const_and_vvar_assignment(stmt: Statement) -> bool:
+    if isinstance(stmt, Assignment):
+        walker = AILBlacklistExprTypeWalker((Tmp, Load, Register, Phi, Call, DirtyExpression))
+        walker.walk_expression(stmt.src)
+        return not walker.has_blacklisted_exprs
+    return False
+
+
+def is_const_vvar_tmp_assignment(stmt: Statement) -> bool:
+    if isinstance(stmt, Assignment):
+        walker = AILBlacklistExprTypeWalker((Load, Register, Phi, Call, DirtyExpression))
+        walker.walk_expression(stmt.src)
+        return not walker.has_blacklisted_exprs
+    return False
+
+
+def is_const_vvar_load_assignment(stmt: Statement) -> bool:
+    if isinstance(stmt, Assignment):
+        walker = AILBlacklistExprTypeWalker((Tmp, Register, Phi, Call, DirtyExpression))
+        walker.walk_expression(stmt.src)
+        return not walker.has_blacklisted_exprs
+    return False
+
+
+def is_const_vvar_load_dirty_assignment(stmt: Statement) -> bool:
+    if isinstance(stmt, Assignment):
+        walker = AILBlacklistExprTypeWalker((Tmp, Register, Phi, Call))
+        walker.walk_expression(stmt.src)
+        return not walker.has_blacklisted_exprs
+    return False
+
+
+def is_phi_assignment(stmt: Statement) -> bool:
+    return isinstance(stmt, Assignment) and isinstance(stmt.src, Phi)
+
+
+def has_load_expr(stmt: Statement, skip_if_contains_vvar: int | None = None) -> bool:
+    walker = AILBlacklistExprTypeWalker((Load,), skip_if_contains_vvar=skip_if_contains_vvar)
+    walker.walk_statement(stmt)
+    return walker.has_blacklisted_exprs
+
+
+def phi_assignment_get_src(stmt: Statement) -> Phi | None:
+    if isinstance(stmt, Assignment) and isinstance(stmt.src, Phi):
+        return stmt.src
+    return None
+
+
+def is_dephi_vvar(vvar: VirtualVariable) -> bool:
+    return vvar.varid == DEPHI_VVAR_REG_OFFSET
+
+
+def has_ite_expr(expr: Expression) -> bool:
+    walker = AILBlacklistExprTypeWalker((ITE,))
+    walker.walk_expression(expr)
+    return walker.has_blacklisted_exprs
+
+
+def has_ite_stmt(stmt: Statement) -> bool:
+    walker = AILBlacklistExprTypeWalker((ITE,))
+    walker.walk_statement(stmt)
+    return walker.has_blacklisted_exprs
+
+
+def has_tmp_expr(expr: Expression) -> bool:
+    walker = AILBlacklistExprTypeWalker((Tmp,))
+    walker.walk_expression(expr)
+    return walker.has_blacklisted_exprs
+
+
+class AILReferenceFinder(AILBlockViewer):
+    """
+    Walks an AIL expression or statement and finds if it contains references to certain expressions.
+    """
+
+    def __init__(self, vvar_id: int):
+        super().__init__()
+        self.vvar_id = vvar_id
+        self.has_references_to_vvar = False
+
+    def _handle_UnaryOp(
+        self, expr_idx: int, expr: UnaryOp, stmt_idx: int, stmt: Statement | None, block: Block | None
+    ) -> Any:
+        if expr.op == "Reference" and isinstance(expr.operand, VirtualVariable) and expr.operand.varid == self.vvar_id:
+            self.has_references_to_vvar = True
+            return None
+        return super()._handle_UnaryOp(expr_idx, expr, stmt_idx, stmt, block)
+
+
+def has_reference_to_vvar(stmt: Statement, vvar_id: int) -> bool:
+    walker = AILReferenceFinder(vvar_id)
+    walker.walk_statement(stmt)
+    return walker.has_references_to_vvar
+
+
+def check_in_between_stmts(
+    graph: networkx.DiGraph,
+    blocks: dict[tuple[int, int | None], Block],
+    defloc: AILCodeLocation,
+    useloc: AILCodeLocation,
+    predicate: Callable,
+):
+    use_block = blocks[(useloc.addr, useloc.block_idx)]
+    def_block = blocks[(defloc.addr, defloc.block_idx)]
+
+    # traverse the graph, go from use_block until we reach def_block, and look for Store statements
+    seen = {use_block}
+    queue = [use_block]
+    while queue:
+        block = queue.pop(0)
+
+        starting_stmt_idx, ending_stmt_idx = 0, len(block.statements)
+        if block is def_block:
+            starting_stmt_idx = defloc.stmt_idx + 1
+        if block is use_block:
+            ending_stmt_idx = useloc.stmt_idx
+
+        for i in range(starting_stmt_idx, ending_stmt_idx):
+            if predicate(block.statements[i]):
+                return True
+
+        if block is def_block:
+            continue
+
+        for pred in graph.predecessors(block):
+            if pred not in seen:
+                seen.add(pred)
+                queue.append(pred)
+
+    return False
+
+
+def has_store_stmt_in_between_stmts(
+    graph: networkx.DiGraph,
+    blocks: dict[tuple[int, int | None], Block],
+    defloc: AILCodeLocation,
+    useloc: AILCodeLocation,
+) -> bool:
+    return check_in_between_stmts(graph, blocks, defloc, useloc, lambda stmt: isinstance(stmt, Store))
+
+
+def has_call_in_between_stmts(
+    graph: networkx.DiGraph,
+    blocks: dict[tuple[int, int | None], Block],
+    defloc: AILCodeLocation,
+    useloc: AILCodeLocation,
+    skip_if_contains_vvar: int | None = None,
+) -> bool:
+
+    def _contains_call(stmt: Statement) -> bool:
+        if isinstance(stmt, Call):
+            return True
+        # walk the statement and check if there is a call expression
+        walker = AILBlacklistExprTypeWalker((Call,), skip_if_contains_vvar=skip_if_contains_vvar)
+        walker.walk_statement(stmt)
+        return walker.has_blacklisted_exprs
+
+    return check_in_between_stmts(graph, blocks, defloc, useloc, _contains_call)
+
+
+def has_load_expr_in_between_stmts(
+    graph: networkx.DiGraph,
+    blocks: dict[tuple[int, int | None], Block],
+    defloc: AILCodeLocation,
+    useloc: AILCodeLocation,
+    skip_if_contains_vvar: int | None = None,
+) -> bool:
+    return check_in_between_stmts(
+        graph, blocks, defloc, useloc, lambda stmt: has_load_expr(stmt, skip_if_contains_vvar=skip_if_contains_vvar)
+    )
+
+
+def is_vvar_propagatable(vvar: VirtualVariable, def_stmt: Statement | None) -> bool:
+    if vvar.was_tmp or vvar.was_reg or vvar.was_parameter:
+        return True
+    if vvar.was_stack and isinstance(def_stmt, Assignment):  # noqa:SIM102
+        if (
+            isinstance(def_stmt.src, VirtualVariable)
+            and def_stmt.src.was_stack
+            and def_stmt.src.stack_offset == vvar.stack_offset
+        ):
+            # special case: the following block
+            #   ## Block 401e98
+            #   00 | 0x401e98 | LABEL_401e98:
+            #   01 | 0x401e98 | vvar_227{stack -12} = 𝜙@32b [((4202088, None), vvar_277{stack -12}), ((4202076, None),
+            #                   vvar_278{stack -12})]
+            #   02 | 0x401ea0 | return Conv(32->64, vvar_227{stack -12});
+            # might be simplified to the following block after return duplication
+            #   ## Block 401e98.1
+            #   00 | 0x401e98 | LABEL_401e98__1:
+            #   01 | 0x401e98 | vvar_279{stack -12} = vvar_277{stack -12}
+            #   02 | 0x401ea0 | return Conv(32->64, vvar_279{stack -12});
+            # in this case, vvar_279 is eliminatable.
+            return True
+    return False
+
+
+def is_vvar_eliminatable(vvar: VirtualVariable, def_stmt: Statement | None) -> bool:
+    if vvar.was_tmp or vvar.was_reg or vvar.was_parameter:
+        return True
+    if (  # noqa: SIM103
+        vvar.was_stack
+        and isinstance(def_stmt, Assignment)
+        and isinstance(def_stmt.src, VirtualVariable)
+        and def_stmt.src.was_stack
+        and def_stmt.src.stack_offset == vvar.stack_offset
+    ):
+        # special case: the following block
+        #   ## Block 401e98
+        #   00 | 0x401e98 | LABEL_401e98:
+        #   01 | 0x401e98 | vvar_227{stack -12} = 𝜙@32b [((4202088, None), vvar_277{stack -12}), ((4202076, None),
+        #                   vvar_278{stack -12})]
+        #   02 | 0x401ea0 | return Conv(32->64, vvar_227{stack -12});
+        # might be simplified to the following block after return duplication
+        #   ## Block 401e98.1
+        #   00 | 0x401e98 | LABEL_401e98__1:
+        #   01 | 0x401e98 | vvar_279{stack -12} = vvar_277{stack -12}
+        #   02 | 0x401ea0 | return Conv(32->64, vvar_279{stack -12});
+        # in this case, vvar_279 is eliminatable.
+        return True
+    return False
+
+
+__all__ = (
+    "VVarUsesCollector",
+    "check_in_between_stmts",
+    "get_tmp_deflocs",
+    "get_tmp_uselocs",
+    "get_vvar_deflocs",
+    "get_vvar_uselocs",
+    "has_call_in_between_stmts",
+    "has_ite_expr",
+    "has_load_expr_in_between_stmts",
+    "has_store_stmt_in_between_stmts",
+    "is_const_and_vvar_assignment",
+    "is_const_assignment",
+    "is_const_vvar_load_assignment",
+    "is_const_vvar_load_dirty_assignment",
+    "is_phi_assignment",
+    "is_vvar_eliminatable",
+    "phi_assignment_get_src",
+)

angr/utils/ssa/tmp_uses_collector.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from collections import defaultdict
+
+from angr.ailment import AILBlockViewer
+from angr.ailment.expression import Tmp
+from angr.ailment.statement import Statement, Assignment
+from angr.ailment.block import Block
+
+
+class TmpUsesCollector(AILBlockViewer):
+    """
+    Collect all uses of temporary variables and their use statement IDs in an AIL block.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+        self.tmp_and_uselocs: dict[tuple[int, int], set[tuple[Tmp, int]]] = defaultdict(set)
+
+    def _handle_Tmp(self, expr_idx: int, expr: Tmp, stmt_idx: int, stmt: Statement, block: Block | None):
+        if isinstance(stmt, Assignment) and expr is stmt.dst:
+            return
+        self.tmp_and_uselocs[(expr.tmp_idx, expr.bits)].add((expr, stmt_idx))

angr/utils/ssa/vvar_uses_collector.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from collections import defaultdict
+
+from angr.ailment import AILBlockViewer
+from angr.ailment.expression import VirtualVariable, Phi
+from angr.ailment.statement import Statement, Assignment
+from angr.ailment.block import Block
+from angr.code_location import AILCodeLocation
+
+
+class VVarUsesCollector(AILBlockViewer):
+    """
+    Collect all uses of virtual variables and their use locations in an AIL block. Skip collecting use locations if
+    block is not specified.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+        self.vvar_and_uselocs: dict[int, list[tuple[VirtualVariable, AILCodeLocation]]] = defaultdict(list)
+        self.vvars: set[int] = set()
+
+    def _handle_VirtualVariable(
+        self, expr_idx: int, expr: VirtualVariable, stmt_idx: int, stmt: Statement | None, block: Block | None
+    ):
+        if isinstance(stmt, Assignment):
+            if expr is stmt.dst:
+                return
+            if isinstance(stmt.dst, VirtualVariable) and isinstance(stmt.src, Phi) and expr.varid == stmt.dst.varid:
+                # avoid phi loops
+                return
+        if block is not None and stmt is not None:
+            self.vvar_and_uselocs[expr.varid].append(
+                (expr, AILCodeLocation(block.addr, block.idx, stmt_idx, stmt.tags.get("ins_addr")))
+            )
+        self.vvars.add(expr.varid)

angr/utils/strings.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+
+def decode_utf16_string(data: bytes) -> str:
+    """
+    Decode a UTF-16 encoded string from a bytes object in a resilient manner.
+
+    :param data: The bytes object containing the UTF-16 encoded string.
+    :param errors: The error handling scheme. Default is 'strict'.
+                   Other options include 'ignore', 'replace', etc.
+    :return: The decoded string.
+    """
+    if len(data) % 2 == 1:
+        data = data[:-1]  # Trim off the last byte if the length is odd
+
+    # If no BOM, try to decode as little-endian first
+    try:
+        return data.decode("utf-16-le")
+    except UnicodeDecodeError:
+        return "<utf16-decode-error>"

angr/utils/tagged_interval_map.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+from collections.abc import Iterator
+
+from sortedcontainers import SortedDict
+
+
+class TaggedIntervalMap:
+    """
+    Catalogs features of intervals.
+    """
+
+    def __init__(self, nbits: int = 0):
+        """
+        :param nbits: Number of binning bits. Higher values reduce detail. 0 for no binning.
+        """
+        self._nbits: int = nbits
+        self._map: SortedDict = SortedDict()  # SortedDict[int, int]
+
+    @property
+    def nbits(self) -> int:
+        return self._nbits
+
+    def add(self, addr: int, size: int, tags: int) -> None:
+        """
+        Add interval starting at `addr` of `size` bytes.
+
+        When binning, intervals endpoints are aligned to 2^nbits. Gaps between added intervals are populated with
+        implicit intervals having tag value of 0. Overlapping intervals will have tag bits OR'd together.
+
+        Adjacent intervals in the interval map have unique tags. When intervals are added to the map, any adjacent stops
+        with identical tags will be eliminated so the map retains this property.
+
+        For example: if an interval(addr=0, size=100, tags=1) is added, followed by (100, 100, 1), the resulting
+        interval in the map will be (0, 200, 1).
+        """
+        assert addr >= 0
+        assert size >= 0
+        assert tags != 0
+
+        if size == 0:
+            return
+
+        max_bin_offset = (1 << self._nbits) - 1
+        mask = ~max_bin_offset
+
+        start_addr = addr & mask  # Round down to bin alignment
+        end_addr = (addr + size + max_bin_offset) & mask  # Round up to bin alignment
+
+        if self._is_already_covered(start_addr, end_addr, tags):
+            return
+
+        self._insert_stop(start_addr)
+        self._insert_stop(end_addr)
+        for affected_addr in self._map.irange(start_addr, end_addr, inclusive=(True, False)):
+            self._map[affected_addr] |= tags
+        self._eliminate_extraneous_stops(start_addr, end_addr)
+
+    def _insert_stop(self, addr: int) -> None:
+        """
+        Insert a new interval stop point at `addr`, if one is not already present in the map. Tags are copied from
+        nearest stop before `addr`.
+        """
+        if addr not in self._map:
+            idx = self._map.bisect(addr) - 1
+            self._map[addr] = self._map.peekitem(idx)[1] if idx >= 0 else 0
+
+    def _is_already_covered(self, min_addr: int, end_addr: int, tags: int) -> bool:
+        """
+        Determine if interval [min_addr, end_addr) is covered by an existing range with identical tags.
+        """
+        idx = self._map.bisect(min_addr) - 1
+        if idx >= 0 and len(self._map) > idx + 1:
+            e_addr, e_tags = self._map.peekitem(idx)
+            e_addr_next, _ = self._map.peekitem(idx + 1)
+            return (e_addr <= min_addr) and (end_addr <= e_addr_next) and (e_tags == tags)
+        return False
+
+    def _eliminate_extraneous_stops(self, min_addr: int, max_addr: int) -> None:
+        """
+        Canonicalize the map by eliminating adjacent stops with identical tags both inside and directly outside of
+        [min_addr, max_addr].
+        """
+        keys_to_drop = []
+        prev_tags = None
+        for addr, _, tags in self.irange(min_addr, max_addr):
+            if tags == prev_tags:
+                keys_to_drop.append(addr)
+            else:
+                prev_tags = tags
+
+        for addr in keys_to_drop:
+            del self._map[addr]
+
+    def irange(self, min_addr: int | None = None, max_addr: int | None = None) -> Iterator[tuple[int, int, int]]:
+        """
+        Iterate over intervals intersecting [min_addr, max_addr], yielding interval (addr, size, tags) tuples. Implicit
+        gap intervals (with tags=0) are also returned.
+
+        :param min_addr: Minimum address (inclusive) to begin iterating from. If None, iterate from start of map.
+        :param max_addr: Maximum address (inclusive) to iterate to. If None, iterate to end of map.
+        """
+        if not self._map:
+            return
+
+        start_idx = 0 if min_addr is None else max(0, self._map.bisect_left(min_addr) - 1)
+        stop_idx = None if max_addr is None else (self._map.bisect(max_addr) + 1)
+
+        start_addr, tags = self._map.peekitem(start_idx)
+        for addr in self._map.islice(start_idx + 1, stop_idx):
+            yield (start_addr, addr - start_addr, tags)
+            tags = self._map[addr]
+            start_addr = addr