[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.
This commit is contained in:
Travis Geiselbrecht
126
docs/index.md
Normal file
126
docs/index.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# LK (Little Kernel) Documentation
|
||||
|
||||
Welcome to the LK (Little Kernel) documentation. LK is a small operating system designed for embedded systems, offering a lightweight kernel with threading, memory management, and device drivers.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### Getting Started
|
||||
- [Getting Started Guide](getting_started.md) - Quick start guide for building and running LK
|
||||
- [TODO List](todo.md) - Current development tasks and known issues
|
||||
|
||||
### Core Kernel Documentation
|
||||
- [Threading and Scheduler System](threading_and_scheduler.md) - Comprehensive guide to LK's preemptive multithreading system
|
||||
- [Blocking Primitives](blocking_primitives.md) - Synchronization primitives (mutexes, semaphores, events, ports, spinlocks)
|
||||
- [VMM Overview](vmm_overview.md) - Virtual Memory Management system architecture and implementation
|
||||
- [Source Tree Structure](source_tree_structure.md) - Organization and structure of the LK source code repository
|
||||
|
||||
### Platform-Specific Documentation
|
||||
|
||||
#### ARM Fixed Virtual Platform (FVP)
|
||||
- [FVP Base - How to Run](fvp-base/how_to_run.md) - Build and run instructions for FVP Base platform
|
||||
- [FVP Base - Internal Overview](fvp-base/internal.md) - Boot sequence, memory layout, and peripheral details
|
||||
|
||||
### Development and Testing
|
||||
- [Network Setup for QEMU](lk_tap.md) - Setting up tun/tap networking for QEMU testing
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
LK is designed as a modular kernel with the following key components:
|
||||
|
||||
- **Threading System**: Preemptive multithreading with priority-based scheduling
|
||||
- **Memory Management**: Physical memory management (PMM) and virtual memory management (VMM)
|
||||
- **Synchronization**: Comprehensive set of blocking primitives for thread coordination
|
||||
- **Device Support**: Drivers for common embedded peripherals
|
||||
- **Platform Abstraction**: Support for multiple CPU architectures and platforms
|
||||
|
||||
## Supported Architectures
|
||||
|
||||
- ARM (32-bit and 64-bit)
|
||||
- RISC-V (32-bit and 64-bit)
|
||||
- x86/x86_64
|
||||
- Motorola 68000
|
||||
- Microblaze
|
||||
- MIPS
|
||||
- OpenRISC 1000
|
||||
- VAX (experimental)
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- QEMU virtual platforms (ARM, RISC-V, x86)
|
||||
- ARM Fixed Virtual Platform (FVP)
|
||||
- Various embedded development boards
|
||||
- Custom hardware platforms
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Real-time capable**: Priority-based preemptive scheduler with real-time thread support
|
||||
- **Memory protection**: Virtual memory management with address space isolation
|
||||
- **SMP support**: Symmetric multiprocessing for multi-core systems
|
||||
- **Modular design**: Component-based architecture for easy customization
|
||||
- **Small footprint**: Designed for resource-constrained embedded systems
|
||||
|
||||
## Contributing
|
||||
|
||||
LK is an open-source project. For the latest development status and to contribute:
|
||||
|
||||
- [GitHub Repository](https://github.com/littlekernel/lk)
|
||||
- [Issue Tracker](https://github.com/littlekernel/lk/issues)
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Install or build a recent version of qemu. Make sure qemu-system-riscv64 is in your path.
|
||||
|
||||
2. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/littlekernel/lk
|
||||
cd lk
|
||||
```
|
||||
|
||||
3. Download a toolchain:
|
||||
|
||||
```bash
|
||||
scripts/fetch-toolchains.py --prefix riscv64-elf
|
||||
export PATH=$PWD/toolchain/riscv64-elf-15.1.0-Linux-x86_64/bin:$PATH
|
||||
```
|
||||
|
||||
4. Build and run:
|
||||
|
||||
```bash
|
||||
make qemu-virt-riscv64-test
|
||||
scripts/do-qemuriscv -6S
|
||||
```
|
||||
|
||||
For detailed instructions, see the [Getting Started Guide](getting_started.md).
|
||||
|
||||
This will get you a interactive prompt into LK which is running in qemu
|
||||
arm64 machine 'virt' emulation. type 'help' for commands.
|
||||
|
||||
Note: for ubuntu x86-64
|
||||
sudo apt-get install gcc-aarch64-linux-gnu
|
||||
or fetch a prebuilt toolchain from
|
||||
https://newos.org/toolchains/aarch64-elf-15.1.0-Linux-x86_64.tar.xz
|
||||
|
||||
### Building with LLVM-based toolchains
|
||||
|
||||
To build LK with a LLVM-based toolchain you will have to manually specify the compiler and linker in the environemnt.
|
||||
Unlike GCC clang is a cross-compiler by default, so the target needs to be specified as part of the CC/CXX/CPP variables.
|
||||
For example, assuming LLVM is in `/opt/llvm/bin/`, the following command will work to build for 64-bit RISC-V:
|
||||
|
||||
```bash
|
||||
gmake qemu-virt-riscv64-test 'CC=/opt/llvm/bin/clang --target=riscv64-unknown-elf' 'CPP=/opt/llvm/bin/clang-cpp --target=riscv64-unknown-elf' 'CXX=/opt/llvm/bin/clang++ --target=riscv64-unknown-elf' 'LD=/opt/llvm/bin/ld.lld' TOOLCHAIN_PREFIX=/opt/llvm/bin/llvm- CPPFILT=/opt/llvm/bin/llvm-cxxfilt
|
||||
```
|
||||
|
||||
TOOLCHAIN_PREFIX can be set to use the LLVM binutils, but due to the different naming of `llvm-cxxfilt` vs `c++filt` it needs to be set explicitly.
|
||||
|
||||
To build for AArch64 the command looks similar, just with a different `--target=` flag.
|
||||
|
||||
```bash
|
||||
gmake qemu-virt-arm64-test 'CC=/opt/llvm/bin/clang --target=aarch64-unknown-elf' 'CPP=/opt/llvm/bin/clang-cpp --target=aarch64-unknown-elf' 'CXX=/opt/llvm/bin/clang++ --target=aarch64-unknown-elf' 'LD=/opt/llvm/bin/ld.lld' TOOLCHAIN_PREFIX=/opt/llvm/bin/llvm- CPPFILT=/opt/llvm/bin/llvm-cxxfilt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## [TODO](todo.md)
|
||||
|
||||
*This documentation covers the core aspects of the LK kernel. For specific implementation details, refer to the source code and individual documentation files.*
|
||||
Reference in New Issue
Block a user