sleela_opcode.h
native/include/sleela_opcode.h · 86 line(s) · c
/*
* native/include/sleela_opcode.h
* SLeeLa Native Opcode Bridge โ stable C ABI.
*
* This header is the explicit VM/OS bridge below the SLeeLa /lib/opcodes
* single-opcode classes. Those classes declare the one-opcode-per-object model
* in SLeeLa source; the actual "advance the instruction pointer" (fetch) and
* "execute exactly one decoded opcode" (dispatch one) steps are value/VM
* primitives delegated here.
*
* The authoritative runtime remains /impl/core (impl/core/sleela_core.c), whose
* dispatch loop is `SLInstr in = vm->code[ip++]; switch (in.op) { ... }`. This
* bridge exposes that same discipline one step at a time so a SLeeLa opcode
* object can request the fetch and then its single dispatch.
*
* Canonical ISA: 103 opcodes, codes 0..102. Codes 0..97 are the base 98
* (OP_NOP .. OP_AUDIO_PLATFORM); codes 98..102 are the array extension.
*
* Author: Max Rupplin โ MEARVK LLC โ 2026
*/
#ifndef SLEELA_OPCODE_H
#define SLEELA_OPCODE_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define SLEELA_OPCODE_MIN_CODE 0
#define SLEELA_OPCODE_MAX_CODE 102
#define SLEELA_OPCODE_BASE_COUNT 98 /* codes 0..97 */
#define SLEELA_OPCODE_TOTAL_COUNT 103
/*
* Fetch: carefully advance the VM frame to its next instruction and return the
* resulting instruction pointer, or -1 on an inactive/invalid frame. This does
* not execute anything; it is the ip++ half of the dispatch loop.
*/
int32_t sleela_opcode_vm_next(int32_t frame);
/*
* Dispatch-one: execute exactly the single opcode `code` against the VM frame at
* instruction pointer `ip`. Returns the next instruction pointer to continue
* from, or -1 when the VM halts (OP_HALT) or rejects an unknown/unsupported
* opcode. An out-of-range code is rejected (mirrors the canonical map rule:
* unknown opcodes are never silently treated as no-ops).
*/
int32_t sleela_opcode_execute_one(int32_t frame, int32_t code, int32_t ip);
/* Canonical mnemonic for a code (0..102), or "OP_UNKNOWN". Never NULL. */
const char *sleela_opcode_mnemonic(int32_t code);
/* 1 if code is a valid canonical opcode (0..102), else 0. */
int sleela_opcode_is_valid(int32_t code);
/*
* Running-helper signals (used by lib/opcodes/running). Observe a well-known VM
* signal for the conditional-reactive layer. `signal` is one of the SIG_*
* selectors below; `index` is the current stream position (passed through for
* index-relative signals). Returns the observed value, or -1 on invalid frame.
*/
#define SLEELA_OPCODE_SIG_IP 1 /* live instruction pointer */
#define SLEELA_OPCODE_SIG_LOCK_DEPTH 2 /* locks currently held */
#define SLEELA_OPCODE_SIG_CALL_DEPTH 3 /* open call frames */
#define SLEELA_OPCODE_SIG_OPEN_SOCKETS 4 /* open sockets */
#define SLEELA_OPCODE_SIG_WARN_COUNT 5 /* governance warnings so far */
#define SLEELA_OPCODE_SIG_INDEX 6 /* current stream index */
int32_t sleela_opcode_signal(int32_t frame, int32_t signal, int32_t index);
/*
* Pre-stage (warm) an opcode: ask the VM to make the opcode `code` ready to fire
* with no cold-start cost. Returns 1 when staged, 0 when the code is invalid.
* Warming never executes the opcode.
*/
int sleela_opcode_prestage(int32_t frame, int32_t code);
/* Last human-readable error (never NULL). */
const char *sleela_opcode_last_error(void);
#ifdef __cplusplus
}
#endif
#endif /* SLEELA_OPCODE_H */