Frequently Asked Questions

General Questions

What is guideXOS?

guideXOS is a bare-metal operating system written entirely in C# that runs directly on x86/x64 hardware. It includes a custom kernel, device drivers, network stack, filesystem, GUI desktop environment, and built-in applications—all compiled with Microsoft's NativeAOT technology.

Is guideXOS based on Cosmos?

No. While both are C# operating systems, guideXOS uses Microsoft's official NativeAOT compiler instead of Cosmos's custom IL-to-x86 translator. This provides better performance, stability, and production-grade code generation.

What makes guideXOS unique?

• NativeAOT compilation - Industrial-strength code generation
• Complete networking - Full IPv4 TCP/IP stack with web browser
• Modern GUI - Window manager with desktop environment
• Real hardware support - Runs on physical x86 machines
• No garbage collection - Custom memory allocator

Is guideXOS production-ready?

No. guideXOS is an educational and experimental project. It demonstrates what's possible with C# in a bare-metal environment, but it lacks many features required for production use (security, process isolation, extensive hardware support, etc.).

Can I use guideXOS as my daily OS?

Not recommended. guideXOS is best suited for:

• Learning OS development concepts
• Experimenting with bare-metal C#
• Understanding low-level hardware programming
• Fun and educational exploration

Technical Questions

How does C# run without Windows?

guideXOS uses NativeAOT (Ahead-of-Time compilation). The C# code is compiled directly to native x86/x64 machine code, eliminating the need for the .NET runtime. The OS provides its own minimal CoreLib implementation for basic types and functions.

Why no garbage collection?

Implementing a garbage collector in a bare-metal environment is complex and adds overhead. guideXOS uses manual memory management with a page-based allocator, similar to C's malloc/free. This provides:

• Predictable performance (no GC pauses)
• Lower memory footprint
• Deterministic resource cleanup

What hardware does it support?

Does it support multicore/multithreading?

Limited support. guideXOS can detect multiple CPU cores but currently runs on a single core. Multithreading support is planned for future versions.

Can it read/write to hard drives?

Currently, the file system is in-memory only. The IDE driver can read from disks and CD-ROMs, but persistent storage (reading/writing FAT32, ext2, etc.) is not yet implemented.

Does guideXOS boot from UEFI or legacy BIOS?

guideXOS uses legacy BIOS boot only. It boots via GRUB2 with the El Torito bootloader specification.

Why legacy BIOS? It's simpler for OS development and works in all VM environments. Modern systems can still boot in legacy mode, though you may need to enable "CSM" (Compatibility Support Module) in your BIOS/UEFI settings to run on physical hardware.

What GPU drivers does guideXOS use?

guideXOS includes minimal graphics drivers optimized for virtual machine environments:

No native GPU support: There are no NVIDIA, AMD, or Intel graphics drivers. 3D acceleration, OpenGL, DirectX, and Vulkan are not supported. The system is designed for 2D GUI operations only, which work well via VESA framebuffer on most hardware.

Is guideXOS a microkernel?

No. guideXOS is a monolithic kernel, similar to Linux or early FreeBSD.

Why monolithic? It's simpler to develop, provides better performance (no context switches), and works well with C# NativeAOT compilation. The tradeoff is that a driver crash can bring down the entire system, but this is acceptable for an educational/experimental OS.

Similar architectures: Linux kernel, MS-DOS, early BSD variants.

Usage Questions

How do I install guideXOS?

guideXOS runs from an ISO image—you don't install it. Simply:

1. Download the ISO
2. Boot it in a VM (QEMU, VMware, VirtualBox)
3. Or burn to CD/USB and boot on real hardware

See the Getting Started guide for details.

Can I browse the web?

Partially. The built-in web browser supports:

• ✅ HTTP (plain text websites)
• ✅ Basic HTML rendering
• ❌ HTTPS (no TLS/SSL support)
• ❌ JavaScript
• ❌ CSS styling

It's suitable for simple text-based websites and testing network connectivity.

How do I connect to the internet?

1. Boot guideXOS
2. Open Console
3. Type: netinit
4. Wait for DHCP configuration
5. Test: ping 8.8.8.8

Make sure your VM is configured with a supported network adapter (Intel PRO/1000 or Realtek).

Where are my files saved?

All files are stored in RAM and are lost on reboot. The filesystem is volatile—think of it as a live CD environment.

What applications are included?

• 📝 Notepad - Text editor
• 🎨 Paint - Graphics editor
• 🧮 Calculator - Basic math
• 📋 Console - Command line
• 📁 File Manager - File browser
• 🌐 Web Browser - HTTP client
• 💬 IRC Client - Chat
• 📊 Task Manager - System monitor

Development Questions

Can I create my own applications?

Yes! Applications are compiled as .gxm executables using NativeAOT. You write C# code, compile it, and package it in the custom .gxm format. See the Development guide.

How do I add a new device driver?

1. Study existing drivers in Drivers/ folder
2. Implement PCI device detection
3. Write initialization code (MMIO, interrupts, DMA)
4. Add to PCI.cs device table
5. Rebuild kernel and ISO

What's the build time?

On a modern PC with SSD:

• Kernel only: 5-10 seconds
• Full build (with ISO): 15-30 seconds
• Incremental build: 2-5 seconds

Can I use standard .NET libraries?

No. Standard .NET libraries depend on the CLR runtime and Windows/Linux APIs. guideXOS provides its own minimal CoreLib implementation. You must use only:

• Basic types (int, string, arrays)
• guideXOS system APIs
• Unsafe code and pointers

Troubleshooting

guideXOS won't boot

Check these items:

• VM configured as "Other" or "Other 64-bit" OS
• At least 512MB RAM (2GB recommended)
• Boot order set to CD/DVD first
• ISO image mounted correctly
• Try QEMU if other VMs fail

Network doesn't work

Common fixes:

• Run netinit command first
• Use Intel PRO/1000 (82540EM) in VirtualBox
• Use Realtek RTL8139 in QEMU
• Check VM network adapter is "NAT" or "Bridged"
• Verify DHCP server is available

Screen is black or corrupted

Possible solutions:

• Increase video memory to 128MB in VM settings
• Disable 3D acceleration
• Try different VM software (QEMU vs VMware vs VirtualBox)
• Check serial console output for error messages

Keyboard/mouse not working

Try these:

• Use PS/2 emulation mode in VM
• Disable USB passthrough
• Click inside VM window to capture input
• Check VM's input settings

Build errors

Most common issues:

• NASM not in PATH
• Missing dependencies (restore NuGet packages)

Related Topics