Crate keos 

KeOS: KAIST Educational Operating System

Welcome to the KeOS project!

Operating systems (OS) form the backbone of modern computing, managing hardware resources and providing a foundation for applications to run efficiently. Understanding how an OS works is crucial for grasping the inner workings of computer systems and software performance.

KeOS is designed to offer a hands-on learning experience with core OS components. Through this project, you will explore the fundamental principles of OS design while building a minimal but functional operating system from the ground up.

We prioritize simplicity, focusing on the most essential aspects of OS development. You won’t have to worry about handling obscure edge cases or hidden test cases. The score you receive after running the grading scripts is your final score. Our goal is to make this project as straightforward as possible. If you have suggestions on how we can further minimize unnecessary complexity and focus on the core concepts, we encourage your feedback.

Project Structure

The KeOS project is divided into five projects:

1. System Call – Learn how the OS interacts with user applications.
2. Memory Management – Implement basic memory management and user-space execution.
3. Advanced Memory Management – Expand the KeOS’s memory management system with advanced features.
4. Process Management – Implement the advanced process management, including round robin scheduler and sychronization primitives.
5. File System – Develop a simple yet functional filesystem for data storage.

Each project builds upon the previous ones, helping you progressively develop a deeper understanding of OS design.

Why Rust?

We have chosen Rust for this project because of its memory safety, zero-cost abstractions, and most importantly, its concurrency model. These features make Rust an excellent choice for operating system development.

In traditional system programming languages, concurrency and memory bugs such as data races, use-after-free errors, and null pointer dereferences are common. Rust prevents these issues at compile time by enforcing strict ownership, borrowing, and lifetime rules. This allows you to write safe and efficient concurrent code without sacrificing performance, and reduces debugging time for those bugs.

By using Rust in KeOS, you will:

• Develop safe and efficient concurrent programs without the risk of data races.
• Avoid common concurrency pitfalls such as race conditions.

Getting Started

To set up your KeOS development environment, run the following commands:

$ mkdir keos
$ cd keos
$ curl https://raw.githubusercontent.com/casys-kaist/KeOS/refs/heads/main/scripts/install-keos.sh | sh

We recommend using VS Code as the editor, along with rust-analyzer for Rust support.

• DO NOT make public forks of this project.
• The KeOS license explicitly prohibits public redistribution of this work.
• You MUST NOT share or distribute your work based on the provided template.

Failure to comply may result in academic integrity violations.

Grading

During grading, we will overwrite all files except those explicitly whitelisted for each project. Any modifications to non-whitelisted files may result in a zero score, even if your implementation otherwise works correctly.

You can run the cargo grade command to check your current score locally. This reported score will be treated as your final grade, as long as your submission complies with the whitelist policy.

Grading rubrics and the list of whitelisted files can be found in each grader’s .grade-target file.

⚠️ IMPORTANT NOTES on GRADING

• The KeOS license explicitly prohibits sharing or distributing your work based on the provided template.
• Please DO NOT make public forks of this project.
• Cheating, plagiarism, or uploading your code online is strictly prohibited and will result in disqualification.

Failure to comply may result in academic integrity violations.

For the grading, please refer to the following policy:

• Your submission must pass all test cases without modifying the non-whitelisted code in each project.
• Submissions that fail to compile will receive 0 points.

Useful Materials

We strongly recommend reading the following materials to help you successfully complete the KeOS project:

• Tips on Implementation
• Debugging

Modules

channel

Multi-producer, multi-consumer FIFO queue communication primitives.

debugging

This modules explains debugging tips for KeOS.

fs

Filesystem abstraction.

intrinsics

Intrinsics of x86_64 not included in core::arch::x86_64.

lang 🔒

Rust-specific implemenations.

mm

Memory Management.

sync

Synchronization primitives.

syscall

System call infrastructure.

task

Task trait for interact with user process.

teletype

A teletype (TTY) interface for character-based I/O.

thread

Thread abstration, an abstraction of a cpu core.

tips

Useful tips for implementing KeOS Projects.

util

Debugging Utilities.

Macros

debug

Display a debug message.

info

Display an information message.

print

Prints out the message.

println

Prints out the message with a newline.

warning

Display a warning message.

Structs

SystemConfigurationBuilder

A builder for system configuration settings.

TestDriver

A driver for running tests.

TryFromError

The given isize does not indicate an KernelError.

Enums

KernelError

Enum representing errors that can occur during a kernel operation.

Constants

MAX_CPU

Maximum number of CPU the kernel can support.

Statics

PANIC_DEPTH

Panic depth level.

Functions

rust_ap_main^⚠

The entry of the KeOS for application processor.

rust_main^⚠

The entry of the KeOS for bootstrap processor.