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 - Quick start guide for building and running LK
• TODO List - Current development tasks and known issues

Core Kernel Documentation

• Threading and Scheduler System - Comprehensive guide to LK's preemptive multithreading system
• Blocking Primitives - Synchronization primitives (mutexes, semaphores, events, ports, spinlocks)
• VMM Overview - Virtual Memory Management system architecture and implementation
• Source Tree Structure - Organization and structure of the LK source code repository

Platform-Specific Documentation

ARM Fixed Virtual Platform (FVP)

• FVP Base - How to Run - Build and run instructions for FVP Base platform
• FVP Base - Internal Overview - Boot sequence, memory layout, and peripheral details

Development and Testing

• Network Setup for QEMU - Setting up tun/tap networking for QEMU testing
• GDB Debug Support for GBL - Debugging GBL using GDB with UEFI debug support protocol

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
• 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
• Issue Tracker

Quick Start

1. Install or build a recent version of qemu. Make sure qemu-system-riscv64 is in your path.

2. Clone the repository:

   git clone https://github.com/littlekernel/lk
   cd lk
   

3. Download a toolchain:

   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:

   make qemu-virt-riscv64-test
   scripts/do-qemuriscv -6S
   

For detailed instructions, see the Getting Started Guide.

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:

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.

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

This documentation covers the core aspects of the LK kernel. For specific implementation details, refer to the source code and individual documentation files.