CDNEE — Control Dynamic Native Execution Engine

01 — About

What is CDNEE?

CDNEE (Control Dynamic Native Execution Engine) is a high-level assembly-oriented programming language designed for direct access to native machine-code execution without the complexity of traditional assemblers or low-level compilers. It sits at a unique intersection: readable, structured syntax on the surface, bare-metal native performance underneath.

Programs are written in .cdnee source files and run through the CDNEE runtime, which compiles and executes x86-64 machine code on the fly using a built-in JIT engine backed by NASM. You can drop into raw assembly, benchmark it, patch it at runtime, inspect its disassembly, snapshot its memory, and call foreign libraries — all from a single coherent source file.

Native First

Every math operation, sort, and hash function goes through the DNEE engine's NASM-compiled native library. No slow path, no interpreted fallback by default. The language exposes what the CPU does, not what is convenient.

JIT as a First-Class Citizen

Inline NASM assembly is not an escape hatch — it is a core language feature. Write assembly snippets directly in source using triple-quoted blocks, compile them to executable memory regions, and call them like any other function.

Introspection and Control

A CDNEE program can disassemble its own compiled regions, compute checksums, walk patch history, inspect CPU cache topology, and read cycle-accurate timing via RDTSC. You always know what is in memory and how it is performing.

Structured Simplicity

Despite its low-level power, CDNEE code reads linearly. No pointers in source syntax, no manual stack management, no header files. Labels, functions, error handling, and I/O all follow a clean, consistent grammar learnable in an afternoon.

3 Execution Tiers

50+ Native Math Ops

x86-64 Architecture

v1.0 Current Version

02 — Language Tiers

Execution Model

CDNEE is organized into three execution tiers. Tier 1 requires no compilation step and is available immediately in any program. Tier 2 gives you the full JIT/MEX engine. Tier 3 targets bare-metal OS development — flat binaries and freestanding ELF64 kernels.

Tier 1 — Native Math Library

Built-in NASM Routines

Scalar arithmetic — ADD, SUB, MUL, DIV, MOD, POW, ABS, NEG, SIGN
Integer math — ISQRT, GCD, LCM, FACTORIAL, FIBONACCI, MULDIV, CLAMP
Number theory — IS_PRIME, NEXT_PRIME, PREV_PRIME, TOTIENT, COLLATZ
Bit operations — POPCOUNT, NLZ, NTZ, BIT_REV, ROL64, ROR64, BSWAP64
Hashing — HASH_FNV64 (FNV-1a 64-bit), HASH_MURMUR64
Modular arithmetic — MULMOD64, ADDMOD64, POWMOD64, MODINV64
Safe arithmetic — SAFE_ADD, SAFE_SUB, SAFE_MUL (with overflow flags)
Sorting & searching — SORT_NET4, BIN_SEARCH, LIN_SEARCH, LOWER_BOUND
Timing — RDTSC_START, RDTSC_STOP, CPUID

Tier 2 — JIT / MEX Engine

Machine Execution Engine

JIT compilation — compile inline NASM or .asm files into executable memory regions
Binary I/O — export compiled regions to .bin; reload in future runs
Memory control — freeze/thaw, snapshots, restore, clone, copy-on-write
Hot patching — overwrite bytes, NOP ranges, replace hex patterns, revert step-by-step
Inspection — disassemble regions, hex-dump, compute CRC-32, walk patch history
FFI — load shared libraries, bind exported symbols, call as native functions
Profiling — RDTSC-accurate benchmarking, per-region call counters, cache statistics
Trampoline patching — insert jump redirects into compiled regions

03 — Language Syntax

Program Structure & Syntax

CDNEE source files are plain UTF-8 text with the .cdnee extension. One statement per line, no semicolons needed. Comments start with ; or #. Execution begins at the @entry label.

Hello World

hello.cdnee

; hello.cdnee
@entry main

main:
    PRINTLN "Hello, CDNEE!"
    EXIT

Variables & Arithmetic

vars.cdnee

SET x, 42
LET name, "Alice"
SET pi, 3.14159
SET flag, TRUE

ADD result, x, 100    ; result = 142
MUL sq, x, x           ; sq = 1764
MOD rem, x, 5          ; rem = 2
PRINTLN result

Control Flow

loop.cdnee

SET i, 1
loop:
    CMP i, 10
    JGT done
    PRINTLN i
    ADD i, i, 1
    JMP loop
done:
    EXIT

Functions

func.cdnee

FUNC square, n:
    MUL r, n, n
    RETURN r
END

main:
    SET result, CALL square, 9
    PRINTLN result    ; → 81
    EXIT

Error Handling

try.cdnee

TRY:
    SET r, CALL risky_fn, 42
CATCH err:
    PRINT "Error: "
    PRINTLN err
END

Inline JIT Assembly

jit.cdnee

JIT_COMPILE_INLINE """
BITS 64
mov rax, rdi
imul rax, rdi
ret
""", tag=sq

SET result, CALL sq, 9   ; → 81
PRINTLN result

Conditional Jump Opcodes

Opcode	Syntax	Condition
JE	JE label	Jump if left == right (after CMP)
JNE	JNE label	Jump if left != right
JLT	JLT label	Jump if left < right
JGT	JGT label	Jump if left > right
JLE	JLE label	Jump if left <= right
JGE	JGE label	Jump if left >= right
JMP	JMP label	Unconditional jump

Auto-Set Runtime Variables

These variables are automatically set by the runtime after certain operations:

Variable	Set By
_last_offset	FIND
_found_offset	BIN_SEARCH, LIN_SEARCH
_checksum	CHECKSUM
_disasm	DISASM (when captured)
_dump	DUMP (when captured)
_bench_mean	BENCHMARK
_bench_min	BENCHMARK
_asm_size	ASM_SIZEOF
_reverted	PATCH_REVERT
_profile_ms	PROFILE_END

04 — Standard Library

Tier-1 Standard Library

All Tier-1 operations run via the DNEE native engine when available, or fall back to pure Python. Every operation stores its result in the dest variable. No compilation step required.

calculate Scalar Math

ADD dest, a, b — a + b
SUB dest, a, b — a − b
MUL dest, a, b — a × b
DIV dest, a, b — a ÷ b (integer when both ints)
MOD dest, a, b — a mod b
POW dest, a, b — a ^ b
ABS dest, a — |a|
NEG dest, a — −a
SIGN dest, a — −1, 0, or 1
ISQRT dest, a — floor(√a)
LOG2 / LOG10 — floor(log₂a), floor(log₁₀a)
MIN_VAL / MAX_VAL — min/max of two values
CLAMP dest, val, lo, hi — clamped value
CEIL_DIV / FLOOR_DIV / MULDIV / AVERAGE

functions Number Theory

GCD dest, a, b — greatest common divisor
LCM dest, a, b — least common multiple
FACTORIAL dest, n — n!
FIBONACCI dest, n — F(n), 0-indexed
COLLATZ dest, n — steps to reach 1
TOTIENT dest, n — Euler's φ(n)
IS_PRIME dest, n — 1 if prime
NEXT_PRIME dest, n — smallest prime > n
PREV_PRIME dest, n — largest prime < n
IS_PERFECT / IS_ABUNDANT / IS_DEFICIENT

memory Bit Operations

POPCOUNT dest, n — count set bits
NLZ dest, n — leading zeros (64-bit)
NTZ dest, n — trailing zeros
ROL64 dest, n, k — rotate left 64-bit by k
ROR64 dest, n, k — rotate right 64-bit by k
BIT_REV dest, n — reverse all bits
BSWAP64 dest, n — byte-swap (endian flip)
PARITY64 dest, n — XOR of all bits
IS_POW2 / NEXT_POW2

shield Safe Arithmetic

SAFE_ADD dest, a, b, flag — overflow-detected add
SAFE_SUB dest, a, b, flag — overflow-detected sub
SAFE_MUL dest, a, b, flag — overflow-detected mul
DIVMOD quot, rem, a, b — quotient and remainder
flag = 1 on overflow, 0 otherwise

tag Hashing & Modular

HASH_FNV64 dest, data, len — FNV-1a 64-bit hash
HASH_MURMUR64 dest, x — Murmur-style 64-bit mix
ADDMOD64 / SUBMOD64 / MULMOD64 — (a ± b) mod m
POWMOD64 dest, a, b, m — modular exponentiation
MODINV64 dest, a, m — modular inverse (extended GCD)

sort Sort, Search & Timing

SORT_NET4 arr — optimal sorting network for 4 elements
BIN_SEARCH dest, arr, n, target — binary search, -1 if not found
LIN_SEARCH dest, arr, n, target — linear search
LOWER_BOUND dest, arr, n, target — std::lower_bound equivalent
RDTSC_START / RDTSC_STOP — cycle-accurate timing
CPUID dest — CPU identification info

Stdlib Usage Example

stdlib_demo.cdnee

@entry main

main:
    ; Primality and number theory
    IS_PRIME   p, 97          ; p = 1
    NEXT_PRIME q, 100         ; q = 101
    TOTIENT    t, 12           ; t = 4

    ; Safe arithmetic with overflow detection
    SAFE_MUL r, 999999999, 999999999, ov
    CMP ov, 1
    JE  overflow_handler

    ; Cycle-accurate timing
    RDTSC_START t0
    FIBONACCI   f, 40
    RDTSC_STOP  t1
    SUB cycles, t1, t0
    PRINT "Fib(40)="
    PRINT f
    PRINT " cycles="
    PRINTLN cycles
    EXIT

overflow_handler:
    PRINTLN "Overflow detected!"
    EXIT

05 — JIT & MEX Engine

JIT Compilation & Memory Control

Tier-2 gives you the full Machine Execution Engine (MEX). Compile inline NASM or .asm files into executable memory, benchmark them, patch them live, snapshot and restore, export to disk, and reload across sessions.

JIT Type System

JIT functions require explicit type annotations to build the correct ctypes.CFUNCTYPE. Multiple arguments use colon-separated types.

i64

c_int64

Default for args & return

u64

c_uint64

−1 wraps to 2⁶⁴−1

i32

c_int32

Truncated outside ±2GiB

u32

c_uint32

32-bit unsigned

i8 / u8

c_int8 / c_uint8

Wraps at 128 / 256

f64

c_double

Python float (64-bit)

f32

c_float

Narrowed from float

ptr

c_void_p

Raw memory address

bool

c_bool

0 / 1

void

None

Return type only

Calling Convention (x86-64 System V ABI): Integer/pointer args in rdi, rsi, rdx, rcx, r8, r9. Float args in xmm0–xmm5. Integer return in rax. Float return in xmm0. Mixed-type functions use both register sets counted separately.

JIT Operations

①

Compile

JIT_COMPILE / JIT_COMPILE_INLINE

Assemble a .asm file or triple-quoted inline block into an executable memory region tagged with a name. Specify argtypes and rettype for the correct calling convention. Use overwrite=true to replace an existing region.

②

Batch / Count

JIT_COMPILE_MANY / JIT_COUNTED / JIT_FN

Compile multiple assembly files in one call with JIT_COMPILE_MANY. JIT_COUNTED and JIT_FN wrap the compiled function with a call counter, accessible via CALL_STATS for profiling.

③

Export / Import

EXPORT_BIN / IMPORT_BIN / CALL_BIN / BIN_CONTEXT

Serialize compiled JIT regions to disk as .bin files and reload them in future sessions — bypassing assembly overhead. CALL_BIN imports and calls in one step. BIN_CONTEXT scopes the lifetime to a block.

④

Memory

FREEZE / THAW / SNAPSHOT / RESTORE / CLONE / COPY_ON_WRITE

Control the mutability and lifecycle of JIT regions. FREEZE prevents further patching. SNAPSHOT saves the current bytes; RESTORE reverts. CLONE duplicates a region. COPY_ON_WRITE creates a copy with specific bytes changed.

⑤

Patch

PATCH_NOP / PATCH_INT64 / PATCH_FILL / PATCH_REPLACE / PATCH_BYTES

Overwrite bytes in live JIT regions. All patch operations are recorded in a patch history. Use PATCH_REVERT to undo N steps or PATCH_REVERT_ALL to restore the original. TRAMPOLINE inserts a jump redirect at an offset.

⑥

Inspect

DISASM / DUMP / FIND / CHECKSUM / REGION_INFO / PATCH_HISTORY

Inspect live JIT regions. Disassemble bytes, hex-dump, search for byte patterns, compute CRC-32 checksums, view region address/size/permissions, and walk the full patch history.

⑦

Profile

BENCHMARK / PROFILE_BLOCK / JIT_STATS / CACHE_STATS

BENCHMARK runs a function with warmup and timed iterations, reporting mean/min/max/stddev. PROFILE_BLOCK is a scoped timer. CACHE_WARM, CACHE_CLEAR, and CACHE_INVALIDATE manage the JIT code cache.

JIT + Patching Example

jit_patch.cdnee

@entry main

main:
    ; Compile inline NASM with typed signature
    JIT_COMPILE_INLINE """
BITS 64
mov  rax, rdi
imul rax, rsi
ret
""", tag=mul, argtypes=i64:i64, rettype=i64

    SET r, CALL mul, 6, 7
    PRINTLN r              ; → 42

    ; Benchmark it
    BENCHMARK mul, 6, 7, iterations=1000000, warmup=100

    ; Snapshot and inspect
    SNAPSHOT mul
    SET r_, DISASM   mul, 32
    CHECKSUM mul
    PRINTLN  _checksum

    ; NOP the imul instruction (bytes 3-9)
    PATCH_NOP mul, 3, 4

    ; Revert the patch
    PATCH_REVERT mul, 1

    ; Export for future use
    EXPORT_BIN "./cache"
    JIT_RELEASE mul
    EXIT

06 — Foreign Function Interface

FFI — Native Library Bindings

The CDNEE FFI has two complementary halves: EXTERN file imports (.cdneef header files that add pure-CDNEE functions) and native symbol bindings (shared libraries loaded via ctypes).

EXTERN — .cdneef Headers

import_header.cdnee

; Import a function header
EXTERN "math_utils.cdneef"

; Namespace prefix to avoid collisions
EXTERN "vec2.cdneef", alias_prefix=v2_
EXTERN "vec3.cdneef", alias_prefix=v3_

SET r, CALL v2_add, 10, 20
SET r, CALL v3_add, 1, 2, 3

EXTERN_FUNC — Native Symbols

native_bind.cdnee

; Bind libm sqrt
EXTERN_FUNC "m", func=sqrt, alias=fsqrt,
    argtypes=f64, rettype=f64

SET r, CALL fsqrt, 144.0
PRINTLN r   ; → 12.0

; Windows API — stdcall
EXTERN "kernel32", func=Sleep,
    alias=sleep_ms, argtypes=u32,
    rettype=void, cdecl=false

Portable Math Example

portable_math.cdnee

@entry main

EXTERN_FUNC "c", func=abs,  alias=iabs,
    argtypes=i32, rettype=i32
EXTERN_FUNC "m", func=pow,  alias=fpow,
    argtypes=f64:f64, rettype=f64

main:
    SET a, CALL iabs, -123
    PRINTLN a         ; → 123

    SET b, CALL fpow, 3.0, 8.0
    PRINTLN b         ; → 6561.0
    EXIT

Portable Short Library Names

Linux / macOS (POSIX)

clibc.so.6
mlibm.so.6
pthreadlibpthread.so.0
dllibdl.so.2
zlibz.so.1
ssllibssl.so
cryptolibcrypto.so
stdc++libstdc++.so.6
opengllibGL.so.1
x11libX11.so.6

Windows

c / mmsvcrt.dll
kernel32kernel32.dll
user32user32.dll
ntdllntdll.dll
gdi32gdi32.dll
shell32shell32.dll
ws2_32ws2_32.dll
d3d11d3d11.dll
d3d12d3d12.dll
openglopengl32.dll

Path Resolution for .cdneef: (1) Absolute path — used as-is. (2) Relative to the directory of the current .cdnee source file. (3) Relative to the current working directory. Circular imports are detected and silently ignored.

07 — CLI & Compiler

CLI & Compiler Reference

CDNEE ships two command-line tools: CDNEE (the interpreter / REPL) and CDNEE-CC (the ahead-of-time compiler). Both are installed alongside the package.

CDNEE — Interpreter Flags

usage: CDNEE [OPTIONS] [file.cdnee]

-h, --help

Show help and exit

-v, --verbose

Verbose output during execution

-V, --version

Print runtime version

--no-dnee

Disable JIT; use software math fallback only

--lex

Tokenise source and print token stream

--ast

Parse source and print AST

--fmt

Pretty-format source

--check

Syntax check only — no execution

--disasm TAG

Disassemble region TAG after run

--dump TAG

Hex-dump region TAG after run

--stats

Print JIT and cache statistics after run

--bench TAG

Benchmark region TAG after run

--bench-args [ARGS...]

Arguments to pass when benchmarking

--bench-iters N

Benchmark iteration count (default 100000)

--strict-wx

Enforce W^X memory protection

--workers N

JIT thread-pool size (default 4)

--math PATH

Path to custom math.asm

--out FILE

Redirect PRINT/PRINTLN output to FILE

--repl

Force REPL mode

--os-sim

Run in OS simulation mode — verbose OS opcode feedback

--os-state

Dump _os_state dict after script execution

--os-vga

Render simulated 80×25 VGA text buffer after execution

--os-image FILE

Write accumulated OS_DB/DW/DD/DQ image bytes to FILE

CDNEE-CC — Compiler Flags

usage: CDNEE-CC [OPTIONS] [source.cdnee]

-o DIR, --output DIR

Output directory for compiled files

--name NAME

Base name for output files

--exe

Produce a standalone executable (shared-lib target)

--flat

[OS v2.4] Compile to flat binary — nasm -f bin, no linker (MBR / COM)

--os

[OS v2.4] Compile to freestanding ELF64 kernel

--abi {sysv,win64,auto}

Select calling convention ABI

--asm-only

Stop after NASM generation — emit .asm only

--show-asm

Print generated NASM to stdout

--no-export-all

Export only the @entry symbol

--keep-obj

Keep the intermediate object file (.o)

--load-test

ctypes smoke-test the compiled output after build

--list-exports

List all exported symbols and exit

--run

Run the executable immediately after compiling (implies --exe)

--run-args ...

Arguments for the executable when --run is used (after --)

--opt LEVEL

Optimization: 0=none 1=peephole 2=peephole+strength (default: 0)

--nasm-flag FLAG

Pass extra flag to NASM

--link-flag FLAG

Pass extra flag to the linker

--load-addr ADDR

[--os] Kernel physical load address (default: 0x100000 = 1 MiB). Accepts decimal or 0x hex.

--ld-script FILE

[--os] Custom LD linker script (auto-generated if omitted)

--qemu

After compiling, launch QEMU to run the result

--qemu-args ...

Extra arguments forwarded to QEMU (after --)

--qemu-bin BIN

QEMU binary to use (default: qemu-system-i386 for flat, qemu-system-x86_64 for os)

CDNEE-CC Usage Examples

compiler examples

# Standard modes
CDNEE-CC program.cdnee                  # compile to .so/.dll
CDNEE-CC program.cdnee -o dist/         # output to dist/
CDNEE-CC program.cdnee --asm-only       # emit NASM only
CDNEE-CC program.cdnee --show-asm       # print NASM to stdout
CDNEE-CC program.cdnee --load-test      # compile + ctypes smoke-test
CDNEE-CC program.cdnee --list-exports   # show exported symbols
CDNEE-CC program.cdnee --exe            # compile to executable
CDNEE-CC program.cdnee --exe --run      # compile + run immediately
CDNEE-CC program.cdnee --opt 2          # peephole + strength reduction

# OS / flat-binary modes (v2.4)
CDNEE-CC boot.cdnee   --flat                   # MBR / flat binary
CDNEE-CC kernel.cdnee --os                     # freestanding ELF64 kernel
CDNEE-CC kernel.cdnee --os --load-addr 1M      # load at 1 MiB
CDNEE-CC kernel.cdnee --os --ld-script k.ld   # custom linker script
CDNEE-CC boot.cdnee   --flat --qemu            # flat binary + QEMU
CDNEE-CC kernel.cdnee --os --qemu              # kernel + QEMU -kernel

REPL Commands

CDNEE interactive session

$ CDNEE --repl

DNEE> RUN program.cdnee
DNEE> EXEC SET x, 42
DNEE> EXEC PRINTLN x
DNEE> DISASM sq
DNEE> DUMP sq
DNEE> JIT_STATS
DNEE> CACHE_STATS
DNEE> REGION_INFO sq
DNEE> BENCHMARK sq 9 iterations=500000
DNEE> VARS
DNEE> HELP
DNEE> EXIT

08 — OS Development (v2.4)

OS Development Tier

CDNEE v2.4 adds a complete OS-development tier. Write bootloaders, kernels, and bare-metal programs using high-level OS opcodes that compile to flat binaries or freestanding ELF64. The same source runs in the interpreter's simulation mode for unit-testing OS logic without QEMU.

Flat Binary — MBR / COM

Real-mode Bootloader

OS_BITS 16 — real-mode code
OS_ORG 0x7C00 — BIOS loads MBR here
OS_BOOT_SIG — pads to 510 bytes, appends 0xAA55
Compiled with: CDNEE-CC boot.cdnee --flat
Tested with: qemu-system-i386 -drive format=raw,file=boot.bin
Result: exact 512-byte MBR image, no headers

ELF64 Kernel — Long Mode

Freestanding Kernel

OS_BITS 64 — long-mode code
OS_MULTIBOOT [flags] — Multiboot 1 header for GRUB
OS_GLOBAL kernel_start — entry exported to linker
Compiled with: CDNEE-CC kernel.cdnee --os
Tested with: qemu-system-x86_64 -kernel kernel.elf
Custom linker script supported via --ld-script

Hello from the Bootloader

hello_mbr.cdnee

; Minimal x86 real-mode MBR
; Prints "Hi OS!" via BIOS int 0x10

OS_BITS 16
OS_ORG  0x7C00

OS_CLI
OS_STI

JIT_COMPILE_INLINE greet_bios
"""
    mov  si, msg
.loop:
    lodsb
    or   al, al
    jz   .done
    mov  ah, 0x0E
    int  0x10
    jmp  .loop
.done:
    hlt
msg: db "Hi OS!", 13, 10, 0
""" tag=greet_bios

CALL greet_bios, 0
OS_HLT
OS_BOOT_SIG    ; pad + 0xAA55

kernel.cdnee

; Freestanding 64-bit kernel

OS_BITS 64
OS_MULTIBOOT 0x00000003

OS_GLOBAL kernel_start

kernel_start:
    OS_CLI
    OS_VGA_CLEAR 0x0F        ; white on black
    OS_VGA_PUTS 0, 0,
        "CDNEE Kernel v2.4", 0x0F
    OS_SERIAL_INIT 0x3F8, 115200
    OS_SERIAL_PUTS 0x3F8,
        "Kernel alive\r\n"
    OS_HLT

Simulation mode: All OS opcodes also work in the interpreter. Use --os-sim --os-vga to test OS logic without QEMU. Inspect interp._os_state for VGA buffer, serial log, and memory allocator state.

OS Opcode Reference

Section / Layout

Opcode	Syntax	Description
OS_BITS	OS_BITS 16\|32\|64	Set NASM instruction width — must be first in flat sources
OS_ORG	OS_ORG addr	Set origin address (NASM ORG). 0x7C00 for MBR, 0x0100 for COM.
OS_SECTION	OS_SECTION ".text"	Switch assembly section (OS mode only; no-op in flat)
OS_GLOBAL	OS_GLOBAL sym	Export symbol (NASM global directive)
OS_ALIGN	OS_ALIGN n [, fill]	Align to power-of-two boundary, fill gaps (default 0x00)
OS_TIMES	OS_TIMES count, byte	NASM TIMES directive — repeat byte value count times
OS_BOOT_SIG	OS_BOOT_SIG	Pad to 510 bytes + emit 0xAA55 boot signature. Must be last in MBR.
OS_MULTIBOOT	OS_MULTIBOOT [flags]	Emit Multiboot 1 header (magic + flags + checksum) for GRUB

CPU Control & Interrupts

Opcode	Syntax	Description
OS_CLI	OS_CLI	Clear interrupt flag (disable hardware IRQs)
OS_STI	OS_STI	Set interrupt flag (enable hardware IRQs)
OS_HLT	OS_HLT	Halt until next interrupt — generates hlt in a loop
OS_NOP	OS_NOP	Emit a single NOP instruction (timing padding)
OS_IRET	OS_IRET [bits]	Interrupt return — iretq (64-bit) or iret (16/32-bit)
OS_RING	OS_RING 0\|3	Declare privilege ring for documentation/codegen hints
OS_SET_ISR	OS_SET_ISR vector, handler	Dynamically patch running IDT entry at vector to handler

Hardware I/O & VGA & Serial

Opcode	Syntax	Description
OS_OUTB	OS_OUTB port, val	Write byte to x86 I/O port
OS_OUTW	OS_OUTW port, val	Write word to x86 I/O port
OS_INB	OS_INB dest, port	Read byte from I/O port into variable
OS_INW	OS_INW dest, port	Read word from I/O port into variable
OS_VGA_CLEAR	OS_VGA_CLEAR [attr]	Fill 80×25 VGA text screen with spaces and attribute byte
OS_VGA_PUTC	OS_VGA_PUTC col, row, char, attr	Write one character at (col, row) with attribute
OS_VGA_PUTS	OS_VGA_PUTS col, row, str, attr	Write NUL-terminated string starting at (col, row)
OS_SERIAL_INIT	OS_SERIAL_INIT port, baud	Initialise 16550-compatible UART at I/O port
OS_SERIAL_PUTC	OS_SERIAL_PUTC port, char	Transmit one byte — blocks until TX FIFO has space
OS_SERIAL_PUTS	OS_SERIAL_PUTS port, str	Transmit a NUL-terminated string

Descriptor Tables, Paging & Memory

Opcode	Syntax	Description
OS_GDT_ENTRY	OS_GDT_ENTRY base, limit, access, flags	Emit 8-byte GDT segment descriptor inline
OS_IDT_ENTRY	OS_IDT_ENTRY offset, selector, type_attr	Emit 8-byte IDT gate descriptor
OS_LGDT	OS_LGDT gdtr_label	Load GDT register
OS_LIDT	OS_LIDT idtr_label	Load IDT register
OS_MAP_PAGE	OS_MAP_PAGE virt, phys, flags	Map one 4 KiB page (flags: 0x1=present, 0x2=write, 0x4=user)
OS_UNMAP_PAGE	OS_UNMAP_PAGE virt	Unmap page and flush TLB entry (INVLPG)
OS_PHYS_ALLOC	OS_PHYS_ALLOC dest, pages	Simulate allocating pages consecutive 4 KiB frames
OS_PHYS_FREE	OS_PHYS_FREE addr, pages	Release physical frames

Raw Data Directives

Opcode	Syntax	Description
OS_DB	OS_DB b1 [, b2, ...]	Emit byte(s) — strings supported: OS_DB "Hello", 0
OS_DW	OS_DW w1 [, w2, ...]	Emit 16-bit little-endian word(s)
OS_DD	OS_DD d1 [, d2, ...]	Emit 32-bit dword(s)
OS_DQ	OS_DQ q1 [, q2, ...]	Emit 64-bit qword(s) — supports label references

Running in QEMU

qemu workflow

# ── Flat binary (MBR bootloader) ────────────────────────────────────
CDNEE-CC hello_mbr.cdnee --flat
# Produces hello_mbr.bin — exactly 512 bytes

qemu-system-i386 -drive format=raw,file=hello_mbr.bin -nographic
qemu-system-i386 -drive format=raw,file=hello_mbr.bin -serial stdio

# ── ELF64 kernel (Multiboot) ─────────────────────────────────────────
CDNEE-CC kernel.cdnee --os --load-addr 0x100000
# Produces kernel.elf — boot with GRUB or QEMU -kernel

qemu-system-x86_64 -kernel kernel.elf -serial stdio -nographic

# ── Inspection ────────────────────────────────────────────────────────
xxd hello_mbr.bin | tail -2           # check boot signature 55 AA
ndisasm -b 16 hello_mbr.bin | head -40 # disassemble MBR
readelf -S kernel.elf                  # ELF sections
objdump -d kernel.elf | head -80       # disassemble .text

# ── Interpreter simulation (no QEMU needed) ───────────────────────────
CDNEE --os-sim --os-vga --os-state kernel.cdnee

10 — Version History

Version History

CDNEE has evolved rapidly since its initial release. Each version adds significant capabilities to the execution engine and language surface.

Version	Notable Changes
v1.0	OS development tier — CDNEE-CC compiler with `--flat` (MBR/COM) and `--os` (ELF64 kernel) modes; OS opcodes (OS_BITS, OS_ORG, OS_VGA_, OS_SERIAL_, OS_GDT_ENTRY, OS_IDT_ENTRY, OS_MAP_PAGE, OS_PHYS_ALLOC, OS_DB/DW/DD/DQ, OS_BOOT_SIG, OS_MULTIBOOT); QEMU integration; interpreter simulation mode (--os-sim, --os-state, --os-vga, --os-image)
v1.0	ExternFileNode, ExternSymNode, ExternLibNode; CDNEE_CTYPES_MAP; _source_dir resolution; full FFI guide with .cdneef header imports and alias_prefix namespacing
v1.0	Dot-label support (.name:) following NASM/GAS convention; Lexer fixes FIX-1 through FIX-5; keyword label-peek disambiguation
v1.0	JitCompileNode argtypes/rettype fields; DneeCallNode; full type system with i8/u8/i16/u16/i32/u32/i64/u64/f32/f64/ptr/bool/void
v1.0	Tier-2 JIT/MEX engine; binary export/import (EXPORT_BIN, IMPORT_BIN, CALL_BIN, BIN_CONTEXT); memory operations (FREEZE, THAW, SNAPSHOT, RESTORE, CLONE, COPY_ON_WRITE, TRAMPOLINE); hot patching; profiling and stats
v1.0	Tier-1 math library (50+ native ops), control flow (CMP/JE/JNE/JLT/JGT/JLE/JGE/JMP), functions (FUNC/CALL/RETURN), error handling (TRY/CATCH/END), basic I/O

CDNEE Write High. Run Native.

What is CDNEE?

Execution Model

Program Structure & Syntax

Hello World

Variables & Arithmetic

Control Flow

Functions

Error Handling

Inline JIT Assembly

Conditional Jump Opcodes

Auto-Set Runtime Variables

Tier-1 Standard Library

Stdlib Usage Example

JIT Compilation & Memory Control

JIT Type System

JIT Operations

JIT + Patching Example

FFI — Native Library Bindings

EXTERN — .cdneef Headers

EXTERN_FUNC — Native Symbols

Portable Math Example

Portable Short Library Names

CLI & Compiler Reference

CDNEE — Interpreter Flags

CDNEE-CC — Compiler Flags

CDNEE-CC Usage Examples

REPL Commands

OS Development Tier

Hello from the Bootloader

OS Opcode Reference

Running in QEMU

File Extensions

Version History