File-Format.md

NVM Bytecode Format (.nb)

This document describes the binary format used to store NVM bytecode for execution by the NVM virtual machine.

Contents

• Byte Order
• NVM Bytecode File Structure
• Magic Signature
• NVM Version
• Bytecode

Byte Order

All multi-byte integer values in the NVM Bytecode format are stored in Little-Endian byte order.

---

NVM Bytecode File Structure

Offset	Size	Section
0	5 bytes	Magic
5	6 bytes	NVM Version
11	—	Bytecode

---

Magic Signature

The first 5 bytes of the file must be:

4E 56 4D 42 43

(NVMBC)

This signature identifies the file as an NVM Bytecode file.

---

NVM Version

Immediately following the magic signature are 6 bytes specifying the version of the NVM with which the file was compiled.

The version is stored as three consecutive u16 values.

<u16><u16><u16>

NVM versions are incompatible with each other: the version stored in the file must exactly match the version of the virtual machine. Otherwise loading the file must fail with a version compatibility error.

---

Bytecode

The file header is immediately followed by a stream of instructions.

Instruction Encoding

[opcode: u8]                 — OperationCode (see opcode.rs)
[operand_count: u8]          — number of operands, 0–3
[operand₁]                   — if count ≥ 1
[operand₂]                   — if count ≥ 2
[operand₃]                   — if count ≥ 3

Operand Encoding

Each operand starts with a 1-byte tag followed by its data:

Tag	Type	Data
0x00	Register	1 byte — register number (u8)
0x01	Immediate	8 bytes — value (u64 Little-Endian)