Operator-system/README.md

Simple UEFI Operating System

A minimal bootable UEFI operating system written in C that demonstrates basic UEFI functionality.

Features

• UEFI Boot: Boots directly on UEFI firmware
• Console I/O: Interactive keyboard input and screen output
• System Information: Displays firmware details
• Simple Commands: Interactive command interface

Requirements

• GCC compiler
• GNU-EFI library
• QEMU with OVMF firmware
• Make

Installation

On Debian/Ubuntu:

make install-deps

Or manually:

sudo apt-get install gnu-efi qemu-system-x86 ovmf gcc binutils make

On Arch Linux:

sudo pacman -S gnu-efi qemu-system-x86 edk2-ovmf gcc binutils make

On Fedora/RHEL:

sudo dnf install gnu-efi qemu-system-x86 edk2-ovmf gcc binutils make

Building

Build the UEFI application:

make

This will create build/EFI/BOOT/BOOTX64.EFI

Running

Test with QEMU (no graphics mode):

make run

QEMU Controls:

• Exit QEMU: Press Ctrl+A, then X
• Shutdown OS: Press q in the OS

Commands in the OS

Once the OS boots, you can use these commands:

• h - Display help
• i - Display system information
• c - Clear screen
• q - Shutdown the system

Project Structure

.
├── main.c          # Main UEFI application source code
├── Makefile        # Build configuration
└── README.md       # This file

How It Works

1. UEFI Entry Point: The efi_main function is the entry point called by UEFI firmware
2. Initialization: GNU-EFI library is initialized with the system table
3. Console Setup: Output is configured and screen is cleared
4. Main Loop: The OS enters a loop waiting for keyboard input
5. Command Processing: User commands are processed and executed
6. Shutdown: UEFI runtime services are used to shutdown the system

Building for Real Hardware

To create a bootable USB drive:

1. Build the project: make
2. Format a USB drive with GPT and create an EFI partition (FAT32)
3. Mount the EFI partition
4. Copy build/EFI/BOOT/BOOTX64.EFI to /EFI/BOOT/ on the USB drive
5. Boot from the USB drive in UEFI mode

Warning: Always backup your data before creating bootable media!

Cleaning

Remove build artifacts:

make clean

Troubleshooting

GNU-EFI headers not found

Make sure GNU-EFI is installed. The headers are typically in /usr/include/efi.

If installed in a different location, update the EFI_INC variable in the Makefile.

OVMF firmware not found

OVMF files might be in different locations depending on your distribution:

• /usr/share/OVMF/
• /usr/share/qemu/
• /usr/share/edk2-ovmf/

Update the paths in the Makefile if needed.

QEMU crashes or fails to start

Ensure you have QEMU with x86_64 support and OVMF firmware installed.

Technical Details

• Architecture: x86_64
• Firmware Interface: UEFI 2.x
• Development Library: GNU-EFI
• Executable Format: PE32+ (Portable Executable for EFI)
• Boot Protocol: UEFI Boot Services

License

This is a minimal educational example. Feel free to use and modify as needed.

Further Development

Ideas for expansion:

• File system support
• Memory management
• Graphics output
• Network stack
• Device drivers
• Multi-tasking

Resources

• UEFI Specification
• GNU-EFI Documentation
• OSDev Wiki