# darwin-on-arm/xnu architecture

> Architecture diagram of the GitHub repository darwin-on-arm/xnu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darwin-on-arm/xnu
- Repository: https://github.com/darwin-on-arm/xnu

## Overview

Step 1: Identify the Project Type and Purpose
- This is the XNU kernel—Apple’s hybrid operating-system kernel combining the Mach microkernel (osfmk), the BSD network/UNIX layer (bsd), the I/O Kit driver/plug-in architecture (iokit), and supporting libraries (libkern, libsyscall, libsa, libkmod).
- Its purpose is to bootstrap hardware (bootloader/libsa/pexpert), provide low-level kernel services (Mach IPC, scheduler, virtual memory, device I/O), expose UNIX/POSIX APIs (BSD), and load third-party kernel extensions (kexts via I/O Kit).

Step 2: Analyze the File Structure
- Top-level build scripts and Makefiles coordinate building everything for multiple architectures.
- SETUP and config directories define build setups, target configs, and export headers.
- osfmk contains the Mach microkernel core: IPC, scheduling, VM, low-level platform code per architecture.
- bsd implements the POSIX layer: VFS, networking stack, syscalls, device pseudo-file systems, man pages.
- iokit holds the driver framework: user-space headers (IOKit/IOKit/*.h), kernel-space classes (iokit/Kernel/*.cpp), built-in platform drivers, examples, and tests.
- libkern is the common kernel support library (C++ STL-like classes, crypto, zlib).
- libsyscall generates and wraps user-space syscall stubs.
- libsa is the standalone boot library used by the XNU bootloader (early startup code).
- pexpert provides platform expert code (board initialization, bootargs).
- tools, tests, and man/* directories supply auxiliary utilities, test suites, and documentation.

Step 3: Key Insights from README
- Building XNU is a multi-step make process that targets OS components (osfmk, mach_kernel, BSD, IOKit).
- Environment variables (SRCROOT, OBJROOT, DSTROOT, SYMROOT) control where artifacts go.
- Multiple “projects” (xnu, xnu_debug, libkmod, Libsyscall) support building different deliverables (boot image, debug kernel, kext libraries).

1. Bootloader Layer: libsa + pexpert
2. Mach Microkernel (osfmk): Scheduler, IPC, VM, kernel primitives
3. BSD UNIX Layer (bsd): VFS, Networking stack, System Calls
4. I/O Kit Framework (iokit): Driver base classes, user-kernel bridge, power management
5. Kernel Libraries (libkern, libkmod, libsyscall): supporting code for allocators, data structures, system-call stubs
6. Kernel Extensions (kexts): dynamically loadable drivers and file-systems
7. User-Space Interfaces: syscall wrappers, headers installed under /usr/include & frameworks

– Bootloader → Mach Microkernel: loads and transfers control to mach_kernel
– Microkernel ↔ Device Drivers (I/O Kit, built-ins): hardware I/O mediated via IOService, I/O Kit user-client interfaces
– Microkernel ↔ BSD Layer: Mach ports used for implementing syscalls and networking protocols
– BSD Layer → User Applications: syscalls and POSIX API (libsyscall wrappers)
– I/O Kit → Kernel Extensions: driver plug-in discovery via IOKit registry
– Kernel Libraries ← all layers: common services, data structures, crypto

c. Architectural Patterns and Principles:
– Layered hybrid kernel: Mach microkernel at core, layered UNIX subsystem on top, driver framework as separate plug-in architecture
– In-kernel C++ (I/O Kit, libkern) combined with C for low-level code
– Makefile-driven componentization enabling multi-architecture builds and selective component building

d. Key Technologies and Frameworks:
– Mach IPC and VM primitives (osfmk)
– POSIX/VFS/Networking in BSD subsystem
– I/O Kit driver model (IOService, IOCatalogue, IOPower)
– Kext loading/unloading mechanisms
– Build system: recursive Makefiles, SETUP scripts, config exports

- Boot path: libsa → pexpert → mach_kernel.
- Microkernel boundaries: separate the Mach core from the BSD and IOKit subsystems.
- Dynamic loading: how kexts plug into I/O Kit.
- User-space boundary: system call stubs (libsyscall) connecting user applications to kernel.

- Clear labels: name each block (e.g., “Mach Microkernel (osfmk)”), each subsystem, each layer.
– Another for OS services (bsd)
– Another for driver framework (iokit, kexts)
– Another for user-space interfaces (libsyscall, headers)

Step 7: Detail and Completeness
- Be exhaustive in capturing components—don’t collapse BSD or I/O Kit internals into “misc.”
- Per-architecture configuration and build scripts as side artifacts, if relevant to deployment.
- Both static (compiled-in drivers) and dynamic (kext) plugin models.

Summary

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bootloader Layer
    subgraph "Bootloader Layer"
        libsa["libsa"]:::boot
        pexpert["pexpert"]:::boot
    end

    %% Mach Microkernel Core
    subgraph "Mach Microkernel (osfmk)"
        osfmk["osfmk"]:::core
    end

    %% BSD UNIX Layer
    subgraph "BSD UNIX Layer (bsd)"
        bsd["bsd"]:::oservices
    end

    %% I/O Kit Framework
    subgraph "I/O Kit Framework (iokit)"
        iokit["iokit"]:::driver
    end

    %% Kernel Extensions
    Kexts["Kernel Extensions (Kexts)"]:::driver

    %% User-Space Interfaces
    EXTERNAL_HEADERS["External User-Space Headers"]:::user

    %% Kernel Libraries
    subgraph "Kernel Libraries"
        libkern["libkern"]:::lib
        libkmod["libkern/kmod"]:::lib
        libsyscall["libsyscall"]:::lib
    end

    %% Build System
    subgraph "Build System"
        setup["SETUP"]:::build
        configdir["config"]:::build
        makefile["Makefile"]:::build
    end

    %% Relationships
    libsa -->|"loads and transfers control"| osfmk
    pexpert -->|"initializes platform"| osfmk
    osfmk <-->|"hardware I/O via IOService"| iokit
    osfmk <-->|"Mach ports interface"| bsd
    bsd -->|"POSIX syscalls"| libsyscall
    iokit -->|"driver plug-in discovery"| Kexts

    %% Kernel Libraries to all layers
    libkern --> osfmk
    libkern --> bsd
    libkern --> iokit
    libkern --> Kexts
    libkmod --> osfmk
    libkmod --> iokit
    libsyscall --> EXTERNAL_HEADERS

    %% Build System dependencies
    setup --> libsa
    setup --> osfmk
    configdir --> bsd
    configdir --> iokit
    makefile --> libkern

    %% Click Events
    click libsa "https://github.com/darwin-on-arm/xnu/tree/master/libsa/"
    click pexpert "https://github.com/darwin-on-arm/xnu/tree/master/pexpert/"
    click osfmk "https://github.com/darwin-on-arm/xnu/tree/master/osfmk/"
    click bsd "https://github.com/darwin-on-arm/xnu/tree/master/bsd/"
    click iokit "https://github.com/darwin-on-arm/xnu/tree/master/iokit/"
    click libkern "https://github.com/darwin-on-arm/xnu/tree/master/libkern/"
    click libkmod "https://github.com/darwin-on-arm/xnu/tree/master/libkern/kmod/"
    click libsyscall "https://github.com/darwin-on-arm/xnu/tree/master/libsyscall/"
    click setup "https://github.com/darwin-on-arm/xnu/tree/master/SETUP/"
    click configdir "https://github.com/darwin-on-arm/xnu/tree/master/config/"
    click makefile "https://github.com/darwin-on-arm/xnu/tree/master/Makefile"
    click Kexts "https://github.com/darwin-on-arm/xnu/tree/master/config/System.kext/"
    click EXTERNAL_HEADERS "https://github.com/darwin-on-arm/xnu/tree/master/EXTERNAL_HEADERS/"

    %% Styles
    classDef boot fill:#f9f,stroke:#333,font-weight:bold
    classDef core fill:#faa,stroke:#333
    classDef oservices fill:#afa,stroke:#333
    classDef driver fill:#aaf,stroke:#333
    classDef lib fill:#ff9,stroke:#333
    classDef user fill:#9ff,stroke:#333
    classDef build fill:#ccc,stroke:#333,stroke-dasharray: 5 5
```
