Device Drivers - FreeWorld OS

Location: kernel/drivers/
Type: Assembly Device Drivers
Purpose: Complete device driver implementations (VGA, keyboard, timer, mouse, VESA)
Status: ✅ Complete and Production-Ready

Overview

The FreeWorld Device Drivers provide complete, production-ready drivers for essential hardware components. All drivers are implemented in assembly for maximum performance and direct hardware access.

Status: All critical device drivers are complete and integrated. Total: ~2,000+ lines of production-ready code.
UEFI Migration Complete (2025): Modern drivers now use UEFI-provided information and PCI enumeration. Legacy drivers (VGA, VESA, ATA PIO, PIT, PIC) are deprecated.

Modern Drivers (UEFI-Aware)

USB xHCI Driver

Location: kernel/drivers/usb_xhci_uefi.asm

USB 3.0+ host controller driver:

  • PCI Enumeration: Scans PCI bus for xHCI controllers (class 0x0C03, subclass 0x30)
  • Device Enablement: Enables PCI devices automatically
  • MMIO Access: Reads MMIO base address from BAR0
  • Initialization: Calls existing xHCI initialization code

NVMe Driver

Location: kernel/drivers/nvme_uefi.asm

Non-Volatile Memory Express (SSD) driver:

  • PCI Enumeration: Scans PCI bus for NVMe controllers (class 0x01, subclass 0x08)
  • Device Enablement: Enables PCI devices automatically
  • MMIO Access: Reads MMIO base address from BAR0
  • Initialization: Calls existing NVMe initialization code

AHCI Driver

Location: kernel/drivers/ahci_uefi.asm

Advanced Host Controller Interface (SATA) driver:

  • PCI Enumeration: Scans PCI bus for AHCI controllers (class 0x01, subclass 0x06)
  • Device Enablement: Enables PCI devices automatically
  • MMIO Access: Reads MMIO base address from BAR5
  • Initialization: Calls existing AHCI initialization code

HPET Driver

Location: kernel/drivers/hpet_uefi.asm

High Precision Event Timer driver:

  • ACPI Discovery: Base address from ACPI HPET table
  • Frequency Detection: Calculates frequency from period
  • High Precision: Microsecond-level timing
  • Timer Configuration: Configurable periodic interrupts

I/O APIC Driver

Location: kernel/interrupts/io_apic_uefi.asm

Modern interrupt controller driver:

  • ACPI Discovery: Base address from ACPI MADT
  • Legacy PIC Disabled: Legacy 8259 PIC is disabled
  • IRQ Routing: Dynamic interrupt routing

Framebuffer Console

Location: kernel/drivers/framebuffer_console.asm

GOP framebuffer-based text console:

  • GOP Framebuffer: Uses Graphics Output Protocol framebuffer
  • 8x16 Font: Bitmap font for ASCII characters
  • Text Rendering: Pixel-by-pixel character rendering
  • Scrolling: Automatic screen scrolling
  • Replaces Serial: No more serial port debugging

Legacy Drivers (Deprecated)

⚠️ Deprecated: The following drivers are deprecated and replaced by modern UEFI-aware alternatives. They are kept for compatibility but should not be used in new code.

VGA Driver (vga.asm) - ⚠️ DEPRECATED

Location: kernel/drivers/vga.asm (510 lines)

Status: ⚠️ Deprecated - Replaced by GOP framebuffer console

Legacy VGA text mode driver (kept for compatibility):

Replacement: Use kernel/drivers/framebuffer_console.asm with GOP framebuffer instead.

Features

  • 80x25 text mode initialization
  • Cursor management (show/hide, position)
  • 16-color support (foreground/background)
  • Auto-scrolling when screen full
  • Print functions (char, string, number, hex)
  • Screen clearing and line clearing

Key Functions

Function Description Parameters
init_vga Initialize VGA text mode None
vga_putchar Print character at cursor AL = character
vga_puts Print null-terminated string ESI = string pointer
vga_set_cursor Set cursor position EAX = X, EBX = Y
vga_get_cursor Get cursor position None
vga_show_cursor Show cursor None
vga_hide_cursor Hide cursor None
vga_clear_screen Clear entire screen None
vga_set_color Set color attribute AL = color byte
vga_scroll Scroll screen up one line None

VGA Constants

  • VGA_MEMORY_BASE: 0xB8000 (text mode framebuffer)
  • VGA_WIDTH: 80 columns
  • VGA_HEIGHT: 25 rows
  • 16 color constants (BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHT_GRAY, DARK_GRAY, LIGHT_BLUE, LIGHT_GREEN, LIGHT_CYAN, LIGHT_RED, LIGHT_MAGENTA, YELLOW, WHITE)

Keyboard Driver (keyboard.asm) - ⚠️ DEPRECATED

Location: kernel/drivers/keyboard.asm (350 lines)

Status: ⚠️ Deprecated - Replaced by USB xHCI HID devices

Legacy PS/2 keyboard driver (kept for compatibility):

Replacement: Use USB xHCI driver for modern USB keyboard support.

Features (Legacy)

  • Complete US QWERTY scan code mapping
  • Circular buffer (256 characters)
  • Key state tracking (Shift, Ctrl, Alt, Caps Lock, Num Lock, Scroll Lock)
  • Non-blocking character retrieval
  • Special key handling (function keys, arrows, etc.)

Key Functions

Function Description Parameters Returns
keyboard_irq_handler IRQ handler for keyboard interrupts None (interrupt handler) None
keyboard_getchar Get character from keyboard buffer None AL = character (0 if none available)
scan_code_to_ascii Convert scan code to ASCII AL = scan code AL = ASCII character (0 if not printable)

Key State Flags

  • KEY_STATE_SHIFT: Shift key pressed
  • KEY_STATE_CTRL: Ctrl key pressed
  • KEY_STATE_ALT: Alt key pressed
  • KEY_STATE_CAPS: Caps Lock active
  • KEY_STATE_NUMLOCK: Num Lock active
  • KEY_STATE_SCROLLLOCK: Scroll Lock active

Timer Driver (timer.asm) - ⚠️ DEPRECATED

Location: kernel/drivers/timer.asm (150 lines)

Status: ⚠️ Deprecated - Replaced by HPET driver

Legacy PIT (Programmable Interval Timer) driver (kept for compatibility):

Replacement: Use kernel/drivers/hpet_uefi.asm for high-precision timing.

Features (Legacy)

  • System time tracking (seconds, milliseconds)
  • Sleep functions (sleep_ms, sleep_seconds)
  • Tick counter (100 Hz timer)
  • IRQ handler for timer interrupts

Key Functions

Function Description Parameters Returns
init_timer Initialize timer driver None None
timer_irq_handler IRQ handler for timer interrupts None (interrupt handler) None
get_time_ms Get system time in milliseconds None EAX = milliseconds since boot
get_time_seconds Get system time in seconds None EAX = seconds since boot
sleep_ms Sleep for milliseconds EAX = milliseconds None
sleep_seconds Sleep for seconds EAX = seconds None

Timer Configuration

  • Frequency: 100 Hz (10ms per tick)
  • IRQ: IRQ 0 (Timer)
  • Interrupt: INT 0x20 (after PIC remapping)
  • PIT Mode: Mode 2 (Rate Generator)

Mouse Driver (mouse.asm) - ⚠️ DEPRECATED

Location: kernel/drivers/mouse.asm (~400 lines)

Status: ⚠️ Deprecated - Replaced by USB xHCI HID devices

Legacy PS/2 mouse driver (kept for compatibility):

Replacement: Use USB xHCI driver for modern USB mouse/keyboard support.

Features (Legacy)

  • PS/2 mouse initialization and configuration
  • 3-byte packet processing (status, X delta, Y delta)
  • Button tracking (left, right, middle)
  • Position tracking with bounds checking (0-1023 X, 0-767 Y)
  • IRQ 12 handler integrated
  • Circular buffer for mouse packets

Key Functions

Function Description Parameters Returns
init_mouse Initialize PS/2 mouse None None
mouse_irq_handler IRQ handler for mouse interrupts (IRQ 12) None (interrupt handler) None
mouse_get_position Get current mouse position None EAX = X, EBX = Y
mouse_get_buttons Get current button state None AL = button flags
mouse_is_button_pressed Check if specific button is pressed AL = button flag AL = 1 if pressed, 0 if not
mouse_get_packet Get mouse packet from buffer (non-blocking) None AL = status, BL = X delta, CL = Y delta, AH = 1 if available

Mouse Constants

  • MOUSE_BUTTON_LEFT: 0x01
  • MOUSE_BUTTON_RIGHT: 0x02
  • MOUSE_BUTTON_MIDDLE: 0x04
  • MOUSE_DATA_PORT: 0x60
  • MOUSE_STATUS_PORT: 0x64
  • MOUSE_COMMAND_PORT: 0x64

VESA Graphics Driver (vesa.asm) - ⚠️ DEPRECATED

Location: kernel/drivers/vesa.asm (~400 lines)

Status: ⚠️ Deprecated - Replaced by GOP framebuffer

Legacy VESA/VBE graphics driver (kept for compatibility):

Replacement: Use kernel/drivers/framebuffer_console.asm with GOP framebuffer instead.

Features (Legacy)

  • VESA BIOS Extensions (VBE) support
  • Linear framebuffer access
  • 1024x768x32 graphics mode
  • Framebuffer information retrieval
  • Graphics primitives (pixel, line, rectangle)
  • Screen clearing

Key Functions

Function Description Parameters Returns
init_vesa Initialize VESA graphics mode None EAX = 0 on success, -1 on failure
vesa_get_framebuffer Get framebuffer address None EAX = framebuffer address
vesa_get_width Get screen width None EAX = width in pixels
vesa_get_height Get screen height None EAX = height in pixels
vesa_get_pitch Get bytes per scanline None EAX = pitch in bytes
vesa_draw_pixel Draw pixel at (X, Y) EAX = X, EBX = Y, ECX = color None
vesa_draw_line Draw line (Bresenham's algorithm) EAX = X1, EBX = Y1, ECX = X2, EDX = Y2, ESI = color None
vesa_draw_rect Draw filled rectangle EAX = X, EBX = Y, ECX = width, EDX = height, ESI = color None
vesa_draw_rect_outline Draw rectangle outline EAX = X, EBX = Y, ECX = width, EDX = height, ESI = color None
vesa_clear_screen Clear framebuffer with color EAX = color (32-bit ARGB) None

VESA Constants

  • VESA_MODE_WIDTH: 1024
  • VESA_MODE_HEIGHT: 768
  • VESA_MODE_BPP: 32
  • VESA_MODE_NUMBER: 0x118 (1024x768x32)
  • VBE_MODE_LINEAR_FRAMEBUFFER: 0x4000
  • VBE_MODE_ENABLE: 0x0001

Integration (UEFI-Aware)

All device drivers are integrated into the kernel via kernel/arch/x64/kernel_64_uefi.asm:

; In kernel_init_64_uefi:
call framebuffer_console_init  ; Initialize GOP framebuffer console
call init_physical_memory_from_uefi_map  ; Initialize UEFI memory map-based PMM
call acpi_init_uefi            ; Initialize ACPI using RSDP from UEFI
call io_apic_init_uefi         ; Initialize I/O APIC (disables legacy PIC)
call hpet_init_uefi            ; Initialize HPET timer (replaces PIT)
call usb_xhci_init_uefi        ; Initialize USB xHCI controllers
call nvme_init_uefi            ; Initialize NVMe controllers
call ahci_init_uefi            ; Initialize AHCI controllers

Status: ✅ Integrated - All modern drivers initialized during UEFI kernel boot

Note: Legacy drivers (VGA, VESA, PIT, PIC, PS/2, ATA PIO) are no longer initialized in UEFI boot path.

Usage Examples

VGA Output

; Print a character
mov al, 'A'
call vga_putchar

; Print a string
mov esi, hello_string
call vga_puts

; Set cursor position
mov eax, 10  ; X
mov ebx, 5   ; Y
call vga_set_cursor

Keyboard Input

; Get character from keyboard
call keyboard_getchar
cmp al, 0
je no_input
; AL contains the character

Timer Functions

; Get current time
call get_time_ms
; EAX contains milliseconds since boot

; Sleep for 1 second
mov eax, 1000
call sleep_ms

Mouse Input

; Get mouse position
call mouse_get_position
; EAX = X position, EBX = Y position

; Check if left button is pressed
mov al, MOUSE_BUTTON_LEFT
call mouse_is_button_pressed
cmp al, 1
je left_button_pressed

VESA Graphics

; Initialize graphics mode
call init_vesa
cmp eax, 0
jne graphics_error

; Draw a pixel
mov eax, 100   ; X
mov ebx, 100   ; Y
mov ecx, 0xFFFFFFFF  ; White (ARGB)
call vesa_draw_pixel

; Draw a rectangle
mov eax, 50    ; X
mov ebx, 50    ; Y
mov ecx, 200   ; Width
mov edx, 100   ; Height
mov esi, 0xFF0000FF  ; Blue
call vesa_draw_rect