# cseslowpoke/nycu-osc architecture

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

- Interactive diagram: https://gitdiagram.com/cseslowpoke/nycu-osc
- Repository: https://github.com/cseslowpoke/nycu-osc

## Overview

##### Main Components
- Bootloader – This is the first-stage component responsible for initializing hardware and loading the kernel. It contains assembly code (boot.s), a linker script (linker.ld), and a C entry point (main.c), plus UART support (uart.c and uart.h) for early debugging/output.
- Kernel – This is the core operating system and is modularly organized into:
- Architecture-specific layer (kernel/arch/arm64): Contains ARM64-specific boot code (boot.s) and exception handling (exception.s), showing platform-dependent initializations.
- Core functionalities (kernel/core): Implements the command system, exception handling, basic shell, simple memory allocation (simple_alloc.c), and user execution, indicating an interactive and possibly multi-user system.
- Drivers (kernel/drivers): Contains code managing interrupts (irq.c), mailbox communication, timers, UART communication, and watchdog timers, thus abstracting hardware interfaces.
- Filesystem (kernel/fs): Implements filesystem-related functionalities such as handling CPIO archives, Flattened Device Trees (FDT), and abstract file operations.
- Common Utilities (kernel/common): Includes shared utility functions (e.g., string operations in string.c and utils in utils.c) used across different kernel components.
- Shared headers in kernel/include: Organizes all the interface definitions by module including types and helper functions.
- Tools – Contains supporting scripts such as send_kernel.py, which is likely used to deploy the kernel image to target hardware.

##### Relationships and Interactions
- Bootloader initiates the system and loads the kernel image into memory.
- The kernel initialization begins in main.c (in the kernel directory) and then diverges into the architecture-specific startup routines (kernel/arch/arm64).
- The core module sets up essential services such as the shell interface, exception handling, and user process execution.
- Drivers provide a hardware abstraction layer essential for system services—IRQ, UART, timer, and others are invoked by both the core and filesystem modules.
- The filesystem module interacts with hardware drivers to read files (e.g., the initial ramdisk in CPIO format) and possibly to parse device trees with FDT.
- The tools, particularly the Python script, support deployment or debugging by interfacing with the bootloader/kernel binaries.

##### Architectural Patterns and Design Principles
- Modularity: The system is clearly divided into well-defined modules (bootloader, core, drivers, filesystem, architecture-specific code) that simplify maintenance and testing.
- Hardware Abstraction: Drivers isolate hardware-specific code from core components.
- Layered Initialization: The bootloader’s responsibility for low-level initialization and the kernel’s structured initialization (architecture layer → core services → drivers/filesystem) follows an organized hierarchy.
- Use of Makefiles: Each module has its own Makefile, indicating that the build process is modular and component-specific.

##### Relevant Technologies, Frameworks, and Libraries
- Assembly language for initial boot (boot.s and exception.s)
- C language for implementing both low-level hardware interfacing and higher-level OS functionalities.
- Makefile-driven builds, which are prevalent across all modules.
- Likely use of linked scripts (linker.ld) to manage memory layout, particularly critical in OS development.

##### Specific Elements
- Component Labels: Bootloader, Kernel (with sub-components Architecture [ARM64], Core, Drivers, Filesystem, and Common Utilities), and Tools.
- Build and Deployment Process: Optionally include a flow to represent the role of the Makefiles and the deployment script (send_kernel.py) in flashing or running the OS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bootloader Node
    BL["Bootloader"]:::bootloader

    %% Kernel Subgraph
    subgraph "Kernel"
        KI["Kernel Initialization (kernel/main.c)"]:::kernel
        ARCH["Architecture (ARM64)"]:::arch
        CORE["Core Functionalities"]:::core
        DRV["Drivers"]:::drivers
        FS["Filesystem Module"]:::fs
        COMMON["Common Utilities & Headers"]:::common
    end

    %% Tools Node
    T["Deployment Tool (send_kernel.py)"]:::tools

    %% Connections for Boot Process
    BL -->|"loads"| KI
    KI -->|"init_arch"| ARCH
    KI -->|"init_core"| CORE
    KI -->|"init_drivers"| DRV
    KI -->|"init_fs"| FS
    KI -->|"init_common"| COMMON

    %% Interactions within Kernel
    CORE -->|"uses"| DRV
    FS -->|"accesses"| DRV

    %% Tools interacting with Bootloader/Kernel for deployment
    T -->|"deploys"| BL
    T -->|"deploys"| KI

    %% Click Events
    click BL "https://github.com/cseslowpoke/nycu-osc/tree/main/bootloader/"
    click KI "https://github.com/cseslowpoke/nycu-osc/blob/main/kernel/main.c"
    click ARCH "https://github.com/cseslowpoke/nycu-osc/tree/main/kernel/arch/arm64/"
    click CORE "https://github.com/cseslowpoke/nycu-osc/tree/main/kernel/core/"
    click DRV "https://github.com/cseslowpoke/nycu-osc/tree/main/kernel/drivers/"
    click FS "https://github.com/cseslowpoke/nycu-osc/tree/main/kernel/fs/"
    click COMMON "https://github.com/cseslowpoke/nycu-osc/tree/main/kernel/common/"
    click T "https://github.com/cseslowpoke/nycu-osc/blob/main/tools/send_kernel.py"

    %% Styles
    classDef bootloader fill:#FFDEAD,stroke:#333,stroke-width:2px;
    classDef kernel fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef arch fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef core fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef drivers fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef fs fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef common fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef tools fill:#FFA07A,stroke:#333,stroke-width:2px;
```
