# fardenghi/so-tp2 architecture

> Architecture diagram of the GitHub repository fardenghi/so-tp2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fardenghi/so-tp2
- Repository: https://github.com/fardenghi/so-tp2

## Overview

##### Project type and purpose
- This is a teaching‐grade monolithic 64‐bit operating system.
- It comprises:
- A Bootloader (BMFS and Pure64 variants)
- A Kernel (interrupts, drivers, memory, scheduler, syscalls)
- A Userland (shell, utilities, tests)
- A Toolchain (cross‐compiler, ModulePacker)
- Build & run scripts (compile.sh, run.sh invoking Docker/QEMU)

##### High‐level file‐tree analysis
- Top‐level folders:
- Bootloader/…
- Image/…
- Kernel/…
- Toolchain/…
- Userland/…
- Support scripts in root: compile.sh, run.sh
- Kernel subdivides into Drivers, Interruptions, Memory, Processes, Semaphores, Pipes, Util, asm, include.
- Userland hosts a sample code module with Programs, Libs, asm stubs, headers.
- Toolchain contains ModulePacker for bundling kernel modules.

##### Key features from README
- Monolithic kernel with preemptive round‐robin scheduler
- Two memory managers: free‐list & buddy
- System calls, semaphores, pipes, drivers (keyboard, video, audio, time)
- Build in Docker container, run in QEMU with optional GDB

##### Main components
a. Build Environment
– Docker container (agodio/itba-so-multi-platform:3.0)
– Scripts: compile.sh (parameters: no-buddy/debug/buddy), run.sh (gdb)
– Toolchain: cross‐compiler toolchain, ModulePacker
b. Bootloader
– BMFS variant (BareMetal FS)
– Pure64 variant (bootsectors, init, syscalls)
– Role: set up CPU mode, load kernel into memory
c. Kernel
– Core initialization (cpu, pic, acpi, smp)
– Interrupt handling (IDT, IRQ dispatcher, exceptions)
– Memory management (free‐list, buddy systems, allocation interfaces)
– Process management (process table, context switching, scheduler)
– IPC mechanisms (unidirectional pipes, blocking I/O)
– Synchronization (semaphores)
– Device drivers (keyboard, video, audio, time)
– System call interface
d. Userland
– Shell (built‐in commands, parser, REPL)
– Utilities: cat, wc, filter, philosophers, help, mem, ps, kill, etc.
– Test programs (sync_test, test_mm, test_processes, etc.)
e. Execution Environment
– QEMU VM (virtual hardware)
– Optional GDB server integration

##### Interactions & data flows
- Build pipeline: compile.sh → Docker → Toolchain → Bootloader + Kernel + User modules → disk image
- run.sh → QEMU VM loads MBR → Bootloader → Loads Kernel → Kernel init → Launch shell process
- Userland apps ↔ Kernel via system calls (I/O, fork/exec, pipes, semaphores)
- Interrupts (timer, keyboard) trigger kernel handlers → scheduler context‐switches
- Drivers interface with virtual hardware via QEMU’s emulated devices

##### Architectural patterns & design principles
- Monolithic kernel: all core services (memory, processes, drivers, IPC) live in kernel space
- Layered initialization: bootstrap → CPU setup → memory manager → device init → scheduler → userland
- Use of modular code (separate C/ASM units, ModulePacker bundles modules)
- Clear separation: Bootloader vs Kernel vs Userland

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Environment
    subgraph "Build Environment"
        direction TB
        CS["compile.sh"]:::build
        RS["run.sh"]:::build
        RM["Makefile"]:::build
        DC["Docker Container\ndagio/itba-so-multi-platform:3.0"]:::build
        CC["Cross-Compiler Toolchain"]:::tool
        TP["ModulePacker"]:::tool
        TM["Toolchain Makefile"]:::tool
    end

    %% Bootloader
    subgraph "Bootloader" 
        direction TB
        BMFS_RD["BMFS README"]:::boot
        BMFS_MK["BMFS Makefile"]:::boot
        BMFS_SRC["bmfs.c"]:::boot
        BMFS_DOC["BareMetal File System.md"]:::doc

        PURE64_MK["Pure64 Makefile"]:::boot
        PURE64_BAT["build.bat"]:::boot
        PURE64_MAN["Pure64 Manual.md"]:::doc
        PURE64_SRC["Pure64/src"]:::boot
        PURE64_DOCS["Pure64/docs"]:::doc
    end

    %% Kernel
    subgraph "Kernel" 
        direction TB
        K_MK["Kernel Makefile"]:::kernel
        K_C["kernel.c"]:::kernel
        K_ASM["loader.asm"]:::kernel
        K_LD["kernel.ld"]:::kernel
        subgraph "Subsystems"
            direction TB
            KD["Drivers"]:::kernel
            KI["Interrupt Handling"]:::kernel
            KM["Memory Management"]:::kernel
            KP["Process & Scheduling"]:::kernel
            IP["IPC (Pipes)"]:::kernel
            SM["Semaphores"]:::kernel
            KU["Util Library"]:::kernel
            KA["ASM Helpers"]:::kernel
            KH["Headers"]:::kernel
        end
    end

    %% Userland
    subgraph "Userland"
        direction TB
        UMK["Userland Makefiles"]:::user
        subgraph "SampleCodeModule"
            direction TB
            SM_C["sampleCodeModule.c"]:::user
            SM_LD["sampleCodeModule.ld"]:::user
            LDR["_loader.c"]:::user
            subgraph "Programs"
                direction TB
                SH["Shell"]:::user
                CAT["cat.c"]:::user
                FIL["filter.c"]:::user
                PHI["philosofers.c"]:::user
                WC["wc.c"]:::user
                SP["shellPrograms.c"]:::user
            end
            subgraph "Shell Internals"
                direction TB
                SHC["shell.c"]:::user
                CMD["commandManagerADT.c"]:::user
            end
            subgraph "Libs"
                direction TB
                LIB["lib.c"]:::user
                LIBC["libc.c"]:::user
            end
            subgraph "ASM Stubs"
                direction TB
                SYSASM["syscaller.asm"]:::user
                ULIBASM["userLib.asm"]:::user
            end
            subgraph "Headers"
                direction TB
                UH["include/*.h"]:::user
            end
            FONT["fontBIG.c"]:::user
            subgraph "Tests"
                direction TB
                T1["testUserland.c"]:::user
                T2["test_util.c"]:::user
            end
        end
    end

    %% Execution Environment
    subgraph "Execution VM/Hardware"
        direction TB
        QEMU["QEMU VM"]:::vm
        GDB[".gdbinit"]:::vm
    end

    %% Connections
    CS -->|invokes| DC
    DC -->|provides| CC
    CC -->|compiles| BMFS_SRC
    CC -->|compiles| PURE64_SRC
    CC -->|links| K_C
    CC -->|packages modules| TP
    CC -->|builds userland| SM_C
    TP -->|outputs modules| KD

    RS -->|starts| QEMU
    QEMU -->|BIOS->MBR| BMFS_SRC
    BMFS_SRC -->|loads| K_C
    PURE64_SRC -->|loads| K_C
    K_C -->|init| KD
    KD -->|register devices| QEMU
    KI -->|handles IRQs| KP
    IP -->|provides| UMK
    SM -->|sync| UMK
    SH -->|syscalls| K_C

    %% Click Events
    click CS "https://github.com/fardenghi/so-tp2/blob/main/./compile.sh"
    click RS "https://github.com/fardenghi/so-tp2/blob/main/./run.sh"
    click RM "https://github.com/fardenghi/so-tp2/tree/main/./Makefile"
    click TM "https://github.com/fardenghi/so-tp2/tree/main/./Toolchain/Makefile"
    click TP "https://github.com/fardenghi/so-tp2/blob/main/./Toolchain/ModulePacker/main.c"
    click TP "https://github.com/fardenghi/so-tp2/blob/main/./Toolchain/ModulePacker/modulePacker.h"
    click TP "https://github.com/fardenghi/so-tp2/tree/main/./Toolchain/ModulePacker/Makefile"
    click BMFS_RD "https://github.com/fardenghi/so-tp2/blob/main/./Bootloader/BMFS/README.md"
    click BMFS_MK "https://github.com/fardenghi/so-tp2/tree/main/./Bootloader/BMFS/Makefile"
    click BMFS_SRC "https://github.com/fardenghi/so-tp2/blob/main/./Bootloader/BMFS/bmfs.c"
    click BMFS_DOC "https://github.com/fardenghi/so-tp2/blob/main/./Bootloader/BMFS/BareMetal File System.md"
    click PURE64_MK "https://github.com/fardenghi/so-tp2/tree/main/./Bootloader/Pure64/Makefile"
    click PURE64_BAT "https://github.com/fardenghi/so-tp2/blob/main/./Bootloader/Pure64/build.bat"
    click PURE64_MAN "https://github.com/fardenghi/so-tp2/blob/main/./Bootloader/Pure64/Pure64 Manual.md"
    click PURE64_SRC "https://github.com/fardenghi/so-tp2/tree/main/./Bootloader/Pure64/src"
    click PURE64_DOCS "https://github.com/fardenghi/so-tp2/tree/main/./Bootloader/Pure64/docs"
    click K_C "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/kernel.c"
    click K_ASM "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/loader.asm"
    click K_LD "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/kernel.ld"
    click K_MK "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/Makefile"
    click KD "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/Drivers/"
    click KI "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/Interruptions/"
    click KM "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/Memory/memoryManagementADT.c"
    click KM "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/Memory/buddyMemoryManagementADT.c"
    click KM "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/Memory/memoryManager.c"
    click KP "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/Processes/"
    click IP "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/Pipes/pipes.c"
    click SM "https://github.com/fardenghi/so-tp2/blob/main/./Kernel/Semaphores/semaphores.c"
    click KU "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/Util/"
    click KA "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/asm/"
    click KH "https://github.com/fardenghi/so-tp2/tree/main/./Kernel/include/"
    click UMK "https://github.com/fardenghi/so-tp2/tree/main/./Userland/Makefile"
    click SM_C "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/sampleCodeModule.c"
    click SM_LD "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/sampleCodeModule.ld"
    click LDR "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/_loader.c"
    click SH "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/Shell/shell.c"
    click CAT "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/cat.c"
    click FIL "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/filter.c"
    click PHI "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/philosofers.c"
    click WC "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/wc.c"
    click SP "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Programs/shellPrograms.c"
    click SYSASM "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/asm/syscaller.asm"
    click ULIBASM "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/asm/userLib.asm"
    click FONT "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Fonts/fontBIG.c"
    click T1 "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Tests/testUserland.c"
    click T2 "https://github.com/fardenghi/so-tp2/blob/main/./Userland/SampleCodeModule/Tests/test_util.c"
    click QEMU "https://github.com/fardenghi/so-tp2/blob/main/./run.sh"
    click GDB "https://github.com/fardenghi/so-tp2/blob/main/./.gdbinit"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#1E88E5,color:#000;
    classDef tool fill:#90CAF9,stroke:#42A5F5,color:#000;
    classDef boot fill:#FFA500,stroke:#F57C00,color:#000;
    classDef kernel fill:#FDD835,stroke:#F9A825,color:#000;
    classDef user fill:#A5D6A7,stroke:#66BB6A,color:#000;
    classDef vm fill:#B0BEC5,stroke:#78909C,color:#000;
    classDef doc fill:#E0E0E0,stroke:#9E9E9E,color:#000;
```
