Architecture

Architecture Overview

JNode is a monolithic Java OS structured in six layers, from user-facing applications down to native x86 assembly.

System Layers

┌──────────────────────────────────────────────────────────┐
│  6. Applications / Shell     shell/, cli/                │
├──────────────────────────────────────────────────────────┤
│  5. OS Services              fs/, net/, gui/, sound/     │
├──────────────────────────────────────────────────────────┤
│  4. Core OS / Kernel         core/src/core/              │
│     Plugin manager, naming, security, system resources   │
├──────────────────────────────────────────────────────────┤
│  3. Driver Framework         core/src/driver/            │
│     Device manager, bus drivers, console, serial, input  │
├──────────────────────────────────────────────────────────┤
│  2. Virtual Machine          core/src/core/.../vm/       │
│     JIT compilers, classloading, GC, scheduler, unsafe   │
├──────────────────────────────────────────────────────────┤
│  1. Native / Assembly        core/src/native/x86/        │
│     Multiboot entry, interrupt handlers, memory mgmt     │
└──────────────────────────────────────────────────────────┘

Key Entry Points

What	File	Notes
Multiboot entry	core/src/native/x86/kernel.asm	GRUB loads this; sets up stack, copies multiboot info, jumps to VM
VM bootstrap	core/src/native/x86/vm.asm	Native VM support: method invocation, stack walking
Java entry point	core/src/core/org/jnode/boot/Main.java	vmMain() — first Java code after assembly bootstrap
VM initialization	core/src/core/org/jnode/vm/VmSystem.java	initialize() — sets up classloaders, memory, system properties
Plugin manager	core/src/core/org/jnode/plugin/manager/DefaultPluginManager.java	Loads and starts all system plugins
Scheduler	core/src/core/org/jnode/vm/scheduler/VmScheduler.java	Thread scheduling
JIT L1 compiler	core/src/core/org/jnode/vm/x86/compiler/l1/	Simple stack-based compiler
JIT L2 compiler	core/src/core/org/jnode/vm/x86/compiler/l2/	Optimizing compiler with register allocation

Core Package Structure

Package	Purpose
org.jnode.boot	Boot sequence: Main, InitJarProcessor
org.jnode.vm	VM core: VmSystem, Unsafe, VmMagic, classloaders
org.jnode.vm.bytecode	Bytecode parsing and analysis
org.jnode.vm.classmgr	Class metadata: VmType, VmMethod, VmField, VmCompiledCode
org.jnode.vm.compiler	Compiler framework and IR
org.jnode.vm.compiler.ir	Intermediate representation for L2 compiler
org.jnode.vm.facade	VM API interfaces: Vm, VmArchitecture, VmHeapManager
org.jnode.vm.isolate	Process isolation (isolates)
org.jnode.vm.memmgr	Memory management, heap
org.jnode.vm.objects	Low-level object layout
org.jnode.vm.performance	Performance counters
org.jnode.vm.scheduler	Thread scheduler: VmThread, VmProcessor, Monitor
org.jnode.vm.x86	x86-specific VM: VmX86Architecture, x86 compilers
org.jnode.plugin	Plugin framework: descriptors, extensions, classloaders
org.jnode.plugin.manager	Plugin lifecycle management
org.jnode.plugin.model	XML descriptor parsing and plugin model
org.jnode.system.resource	Hardware resources: IRQ, DMA, I/O ports, memory-mapped I/O
org.jnode.naming	Service registry (InitialNaming)

How the Layers Interact

Boot → VM → Plugins → Services

1. GRUB loads the boot image (built by BootImageBuilder) via Multiboot
2. kernel.asm sets up the CPU, stack, and paging, then jumps to the VM
3. VmSystem.initialize() brings up classloading, memory management, and the scheduler
4. Main.vmMain() creates the PluginManager and loads plugins from the init-jar
5. Plugins register services via InitialNaming (a simple JNDI-like registry)
6. Services (filesystem, network, GUI) start as plugins and register their APIs

Driver Model

Drivers are plugins that register with the DeviceManager. Each driver:

• Has an XML descriptor in <subproject>/descriptors/
• Declares dependencies via <requires> / <import>
• Exports packages via <runtime> / <library> / <export>
• Is loaded by the plugin classloader hierarchy

See Plugin-System and Driver-Framework for details.

The Facade Pattern

The org.jnode.vm.facade package provides interfaces (Vm, VmArchitecture, VmHeapManager, etc.) that abstract the VM internals. Code outside the VM layer should use these interfaces, not the concrete implementations in org.jnode.vm.

Gotchas & Non-Obvious Behavior

• No host OS — JNode does not run on Linux/Windows. It IS the OS. There's no System.exit() that returns to a shell — VmExit halts the machine.
• Single address space — All code runs in one address space. Process isolation is via VmProcess / isolates, not virtual memory separation.
• Boot image — The BootImageBuilder (in builder/) pre-compiles core classes and bakes them into the ISO. This means some code runs differently at build time vs. boot time.
• InitialNaming — Services are registered and looked up via org.jnode.naming.InitialNaming, which is a simple name→object map. It's JNode's equivalent of a service registry. See InitialNaming-Service-Registry.
• VmMagic / Unsafe — Many VM-level operations use org.jnode.vm.Unsafe or magic annotations. These bypass normal Java semantics. See VM-Magic.
• Plugin classloader hierarchy — Each plugin gets its own classloader. Cross-plugin class visibility is controlled by <import> and <export> in the descriptor XML.

Related Pages

• Boot-Sequence — Detailed boot flow
• Plugin-System — How plugins and extensions work
• JIT-Compilers — How bytecode becomes native code
• Interrupt-Handling — IDT setup, CPU exceptions, hardware IRQ dispatch, PIC/APIC
• Memory-Management — GC, paging, address spaces
• VM-Magic — Annotations that break normal Java rules
• Object-Layout — Internal representation of Java objects in memory
• Thread-Scheduling — Thread states, preemptive/cooperative scheduling, @Uninterruptible