Symbolics Ivory I-machine and Open Genera VLM reimplementation specification

Status and reconstruction claim

This specification defines two related targets:

• IMA-R2, the public Symbolics I-machine architecture described by the 366-page I-Machine Architecture Specification, revision 2; and
• OG85-VLM, the guest-visible Ivory version 5 execution environment observed in the repository's preserved Open Genera 8.5 world and historical VLM.

The complete instruction semantics, memory cycles, trap entry/return, stack frames, function calling, and page-hash-table algorithm in sections 1–5 and appendices A, B, D, and F of the public architecture specification are normatively incorporated. This document fixes the implementation profile, state boundaries, VLM mapping, failure ordering, release evidence, and conformance tests needed to use that architecture without conflating hardware, host services, or a modern public fork.

A conforming IMA-R2 implementation can execute architecture-conforming compiled functions. A conforming OG85-VLM implementation can host the selected Open Genera world only after it also implements the VLOD, Life Support, communication-area, device, debugger, X, and host contracts named here.

The Genera browser and WebAssembly investigation and implementation roadmap turns those requirements and remaining oracles into gated OG85-WEB-LOCAL milestones without treating the licensed world as a distributable application asset.

It does not claim:

• source or binary identity with Symbolics' historical VLM;
• that the public descendant is the source of the preserved local executable;
• compatibility with 3600 macrocode, CADR microcode, or their object layouts;
• complete behavior for unpublished implementation-dependent coprocessor commands; or
• successful boot of every Genera release or site configuration.

Normative language and evidence codes

MUST and MUST NOT state requirements for conforming implementations. SHOULD states a requirement that may be departed from only with a documented compatibility reason. MAY marks an optional behavior. These terms define this reconstruction contract; they do not claim that the historical sources used RFC-style terminology.

IMA controls the processor architecture. G85-SRC and G85-RUN can select or constrain the OG85-VLM profile but cannot silently alter IMA-R2. PVLM is not ancestry proof and MUST NOT be used to attribute its fixes to the preserved binary.

Compatibility profiles and levels

Architecture and ownership boundaries

Genera compiled function
    -> Ivory architectural instruction
        -> physical Ivory implementation

Genera compiled function
    -> Ivory architectural instruction
        -> VLM interpreter
            -> Life Support communication and host devices
                -> Unix host

The VLM owns guest processor state and instruction atomicity. Life Support owns host I/O, virtual disks, paging service, network transfer, time, cold-load console, and process lifecycle. A coprocessor instruction is the architectural handoff; its host effect belongs to the selected coprocessor protocol, not to ordinary instruction decode.

Word and object model

An architectural word is 40 bits:

I0 MUST preserve all 40 bits through memory. Stack operations often normalize the cdr code to cdr-next, but MUST do so only where the incorporated instruction contract requires it. Object equality, numeric equality, transport, and memory cycles MUST inspect tags according to IMA; an emulator MUST NOT represent every guest word as an untagged host integer.

The complete data-type code table in IMA section 1.17 is normative. Its major classes include immediate numeric/character objects, list and instance pointers, array and function headers, physical and lexical locatives, invisible/forwarding pointers, compiled-function forms, full-word call forms, external-value-cell pointers, and packed-instruction types.

Executable word formats and sequencing

The processor fetches a 40-bit word and selects behavior from its data type:

1. A packed-instruction word contains even and odd 18-bit instructions. The even halfword at bits 0..17 executes first, then the odd halfword at 18..35. Bits 36..37 contribute the upper opcode bits needed for packed-instruction types octal 60–77.
2. A full-word call instruction uses its data-type code as call opcode and its 32-bit data field as the address.
3. An entry instruction is a packed-instruction word used as one full-word entry descriptor, encoding required/optional argument counts and rest acceptance.
4. An executable object-reference word pushes the constant.
5. An external-value-cell pointer performs the architecture's data-read cycle and pushes the referenced cell contents after required invisible-pointer following.
6. Every other fetched data type raises the specified illegal-instruction exception.

PC is a halfword address. Sequencing code, taken branches, calls, returns, entry dispatch, and traps update it exactly as IMA specifies. No host pointer or host instruction address may become guest-visible.

Packed instruction encoding

The ordinary packed instruction is 18 bits:

The two basic formats are operand-from-stack and ten-bit immediate.

Complete opcode-family inventory

The following is a complete family inventory for IMA-R2. Exact opcode numbers, operand signedness/address interpretation, stack pops, results, memory cycles, exceptions, and next-PC rules are normatively incorporated from IMA chapter 3, appendix B, and appendix F. The licensed i-instruction-set witness and PVLM emulator/aihead.sid cross-check the selected names and encodings.

Opcode holes are illegal even if a host dispatch table has storage for them. The emulator MUST dispatch by the complete 8-bit opcode plus format; it MUST NOT select an operation solely from a mnemonic table that loses packed-type distinctions.

Processor state

At minimum I1 and above preserve:

The internal-register numbers and read/write permissions in IMA section 3.2 and the selected source are normative. Unimplemented, read-only, or privileged accesses raise their specified exception.

Function call and return transaction

A call is a multi-instruction transaction:

1. start-call establishes call-started control state.
2. Argument-producing instructions build the callee argument area.
3. A finish-call instruction identifies the callee, argument count source, apply mode, and value disposition.
4. The processor validates the callable object, follows permitted indirections, constructs the control frame, and fetches the entry descriptor.
5. Entry checks required/optional counts and rest acceptance, creates missing optionals/rest representation, and locates locals.
6. Return restores caller frame and applies effect/value/return/multiple disposition.

Any exception before frame commitment MUST leave restart information sufficient to avoid duplicating arguments or bindings. Cleanup bits govern unwind obligations. Multiple-value return MUST not be reduced to repeated single-value pushes.

Binding, catch, and unwind

Binding records contain the locative and saved contents needed for exact restoration. unbind-n and restore-binding-stack unwind in newest-first order. Catch-open links a catch block to the current control state; catch-close removes the matching open block. Trap or throw unwinding MUST honor cleanup bits and restore bindings/control frames in architecture order. A malformed chain causes the specified exception rather than a host loop or memory fault.

Memory cycles, transport, and GC

IMA chapter 2 and the memory-cycle tables are normative. A memory reference selects a cycle such as data read, binding read, header read, structure offset, scavenge, copy, or raw access. The cycle and encountered data type jointly determine whether to return the word, follow an invisible pointer, transport an oldspace object, invoke a trap, or reject the access.

Writes MUST apply cdr/data-type merge rules, write barriers, ephemeral/oldspace checks, and store-conditional atomicity at the architectural commit point. A VLM may use host locks or atomic primitives internally but MUST preserve guest-visible success/failure and ordering.

Address translation and page hash table

The 32-bit virtual address is classified into mapped, ephemeral, unmapped, or wired regions according to IMA. For mapped access:

1. apply the architecture's PHT hash functions using PHT base and mask;
2. probe entries and validate virtual-page identity;
3. enforce access and write permissions;
4. produce the physical page and retained map attributes; or
5. raise the correct page-not-resident, access, write, or transport-related fault.

Map/cache optimizations are not architecturally visible except through invalidation, fault counts, ordering, and control registers. Invalidating or loading a map entry MUST affect subsequent translations at the boundary specified by the internal register operation.

Exceptions and traps

Exceptions include illegal instruction/format, instruction exception, operand type, arithmetic, memory, page, stack, binding, preemption, and reset conditions. IMA chapter 5 controls priority, trap-vector selection, saved EPC/DPC/continuation/control state, handler arguments, and return/restart.

An emulator MUST:

• distinguish an instruction exception from a memory-cycle exception;
• save the architecturally specified PC, not merely the host dispatcher PC;
• identify whether the faulting instruction's stack effects committed;
• make retry, continue, or unwind produce the specified next state; and
• convert no guest error into an uncontrolled host signal.

Coprocessor and Life Support boundary

%coprocessor-read and %coprocessor-write are ordinary architectural instructions whose selected operand identifies an external register/operation. Their architectural completion is ordered with respect to guest state. For OG85-VLM, the host side can request or report world saving, disk, clock, console, network, and other Life Support work.

Each write-like operation MUST have an exactly-once commit token or equivalent state: a guest trap/retry MUST NOT repeat a completed host side effect. Unknown registers raise the profile's instruction exception. PVLM extensions are unavailable in OG85-VLM unless separately established by G85-SRC or G85-RUN.

VLM execution contract

A VLM instruction step:

1. obtains the word containing PC through guest translation;
2. decodes its executable data type and even/odd position;
3. resolves the packed opcode and operand format or full-word form;
4. performs ordered stack reads/pops and type checks;
5. performs memory cycles and external operations;
6. commits results, stack pointers, and control state;
7. records any exception restart phase; and
8. advances or replaces PC.

Host-code dispatch, caching, threaded interpretation, or generated native code MAY replace this sequence internally. Boundary state at instruction, exception, memory, and coprocessor commit points MUST be identical.

OG85-VLM/I3 additionally implements the fixed Boot, FEP, and System communication areas, their 40-bit word layout and queues, virtual disk/page service, network packet channels, cold-load display and debugger channel, main-display X relay, clock, and shutdown coordination specified in Ivory, FEP, and Open Genera VLM implementation layers. That dossier is a normative companion for those host-facing layouts and lifecycle transitions.

Boot and world loading

The VLOD is serialized world state, not an instruction archive. I4 MUST:

1. validate and privately map the selected VLOD;
2. initialize processor, maps, stack caches, communication areas, and Life Support;
3. load or connect the selected VLM Debugger;
4. establish virtual disks and configured devices;
5. transfer control to the world's recorded restart state; and
6. service guest activity until pause or shutdown.

The VLOD article defines the world boundary. The harness does not imply that a changed private VLOD is a successful Save World, and a forced host shutdown after accepted guest confirmation is not orderly guest persistence.

Failure, recovery, and shutdown

Guest faults remain guest state. Host resource exhaustion, invalid configuration, disk failure, communication queue corruption, or unavailable X/network service MUST be reported without silently fabricating a successful guest operation.

Pause retains the live VLM process and guest memory. Resume continues that process. Process exit destroys unsaved guest state. Save World is a separate in-guest operation and becomes durable only after its own successful completion.

The current historical VLM is known to accept shutdown confirmation, begin cleanup, break X, and then deadlock at a Cold Load channel mutex before bounded host termination. OG85-VLM MUST preserve this as an observed historical-binary defect, not as required architecture behavior. A reimplementation SHOULD complete orderly shutdown while offering a defect-compatibility test mode only if required.

Conformance tests

Every G85-RUN test MUST retain the full Genera harness record required by repository AGENTS.md: exact world, runtime, debugger, preloads, responder, configuration and helper hashes; namespace/network/X state; ordered input intents and outcomes; screenshot/pixel evidence when visible; and shutdown stages.

Oracle gaps

• TODO-OPCODE-FIXTURE: publish a rights-safe generated fixture covering every opcode and exception path; do not extract compiled proprietary functions as the fixture.
• TODO-COPROCESSOR: close the complete Open Genera coprocessor register set and exact host-side failure semantics.
• TODO-LINEAGE: establish the precise source revision and build recipe for the 1,533,760-byte historical VLM executable.
• TODO-HARDWARE: compare instruction-boundary traces with physical Ivory hardware.
• TODO-SAVE-WORLD: verify Save World success on a disposable private copy and distinguish every modified file and commit point.

Unknowns and reserved claims

The historical VLM's exact source ancestry, physical-Ivory trace equivalence, unpublished coprocessor operations, all implementation-dependent timing, and unexercised world profiles remain unknown. Booting the selected world would not establish those claims. PVLM-55B2 behavior is never promoted into OG85-VLM without independent licensed-source or exact-runtime evidence.

Evidence ledger and provenance

The public architecture PDF was verified 2026-07-27. Its original restrictive notice is not treated as permission to reproduce the manual; this specification uses original prose, small facts, and stable citations. Licensed Genera source and world bytes remain untracked.

No screenshot is required for the processor contract itself because its normative outputs are object, instruction, stack, memory, trap, and host-operation traces. A reviewed compiler/disassembly image can illustrate the user-facing tools in the companion compiler dossier but cannot prove unexercised instruction semantics.