UTTORI ASM · IN DEVELOPMENT

Instruction annotations

Use instruction annotations when creating or verifying a ROM analysis project.

buildInstructionAnalysisAnnotations() projects validated native records into deterministic, target-neutral facts for each qualified instruction location. The projection combines persisted CFG nodes, static effective-address explanations, distinct context-specific abstract-state transitions, manual and runtime state observations, instruction execution counts, runtime coverage, attributed memory reads/writes, record ids, and provenance. It retains architecture hints and explicit output offsets so a host can present one logical instruction in source, ROM, or debugger views without discarding its identity.

Logical evidence joins only by exact named address-space/address pairs. File-space evidence joins only through an explicit persisted output offset. The projector never calls a mapper or assumes that two equal numeric addresses describe the same memory. Opaque malformed effective-address metadata is returned as a non-fatal diagnostic rather than rendered. Range joins use sorted indexes, keeping the model suitable for large runtime-coverage collections without an annotation-by-instruction scan.

Editor previews use prepareAnnotationQueries() followed by instructionAnnotationView(ranges) inside a read transaction. Additive SQLite indexes select logical addresses and explicit output offsets before payload decoding. Initial setup extracts offsets from CFG/execution payloads once. SQL triggers queue only changed rows for later extraction. Derived columns live with their owning rows, so compaction and unrelated schema additions cannot detach offsets. A narrow offset/ID index orders compressed export projections without duplicating their entire payload in a covering index. Index setup is transactional and does not change the semantic revision. annotationEditView() and annotationNodesAt() load names/provenance and selected boundaries for bounded research inspection without loading all CFG variants.

Persisted views use SqliteAnalysisStore queries: source counts/pages, ROM coverage totals and 200-row segment/detail pages, call ownership, processor hints, bounded navigation, and evidence inspection. Coverage and graph builds use temporary SQL tables and publish complete results under a short writer lock. Dependency triggers invalidate relevant caches. A comment edit does not rebuild runtime coverage, graph ownership, or decoder variants.

sourceExportView() reads only editable metadata, function candidates, and conflicts. Pair it with instructionExportGroups() in the same read transaction to stream every instruction variant in ROM order. runtimeInstructionVariants() groups captured bytes and decoder state in SQL, then returns a cursor. Prepare it before opening its consuming read transaction. Reanalysis reads grouped execution seeds and selected MMIO accesses, while all original runtime facts remain in the database.

Git source research is saved as ordinary JSON, then synchronized into the evidence index. commitRuntimeEvidenceBatch() merges offline imports against destination IDs without expanding the saved trace history. Full snapshot APIs remain available for callers explicitly requesting a complete in-memory project. Normal editor queries, source regeneration, and offline imports do not use them.

Viewport requests accept at most 2,000 ranges and locations. Previews retain at most 64 execution, CPU-state, or attributed-memory records per location, with shared record budgets for large pages. The view returns limited when a budget is reached and separate SQL execution totals covering all matching execution records. Hosts must apply those totals to the projection and disclose limited details. A bounded view must never replace the full analysis/export snapshot or be persisted as complete history.