lk/docs/source_tree_structure.md

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:

# 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.