📝 MXVM Language & Usage Guide

Overview

MXVM is a custom virtual machine, interpreter, and compiler project designed as a learning sandbox. It is not intended for production; instead it helps users explore and experiment with:

• Virtual machine design and instruction execution.
• Custom language parsing and abstract syntax tree generation.
• Modular system architecture with external and runtime externs.
• Code generation (including x86_64 translation) and execution.
• Memory & stack manipulation, control flow, and debugging.
• C++ integration, build systems (CMake), and cross-platform thinking.

The language combines assembly-like instructions with higher-level constructs like functions, modules, and formatted I/O to create an accessible pedagogical VM environment.

Getting Started

Prerequisites

• C++20 compatible compiler (gcc, clang, MSVC) or MXVM Online
• cmake (version 3.15+ recommended)
• Make or ninja for building
• Git (for cloning if not already local)

Typical Build

# Clone or go into your copy of the repo
cd MXVM-main/MXVM-main
mkdir build
cd build
cmake ..
make

This produces the compiler/interpreter binary (e.g., src/vm/mxvmc) and supporting modules.

Running a Sample Program

# from inside the build directory, run an example like demo.mxvm
./src/vm/mxvmc ../mxvm_src/demo.mxvm

Replace demo.mxvm with other examples such as fibonacci.mxvm, Comments.mxvm, or your own programs.

Language Basics

Program and Object

The entry point is a program block. Objects are reusable units that encapsulate code, data, and expose functions. Syntax:

program Name { ... }

object Name { ... }

Objects are referenced via section object.

Sections

• module: Include external functionality (e.g., io, string).
• data: Declare variables, pointers, strings, constants, and exports.
• object: Declare dependencies on other objects.
• code: Control flow, functions, labels, and instructions.

Variables and Types

Supported types include:

Example:

section data { 
    int x = 0
    string message = "Hello, MXVM!\n"
}

Functions and Labels

Define functions with the function name: syntax. Use call to invoke and ret to return. Labels serve as jump targets.

section code {
    start:
        call some_function
        done

    function some_function:
        ; work
        ret
}

Instruction Reference

Detailed description of available instructions:

Example Walkthroughs

Demo

A simple program that increments a variable from 0 to 10, then decrements it back to 0, demonstrating loops, comparison, and conditional jumps.

program Demo {
    section data {
        int x = 0;
        string fmt_str = "Hello World! Value of x is: %d\n";
        string fmt_end = "Goodbye!\n";
    }
    section code {
        mov x, 1
    start:
        add x, 1
        print fmt_str, x
        cmp x, 10
        jne start
        print fmt_end
    loop:
        sub x, 1
        print fmt_str, x
        cmp x, 0
        jg loop
        print fmt_end
    stop:
        done
    }
}

Fibonacci

Computes Fibonacci numbers up to n safely with range checking.

program Fibonacci {
    section data {
        int n = 30
        int a = 0
        int b = 1
        int i = 2
        string format = "%lld "
        string newline = "\n"
    }
    section code {
        cmp n, 0
        jl out_of_range
        print format, a
        print format, b
    loop:
        cmp i, n
        jge done_fib
        add temp, a, b
        mov a, b
        mov b, temp
        print format, b
        add i, 1
        jmp loop
    done_fib:
        print newline
        done
    }
}

ReadFile & Hex Printer

Demonstrates external module usage, file I/O, buffer manipulation, and formatting with invoke, load, and store.

Key pattern: allocate a buffer, read file contents, and print bytes in hex.

Comments Example

Shows looping, formatted printing, and decrementing counters.

Quick Reference

Minimal cheat sheet for writing MXVM programs:

// Program skeleton
program Name {
    section module { io, string }
    section object { other_object }
    section data {
        int counter = 0
        string msg = "Hi\n"
    }
    section code {
        mov counter, 5
        start:
            print msg, counter
            done
    }
}

Use labels and conditional jumps (jmp, je, etc.), call / ret for functions, and invoke to call external APIs.

Appendix

Module Inclusion

Include built-in functionality by adding it to the module section. Example:

section module { io }

This enables functions like fopen, fread, fprintf, and formatted I/O.

Common Patterns

• Looping: Use cmp + conditional jumps with labels.
• Function calls: Define reusable routines with function name: and invoke via call.
• External Interop: invoke + return to communicate with C-style APIs.

Debug Tips

Watch comparisons feeding conditional jumps. Maintain stack discipline when using push / pop / stack_load / stack_store. Use clear format strings to trace state.