Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,5 @@ jobs:
fi
echo "✅ Build successful!"

- name: Boot smoke test
run: make smoke
3 changes: 1 addition & 2 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2025 uROS Team (Thomas, Simón, María Paula)
Copyright (c) 2025 Thomas

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand All @@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

6 changes: 4 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ OBJ_S = $(patsubst %.S,build/%.o,$(SRC_S))
OBJ = $(OBJ_C) $(OBJ_S)

# Targets
.PHONY: all run clean dtb
.PHONY: all run smoke clean dtb

all: build/kernel.elf

Expand All @@ -41,11 +41,13 @@ build/%.o: %.S
run: build/kernel.elf
@bash scripts/run-qemu.sh

smoke: build/kernel.elf
@bash scripts/smoke.sh

clean:
rm -rf build/

dtb:
qemu-system-riscv64 -machine virt,dumpdtb=virt.dtb -nographic -bios default
dtc -I dtb -O dts virt.dtb -o virt.dts
@echo "DTB dumped to virt.dtb and virt.dts"

12 changes: 6 additions & 6 deletions OS DEV_ OPEN C906 RISC-V.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,17 @@ Matemáticas Aplicadas y Ciencias de la Computación

## 1. INTRODUCTION

The RISC-V architecture offers an open-source alternative to proprietary Instruction Set Architectures (ISAs) like x86 or ARM. However, the ecosystem for RISC-V operating systems is still maturing. This gap motivated the development of **Helios**, a minimal operating system designed for educational purposes on the RISC-V 64-bit environment.
The RISC-V architecture offers an open-source alternative to proprietary Instruction Set Architectures (ISAs) like x86 or ARM. However, the ecosystem for RISC-V operating systems is still maturing. This gap motivated the development of **HeliOS**, a minimal operating system designed for educational purposes on the RISC-V 64-bit environment.

The primary goal of this project is to demonstrate fundamental operating system concepts through practical implementation. Rather than aiming for production-level features, we focused on creating a clean, understandable codebase that illustrates core OS mechanisms including process scheduling, memory management, hardware abstraction, and system calls.

**Helios** serves as both a learning tool and a research platform. By implementing real OS components from the ground up, we gained deeper insights into the practical considerations of system software development that theoretical study alone cannot provide.
**HeliOS** serves as both a learning tool and a research platform. By implementing real OS components from the ground up, we gained deeper insights into the practical considerations of system software development that theoretical study alone cannot provide.

---

## 2. PROJECT VISION & ARCHITECTURE

**Helios** is built around a microkernel-inspired architecture that keeps the core system lean while isolating hardware-specific components. This design facilitates reasoning about the system and allows for future expansion. The kernel is organized into distinct layers:
**HeliOS** is built around a microkernel-inspired architecture that keeps the core system lean while isolating hardware-specific components. This design facilitates reasoning about the system and allows for future expansion. The kernel is organized into distinct layers:

| Layer | Core Function | Components |
| :----------------------------------- | :----------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -197,7 +197,7 @@ _Figure 3: Real-time memory usage statistics showing heap allocation._
We implemented a complete context switch that preserves all 31 RISC-V general-purpose registers and critical CSRs (sstatus, sepc). This enables true preemptive multitasking.

**[INSERT IMAGE HERE: Screenshot of the boot sequence with the ASCII Art Banner]**
_Figure 4: Helios OS Boot Sequence._
_Figure 4: HeliOS OS Boot Sequence._

### 4.2 Task Management System

Expand All @@ -208,7 +208,7 @@ _Figure 5: Process Control Block structure._

### 4.3 Interactive Shell

Unlike many educational OS projects that are static, **Helios** features a fully interactive shell with over 10 commands.
Unlike many educational OS projects that are static, **HeliOS** features a fully interactive shell with over 10 commands.

- **Commands:** `help`, `ps` (process list), `kill` (terminate process), `sched` (switch scheduler), `bench` (benchmark), `meminfo` (memory stats).

Expand All @@ -219,7 +219,7 @@ _Figure 6: Interactive Shell Interface._

## 5. CONCLUSION

The **Helios** project successfully demonstrates the implementation of a functional operating system kernel for RISC-V. We have achieved:
The **HeliOS** project successfully demonstrates the implementation of a functional operating system kernel for RISC-V. We have achieved:

1. **Stability:** A robust kernel that handles interrupts and context switches without crashing.
2. **Functionality:** A rich set of features including multitasking, synchronization, and dynamic memory.
Expand Down
56 changes: 28 additions & 28 deletions PROJECT_SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# uROS - RISC-V Mini-OS Implementation Summary
# HeliOS - RISC-V Mini-OS Implementation Summary

## Project Overview

Expand All @@ -10,7 +10,7 @@ All components have been implemented according to the specification.

## Components Delivered

### 1. Core Infrastructure (`include/uros.h`)
### 1. Core Infrastructure (`include/helios.h`)
- Complete type definitions (u8, u16, u32, u64, size_t)
- Context structure with all 31 GP registers + sstatus + sepc (272 bytes total)
- PCB structure with scheduling metadata (burst estimation, arrival/finish times)
Expand Down Expand Up @@ -173,14 +173,14 @@ Offset Register
## Build Status

✅ Compiles without errors
✅ Links successfully
✅ Links successfully
✅ Generates 57KB ELF executable
✅ All required files created

## Files Created

### Source Files (14 total)
- `include/uros.h` - Main header (180 lines)
- `include/helios.h` - Main header (180 lines)
- `linker.ld` - Linker script
- `boot/start.S` - Boot assembly + context switch (105 lines)
- `kernel/kmain.c` - Kernel entry
Expand All @@ -200,26 +200,26 @@ Offset Register

## Definition of Done - Checklist

✅ `make` compiles successfully
✅ `make run` boots to banner
✅ Prompt "uROS> " implemented
✅ `help` command lists all commands
✅ `run cpu` and `run io` create tasks
✅ `ps` shows task information
✅ `sched rr` and `sched sjf` switch modes
✅ `bench` compares RR vs SJF with metrics
✅ `uptime` shows system time
✅ `meminfo` shows memory usage
✅ `kill <pid>` terminates tasks
✅ Timer configured for 100 Hz
✅ Context switch preserves all registers
✅ SBI timer interface implemented
✅ UART TX/RX functional
✅ Round-Robin with 5-tick quantum
✅ SJF with exponential averaging
✅ Benchmark with 6 tasks and metrics
✅ README with full documentation
✅ All scripts executable
✅ `make` compiles successfully
✅ `make run` boots to banner
✅ Prompt "HeliOS> " implemented
✅ `help` command lists all commands
✅ `run cpu` and `run io` create tasks
✅ `ps` shows task information
✅ `sched rr` and `sched sjf` switch modes
✅ `bench` compares RR vs SJF with metrics
✅ `uptime` shows system time
✅ `meminfo` shows memory usage
✅ `kill <pid>` terminates tasks
✅ Timer configured for 100 Hz
✅ Context switch preserves all registers
✅ SBI timer interface implemented
✅ UART TX/RX functional
✅ Round-Robin with 5-tick quantum
✅ SJF with exponential averaging
✅ Benchmark with 6 tasks and metrics
✅ README with full documentation
✅ All scripts executable

## Next Steps for Testing

Expand Down Expand Up @@ -249,7 +249,7 @@ Offset Register

## Conclusion

The uROS mini-OS is a complete, compilable implementation meeting all specified requirements. It demonstrates core OS concepts including:
The HeliOS mini-OS is a complete, compilable implementation meeting all specified requirements. It demonstrates core OS concepts including:
- Interrupt handling
- Context switching
- Process scheduling (RR & SJF)
Expand All @@ -260,8 +260,8 @@ The uROS mini-OS is a complete, compilable implementation meeting all specified
Ready for demonstration and further development.

---
**Generated**: October 23, 2025
**Platform**: RISC-V 64 (rv64gc) / QEMU virt
**Build**: Successful
**Generated**: October 23, 2025
**Platform**: RISC-V 64 (rv64gc) / QEMU virt
**Build**: Successful
**Status**: COMPLETE ✅

71 changes: 41 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# uROS - Mini OS en RISC-V 64
# HeliOS - Mini OS en RISC-V 64

> Un sistema operativo educativo minimalista para RISC-V 64 corriendo en QEMU
>
> El nombre combina **Helium Browser** + **OS**: **HeliOS**.

[![RISC-V](https://img.shields.io/badge/RISC--V-64-blue)](https://riscv.org/)
[![QEMU](https://img.shields.io/badge/QEMU-virt-orange)](https://www.qemu.org/)
Expand All @@ -12,10 +14,12 @@
- ✅ **QEMU virt** con OpenSBI
- ✅ **Shell interactiva** con 10+ comandos
- ✅ **Sistema de tareas** con context switching
- ✅ **Scheduler Round-Robin** cooperativo
- ✅ **Scheduler Round-Robin** cooperativo o preemptivo
- ✅ **Scheduler SJF** con estimación de ráfagas
- ✅ **Driver UART** NS16550A
- ✅ **Printf** implementado
- ✅ **Gestión de memoria** con bump allocator
- ✅ **Gestión de memoria** con free-list allocator
- ✅ **Smoke test en QEMU** para CI

## 🚀 Inicio Rápido

Expand All @@ -38,13 +42,16 @@ make clean && make -j
# 2. Ejecutar
make run

# 3. En el prompt uROS>, prueba:
# 3. En el prompt HeliOS>, prueba:
help
ps
run cpu
run io
ps
sched preempt on
uptime
meminfo
intstats
```

**Para salir:** `Ctrl+C`
Expand All @@ -59,17 +66,22 @@ Ejecuta automáticamente: `help` → `ps` → `run cpu` → `run io` → `ps`

## 📋 Comandos Disponibles

| Comando | Descripción |
| ------------ | -------------------------- |
| `help` | Lista todos los comandos |
| `ps` | Muestra tareas activas |
| `run cpu` | Crea tarea CPU-bound |
| `run io` | Crea tarea I/O-bound |
| `kill <pid>` | Termina una tarea |
| `sched rr` | Scheduler Round-Robin |
| `bench` | Benchmark (requiere timer) |
| `uptime` | Tiempo de ejecución |
| `meminfo` | Uso de memoria |
| Comando | Descripción |
| ----------------------- | ----------------------------------- |
| `help` | Lista todos los comandos |
| `ps` | Muestra tareas activas |
| `run cpu` | Crea tarea CPU-bound |
| `run io` | Crea tarea I/O-bound |
| `kill <pid>` | Termina una tarea |
| `sched rr` | Scheduler Round-Robin |
| `sched sjf` | Scheduler Shortest Job First |
| `sched preempt on|off` | Activa/desactiva preemption por timer |
| `sleep <ticks>` | Espera N ticks |
| `pcdemo` | Demo productor-consumidor |
| `bench` | Benchmark de scheduling |
| `uptime` | Tiempo de ejecución |
| `meminfo` | Uso de memoria |
| `intstats` | Estado de timer/interrupciones |

## 📁 Estructura

Expand All @@ -86,7 +98,7 @@ mini-os/
│ ├── uart.c # NS16550A
│ └── timer.c # Timer SBI
├── lib/printf.c # Printf
├── include/uros.h # Headers
├── include/helios.h # Headers
└── scripts/ # Scripts útiles
```

Expand All @@ -97,16 +109,16 @@ make # Compila el proyecto
make run # Ejecuta en QEMU
make run-gdb # Ejecuta con debugger
make gdb # Conecta GDB
make smoke # Compila y ejecuta smoke test en QEMU
make clean # Limpia build/
make dtb # Extrae device tree
```

## 📖 Documentación

- **[GUIA_COMPLETA.md](GUIA_COMPLETA.md)** - Guía detallada con ejemplos
- **[README_RAPIDO.md](README_RAPIDO.md)** - Referencia rápida
- **[VERIFICATION.md](VERIFICATION.md)** - Verificación técnica
- **[docs/README.md](docs/README.md)** - Documentación técnica
- **[docs/visualization.html](docs/visualization.html)** - Visualización web

## 🎓 Ejemplo de Uso

Expand All @@ -116,28 +128,28 @@ $ make run
OpenSBI v1.5.1
[Boot info...]

uROS (rv64gc, QEMU virt) - console ready
HeliOS (rv64gc, QEMU virt) - console ready
ticks=0
Initializing task system...
Initializing scheduler...
Creating idle task...
System initialized, starting shell...

uROS> help
HeliOS> help
Available commands:
help - Show this help
ps - List tasks
run cpu - Create CPU-bound task
...

uROS> ps
HeliOS> ps
PID STATE TICKS BURST_EST ARRIVAL
0 READY 0 1 0

uROS> run cpu
HeliOS> run cpu
Created CPU task with PID 1

uROS> ps
HeliOS> ps
PID STATE TICKS BURST_EST ARRIVAL
0 READY 0 1 0
1 READY 0 20 0
Expand All @@ -162,9 +174,9 @@ make gdb
- **Boot**: OpenSBI (-bios default)
- **Mode**: S-mode bare metal
- **UART**: 0x10000000 (NS16550A)
- **Scheduler**: Round-Robin cooperativo (sin timer por estabilidad)
- **Memory**: Bump allocator, 256KB heap
- **Tasks**: Max 32, 4KB stack cada una
- **Scheduler**: Round-Robin cooperativo/preemptivo y SJF
- **Memory**: Free-list allocator con coalescing, 256KB heap
- **Tasks**: Max 32, 8KB stack cada una

## ✅ Estado del Proyecto

Expand All @@ -178,18 +190,17 @@ make gdb
- ✅ UART input/output
- ✅ Gestión de memoria
- ✅ Visualización Web (ver `docs/visualization.html`)
- ✅ Smoke test automatizado en QEMU

**Limitaciones actuales (por diseño):**

- Sin MMU (memoria física directa)
- Sin sistema de archivos (todo en RAM)
- Modo Supervisor único (sin separación User/Kernel estricta)

## 🤝 Colaboradores
## 👤 Autor

- **Thomas**
- **Simón**
- **María Paula**

## 📝 Licencia

Expand All @@ -199,4 +210,4 @@ MIT License - ver archivo LICENSE

**🚀 ¡Listo para demostración y evaluación!**

Para más detalles, consulta [GUIA_COMPLETA.md](GUIA_COMPLETA.md)
Para más detalles, consulta [docs/README.md](docs/README.md)
Loading
Loading