dollspace.gay
Microkernel based hobby OS
dollspacegay.tngl.sh
1╔══════════════════════════════════════════════════════════════════════════════╗
2║ AethelOS Architecture ║
3║ "Symbiotic Computing in Action" ║
4╚══════════════════════════════════════════════════════════════════════════════╝
5
6┌──────────────────────────────────────────────────────────────────────────────┐
7│ USER SPACE │
8│ │
9│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
10│ │ Applications │ │ Applications │ │ Applications │ │
11│ │ │ │ │ │ │ │
12│ └────────┬───────┘ └────────┬───────┘ └────────┬───────┘ │
13│ │ │ │ │
14│ └───────────────────┴───────────────────┘ │
15│ │ │
16│ ┌──────────▼──────────┐ │
17│ │ Ancient Runes │ │
18│ │ (Core Libraries) │ │
19│ │ │ │
20│ │ • Corelib │ │
21│ │ • Weaving API │ │
22│ │ • Eldarin Script │ │
23│ └──────────┬──────────┘ │
24│ │ │
25│ ┌───────────────────┴───────────────────┐ │
26│ │ │ │
27│ ┌────────▼─────────┐ ┌─────────────┐ ┌───────▼────────┐ │
28│ │ World-Tree │ │ Lanthir │ │ The Weave │ │
29│ │ Grove │ │ Grove │ │ Grove │ │
30│ │ (Filesystem) │ │ (WM) │ │ (Compositor) │ │
31│ └────────┬─────────┘ └──────┬──────┘ └────────┬───────┘ │
32│ │ │ │ │
33│ └───────────────────┴───────────────────┘ │
34│ │ │
35│ ┌──────────▼──────────┐ │
36│ │ Network Sprite │ │
37│ │ (Network Daemon) │ │
38│ └──────────┬──────────┘ │
39└───────────────────────────────┼───────────────────────────────────────────┘
40 │
41════════════════════════════════╪════════════════════════════════════════════
42 │ System Call Interface (via Nexus)
43════════════════════════════════╪════════════════════════════════════════════
44 │
45┌───────────────────────────────▼───────────────────────────────────────────┐
46│ KERNEL SPACE (The Heartwood) │
47│ │
48│ ┌─────────────────────────────────────────────────────────────────────┐ │
49│ │ The Nexus │ │
50│ │ (Inter-Process Communication Core) │ │
51│ │ │ │
52│ │ • Asynchronous message passing │ │
53│ │ • Capability-based channels │ │
54│ │ • Priority-aware routing │ │
55│ │ • Zero-copy where possible │ │
56│ └─────────────────────┬───────────────────────┬───────────────────────┘ │
57│ │ │ │
58│ ┌────────────▼────────────┐ ┌──────▼───────────────┐ │
59│ │ Loom of Fate │ │ Mana Pool │ │
60│ │ (Scheduler) │ │ (Memory Manager) │ │
61│ │ │ │ │ │
62│ │ • Harmony-based │ │ • Capability-based │ │
63│ │ • Cooperative │ │ • Object-oriented │ │
64│ │ • Parasite detection │ │ • Purpose-driven │ │
65│ │ │ │ │ │
66│ │ Thread States: │ │ Regions: │ │
67│ │ - Weaving │ │ - Sanctuary │ │
68│ │ - Resting │ │ - Ephemeral Mist │ │
69│ │ - Tangled │ │ │ │
70│ │ - Fading │ │ │ │
71│ └────────────┬────────────┘ └──────┬───────────────┘ │
72│ │ │ │
73│ └──────────┬───────────┘ │
74│ │ │
75│ ┌──────────▼──────────┐ │
76│ │ Attunement Layer │ │
77│ │ (Hardware HAL) │ │
78│ │ │ │
79│ │ • CPU management │ │
80│ │ • Interrupts │ │
81│ │ • Timers │ │
82│ └──────────┬──────────┘ │
83└───────────────────────────────────┼───────────────────────────────────────┘
84 │
85════════════════════════════════════╪════════════════════════════════════════
86 │ Hardware Interface
87════════════════════════════════════╪════════════════════════════════════════
88 │
89┌───────────────────────────────────▼───────────────────────────────────────┐
90│ HARDWARE │
91│ │
92│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
93│ │ CPU │ │ Memory │ │ Disk │ │ Network │ │ GPU │ │
94│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
95└────────────────────────────────────────────────────────────────────────────┘
96
97
98═══════════════════════════════════════════════════════════════════════════════
99 KEY CONCEPTS
100═══════════════════════════════════════════════════════════════════════════════
101
102┌──────────────────────────────────────────────────────────────────────────────┐
103│ THE NEXUS - Communication Backbone │
104│ │
105│ Process A Process B │
106│ │ │ │
107│ │ (ChannelCapability) │ │
108│ ▼ ▼ │
109│ ┌────────┐ ┌────────┐ │
110│ │Channel │ ◄─────────── Nexus Core ──────────► │Channel │ │
111│ └────────┘ (Router) └────────┘ │
112│ │ │ │
113│ └──────────────► Message Queue ◄───────────────┘ │
114│ (Priority-ordered) │
115└──────────────────────────────────────────────────────────────────────────────┘
116
117┌──────────────────────────────────────────────────────────────────────────────┐
118│ THE LOOM OF FATE - Harmony-Based Scheduling │
119│ │
120│ Threads ──► Harmony Analyzer ──► Scheduler ──► CPU │
121│ │ │
122│ └──► Scores (0.0 - 1.0) │
123│ │ │
124│ ├─► > 0.7: Harmonious │
125│ ├─► 0.3 - 0.7: Normal │
126│ └─► < 0.3: Parasitic (throttle) │
127└──────────────────────────────────────────────────────────────────────────────┘
128
129┌──────────────────────────────────────────────────────────────────────────────┐
130│ THE MANA POOL - Capability-Based Memory │
131│ │
132│ User Process │
133│ │ │
134│ │ (ObjectHandle - no raw pointers!) │
135│ ▼ │
136│ Object Manager │
137│ │ │
138│ ├─► Sanctuary (long-lived, stable) │
139│ └─► Ephemeral Mist (short-lived, volatile) │
140│ │ │
141│ ▼ │
142│ Physical Memory (protected by MMU) │
143└──────────────────────────────────────────────────────────────────────────────┘
144
145┌──────────────────────────────────────────────────────────────────────────────┐
146│ WORLD-TREE FILESYSTEM - Query-Based │
147│ │
148│ Traditional: /home/user/docs/file.txt │
149│ │
150│ AethelOS: Seek { │
151│ essence: "Scroll", │
152│ creator: "Elara", │
153│ name: "file" │
154│ } │
155│ │
156│ ┌──────────┐ │
157│ │ Query │ ──► Database Index ──► File Objects │
158│ └──────────┘ │ │
159│ ├─► Metadata │
160│ ├─► Data │
161│ └─► Version History │
162└──────────────────────────────────────────────────────────────────────────────┘
163
164┌──────────────────────────────────────────────────────────────────────────────┐
165│ THE WEAVE - Vector Graphics Compositor │
166│ │
167│ Scene Graph ──► Transform ──► Rasterize ──► Shaders ──► Framebuffer │
168│ │ (Glyphs) │
169│ │ │
170│ ├─► Window 1 (Bézier shape) │
171│ │ ├─► Title Bar │
172│ │ └─► Content │
173│ │ │
174│ └─► Window 2 (Custom shape) │
175│ └─► Widgets │
176│ │
177│ All rendering is vector-based (resolution-independent) │
178└──────────────────────────────────────────────────────────────────────────────┘
179
180
181═══════════════════════════════════════════════════════════════════════════════
182 DATA FLOW EXAMPLES
183═══════════════════════════════════════════════════════════════════════════════
184
185Example 1: Application Opens a File
186───────────────────────────────────
187
188Application
189 │
190 │ Query: Seek { essence: "Scroll", name: "config" }
191 ▼
192Ancient Runes (Corelib)
193 │
194 │ Message: FileQuery { ... }
195 ▼
196Nexus (IPC)
197 │
198 │ Route to World-Tree Grove
199 ▼
200World-Tree Grove
201 │
202 │ Database lookup
203 ▼
204 │ Request memory capability
205 ▼
206Nexus → Heartwood → Mana Pool
207 │
208 │ Grant ObjectHandle
209 ▼
210 │ Return FileObject with handle
211 ▼
212Application receives handle (not raw pointer!)
213
214
215Example 2: Window Drag Animation
216─────────────────────────────────
217
218User Input (Mouse Move)
219 │
220 ▼
221Lanthir Grove (Window Manager)
222 │
223 │ Update window position
224 │ Apply ripple transformation
225 ▼
226The Weave Grove (Compositor)
227 │
228 │ Modify scene graph node
229 │ Apply distortion glyph (shader)
230 ▼
231 │ Render to framebuffer
232 ▼
233GPU → Display
234
235
236Example 3: Parasite Detection
237──────────────────────────────
238
239Thread running
240 │
241 │ Resource usage monitored
242 ▼
243Loom of Fate (Scheduler)
244 │
245 │ Harmony Analyzer runs
246 ▼
247 │ Detect: harmony_score < 0.3
248 ▼
249 │ Throttle thread (reduce CPU allocation)
250 │ Send DisharmonyAlert message to parent
251 ▼
252Parent process
253 │
254 │ Receive alert, decide action
255 └──► Can request thread termination if needed
256
257
258═══════════════════════════════════════════════════════════════════════════════
259 SECURITY MODEL
260═══════════════════════════════════════════════════════════════════════════════
261
262Capability Propagation
263──────────────────────
264
265Process A (has FileCapability)
266 │
267 │ Can create derived capability with FEWER rights
268 ▼
269Derived Capability (READ only)
270 │
271 │ Can transfer to Process B
272 ▼
273Process B (receives READ-only capability)
274 │
275 │ CANNOT escalate to WRITE
276 └──► Security enforced by kernel
277
278
279Isolation Boundaries
280────────────────────
281
282Hardware (Ring 0)
283 ▲
284 │ MMU enforces memory boundaries
285 │
286Heartwood (Ring 0)
287 ▲
288 │ Capability checks
289 │
290Groves (Ring 3)
291 ▲
292 │ Message passing via Nexus
293 │
294Applications (Ring 3)
295
296
297═══════════════════════════════════════════════════════════════════════════════
298 MEMORY LAYOUT (x86_64)
299═══════════════════════════════════════════════════════════════════════════════
300
3010xFFFF_FFFF_FFFF_FFFF ┬─────────────────────────────────
302 │
303 │ Kernel Stack
304 │
3050xFFFF_A000_0000_0000 ├─────────────────────────────────
306 │
307 │ Device Memory (MMIO)
308 │
3090xFFFF_9000_0000_0000 ├─────────────────────────────────
310 │
311 │ Kernel Heap (Mana Pool)
312 │
3130xFFFF_8000_0000_0000 ├─────────────────────────────────
314 │
315 │ Kernel Code (.text, .data)
316 │
317 ╞═════════════════════════════════
318 │ Non-canonical addresses
319 ╞═════════════════════════════════
320 │
321 │ User Space Heap
322 │
3230x0000_4000_0000_0000 ├─────────────────────────────────
324 │
325 │ User Space Stack
326 │ (grows downward)
327 │
3280x0000_0000_0040_0000 ├─────────────────────────────────
329 │
330 │ User Space Code
331 │
3320x0000_0000_0000_1000 ├─────────────────────────────────
333 │ Null page (unmapped)
3340x0000_0000_0000_0000 └─────────────────────────────────
335
336
337═══════════════════════════════════════════════════════════════════════════════
338 BOOT SEQUENCE
339═══════════════════════════════════════════════════════════════════════════════
340
3411. BIOS/UEFI
342 │
343 │ Load boot sector into 0x7c00
344 ▼
3452. boot.asm (First Spark)
346 │
347 │ Initialize hardware
348 │ Load second stage
349 ▼
3503. heartwood_loader (Second Stage)
351 │
352 │ Enable protected mode
353 │ Set up paging
354 │ Map kernel to higher half
355 │ Load kernel ELF
356 ▼
3574. Heartwood kernel (_start)
358 │
359 ├──► Initialize VGA buffer
360 ├──► Initialize Mana Pool
361 ├──► Initialize Nexus
362 ├──► Initialize Loom of Fate
363 ├──► Initialize Attunement Layer
364 │
365 ├──► Spawn World-Tree Grove
366 ├──► Spawn The Weave Grove
367 ├──► Spawn Lanthir Grove
368 └──► Spawn Network Sprite
369 │
370 ▼
3715. System Ready
372 │
373 │ The Heartwood lives!
374 └──► Eternal loop (hlt)
375
376
377═══════════════════════════════════════════════════════════════════════════════
378 FILE STRUCTURE
379═══════════════════════════════════════════════════════════════════════════════
380
381aethelos-source/
382│
383├── GENESIS.scroll ← Philosophy and high-level design
384├── DESIGN.md ← Technical deep dive
385├── ARCHITECTURE.txt ← This file
386├── README.md ← Project overview
387├── QUICKSTART.md ← Getting started guide
388├── Makefile ← Build system
389├── Cargo.toml ← Rust workspace config
390│
391├── awakening/ ← Bootloader
392│ ├── boot.asm ← 16-bit real mode boot sector
393│ └── heartwood_loader/ ← 32/64-bit loader
394│
395├── heartwood/ ← The Kernel
396│ ├── src/
397│ │ ├── main.rs ← Kernel entry point
398│ │ ├── lib.rs ← Kernel library exports
399│ │ ├── vga_buffer.rs ← Early console output
400│ │ ├── nexus/ ← IPC system
401│ │ ├── loom_of_fate/ ← Scheduler
402│ │ ├── mana_pool/ ← Memory manager
403│ │ └── attunement/ ← Hardware abstraction
404│ └── Cargo.toml
405│
406├── groves/ ← User-space services
407│ ├── world-tree_grove/ ← Filesystem
408│ ├── the-weave_grove/ ← Compositor
409│ ├── lanthir_grove/ ← Window manager
410│ └── network_sprite/ ← Network daemon
411│
412└── ancient-runes/ ← Core libraries
413 ├── corelib/ ← Standard library
414 ├── weaving/ ← GUI toolkit
415 └── script/ ← Shell API
416
417
418═══════════════════════════════════════════════════════════════════════════════
419 END OF ARCHITECTURE DIAGRAM
420═══════════════════════════════════════════════════════════════════════════════
421
422For more information:
423 • Read GENESIS.scroll for the philosophy
424 • Read DESIGN.md for technical details
425 • Read QUICKSTART.md to get started
426 • Read the source code - it's the ultimate documentation!
427
428"The code does not command the silicon. The silicon does not serve the code.
429 They dance together, and in that dance, life emerges."