[docs] start building more comprehensive documentation

About half and half AI generated stuff and manually curated, but it's a
pretty good start.

Add a helpful markdown addon to the workspace.

docs/source_tree_structure.md

@@ -0,0 +1,177 @@
+# LK Source Tree Structure
+
+This document describes the organization and structure of the Little Kernel (LK) source code repository.
+
+## Top-Level Directories
+
+### `/arch/`
+Architecture-specific code for different CPU architectures:
+- `arm/` - ARM 32-bit and cortex-m support
+- `arm64/` - ARM 32-bit and 64-bit support
+- `riscv/` - RISC-V 32-bit and 64-bit support
+- `m68k/` - Motorola 68000 support
+- `microblaze/` - Microblaze support
+- `mips/` - MIPS support
+- `or1k/` - OpenRISC 1000 support
+- `x86/` - x86 and x86_64 support
+- `vax/` - VAX support (experimental)
+
+Each architecture directory contains:
+- CPU-specific initialization code
+- Memory management unit (MMU) setup
+- Exception and interrupt handling
+- Low level context switching and thread support
+- Architecture-specific assembly code
+
+### `/kernel/`
+Core kernel functionality:
+- `mutex.c`, `semaphore.c` - Synchronization primitives
+- `mp.c` - Symmetric multiprocessing support
+- `timer.c` - Kernel timers
+- `event.c` - Event handling
+- `port.c` - Message passing
+- `thread.c` - Threading system and scheduler
+- `vm/` - Virtual memory management
+- `novm/` - Memory management for architectures without an mmu
+
+### `/lib/`
+Library and utility code:
+- `libc/` - Basic C library functions
+- `libm/` - Math library
+- `bio/` - Block I/O layer
+- `fs/` - File system support
+- `heap/` - Dynamic memory allocation
+- `io/` - I/O utilities
+- `console/` - Console and debugging support
+- `cksum/` - Checksum algorithms
+- `debug/` - Debugging utilities
+- many more helper libraries and utility routines
+
+### `/dev/`
+Device drivers organized by category:
+- `bus/` - Bus drivers (PCI, etc.)
+- `display/` - Display and graphics drivers
+- `interrupt/` - Interrupt controller drivers
+- `net/` - Network device drivers
+- `timer/` - Hardware timer drivers
+- `uart/` - Serial port drivers
+- `usb/` - USB device side drivers
+- `virtio/` - VirtIO device support
+
+### `/platform/`
+Platform specific code (not all listed):
+- `qemu-*/` - QEMU virtual machine platforms
+- `fvp-base/` - ARM Fixed Virtual Platform support
+- `stm32*/` - Support for various STM32 SOCs
+- Hardware-specific board support packages
+- Platform initialization and device tree handling
+
+### `/target/`
+Target specific code:
+- A specific board or combination of platform and architecture. For example:
+- `stm32f4-discovery`
+- `pc-x86`
+- `pico`
+
+### `/app/`
+Application and test code:
+- Test applications for kernel functionality
+- Sample applications demonstrating LK features
+- Shell and command-line interface
+- Network applications and services
+- Location where general embedded device logic go
+
+### `/external/`
+Third-party code and libraries:
+- External dependencies
+- Imported code from other projects
+- Third-party drivers and utilities
+
+### `/scripts/`
+Build and development scripts:
+- `do-qemu*` - QEMU launch scripts for different architectures
+- `fetch-toolchains.py` - Toolchain download utility
+- Build automation and testing scripts
+
+### `/tools/`
+Development and build tools:
+- Custom build utilities
+- Code generation tools
+- Development helpers
+
+### `/docs/`
+Documentation:
+- Architecture documentation
+- Platform-specific guides
+- API documentation
+- Development guides
+
+## Key Files
+
+### `/make/`
+Build system components:
+- Makefile fragments for different components
+- Architecture and platform build rules
+- Toolchain configuration
+
+### Root Directory Files
+- `Makefile` - Main build system entry point
+- `engine.mk` - Core build engine
+- `project/*.mk` - Project configuration files
+- `target/*.mk` - Target-specific build configurations
+
+## Build System Organization
+
+The LK build system is modular and component-based:
+
+1. **Projects** (`project/*.mk`) define high-level configurations
+2. **Targets** (`target/*.mk`) specify platform and architecture combinations
+3. **Modules** (scattered throughout source tree) define buildable components
+4. **Rules** (`make/*.mk`) provide build logic for different file types
+
+Each directory can contain:
+- `rules.mk` - Module definition and build rules
+- Source files (`.c`, `.cpp`, `.S`)
+- Local headers and includes
+
+## Module System
+
+LK uses a module-based build system where each component is defined as a module:
+
+```make
+# Example module definition in rules.mk
+LOCAL_DIR := $(GET_LOCAL_DIR)
+MODULE := $(LOCAL_DIR)
+
+MODULE_SRCS += \
+    $(LOCAL_DIR)/file1.c \
+    $(LOCAL_DIR)/file2.c
+
+MODULE_DEPS += \
+    lib/libc \
+    kernel
+
+include make/module.mk
+```
+
+This allows for:
+- Selective compilation of components
+- Dependency management between modules
+- Platform-specific module inclusion/exclusion
+- Modular kernel configuration
+
+## Platform and Architecture Interaction
+
+The relationship between platforms and architectures:
+
+1. **Architecture** (`/arch/`) provides CPU-specific low-level support
+2. **Platform** (`/platform/`) provides system-specific support (generally system-on-chip)
+3. **Target** (`/target/`) combines a specific platform with board specific customization (GPIOs, etc)
+4. **Project** (`/project/`) selects the target and a list of modules to include for a complete system
+
+Example target `stm32f4-discovery` combines:
+- Platform: `stm32f4xx` (support for STM32 F4 series SOC)
+- Architecture: `arm` (32-bit ARM)
+- Modules: Selected via project configuration
+
+This structure allows LK to support diverse hardware while maintaining code reuse and modularity.