Nano OS

Nano OS is a lightweight, 32-bit hobby operating system developed from scratch. It features a custom bootloader, a protected-mode hybrid C/C++/Zig kernel, VGA hardware drivers, interrupt management, and an interactive command-line shell.

Note: Please don't confuse our os with this OS. We have different compatibility features compared to the NanoSoft ones.

Key Features

• Custom Bootloader: Minimalist 16-bit real-mode assembly boot sector.
• 32-bit Protected Mode: Seamless transition to high-performance execution.
• Hybrid Kernel Runtime: Core safety checks and modules compiled seamlessly from C, C++, Zig, and Rust source files.
• Hardware Drivers: VGA text-mode driver with screen scrolling and cursor control.
• Interrupt Management: Full Interrupt Descriptor Table (IDT) implementation for hardware/CPU event handling.
• Keyboard Driver: Real-time hardware interrupt-driven keyboard input with scancode-to-ASCII translation.
• Nano Shell: Built-in CLI with command parsing, backspace/newline support, and custom command execution.
• Automated Build System: Professional Makefile-driven compilation supporting multiple toolchains.

Build & Run Instructions

Prerequisites

• nasm: Assembler
• i686-elf-gcc / i686-elf-ld: Cross-compiler toolchain
• zig (v0.16.0 or compatible): Alternative compiler for core modules
• rustup (nightly toolchain with build-std support): Compiler for core Rust components
• LLVM / Clang: Required for Rust automated binding generation (bindgen)
• make: Build automation
• Almost any virtual machine (e.g., QEMU, VirtualBox) or emulator (e.g., Bochs) that supports booting from a disk image.

Building

To clone the repository and build the OS, follow these steps:

git clone https://github.com/JimmiesAndTheCoders/nano-os.git
cd nano-os

Then, to build the OS, simply run:

make clean && make

Hybrid Rust Toolchain Setup

To compile the bare-metal Rust module, ensure you have the nightly toolchain installed:

rustup toolchain install nightly
rustup default nightly

Running

Using VirtualBox

The build system automatically compiles the VDI image and applies the target UUID configured in your Makefile.

1. Open VirtualBox.
2. Create a new virtual machine (e.g., "Nano OS") with the following settings:
   • Type: Other
   • Version: Other/Unknown (32-bit)
   • Memory: 512 MB
   • Hard Disk: Use an existing virtual hard disk file → Select build/nano-os.vdi
3. Start the virtual machine to boot into Nano OS.

Note: If the mouse is captured, press the Host key to release it.

Using QEMU (Recommended for testing)

QEMU is highly recommended for OS development because it boots raw files directly and has no disk cache locks. To run Nano OS with QEMU, use the following command:

qemu-system-i386 -drive format=raw,file=build/nano_os.img

Using VMware

VMware supports the Virtual Machine Disk (.vmdk) format. You can convert the raw image file to VMDK format:

# Convert raw image to VMware format
VBoxManage convertfromraw build/nano_os.img nano_os.vmdk --format VMDK

Once you have the VMDK file, follow these steps:

1. Open VMware Workstation or VMware Player.
2. Click on Create a New Virtual Machine (or press Ctrl+N).
3. Select Custom (advanced) and click Next.
4. Leave the hardware compatibility at the default highest version and click Next.
5. Select I will install the operating system later and click Next.
6. For the guest operating system, select Other and choose Other 32-bit. Click Next.
7. Name your virtual machine (e.g., "Nano OS").
8. For processors, 1 CPU and 1 core is more than enough. Click Next.
9. Assign 64 MB to 128 MB of RAM and click Next.
10. For network type, you can select Do not use a network connection since we won't be using network features.
11. For the I/O controller type, select LSI Logic.
12. On the Select a Disk page, choose Use an existing virtual disk and click Next.
13. Browse to the converted nano_os.vmdk file and select it.
14. When you click Next, VMware may prompt you to convert the disk to the latest format. Choose "Keep existing format" to avoid unnecessary conversions.
15. Click Finish to create the virtual machine.

Using Hyper-V

Hyper-V requires a Virtual Hard Disk (.vhdx) format. You can convert your raw image file to VHDX format:

# Convert raw image to Hyper-V format
VBoxManage convertfromraw build/nano_os.img nano_os.vhdx --format VHDX

Once you have the VHDX file, follow these steps:

1. Open Hyper-V Manager.
2. In the right-hand Actions panel, click New -> Virtual Machine.
3. Click Next and give your VM a name (e.g., "Nano OS").
4. Select Generation 1 (Generation 2 only boots UEFI; we are booting legacy BIOS).
5. Assign 64 MB to 128 MB of RAM.
6. Uncheck "Use Dynamic Memory for this virtual machine", and click Next.
7. For a custom hobby OS, you can usually leave this on Not Connected since we won't be using network features.
8. Select "Use an existing virtual hard disk" and browse to the converted nano_os.vhdx file. Click Next.
9. Click Finish to create the virtual machine.
10. Right-click the new VM, select Connect, and then click Start to boot into Nano OS.

Using Bochs

Bochs is a highly configurable x86 emulator. To run Nano OS with Bochs, use the following command:

bochs -f bochsrc

Using Nano Shell

Check out Nano Shell for more information about this shell.

Note: We'll be adding more commands in the future, so stay tuned!

Release

Check out Releases for all releases and updates about the OS.

Documentation

For detailed technical specifications of the operating system internals, please refer to the following documentation files:

Memory Architecture: Information regarding the physical memory map, page sizes, and heap management.

Driver API: Hardware interaction references for VGA, VESA graphics, timer, and keyboard sub-systems.

Roadmap

Check out the Roadmap for upcoming features and improvements.

Reporting Bugs

We welcome feedback and bug reports to help improve the stability and performance of Nano OS. If you encounter any compilation failures, system crashes, or unexpected kernel behaviors, please open an issue in the repository.

To help us diagnose and resolve the issue quickly, please include the following details in your report:

• Host Operating System: (e.g., Windows 11, macOS Sequoia, Ubuntu 24.04)
• Toolchain Versions: The output of i686-elf-gcc --version, zig version, and rustc --version (if applicable).
• Environment: The emulator or virtual machine used (e.g., QEMU, Bochs, VirtualBox, VMware) and its configuration (RAM, CPUs).
• Reproduction Steps: Clear, step-by-step instructions on how to trigger the issue from a clean build.
• Diagnostics: Any console logs, register dumps, or call stack traces displayed during a kernel panic.