Skip to content

Commit a952237

Browse files
LSanthaLSantha
committed
docs: add MkDocs Material site for GitHub Pages
- Curated getting-started guides (build, QEMU, VirtualBox) - Architecture overview with component diagram - Development workflow (build, test, debug) - Subsystem reference tables with wiki deep-links - Command/boot-param/config reference - MkDocs Material config with search, revision dates, minify - GitHub Actions workflow for auto-deploy to Pages
1 parent 0e785b2 commit a952237

13 files changed

Lines changed: 1343 additions & 0 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths:
7+
- 'website/**'
8+
- 'mkdocs.yml'
9+
- '.github/workflows/pages.yml'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0 # needed for git-revision-date-localized plugin
29+
30+
- name: Setup Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.11'
34+
35+
- name: Install MkDocs
36+
run: |
37+
pip install --upgrade pip
38+
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin
39+
40+
- name: Build Site
41+
run: mkdocs build --strict --verbose
42+
43+
- name: Upload Artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: ./site
47+
48+
deploy:
49+
needs: build
50+
runs-on: ubuntu-latest
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ classlib.pack.gz
1717
/.idea/
1818
/.wiki/
1919
__pycache__/
20+
site/

‎mkdocs.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
site_name: JNode
2+
site_description: A Java Operating System
3+
site_url: https://lsantha.github.io/jnode_ai_oc
4+
repo_url: https://github.com/LSantha/jnode_ai_oc
5+
repo_name: LSantha/jnode_ai_oc
6+
edit_uri: edit/master/website/
7+
8+
docs_dir: website
9+
site_dir: site
10+
11+
theme:
12+
name: material
13+
palette:
14+
- scheme: default
15+
primary: indigo
16+
accent: indigo
17+
- scheme: slate
18+
primary: indigo
19+
accent: indigo
20+
features:
21+
- navigation.tabs
22+
- navigation.sections
23+
- navigation.expand
24+
- navigation.top
25+
- search.highlight
26+
- search.share
27+
- content.code.copy
28+
- content.code.annotate
29+
30+
nav:
31+
- Home: index.md
32+
- Getting Started:
33+
- Quick Start: getting-started/quick-start.md
34+
- Building: getting-started/building.md
35+
- Running in QEMU: getting-started/qemu.md
36+
- Running in VirtualBox: getting-started/virtualbox.md
37+
- Architecture:
38+
- Overview: architecture/overview.md
39+
- Development:
40+
- Build & Test: development/index.md
41+
- Testing: development/testing.md
42+
- Subsystems: subsystems.md
43+
- Reference: reference.md
44+
- Wiki: https://github.com/LSantha/jnode_ai.wiki/wiki
45+
46+
markdown_extensions:
47+
- admonition
48+
- codehilite:
49+
guess_lang: false
50+
- toc:
51+
permalink: true
52+
- pymdownx.highlight:
53+
anchor_linenums: true
54+
- pymdownx.inlinehilite
55+
- pymdownx.snippets
56+
- pymdownx.superfences
57+
- pymdownx.tabbed:
58+
alternate_style: true
59+
- pymdownx.tasklist:
60+
custom_checkbox: true
61+
- attr_list
62+
- md_in_html
63+
64+
plugins:
65+
- search
66+
- git-revision-date-localized:
67+
enable_creation_date: true
68+
- minify:
69+
minify_html: true

‎website/architecture/overview.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Architecture Overview
2+
3+
## High-Level Components
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────┐
7+
│ Boot Loader │
8+
│ (GRUB → kernel.asm) │
9+
└──────────────────────────┬──────────────────────────────────┘
10+
│
11+
┌──────────────────────────▼──────────────────────────────────┐
12+
│ Kernel │
13+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
14+
│ │ Scheduler │ │ Memory Mgmt│ │ Interrupt Handling │ │
15+
│ │ (Isolate) │ │ (MMTk/GC) │ │ (IDT, PIC, APIC) │ │
16+
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
17+
└──────────────────────────┬──────────────────────────────────┘
18+
│
19+
┌──────────────────────────▼──────────────────────────────────┐
20+
│ VmImpl (JVM) │
21+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
22+
│ │ Classloader│ │ JIT Compiler│ │ VM Magic / Unsafe │ │
23+
│ │ (Plugin) │ │ (L1 / L2) │ │ (VMMagic annos) │ │
24+
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
25+
└──────────────────────────┬──────────────────────────────────┘
26+
│
27+
┌──────────────────────────▼──────────────────────────────────┐
28+
│ Plugin System │
29+
│ PluginDescriptor → PluginManager → Extension Points │
30+
└──────────────────────────┬──────────────────────────────────┘
31+
│
32+
┌──────────────────┼──────────────────┐
33+
▼ ▼ ▼
34+
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
35+
│ Core Services│ │ Drivers │ │ Filesystems │
36+
│ (Naming, │ │ (PCI, USB, │ │ (Ext2, FAT, │
37+
│ Security, │ │ IDE, Net, │ │ ISO9660, │
38+
│ Logging) │ │ Audio) │ │ NFS, NTFS) │
39+
└───────────────┘ └───────────────┘ └───────────────┘
40+
│ │ │
41+
▼ ▼ ▼
42+
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
43+
│ Network Stack│ │ Shell │ │ GUI/AWT │
44+
│ (IPv4, TCP, │ │ (Commands, │ │ (Video, │
45+
│ UDP, DNS) │ │ Aliases, │ │ Input, │
46+
│ │ │ Plugins) │ │ Thinlet) │
47+
└───────────────┘ └───────────────┘ └───────────────┘
48+
```
49+
50+
## Key Design Principles
51+
52+
### 1. Java-First
53+
> 95%+ of code is Java. Only ~25 assembly files for:
54+
- `kernel.asm` — entry point, GDT/IDT setup, context switch
55+
- `vm.asm` — VM primitives, stack frame layout, safepoints
56+
- `mm32.asm` / `mm64.asm` — Memory management, page tables
57+
- `apic.asm` — Local APIC, IPI handling
58+
59+
### 2. Isolate-Based Architecture
60+
JNode uses **Isolates** (similar to processes but lighter-weight):
61+
- Each isolate has its own classloader, heap, thread groups
62+
- Communication via **channels** (typed message passing)
63+
- Security via **capabilities** (unforgeable references)
64+
- See [Isolate Implementation](https://github.com/LSantha/jnode_ai.wiki/wiki/Isolate-Implementation)
65+
66+
### 3. Plugin System
67+
- **PluginDescriptor** (XML) declares exports/imports
68+
- **PluginManager** resolves dependencies at boot
69+
- Extension points for: filesystems, drivers, shell commands, network layers
70+
- See [Plugin System](https://github.com/LSantha/jnode_ai.wiki/wiki/Plugin-System)
71+
72+
### 4. MMTk Integration
73+
- **Memory Management Toolkit** (Rust) for GC
74+
- JNode binds via JNI: `org.jnode.vm.memmgr.mmtk`
75+
- Supports: Immix, GenImmix, MarkSweep, SemiSpace
76+
- See [MMTk Bindings](https://github.com/LSantha/jnode_ai.wiki/wiki/MMTk-Bindings)
77+
78+
### 5. VMMagic Annotations
79+
- `@Uninterruptible`, `@Inline`, `@Offset`, `@Address`
80+
- Enable low-level operations in Java
81+
- Processed by JNasm and BootImageBuilder
82+
- See [VMMagic Annotations](https://github.com/LSantha/jnode_ai.wiki/wiki/VMMagic-Annotations)
83+
84+
## Boot Sequence
85+
86+
1. **GRUB** loads `kernel.asm` at 1 MB
87+
2. **kernel.asm**: GDT, IDT, paging, enter protected mode
88+
3. **VmImpl.<clinit>**: Boot classloader, VM magic init
89+
4. **PluginManager**: Load `default-plugin-list.xml`
90+
5. **Core services**: Naming, Security, DeviceManager
91+
6. **Drivers**: PCI enumeration, device matching
92+
7. **Filesystems**: Mount root (ISO9660 → ramdisk)
93+
8. **Shell**: Start `init` isolate → command prompt
94+
95+
See [Boot Sequence](https://github.com/LSantha/jnode_ai.wiki/wiki/Boot-Sequence) for detailed trace.
96+
97+
## Memory Layout (x86, 32-bit)
98+
99+
```
100+
0xFFFFFFFF ┌─────────────────────┐
101+
│ Kernel Space │ 1 GB (0xC0000000–0xFFFFFFFF)
102+
│ (Identity mapped) │
103+
0xC0000000 ├─────────────────────┤
104+
│ User / Isolate │ 3 GB (0x00000000–0xBFFFFFFF)
105+
│ Heaps, Stacks │
106+
0x00000000 └─────────────────────┘
107+
```
108+
109+
- **Kernel** runs at high addresses (negative pointers)
110+
- **Isolates** allocated in low 3 GB
111+
- **Direct memory** via `VmUnsafe` for DMA, framebuffer
112+
113+
See [Paging Implementation](https://github.com/LSantha/jnode_ai.wiki/wiki/Paging-Implementation) and [Memory Management](https://github.com/LSantha/jnode_ai.wiki/wiki/Memory-Management).
114+
115+
## Threading & Scheduling
116+
117+
- **Green threads** mapped 1:1 to kernel threads
118+
- **Priority-based preemptive** scheduler
119+
- **Yieldpoints** at method calls, loop backedges, allocations
120+
- **IsolateThread** = Java thread + kernel context
121+
- See [Core Thread Scheduling](https://github.com/LSantha/jnode_ai.wiki/wiki/Core-Thread-Scheduling)
122+
123+
## JIT Compilers
124+
125+
| Compiler | Tier | Status |
126+
|----------|------|--------|
127+
| **L1** | Baseline | ✅ Stable |
128+
| **L2** | Optimizing | ⚠️ Experimental |
129+
| **None** | Interpreter | ✅ Always available |
130+
131+
- L1: Fast compilation, basic optimization
132+
- L2: SSA-based, inlining, escape analysis
133+
- Selected via `jnode.compiler` property
134+
- See [JIT Compilers](https://github.com/LSantha/jnode_ai.wiki/wiki/JIT-Compilers)
135+
136+
## Further Reading
137+
138+
| Topic | Wiki Page |
139+
|-------|-----------|
140+
| Kernel Entry Point | [Kernel-Entry-Point](https://github.com/LSantha/jnode_ai.wiki/wiki/Kernel-Entry-Point) |
141+
| Device Manager | [Device-Manager](https://github.com/LSantha/jnode_ai.wiki/wiki/Device-Manager) |
142+
| Driver Framework | [Driver-Framework](https://github.com/LSantha/jnode_ai.wiki/wiki/Driver-Framework) |
143+
| Filesystem Layer | [Filesystem-Layer](https://github.com/LSantha/jnode_ai.wiki/wiki/Filesystem-Layer) |
144+
| Network Stack | [Network-Stack](https://github.com/LSantha/jnode_ai.wiki/wiki/Network-Stack) |
145+
| Object Layout | [Object-Layout](https://github.com/LSantha/jnode_ai.wiki/wiki/Object-Layout) |
146+
| Stack Frame Layout | [Stack-Frame-Layout](https://github.com/LSantha/jnode_ai.wiki/wiki/Stack-Frame-Layout) |
147+
| Virtual Methods Dispatch | [Virtual-Methods-Dispatch](https://github.com/LSantha/jnode_ai.wiki/wiki/Virtual-Methods-Dispatch) |

0 commit comments

Comments
 (0)