Conventions and evidence

This page defines the notation, evidence labels, and naming conventions used throughout the wiki.

Suggested reading order

1. System overview introduces the machine, OS, and evidence model.
2. Subsystem map shows the major services and their dependencies.
3. Memory map, Paging, The bcall mechanism, and Interrupts cover the shared architecture.
4. Continue with a core subsystem such as Floating point, Variables and the VAT, Tokenizer and TI-BASIC tokens, or Display and LCD, followed by its linked deep dives.
5. Glossary for any unfamiliar term.

Address notation

• pp:addr — Flash page pp (00–3F) and logical address addr. Banked pages run in the 0x4000–0x7FFF window, so _PutS at 01:5C39 means page 01, address 0x5C39.
• ram:addr — page 0 (the always-mapped kernel) and the RAM window; Ghidra keeps page 0 in its ram space, so ram:229E ≡ 00:229E.
• Ghidra’s overlay space writes flash addresses as page_pp:addr (e.g. page_38:4000); the wiki normalizes these to the short pp:addr form, so page_38:4000 is written 38:4000.
• A bare 0x…. (no page) is a RAM data address or an unpaged value (e.g. flags 0x89F0, the bcall-ID ranges 0x4xxx/0x8xxx, a page number like 0x3B).
• bcall ID ≠ address. A bcall has an ID (the 2-byte word after rst 28h, such as _FindSym = 0x42F4) and a body address (00:0E65). The ID indexes the jump table; it is not where the code lives.

Confidence flags

Every non-obvious claim is tagged:

Function naming

• _CamelCase — an official TI bcall/equate name (from ti83plus.inc, the full 2007 TI-83 Plus SDK equates file, or the TI SDK), e.g. _FindSym, _FPAdd. High confidence.
• snake_case — a name inferred from a routine’s behavior, including its callees and RAM or port accesses, such as findsym_scan or fp_normalize. Any individual low-level helper name remains a best-effort interpretation.

The rebuilt Ghidra project keeps each kind of name in a separate checked registry:

• tools/symbols/names.txt contains function entries. Its importer disassembles the entry and creates a function.
• tools/symbols/labels.txt contains ROM data and internal code-entry labels. Rows marked entry seed and preserve disassembly without creating an overlapping function.
• tools/symbols/ram.txt contains RAM symbols, including official SDK equates and carefully named inferred state.
• tools/symbols/ports.txt contains I/O-port symbols.
• tools/symbols/poffsets.txt contains reviewed base-plus-offset references. These make an operand such as mathprintArenaState + 0x0D render as a structure member without inventing a second global name for the field address.

tools/symbols/ty_regions.txt applies the C layouts built by BuildTypes.java. The prose can therefore use expressions such as table_value_cache.band[1].value[row] once it introduces the typed base and its concrete address. A physical boundary, trace target, or byte-level proof still keeps its concrete address. [confirmed]

tools/symbols/ty_enum_operands.txt applies enum-member equates only at reviewed scalar operands. Each row includes the instruction bytes, so a changed opcode or constant stops the database build instead of attaching a stale enum name. [confirmed]

Math notation

Formulas are written in LaTeX and rendered by KaTeX (offline, client-side): $…$ for inline math and $$…$$ for display. Algorithms render as pseudocode blocks and data/control-flow diagrams as Mermaid.

Evidence and reproducibility

• The Ghidra database is rebuilt from the ROM by tools/build.sh (a 15-stage reproducible pipeline around Ghidra’s headless analyzer). It loads all 64 flash pages (page 0 + overlays at 4000), then resolves routines, applies function and data symbols, and installs the checked C layouts and offset references.
• Local ROM trust boundary. tools/ti84re/rom/assemble_local_rom.py --check validates the exact ignored base-ROM and AppVar hashes without writing output. Its reusable tools/ti84re/rom/assembly.py library decodes each TI variable container, verifies its checksum, type, name, flags, duplicate length fields, internal 16 KiB size, and payload hash, then requires the assembled-ROM hash. This proves which bytes the analysis uses; it does not prove that the files were captured from a physical calculator. The pinned base already contains the D84PBE1.8Xv page-3F payload byte for byte. Only D84PBE2.8Xv, installed at page 2F, changes the base image (8,615 bytes). [confirmed]
• bcall table resolution. Scoring all 64 Flash pages selects page 3B for the main table. The dispatcher at ram:2A5E–ram:2A6D independently selects that page, and the five RST shortcuts match their bcall targets. All 645 checked main-table rows resolve from bytes; this does not establish runtime coverage of every body. The retail boot table contains 87 populated entries on page 3F, including targets on USB page 2F. tools/symbols/bcalls8x_targets.txt records the 83 SDK-named entries; four other slots have inferred names. The resolver rejects BootFree and unknown prefixes, but its prefix check does not validate the full image or USB page. Use the provenance checks for that boundary.
• Decompiler caveats. Ghidra’s Z80 decompiler can mis-render SET b,(IY+d) flag operations, CALL cross_page_jump (ram:2B09) trampolines, and register-passed arguments on banked pages. Raw disassembly and ROM bytes are authoritative for these cases.

See the repository README.md for the exact build pipeline and tooling.