Skip to content

Commit bd459ff

Browse files
committed
docs: correct feature claims across website pages
Fix unrealistic wording verified against source: shell commands, build targets and properties, MMTk plans, JIT compiler tiers, filesystem read/write status, driver lists, JDWP port, and boot parameters. Restore 'Developed with AI Agents' section on front page. Remove JDWP integration test coverage from docs.
1 parent 1082530 commit bd459ff

9 files changed

Lines changed: 114 additions & 170 deletions

File tree

website/architecture/overview.md

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@
1212
│ Kernel │
1313
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
1414
│ │ Scheduler │ │ Memory Mgmt│ │ Interrupt Handling │ │
15-
│ │ (Isolate) │ │ (MMTk/GC) │ │ (IDT, PIC, APIC) │ │
15+
│ │ (Isolate) │ │ (def/GC) │ │ (IDT, PIC, APIC) │ │
1616
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
1717
└──────────────────────────┬──────────────────────────────────┘
1818
1919
┌──────────────────────────▼──────────────────────────────────┐
2020
│ VmImpl (JVM) │
2121
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
2222
│ │ Classloader│ │ JIT Compiler│ │ VM Magic / Unsafe │ │
23-
│ │ (Plugin) │ │ (L1 / L2) │ │ (VMMagic annos) │ │
23+
│ │ (Plugin) │ │ (L1a/L1b/L2)│ │ (VMMagic annos) │ │
2424
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
2525
└──────────────────────────┬──────────────────────────────────┘
2626
@@ -35,7 +35,7 @@
3535
│ Core Services│ │ Drivers │ │ Filesystems │
3636
│ (Naming, │ │ (PCI, USB, │ │ (Ext2, FAT, │
3737
│ Security, │ │ IDE, Net, │ │ ISO9660, │
38-
│ Logging) │ │ Audio) │ │ NFS, NTFS) │
38+
│ Logging) │ │ Video) │ │ NFS, NTFS) │
3939
└───────────────┘ └───────────────┘ └───────────────┘
4040
│ │ │
4141
▼ ▼ ▼
@@ -70,9 +70,9 @@ JNode uses **Isolates** (similar to processes but lighter-weight):
7070
- See [Plugin System](https://github.com/LSantha/jnode_ai/wiki/Plugin-System)
7171

7272
### 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
73+
- **Memory Management Toolkit** bindings for garbage collection
74+
- Available MMTk plans: `org.jnode.vm.memmgr.mmtk.ms` (MarkSweep), `...genrc` (generational), `...nogc` (no collection)
75+
- Default memory manager is `org.jnode.vm.memmgr.def`; MMTk plans are experimental
7676
- See [MMTk Bindings](https://github.com/LSantha/jnode_ai/wiki/MMTk-Bindings)
7777

7878
### 5. VMMagic Annotations
@@ -124,13 +124,12 @@ See [Paging Implementation](https://github.com/LSantha/jnode_ai/wiki/Paging-Impl
124124

125125
| Compiler | Tier | Status |
126126
|----------|------|--------|
127-
| **L1** | Baseline | ✅ Stable |
128-
| **L2** | Optimizing | ⚠️ Experimental |
129-
| **None** | Interpreter | ✅ Always available |
127+
| **L1A / L1B** | Baseline | Default |
128+
| **Stub** | Stub generation | For non-Java natives |
129+
| **L2** | Optimizing | Test-only, not selected at boot |
130130

131-
- L1: Fast compilation, basic optimization
132-
- L2: SSA-based, inlining, escape analysis
133-
- Selected via `jnode.compiler` property
131+
- L1A/L1B: baseline bytecode compilers; `jnode.compiler` accepts `L1A`, `L1B`, or `default` (→ L1A)
132+
- L2: optimizing compiler, used only in test harness (`testCompilers`)
134133
- See [JIT Compilers](https://github.com/LSantha/jnode_ai/wiki/JIT-Compilers)
135134

136135
## Further Reading

website/development/index.md

Lines changed: 4 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -76,21 +76,6 @@ sh build.sh regression-tests
7676

7777
Runs shell command tests against a booted JNode image.
7878

79-
### JDWP Integration Tests
80-
81-
Requires a **running JNode VM with JDWP listener** (VirtualBox recommended):
82-
83-
```bash
84-
# Start JNode in VirtualBox with JDWP on port 8000
85-
# Then run:
86-
cd tests/jdwp
87-
python3 -m pytest -v
88-
```
89-
90-
- 75 tests covering: classes, methods, fields, threads, invocation, constructors
91-
- See [tests/jdwp/AGENTS.md](https://github.com/LSantha/jnode_ai/blob/master/tests/jdwp/AGENTS.md) for setup
92-
- **Run these after any JDWP code change** — they are the regression suite
93-
9479
### Boot Testing
9580

9681
```bash
@@ -129,8 +114,8 @@ See [jnode-interact skill](https://github.com/LSantha/jnode_ai/blob/master/.open
129114
Best with VirtualBox:
130115

131116
1. Enable Serial Port 1 → Host Pipe → `/tmp/jnode-com1`
132-
2. Port forward: `VBoxManage modifyvm "JNode" --natpf1 "jdwp,tcp,,8000,,8000"`
133-
3. Connect: `jdb -attach localhost:8000`
117+
2. Port forward: `VBoxManage modifyvm "JNode" --natpf1 "jdwp,tcp,,6789,,6789"`
118+
3. Connect: `jdb -attach localhost:6789`
134119

135120
See [VirtualBox Guide](../getting-started/virtualbox.md) for JDWP setup.
136121

@@ -181,20 +166,10 @@ The project uses a label system managed by [sync-labels.js](https://github.com/L
181166

182167
| Family | Examples |
183168
|--------|----------|
184-
| `kind/*` | `kind/bug`, `kind/feature`, `kind/investigate`, `kind/wiki` |
169+
| `kind/*` | `kind/bug`, `kind/feature`, `kind/investigate`, `kind/chore` |
185170
| `agent/*` | `agent/in-progress`, `agent/done`, `agent/needs-info` |
186171
| `area/*` | `area/core`, `area/fs`, `area/net`, `area/vm`, `area/build` |
187172

188173
### Agent Automation
189174

190-
Trigger OpenCode agent via issue comments:
191-
192-
```bash
193-
/oc fix # Fix the issue
194-
/oc investigate # Investigate and report
195-
/oc review # Review a PR
196-
/oc wiki # Update wiki
197-
/oc triage # Triage new issue
198-
```
199-
200-
See [opencode.yml](https://github.com/LSantha/jnode_ai/blob/master/.github/workflows/opencode.yml) and [jnode-issue-resolver skill](https://github.com/LSantha/jnode_ai/blob/master/.opencode/skills/jnode-issue-resolver/SKILL.md).
175+
An experimental agent-based workflow exists for triaging and resolving issues. It's still exploratory — see [opencode.yml](https://github.com/LSantha/jnode_ai/blob/master/.github/workflows/opencode.yml) and [jnode-issue-resolver skill](https://github.com/LSantha/jnode_ai/blob/master/.opencode/skills/jnode-issue-resolver/SKILL.md) for details.

website/development/testing.md

Lines changed: 8 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
|------|---------|-------------|
77
| **JUnit** | `sh build.sh tests` | Unit tests for all subprojects |
88
| **Regression** | `sh build.sh regression-tests` | Shell command integration tests |
9-
| **JDWP** | `pytest tests/jdwp/` | Remote debugging protocol tests |
109
| **Boot** | QEMU/VirtualBox | Full OS boot verification |
1110

1211
## JUnit Tests
@@ -38,37 +37,6 @@ sh build.sh regression-tests
3837

3938
Tests are defined in `tests/regression/` and executed via the shell.
4039

41-
## JDWP Integration Tests
42-
43-
**Requirements:**
44-
- JNode running in VirtualBox with JDWP listener on port 8000
45-
- Serial console configured (for agent interaction)
46-
- Python 3.8+ with pytest
47-
48-
```bash
49-
# 1. Start JNode in VirtualBox (see VirtualBox guide)
50-
# 2. Verify JDWP: telnet localhost 8000 → "JDWP Handshake"
51-
# 3. Run tests
52-
cd tests/jdwp
53-
python3 -m pytest -v
54-
```
55-
56-
### Test Coverage (75 tests)
57-
58-
| Category | Tests |
59-
|----------|-------|
60-
| Classes, methods, fields | 18 |
61-
| Threads, thread groups | 12 |
62-
| Stack traces (`where`) | 8 |
63-
| Classpath, connectors | 6 |
64-
| Method invocation | 15 |
65-
| Constructors | 10 |
66-
| Version, capabilities | 6 |
67-
68-
**Run after any JDWP code change** — this is the regression suite for the debug backend.
69-
70-
See [tests/jdwp/AGENTS.md](https://github.com/LSantha/jnode_ai/blob/master/tests/jdwp/AGENTS.md) for full setup.
71-
7240
## Boot Testing
7341

7442
### QEMU (CI)
@@ -134,11 +102,12 @@ The [ant.yml](https://github.com/LSantha/jnode_ai/blob/master/.github/workflows/
134102

135103
## Test Utilities
136104

137-
| Tool | Purpose |
138-
|------|---------|
139-
| `jnode-interact` skill | Interactive QEMU testing via serial |
140-
| `jnode-java-coding` skill | Compile/run Java on live JNode |
141-
| `filesystem-debug` skill | Analyze FS test failures |
142-
| `jnode-kdb-serial` skill | Kernel debugger via serial |
105+
| Tool | Purpose | Location |
106+
|------|---------|----------|
107+
| `jnode-interact` skill | Interactive QEMU testing via serial | repo `.opencode/skills/` |
108+
| `filesystem-debug` skill | Analyze FS test failures | repo `.opencode/skills/` |
109+
| `jnode-issue-resolver` skill | Issue/PR resolution protocol | repo `.opencode/skills/` |
110+
| `jnode-java-coding` skill | Compile/run Java on live JNode | user config |
111+
| `jnode-kdb-serial` skill | Kernel debugger via serial | user config |
143112

144-
See [.opencode/skills/](https://github.com/LSantha/jnode_ai/tree/master/.opencode/skills) for available debugging skills.
113+
See [.opencode/skills/](https://github.com/LSantha/jnode_ai/tree/master/.opencode/skills) for the repo's skills.

website/getting-started/building.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ sh build.sh <target> [options]
1313
| Target | Description |
1414
|--------|-------------|
1515
| `assemble` | Compile Java, build native, create bootimage (no ISO) |
16-
| `cd-x86-lite` | **Minimal x86 ISO**kernel, shell, basic drivers (~15 MB) |
17-
| `cd-x86_64-lite` | Minimal x86_64 ISO (experimental) |
18-
| `cd-x86` | Full x86 ISO with GUI, network, all plugins |
16+
| `cd-x86-lite` | Bootable x86 CD image (kernel, shell, core subsystems) |
17+
| `cd-x86_64-lite` | Bootable x86_64 CD image (experimental) |
18+
| `cd-x86` | Same as `cd-x86-lite`, plus source tarball included on the CD |
1919
| `tests` | Run all JUnit + regression tests |
2020
| `clean` | Remove all build artifacts |
2121

@@ -57,10 +57,12 @@ Key properties in `jnode.properties` or via `-D`:
5757
| Property | Default | Description |
5858
|----------|---------|-------------|
5959
| `jnode.bits` | `32` | Target architecture: `32` or `64` |
60-
| `jnode.memmgr.plugin.id` | `org.jnode.vm.memmgr.mmtk.MMTkMemoryManager` | GC implementation |
61-
| `jnode.compiler` | `l1` | JIT: `l1`, `l2`, or `none` |
60+
| `jnode.memmgr.plugin.id` | `org.jnode.vm.memmgr.def` | Memory manager; alternatives: `org.jnode.vm.memmgr.mmtk.nogc` (beta), `org.jnode.vm.memmgr.mmtk.genrc` (alpha), `org.jnode.vm.memmgr.mmtk.ms` |
61+
| `jnode.compiler` | `default` | JIT compiler: `L1A`, `L1B`, or `default` |
6262
| `jnode.enable.jnasm` | `true` | Use JNasm assembler |
63-
| `jnode.plugin.list` | `default-plugin-list.xml` | Plugin set: `default` or `full` |
63+
| `target.plugin.list` | `default` | Plugin set for the jar packager: `default` or `full` |
64+
65+
The bootimage itself always uses `all/conf/system-plugin-list.xml`.
6466

6567
## Build Output Structure
6668

website/getting-started/quick-start.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Quick Start
22

3-
Get JNode running in 5 minutes.
3+
Build a JNode ISO and boot it in QEMU.
44

55
## Prerequisites
66

@@ -44,9 +44,9 @@ jnode>
4444
```bash
4545
jnode> help
4646
jnode> ls /
47-
jnode> ps
47+
jnode> memory
4848
jnode> vminfo
49-
jnode> mem
49+
jnode> uname
5050
```
5151

5252
Type `exit` to shut down cleanly.

website/getting-started/virtualbox.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,18 +36,18 @@ You'll see the boot banner and shell prompt.
3636

3737
## JDWP Remote Debugging
3838

39-
JNode listens for JDWP on port **8000** by default (configured in `jnode.properties`).
39+
JNode's `debug` command starts a JDWP listener on port **6789** by default (override with the `port` argument).
4040

4141
### Port Forwarding (NAT)
4242

4343
```bash
44-
VBoxManage modifyvm "JNode" --natpf1 "jdwp,tcp,,8000,,8000"
44+
VBoxManage modifyvm "JNode" --natpf1 "jdwp,tcp,,6789,,6789"
4545
```
4646

4747
### Connect with jdb
4848

4949
```bash
50-
jdb -attach localhost:8000
50+
jdb -attach localhost:6789
5151
```
5252

5353
### Supported JDWP Features
@@ -63,7 +63,7 @@ jdb -attach localhost:8000
6363
| Watchpoints ||
6464
| Breakpoints | ⚠️ Limited |
6565

66-
See [JDWP Setup Wiki](https://github.com/LSantha/jnode_ai/wiki/GDB-Debugging-Support) and [JDWP Tests](../development/testing.md#jdwp-integration-tests).
66+
See [JDWP Setup Wiki](https://github.com/LSantha/jnode_ai/wiki/GDB-Debugging-Support).
6767

6868
## Shared Folders (Optional)
6969

@@ -81,7 +81,7 @@ For file transfer between host and JNode:
8181
|-------|-----|
8282
| Boot hangs at "Loading..." | Ensure **I/O APIC** enabled, try `-cpu pentium` in QEMU first |
8383
| No serial output | Verify pipe path, check `socat` / PuTTY connection |
84-
| JDWP connection refused | Check port forwarding, firewall, `jnode.properties` `jdwp.port=8000` |
84+
| JDWP connection refused | Check port forwarding, firewall, `debug` command arguments |
8585
| Network not working | Try Bridged Adapter instead of NAT; check `dhcp eth0` |
8686

8787
## VM Export for Distribution

website/index.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,21 @@
44
[![Java 8](https://img.shields.io/badge/Java-8-blue.svg)](https://openjdk.java.net/projects/jdk/8/)
55
[![License](https://img.shields.io/badge/License-LGPL%202.1-green.svg)](https://www.gnu.org/licenses/lgpl-2.1.html)
66

7-
**JNode** is an experimental operating system written in Java. It builds its own JVM, kernel, drivers, filesystems, network stack, and GUI, and boots them on bare metal with only a few hundred lines of assembly at the very bottom. It's a platform for exploring OS design, JVM implementation, and system-level Java. This fork is developed at scale with modern AI-based, agentic methodologies — OpenCode agents resolve issues, review code, and boot-test every build.
7+
**JNode** is an experimental operating system written in Java. It builds its own JVM, kernel, drivers, filesystems, network stack, and GUI, and boots them on bare metal with only a few hundred lines of assembly at the very bottom. It's a platform for exploring OS design, JVM implementation, and system-level Java.
8+
9+
---
10+
11+
## Developed with AI Agents
12+
13+
This is a fork of the classic JNode project, maintained as a living experiment in agent-driven development. GitHub Actions and OpenCode agents triage issues, implement fixes, review pull requests, update the wiki, and boot every build in QEMU before it lands. Batching is coordinated through an orchestrator workflow, with agentic skills for QEMU boot testing, JDWP debugging, and filesystem diagnosis.
814

915
---
1016

1117
## Quick Links
1218

1319
| Topic | Description |
1420
|-------|-------------|
15-
| [:material-rocket-launch: Quick Start](getting-started/quick-start.md) | Build and boot your first JNode ISO in 5 minutes |
21+
| [:material-rocket-launch: Quick Start](getting-started/quick-start.md) | Build and boot your first JNode ISO |
1622
| [:material-hammer-wrench: Building](getting-started/building.md) | Detailed build instructions for x86 and x86_64 |
1723
| [:material-cpu-64-bit: Run in QEMU](getting-started/qemu.md) | Test JNode in QEMU with serial logging |
1824
| [:material-virtualbox: Run in VirtualBox](getting-started/virtualbox.md) | JDWP debugging support via VirtualBox |
@@ -48,7 +54,7 @@ See [Architecture Overview](architecture/overview.md) for details.
4854
| [Network Stack](subsystems.md#network-stack) | IPv4, TCP, UDP, DNS, NetAPI | [Network-Stack](https://github.com/LSantha/jnode_ai/wiki/Network-Stack) |
4955
| [Shell](subsystems.md#shell) | Commands, syntax, aliases, plugins | [Shell-Commands](https://github.com/LSantha/jnode_ai/wiki/Shell-Commands) |
5056
| [GUI/AWT](subsystems.md#gui-awt) | Video drivers, input, AWT peers, Thinlet | [GUI-AWT](https://github.com/LSantha/jnode_ai/wiki/GUI-AWT) |
51-
| [Drivers](subsystems.md#drivers) | PCI, USB, IDE, SCSI, Ethernet, Audio | [Driver-Framework](https://github.com/LSantha/jnode_ai/wiki/Driver-Framework) |
57+
| [Drivers](subsystems.md#drivers) | PCI, USB, IDE, SCSI, Ethernet, video, input | [Driver-Framework](https://github.com/LSantha/jnode_ai/wiki/Driver-Framework) |
5258

5359
See [Subsystems](subsystems.md) for details.
5460

@@ -57,7 +63,7 @@ See [Subsystems](subsystems.md) for details.
5763
## Development
5864

5965
- [Build & Test](development/index.md) — Ant-based build, JUnit, regression tests
60-
- [Testing](development/testing.md) — JUnit, regression tests, JDWP integration tests
66+
- [Testing](development/testing.md) — JUnit, regression, boot testing
6167

6268
---
6369

@@ -78,12 +84,6 @@ See [Reference](reference.md) for details.
7884

7985
---
8086

81-
## Developed with AI Agents
82-
83-
This is a fork of the classic JNode project, maintained as a living experiment in agent-driven development. GitHub Actions and OpenCode agents triage issues, implement fixes, review pull requests, update the wiki, and boot every build in QEMU before it lands. Batching is coordinated through an orchestrator workflow, with agentic skills for QEMU boot testing, JDWP debugging, and filesystem diagnosis.
84-
85-
---
86-
8787
## Community
8888

8989
- **Issues**: [GitHub Issues](https://github.com/LSantha/jnode_ai/issues)

0 commit comments

Comments
 (0)