Home /Modules/impl/NATIVE-MATH-OPCODE-ALLOCATION.md

NATIVE-MATH-OPCODE-ALLOCATION.md

impl/subjects/math/NATIVE-MATH-OPCODE-ALLOCATION.md · 109 line(s) · markdown

Native math opcode allocation and VM integration plan

Existing ISA boundary

The executable source/native ISA now ends at opcode 195. Existing assignments 0–194 are frozen and append-only; 195 is the first implemented math opcode. In particular, the Native IPC worker opcodes remain one contiguous group:

Opcodes 182–194 retain their existing meanings. The old native-math branches assigned OP_MATH_CALL to 179; that assignment conflicts with IPC and must never be imported.

Reserved native-math allocation

The machine-readable allocation mirror is tools/isa/opcode-registry-3.0.json. It records assigned instruction IDs, family boundaries, fail-closed reservations, and the current operand contract documentation status. tools/verify-opcode-registry.py checks this catalog against the authoritative lib/vm/InstructionSet.sleela source order and native SLOp enum. The catalog does not make a reserved ID executable.

The following ranges are now the canonical family allocation. Opcode 195 is implemented; all other vacant positions remain reserved for their family. Ranges are inclusive and must not be filled by unrelated instructions.

Opcode rangeFamilyReserved positions
195–199Shared native math195 implemented; 196–199 reserved
200–207Vector8
208–215Matrix8
216–223Complex8
224–231Decomposition8
232–281Transform50

The shared native-math block has these initial planned identifiers:

The canonical family order is Vector, Matrix, Complex, Decomposition, Transform. Transform begins at 232 and ends at 281 inclusive. The 50-position Transform block is deliberate capacity, not a claim that 50 instructions already exist.

Reservation is not implementation. Opcode 195 is the one implemented exception in the allocation block. Do not add placeholder instructions for 196–281 to InstructionSet.sleela or the native SLOp enum, and do not advertise reserved IDs as executable. A reserved ID becomes an executable opcode only when its compiler contract, native dispatch, artifact validation, supported VM generation behavior, tests, and documentation are implemented together. Unknown/reserved IDs must fail closed. Never renumber or repurpose an existing opcode.

What is integrated now

The standalone native scalar math C ABI is present in math_kernel.hpp, sleela_math_kernel_c.h/.cpp, with an opt-in make -C impl test-native-math-kernel qualification target. It covers the IEEE-754 scalar function set and stable function-ID/arity/method-name dispatch.

The native linear-algebra C ABI is present in linear_algebra.h/.cpp, with an opt-in make -C impl test-linear-algebra qualification target. It covers vectors, matrices, LU/QR, complex arithmetic, eigen decomposition, FFT, and typed buffer dispatch.

This is a native library boundary. Scalar OP_MATH_CALL now reaches this C ABI from compiler-generated bytecode and preserves the Core helper fallback. The typed array ABI still does not pin VM-owned arrays, validate VM object layouts, or marshal VM arrays into typed descriptors. Standalone linear-algebra C ABI tests must not be described as VM bytecode integration.

Required integration continuity

The VM work must complete the original scalar native-math integration as well as the typed array/linear-algebra path. The scalar function-ID table, sl_math_kernel_* C ABI, compiler lowering, native dispatch, and documented bytecode fallback are not to be dropped or replaced by an array-only design. The historical branch is a source of implementation behavior, not an ISA source: its OP_MATH_CALL = 179 assignment conflicts with the fixed IPC block.

The full ownership, marshalling, compiler, artifact, regression, and delivery contracts are maintained in NATIVE-MATH-VM-INTEGRATION-PLAN.md.

Allocation and integration rules

  1. Preserve all existing opcode assignments 0–194 exactly.
  2. Keep each future math family within its allocated inclusive range.
  3. Leave unused positions vacant; never borrow them for another family.
  4. Keep scalar math function IDs and typed operation IDs separate from opcode IDs. One opcode may dispatch multiple stable function/operation IDs.
  5. Keep VM arrays VM-owned. Native kernels receive only bridge-owned snapshots or buffers valid for the synchronous call.
  6. Older VM generations must reject unsupported opcodes explicitly; they must never reinterpret them.
  7. Update source registry, native enum, compile-time assertions, dispatch, compiler, artifact validation, opcode map, VM generation contracts, tests, and trusted manifests as one coordinated implementation change.