Update READMEs and TODOs

README.md

@@ -1,6 +1,40 @@
 # AcadiaOS
 
-AcadiaOS is a hobby operating system Iuse to explore and learn about OS development.
+AcadiaOS is a hobby operating system I use to explore and learn about OS development.
 
-It is built on top of a small microkernel (currently ~3k LOC) that
+It is built on top of a small capability-based microkernel that provides
-is capability based and provides memory management, process scheduling, and hardware access.
+memory management, process scheduling, and hardware access.
+
+## Directory Structure
+
+The subdirectories of the project are as follows:
+- **zion**: Contains kernel code as well as a couple headers that user space uses to interface with the kernel.
+- **lib**: Library code used by the kernel and user space.
+- **sys**: System services.
+- **sysroot**: Files that are copied to the root filesystem.
+- **toolchain** and **scripts**: Contain tooling for the cross-compile environment.
+- **yunq**: Contains the El Yunque IDL used for IPC between processes in userspace.
+
+Where available, further documentation about each of these components can be found in the README files in each respective subdirectory.
+
+## Building AcadiaOS
+
+Run `./scripts/build_toolchain.sh` to build a gcc cross-compile toolchain for the project. (Takes a long time.)
+
+Change into the `build-dbg` directory.
+
+Run `ninja qemu` to build and run AcadiaOS in a VM.
+
+### System Dependencies
+
+TODO
+
+## Boot Process
+
+AcadiaOS uses the limine bootloader to enter into a 64-bit kernel in the negative 2GB address space (mcmodel kernel).
+
+The Zion kernel then sets up interrupts, scheduling, and memory management before passing off control to the Yellowstone process.
+
+The kernel passes capabilities to the Denali and VictoriaFalls binaries to the Yellowstone process to allow it to manage the rest of the boot process.
+
+The Yellowstone, Denali, and VictoriaFalls processes are all passed at boot using limine modules, however any subsequent processes will be loaded off disk.

sys/README.md

@@ -1,6 +1,11 @@
 # System Processes
 
-Current Processes;
+Current Processes:
 
-- **yellowstone**: System Initialization
+- **yellowstone**: System Initialization.
-- **denali**: SATA ACHI Disk Driver
+- **denali**: SATA ACHI Disk Driver.
+- **victoriafalls**: Virtual File System.
+
+## Open work
+
+Check the [TODO file](TODO.md) for current projects.

sys/TODO.md

@@ -0,0 +1,19 @@
+# System TODO
+
+## Yellowstone
+
+- Add registration to the base yellowstone yunq service
+  - Requires: Adding ability to pass capabilities in endpoint calls.
+- Store registered services in a hashmap.
+  - Requires: Adding hashmap to Glacier.
+- Start the next service from a configuration file.
+
+## Denali
+
+- Migrate denali to a yunq definition.
+  - Requires: Adding async yunq servers (or more synchronization primitives)
+- Add the ability to send multiple Ahci commands at once.
+
+## VictoriaFalls
+
+- Add a read file VFS service.

zion/README.md

@@ -0,0 +1,14 @@
+# Zion Microkernel
+
+The Zion Microkernel is a capability based kernel. The types of objects that
+processes can hold a capability to exist in the `object/` directory. The system calls
+used to interact with them are enumerated in `include/zcall.h` and are implemented
+in the `syscalls/` directory.
+
+The system uses a barebones ELF loader (`loader/init_loader.h`) to jump to userspace
+but from there userspace processes are responsible for loading child processes into
+memory and executing them.
+
+## Open Work
+
+The [TODO file](TODO.md) enumerates current areas for improvement.

zion/TODO.md

@@ -0,0 +1,53 @@
+# Zion TODO
+
+## Memory Management
+
+### Physical Memory
+
+- Reserve lower physical memory for hardware accesses as necessary.
+- Return errors rather than panicking on allocation failure
+- Return memory pages to the pool when a MemoryObject goes out of scope.
+- Add diagnostics to inspect physical memory usage.
+
+### Virtual Memory
+
+- Allow different permissions and caching behaviors on mapped memory.
+- Add diagnostics to inspect process memory usage.
+- Properly free user stacks on thread exit.
+
+### Allocation
+
+- Use a buddy allocator with a real free when an object is too large for
+  the slab allocator.
+- Free kernel stacks on thread/process exit.
+
+## Process Management
+
+- Clean up process state and capabilities when it exits.
+
+## Processor
+
+- Enable all instruction types before passing to user space.
+
+## Faults and Interrupts
+
+- Exit process rather than panicking on unhandled Page Fault (and others).
+- Add additional fault handlers to avoid GP faults.
+- Improve process for registering interrupt handlers.
+
+## Capabilities
+
+- Add syscalls for inspecting capabilities.
+- Randomize/obfuscate capability numbers passed to user space.
+
+## Scheduling
+
+- Add different scheduling priorities.
+- Add thread sleep capability.
+- Add synchronization syscalls for userspace.
+
+## Large Projects
+
+- Add multiprocessing support.
+- Add layer on top of limine to enable multiple bootloaders.
+- Add a large amount of debugging info for kernel panics.