vm.h File Reference

Core virtual machine data structures and public VM API. More...

#include "bytecode.h"
#include <stddef.h>

Include dependency graph for vm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Frame
	Call frame representing one active function invocation. More...
struct	VM
	The Fun virtual machine state. More...

Macros
#define	MAX_FRAMES   128
#define	MAX_FRAME_LOCALS   64
#define	MAX_GLOBALS   128
#define	OUTPUT_SIZE   1024
#define	STACK_SIZE   1024

Typedefs
typedef struct VM	VM
	Opaque VM alias for external users.

Functions
void	vm_init (VM *vm)
	Initialize a VM instance to zero/initial state.
void	vm_clear_output (VM *vm)
	Clear the buffered output captured by the VM.
void	vm_print_output (VM *vm)
	Print buffered output entries to stdout (debug aid).
void	vm_free (VM *vm)
	Free all resources owned by the VM (globals, frames, output buffers). The VM object itself is not freed when allocated on the stack.
void	vm_reset (VM *vm)
	Reset VM to initial state, freeing globals/locals/output. The VM object remains valid for reuse after this call.
void	vm_dump_globals (VM *vm)
	Print non-nil globals (index and value) to stdout.
void	vm_run (VM *vm, Bytecode *entry)
	Execute the provided entry bytecode in the VM. Pushes an initial frame and runs until HALT or an unrecoverable error.
void	vm_raise_error (VM *vm, const char *msg)
	Raise a runtime error honoring active try/catch/finally handlers. If a try handler is active in the current frame, control jumps to it with an error string pushed on the stack. Otherwise, prints the error (with location) and terminates execution.
void	vm_debug_reset (VM *vm)
	Reset debugger state: breakpoints and stepping controls.
int	vm_debug_add_breakpoint (VM *vm, const char *file, int line)
	Add a source breakpoint.
int	vm_debug_delete_breakpoint (VM *vm, int id)
	Delete a breakpoint by id.
void	vm_debug_clear_breakpoints (VM *vm)
	Remove all breakpoints from the VM.
void	vm_debug_list_breakpoints (VM *vm)
	Print active breakpoints to stdout.
void	vm_debug_request_step (VM *vm)
	Request single-step execution (stop after next instruction).
void	vm_debug_request_next (VM *vm)
	Request step-over (stop after next instruction in current frame).
void	vm_debug_request_finish (VM *vm)
	Request finish (run until the current frame returns).
void	vm_debug_request_continue (VM *vm)
	Resume normal execution (clear stepping state and stop flag).
int64_t	vm_pop_i64 (VM *vm)
	Pop a numeric Value and convert it to a 64-bit integer (C ABI helper).
void	vm_push_i64 (VM *vm, int64_t v)
	Push a 64-bit integer as a VM int Value (C ABI helper).
int	fun_op_radd (VM *vm)
const char *	fun_rust_get_string (void)
int	fun_rust_print_string (const char *msg)
char *	fun_rust_echo_string (const char *input)
void	fun_rust_string_free (char *ptr)
int	fun_op_cpp_add (struct VM *vm)
	Add two 64-bit integers from the VM stack and push the sum.
size_t	vm_sizeof (void)
	Return sizeof(VM) for external FFI consumers.
size_t	vm_value_sizeof (void)
	Return sizeof(Value) for external FFI consumers.
void *	vm_as_mut_ptr (VM *vm)
	Get a mutable byte pointer to the VM object. Extremely unsafe; for low-level FFI use only.
size_t	vm_offset_of_exit_code (void)
	Obtain offsetof(VM, exit_code) for FFI struct field access.
size_t	vm_offset_of_sp (void)
	Obtain offsetof(VM, sp) for FFI struct field access.
size_t	vm_offset_of_stack (void)
	Obtain offsetof(VM, stack) for FFI struct field access.
size_t	vm_offset_of_globals (void)
	Obtain offsetof(VM, globals) for FFI struct field access.
int	fun_op_rget_sp (VM *vm)
int	fun_op_rset_exit (VM *vm)

Detailed Description

Core virtual machine data structures and public VM API.

Declares the execution stack/frame layout, global state of the Fun VM, human-readable opcode names for diagnostics, and the public functions for initializing, running, resetting, and debugging the VM. FFI helper declarations for Rust/C++ experiments are also exposed here.

Definition in file vm.h.

Macro Definition Documentation

MAX_FRAME_LOCALS

#define MAX_FRAME_LOCALS   64

Definition at line 30 of file vm.h.

MAX_FRAMES

#define MAX_FRAMES   128

Definition at line 26 of file vm.h.

MAX_GLOBALS

#define MAX_GLOBALS   128

Definition at line 34 of file vm.h.

OUTPUT_SIZE

#define OUTPUT_SIZE   1024

Definition at line 38 of file vm.h.

STACK_SIZE

#define STACK_SIZE   1024

Definition at line 42 of file vm.h.

Typedef Documentation

VM

typedef struct VM VM

Opaque VM alias for external users.

Definition at line 148 of file vm.h.

Function Documentation

fun_op_cpp_add()

int fun_op_cpp_add

(

VM *

vm

)

Add two 64-bit integers from the VM stack and push the sum.

C++ demo opcode entry point (C ABI).

Pops two values from the VM stack using vm_pop_i64, adds them as 64-bit signed integers, and pushes the result via vm_push_i64.

Stack effect:

• Input: [..., a:int64, b:int64]
• Output: [..., (a+b):int64]

Parameters

vm	Pointer to the VM instance. Must not be NULL.

Returns

0 on success. Any stack underflow or conversion errors are handled by the VM helpers; non-zero may be used by future implementations to indicate a runtime error.

Definition at line 47 of file add.cpp.

Here is the call graph for this function:

fun_op_radd()

int fun_op_radd

(

VM *

vm

)

Example Rust-implemented opcode (adds top two ints on stack).

Here is the caller graph for this function:

fun_op_rget_sp()

int fun_op_rget_sp

(

VM *

vm

)

fun_op_rset_exit()

int fun_op_rset_exit

(

VM *

vm

)

fun_rust_echo_string()

char * fun_rust_echo_string

(

const char *

input

)

Return a newly allocated duplicate of the input C string (caller frees).

fun_rust_get_string()

const char * fun_rust_get_string

(

void

)

Return a demo null-terminated C string owned by Rust.

Here is the caller graph for this function:

fun_rust_print_string()

int fun_rust_print_string

(

const char *

msg

)

Print a C string via Rust; returns 0 on success.

fun_rust_string_free()

void fun_rust_string_free

(

char *

ptr

)

Free a C string previously returned by fun_rust_echo_string().

vm_as_mut_ptr()

void * vm_as_mut_ptr

(

VM *

vm

)

Get a mutable byte pointer to the VM object. Extremely unsafe; for low-level FFI use only.

Get a mutable byte pointer to the VM object. Extremely unsafe; for low-level FFI use only.

Parameters

vm	VM instance pointer.

Returns

The same pointer reinterpreted as void*.

Definition at line 650 of file vm.c.

vm_clear_output()

void vm_clear_output

(

VM *

vm

)

Clear the buffered output captured by the VM.

Parameters

vm	VM instance.

Clear the buffered output captured by the VM.

Frees any dynamic storage held by buffered output Values and resets the output counters and partial line indicators.

Parameters

vm	VM instance whose output buffer should be cleared.

Definition at line 349 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_debug_add_breakpoint()

int vm_debug_add_breakpoint	(	VM *	vm,
		const char *	file,
		int	line )

Add a source breakpoint.

Add a breakpoint at file:line; returns non-negative id on success or -1.

Parameters

vm	VM instance.
file	Source file path (must not be NULL).
line	One-based source line number (> 0).

Returns

Breakpoint id (>=0) on success, -1 on failure (invalid args or full).

Definition at line 453 of file vm.c.

vm_debug_clear_breakpoints()

void vm_debug_clear_breakpoints

(

VM *

vm

)

Remove all breakpoints from the VM.

Remove all breakpoints.

Parameters

vm	VM instance.

Definition at line 492 of file vm.c.

Here is the call graph for this function:

vm_debug_delete_breakpoint()

int vm_debug_delete_breakpoint	(	VM *	vm,
		int	id )

Delete a breakpoint by id.

Delete a breakpoint by id; returns 1 on success, 0 on failure.

Compacts the internal breakpoint list to keep ids dense.

Parameters

vm	VM instance.
id	Breakpoint identifier previously returned by add.

Returns

1 if deleted, 0 if id was invalid.

Definition at line 472 of file vm.c.

Here is the call graph for this function:

vm_debug_list_breakpoints()

void vm_debug_list_breakpoints

(

VM *

vm

)

Print active breakpoints to stdout.

Print the current list of breakpoints to stdout.

Parameters

vm	VM instance.

Definition at line 501 of file vm.c.

vm_debug_request_continue()

void vm_debug_request_continue

(

VM *

vm

)

Resume normal execution (clear stepping state and stop flag).

Continue execution until next breakpoint/stop.

Parameters

vm	VM instance.

Definition at line 551 of file vm.c.

vm_debug_request_finish()

void vm_debug_request_finish

(

VM *

vm

)

Request finish (run until the current frame returns).

Run until the current frame returns (finish).

Parameters

vm	VM instance.

Definition at line 540 of file vm.c.

vm_debug_request_next()

void vm_debug_request_next

(

VM *

vm

)

Request step-over (stop after next instruction in current frame).

Step over (next) within the current frame.

Parameters

vm	VM instance.

Definition at line 528 of file vm.c.

vm_debug_request_step()

void vm_debug_request_step

(

VM *

vm

)

Request single-step execution (stop after next instruction).

Request single-step execution mode.

Parameters

vm	VM instance.

Definition at line 517 of file vm.c.

vm_debug_reset()

void vm_debug_reset

(

VM *

vm

)

Reset debugger state: breakpoints and stepping controls.

Reset debugger state (clear step mode and breakpoints).

Clears all breakpoints, disables stepping modes, and resets counters.

Parameters

vm	VM instance with debugger state to reset.

Definition at line 429 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_dump_globals()

void vm_dump_globals

(

VM *

vm

)

Print non-nil globals (index and value) to stdout.

Parameters

vm	VM instance.

Print non-nil globals (index and value) to stdout.

Parameters

vm	VM whose globals should be dumped.

Definition at line 408 of file vm.c.

Here is the call graph for this function:

vm_free()

void vm_free

(

VM *

vm

)

Free all resources owned by the VM (globals, frames, output buffers). The VM object itself is not freed when allocated on the stack.

Parameters

vm	VM instance to dispose.

Free all resources owned by the VM (globals, frames, output buffers). The VM object itself is not freed when allocated on the stack.

Currently a no-op because the VM does not allocate persistent internal resources outside frames, globals and outputs, which are managed elsewhere.

Parameters

vm	VM instance to free resources for.

Definition at line 367 of file vm.c.

Here is the caller graph for this function:

vm_init()

void vm_init

(

VM *

vm

)

Initialize a VM instance to zero/initial state.

Parameters

vm	Non-NULL pointer to VM storage to initialize.

Initialize a VM instance to zero/initial state.

Resets stack/frame pointers, output buffers, instruction counters, debugger state and globals. Does not allocate memory.

Parameters

vm	VM instance to initialize.

Definition at line 714 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_offset_of_exit_code()

size_t vm_offset_of_exit_code

(

void

)

Obtain offsetof(VM, exit_code) for FFI struct field access.

Offsets of commonly accessed VM fields (for Rust FFI).

Returns

Byte offset of the exit_code field within VM.

Definition at line 659 of file vm.c.

vm_offset_of_globals()

size_t vm_offset_of_globals

(

void

)

Obtain offsetof(VM, globals) for FFI struct field access.

Returns

Byte offset of the globals field within VM.

Definition at line 686 of file vm.c.

vm_offset_of_sp()

size_t vm_offset_of_sp

(

void

)

Obtain offsetof(VM, sp) for FFI struct field access.

Returns

Byte offset of the sp field within VM.

Definition at line 668 of file vm.c.

vm_offset_of_stack()

size_t vm_offset_of_stack

(

void

)

Obtain offsetof(VM, stack) for FFI struct field access.

Returns

Byte offset of the stack field within VM.

Definition at line 677 of file vm.c.

vm_pop_i64()

int64_t vm_pop_i64

(

VM *

vm

)

Pop a numeric Value and convert it to a 64-bit integer (C ABI helper).

Pop an int64 from the VM stack; accepts int/float; returns truncated value.

Accepts int or float Values on the stack. Other types raise a runtime type error. The popped Value is freed.

Parameters

vm	VM instance.

Returns

The numeric value converted to int64_t.

Definition at line 598 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_print_output()

void vm_print_output

(

VM *

vm

)

Print buffered output entries to stdout (debug aid).

Parameters

vm	VM instance.

Print buffered output entries to stdout (debug aid).

Emits a newline after each value unless the corresponding partial flag is set.

Parameters

vm	VM instance whose output should be printed.

Definition at line 797 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_push_i64()

void vm_push_i64	(	VM *	vm,
		int64_t	v )

Push a 64-bit integer as a VM int Value (C ABI helper).

Push an int64 onto the VM stack.

Parameters

vm	VM instance.
v	Integer value to push.

Definition at line 621 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_raise_error()

void vm_raise_error	(	VM *	vm,
		const char *	msg )

Raise a runtime error honoring active try/catch/finally handlers. If a try handler is active in the current frame, control jumps to it with an error string pushed on the stack. Otherwise, prints the error (with location) and terminates execution.

Parameters

vm	VM instance.
msg	Null-terminated error message.

Raise a runtime error honoring active try/catch/finally handlers. If a try handler is active in the current frame, control jumps to it with an error string pushed on the stack. Otherwise, prints the error (with location) and terminates execution.

If the current frame has a pending try handler, control is transferred to that handler and the error message is pushed onto the stack for the catch clause. If no handler exists, the error is printed and the VM is stopped.

Parameters

vm	Pointer to the VM instance.
msg	Human-readable error message (may be NULL).

Definition at line 248 of file vm.c.

Here is the call graph for this function:

Here is the caller graph for this function:

vm_reset()

void vm_reset

(

VM *

vm

)

Reset VM to initial state, freeing globals/locals/output. The VM object remains valid for reuse after this call.

Parameters

vm	VM instance to reset.

Reset VM to initial state, freeing globals/locals/output. The VM object remains valid for reuse after this call.

Pops all frames (releasing local variables), clears the operand stack and globals, resets the output buffer and debugger state, and zeros the exit code.

Parameters

vm	VM instance to reset.

Definition at line 382 of file vm.c.

Here is the call graph for this function:

vm_run()

void vm_run	(	VM *	vm,
		Bytecode *	entry )

Execute the provided entry bytecode in the VM. Pushes an initial frame and runs until HALT or an unrecoverable error.

Parameters

vm	VM instance.
entry	Entry bytecode to execute; must outlive the call.

Here is the caller graph for this function:

vm_sizeof()

size_t vm_sizeof

(

void

)

Return sizeof(VM) for external FFI consumers.

Size of struct VM in bytes.

Returns

Size of the VM struct in bytes.

Definition at line 631 of file vm.c.

vm_value_sizeof()

size_t vm_value_sizeof

(

void

)

Return sizeof(Value) for external FFI consumers.

Size of struct Value in bytes.

Returns

Size of the Value struct in bytes.

Definition at line 640 of file vm.c.