fantasm Logo

Tutorial

  • Getting started
    • What fantasm does — and doesn’t
    • Installing fantasm
    • Initialising a project
    • Adding the first version
    • Writing a disassembly driver
    • Running the pipeline
    • CI integration
  • Disassembling a disc-loaded program
    • A single-file program in an existing project
      • Verifying with another assembler
    • Starting from scratch
    • A program made of several files
      • Cross-file references
  • fantasm.toml reference
    • Discovery and project context
    • Top-level structure
      • [project]
      • [binary]
      • [versions]
    • Targets
      • [[targets]]
      • [layout]
    • [verify] — the round-trip assembler
    • The driver’s environment
    • [memory] — non-ROM addresses where code and labels can live
    • [[versions.entry]] — the version graph
      • Minimal entry
      • With reloc blocks
      • With parents
      • Free-form metadata
    • [comments.suggest] — label hints for fantasm comments suggest
    • Per-module summary
    • Example: a complete config
  • The version graph
    • Why a DAG, not a chain
    • Path-finding and walked direction
    • Reloc blocks across edges
    • Composing maps along a path
    • Common shapes
      • A linear chain
      • A fork with a branch
      • A merged version
      • A separate root
    • Discovering the structure
    • Programmatic surface
  • Workflows
    • I want to verify my disassembly is byte-correct
    • I want to validate annotation addresses
    • I want to find missing or wrong comments
    • I want to understand a subroutine’s role
    • I want to find the gaps in my annotation work
    • I want a global comment-coverage snapshot
    • I want to review my data declarations
    • I want to know what’s in this byte run
    • I want to find missing print-inline hooks
    • I want to bring annotations from a known version to a new one
    • I want to know which addresses moved between versions
    • I want to find a specific byte sequence in a ROM
    • I want to find duplicated code within a ROM
    • I want to find code shared with another ROM
    • I want to promote auto-generated labels to entry points
    • I want to extract a slice of the assembly listing
    • I want to add a new subroutine declaration to a driver
    • Checking the project / CLI

Reference

  • CLI reference
    • fantasm
      • addresses
      • annotations
      • asm
      • audit
      • backfill
      • bytes
      • cfg
      • comments
      • compare
      • context
      • coverage
      • data
      • disassemble
      • driver
      • fingerprint
      • hooks
      • info
      • labels
      • lint
      • project
      • promote
      • shared
      • sub
      • verify
  • API reference
    • Top-level package
      • InfParseError
      • InfRecord
      • inf_address()
      • parse_inf()
      • read_inf()
      • sidecar_inf_filepath()
      • TargetSpec
      • append_target()
      • TargetConfigError
      • TargetFiles
      • TargetNotFoundError
      • default_target_id()
      • list_target_ids()
      • resolve_target()
      • AssemblerConfig
      • AssemblerConfigError
      • AssemblerNotFoundError
      • AssemblerOutputMissingError
      • AsmSection
      • DotBinaryNotFoundError
      • VersionNotFoundError
      • basic_blocks_to_dot()
      • basic_blocks_to_graph()
      • basic_blocks_to_graphml()
      • build_index()
      • build_memory_regions()
      • build_target_refs()
      • call_graph_to_dot()
      • call_graph_to_graphml()
      • classify_labels()
      • collect_auto_labels()
      • collect_labels()
      • end_type()
      • extract_section()
      • filter_call_graph()
      • find_containing_sub()
      • find_containing_sub_for_addr()
      • find_line_for_target()
      • find_sub()
      • find_undeclared_subs()
      • inbound_refs_to()
      • instruction_length()
      • label_inventory()
      • load_subroutines()
      • mnemonic()
      • opcode_tables()
      • parse_address()
      • project_rom_prefixes()
      • project_versions_dirpath()
      • reference_addr()
      • reference_addrs()
      • reference_kind()
      • region_for_addr()
      • render_dot()
      • resolve_version_dirpath()
      • resolve_version_dirpath_for_project()
      • rom_prefix()
      • rom_prefix_for_project()
      • scan_routine_range()
      • sort_labels()
    • 6502 / 65C02 opcodes and mnemonics
      • opcode_tables()
      • instruction_length()
      • mnemonic()
    • Project paths and version directory layout
      • VersionNotFoundError
      • project_binary_base()
      • project_binary_dirname()
      • project_binary_extension()
      • project_binary_filename_template()
      • project_binary_metadata_filename()
      • project_binary_section()
      • project_cpu()
      • project_driver_dirname()
      • project_driver_filename_template()
      • project_rom_prefixes()
      • project_versions_dirpath()
      • render_binary_filename()
      • render_driver_filename()
      • resolve_version_dirpath()
      • resolve_version_dirpath_for_project()
      • rom_prefix()
      • rom_prefix_for_project()
      • ProjectContext
      • resolve_project_context()
    • Targets: resolving a target’s files
      • TargetConfigError
      • TargetFiles
      • TargetNotFoundError
      • default_target_id()
      • discover_target_ids()
      • list_target_ids()
      • project_layout()
      • project_target_entries()
      • render_layout_template()
      • resolve_target()
      • target_tokens()
      • target_verify_settings()
      • uses_target_config()
    • Acorn .inf sidecar files
      • InfParseError
      • InfRecord
      • inf_address()
      • parse_inf()
      • read_inf()
      • sidecar_inf_filepath()
    • Round-trip verification
      • AssemblerConfig
      • AssemblerConfigError
      • AssemblerNotFoundError
      • AssemblerOutputMissingError
      • BeebasmNotFoundError
      • VerifyResult
      • verify_round_trip()
    • Subroutine audit and memory regions
      • PlaceholderLabel
      • build_memory_regions()
      • end_type()
      • find_containing_sub()
      • find_placeholder_labels()
      • find_sub()
      • find_undeclared_subs()
      • load_subroutines()
      • region_for_addr()
      • scan_routine_range()
    • Comment-vs-code consistency checks
      • ParentVersion
      • build_known_addrs()
      • check_block_md_link_in_code_span()
      • check_block_stale_addr()
      • check_branch_phrasing()
      • check_branch_target()
      • check_byte_of_address()
      • check_chain_comments()
      • check_char_literal_operand()
      • check_code_read_as_data()
      • check_copied_comments()
      • check_cr_value()
      • check_desc_md_link_in_code_span()
      • check_desc_stale_addr()
      • check_md_link_in_code_span()
      • check_mid_item_comments()
      • check_quoted_string_address()
      • check_reg_value()
      • check_stale_addr()
      • check_tube_register()
      • find_chains()
      • find_md_links_in_code_spans()
      • find_stale_addrs()
      • parse_imm_value()
      • run_checks()
    • Comment suggestions
      • CommentSuggestion
      • suggest_comments()
      • suggest_for_instruction()
    • Lint
      • address_in_ranges()
      • address_ranges_from_data()
      • extract_annotations()
      • find_code_block_ranges()
      • find_inline_scheme_links()
      • find_nth_occurrence()
      • glossary_slugs_from_markdown()
      • load_address_ranges()
      • load_valid_addresses()
      • offset_in_code_block()
      • valid_addresses_from_data()
      • valid_label_names_from_data()
    • Call graph and basic blocks
      • BasicBlock
      • BasicBlockEntry
      • BasicBlockExit
      • build_call_graph()
      • find_basic_blocks()
      • resolve_sub_node()
    • Graphviz and GraphML rendering
      • DotBinaryNotFoundError
      • basic_blocks_to_dot()
      • basic_blocks_to_graph()
      • basic_blocks_to_graphml()
      • call_graph_to_dot()
      • call_graph_to_graphml()
      • filter_call_graph()
      • render_dot()
    • Code context (depth, sub-context, uncommented gaps)
      • CallSiteContext
      • CoverageGroup
      • CoverageReport
      • ExitPointContext
      • SubContext
      • UncommentedSubReport
      • analyse_uncommented_subs()
      • compute_call_depths()
      • compute_coverage()
      • extract_sub_context()
    • Auto-label classification and rename application
      • DIRECT_KIND
      • INDEXED_KIND
      • build_target_refs()
      • classify_labels()
      • collect_auto_labels()
      • collect_labels()
      • find_containing_sub_for_addr()
      • inbound_refs_to()
      • label_inventory()
      • sort_labels()
      • apply_renames_inline()
      • apply_renames_to_lines()
      • find_insert_position()
      • find_rename_section()
      • parse_label_decl_lines()
      • parse_label_declarations()
      • update_ref_strings()
    • Cross-reference field accessors
      • reference_addr()
      • reference_addrs()
      • reference_kind()
    • Subroutine-declaration insertion
      • AlreadyDeclared
      • InsertPoint
      • compute_insert_point()
      • find_main_block()
      • parse_subroutine_declarations()
    • Promotion candidates
      • analyze_labels()
      • load_and_analyze_labels()
    • ROM comparison
      • Instruction
      • RomHeader
      • compare_headers()
      • compare_roms()
      • disassemble_linear()
      • format_address()
      • format_instruction()
      • parse_rom_header()
    • Cross-version address mapping
      • RelocatedBlock
      • build_full_address_map()
      • build_primary_map()
      • disassemble_to_opcodes()
      • find_relocated_blocks()
    • Fingerprinting (block-level deduplication)
      • find_duplicate_blocks()
      • fingerprint_blocks()
      • fingerprint_rom_file()
      • fingerprint_window()
      • opcode_fingerprint()
    • Byte-signature search (literal + wildcard patterns)
      • BytePattern
      • ByteMatch
      • find_byte_pattern()
      • parse_byte_pattern()
    • Data-declaration review and heuristic classification
      • Classification
      • CodeClassification
      • DataRun
      • HiBytesTableClassification
      • PaddingClassification
      • StringClassification
      • classify_run_bytes()
      • find_classification_candidates()
      • find_data_runs()
      • looks_like_code()
      • looks_like_hi_bytes_table()
      • looks_like_padding()
      • looks_like_string()
    • Print-inline hook discovery
      • HookCandidate
      • find_hook_candidates()
      • render_hook_subroutine_line()
    • Cross-ROM shared-code matching
      • Instruction
      • RomData
      • find_matching_spans()
      • is_trivial_span()
      • load_rom()
      • matching_byte_count()
      • parse_rom_spec()
      • sweep_opcodes()
    • Annotation backfill across versions
      • AnnotationDiff
      • PropagationCandidate
      • PropagationReport
      • build_confidence_map()
      • build_confidence_map_for_block()
      • diff_annotations()
      • group_logical_statements()
      • make_project_rom_loader()
      • parse_annotations()
      • propose_propagations()
      • propose_translations()
      • subroutine_name()
      • translate_address_in_text()
      • translate_subroutine()
    • Driver-script annotation parsing
      • DriverAnnotation
      • DriverParseError
      • parse_driver_annotations()
    • Driver-script address sorting
      • Unit
      • build_units()
      • emit_units()
      • is_sorted()
      • sort_driver_text()
    • Version graph (DAG) and chain composition
      • Edge
      • NoPathError
      • Region
      • RelocBlock
      • Version
      • VersionGraph
      • VersionGraphCycleError
      • VersionGraphError
      • VersionNotInGraphError
      • compose_chained_map()
      • load_version_graph()
    • Assembly-source extraction
      • AsmSection
      • build_index()
      • extract_section()
      • find_line_for_target()
      • parse_address()
    • Project bootstrap (fantasm project init / add / list)
      • ProjectInitConfig
      • TargetSpec
      • VersionInfo
      • add_version()
      • append_target()
      • binary_addresses()
      • default_target_paths()
      • init_project()
      • list_versions()
      • parse_binary_option()
      • project_relative()
      • render_fantasm_toml()
      • render_target_entry()
  • Testing strategy
    • Why TDD doesn’t apply
    • Characterisation tests
    • Round-trip with beebasm
    • Where to put tests
    • Running the suite

Project history

  • Inventory of disasm_tools/ across the four sibling projects
    • Per-module status
      • Porting strategy that emerged
    • Cross-cutting refactors
    • Porting order
  • Migration readiness — sibling tools/ and root scripts
    • Per-script verdict
      • acorn-adfs/tools/
      • acorn-econet-bridge/tools/
      • acorn-nfs/tools/
      • acorn-nfs/ (root level)
    • Capability gaps
      • 1. port-to-fantasm — new api work (4 items)
      • 2. cli-gap — exposing existing primitives (5 items)
      • 3. fantasm-covered (drop after migration, ~5 items)
      • 4. project-specific (~17 items)
    • Migration readiness verdict
      • Closed
      • Deferred (not blocking)
      • What this means for the siblings
fantasm
  • Search

© Copyright 2026, Robert Smallshire.

Built with Sphinx using a theme provided by Read the Docs.